Clairvoyance is an open-source Python command-line tool for security researchers and penetration testers that recovers a GraphQL API schema even when introspection is disabled, producing JSON that other GraphQL tools can consume.

What it is

Clairvoyance is an Apache-2.0 Python project in the GraphQL security and penetration-testing ecosystem. It addresses GraphQL APIs that have introspection disabled, including deployments such as Apollo Server, which disables introspection automatically when the NODE_ENV environment variable is set to production. The tool helps obtain the API schema in that situation and produces it in JSON format suitable for other tools such as GraphQL Voyager, InQL, and graphql-path-enum.

The concrete problem Clairvoyance solves is the loss of the usual schema-discovery path: when introspection is disabled, standard introspection queries no longer expose the API's schema. Clairvoyance replaces reliance on introspection as the sole schema-discovery mechanism by using wordlists to recover a schema that downstream GraphQL tooling can read. Its README describes several wordlist approaches, including Escape Technologies' GraphQL wordlist, general English lists such as google-10000-english, and target-specific lists extracted from application HTTP traffic or mobile application static files.

Key capabilities

• Recovers a GraphQL API schema when introspection is disabled, including Apollo Server deployments running with NODE_ENV=production.
• Outputs the recovered schema as JSON for use with GraphQL Voyager, InQL, and graphql-path-enum.
• Installs from PyPI as clairvoyance and runs as a command-line tool with an endpoint and output file, as in clairvoyance https://rickandmortyapi.com/graphql -o schema.json.
• Provides a Docker image, nikitastupin/clairvoyance, for containerized execution.
• Supports multiple wordlist strategies: Escape Technologies' graphql-wordlist, general English word lists, and target-specific lists extracted from HTTP traffic or mobile application static files.
• Documents the GraphQL name regex [_A-Za-z][_0-9A-Za-z]* for extracting valid names when building target-specific wordlists.
• Exposes logging configuration through LOG_FMT, LOG_DATEFMT, and LOG_LEVEL environment variables.

Who uses it and how

• Penetration testers and security researchers use it during GraphQL API assessments to recover a schema when introspection has been disabled.
• Bug bounty hunters can use it against in-scope GraphQL endpoints to produce a schema.json file for follow-on analysis with tools such as InQL or graphql-path-enum.
• Security teams can run the Docker image in a containerized assessment environment with docker run --rm nikitastupin/clairvoyance --help.
• Analysts working with a specific target can build a custom wordlist from application HTTP traffic or mobile application static files rather than relying only on general-purpose lists.
• Users can follow the README example against https://rickandmortyapi.com/graphql, which it says should take about two minutes, to produce schema.json.

Getting started

Install from PyPI with pip install clairvoyance, then run clairvoyance https://rickandmortyapi.com/graphql -o schema.json; a Docker image is also available with docker run --rm nikitastupin/clairvoyance --help.

How it compares

Among the tools named in the facts, GraphQL Voyager, InQL, and graphql-path-enum are consumers of the JSON schema Clairvoyance produces, not like-for-like alternatives. The facts do not name a direct competitor or a list of paid products that Clairvoyance replaces, so it stands alone in this registry as a schema-recovery tool for introspection-disabled GraphQL APIs.

When to use it — and when not to

Clairvoyance is appropriate when a GraphQL API has introspection disabled and a JSON schema is needed for downstream tools, but users must run the Python package or Docker image themselves and choose a suitable wordlist, with logging controlled through environment variables. It is not a managed service, and the README directs users to a linked talk and the project wiki for deeper operational detail, so teams wanting a fully documented, hands-off schema source should look elsewhere. Because recovery depends on wordlist coverage, it is a poor fit when introspection is enabled and the authoritative schema is already available, or when an assessment requires a guaranteed complete schema without wordlist-driven gaps.

pip install clairvoyance
clairvoyance https://rickandmortyapi.com/graphql -o schema.json
# should take about 2 minutes

docker run --rm nikitastupin/clairvoyance --help

LOG_FMT=`%(asctime)s \t%(levelname)s\t| %(message)s` # A string format for logging.
LOG_DATEFMT=`%Y-%m-%d %H:%M:%S` # A string format for logging date.
LOG_LEVEL=`INFO` # A string level for logging.