Clairvoyance Documentation

Clairvoyance relies on wordlists to guess GraphQL names. To improve accuracy, consider these three approaches:

1. Specialized GraphQL wordlists: Use lists specifically collected for GraphQL (e.g., from Escape Technologies).
2. General English wordlists: Use common English wordlists (e.g., google-10000-english).
3. Target-specific wordlists: Create a custom list by extracting valid GraphQL names from the target application's HTTP traffic or mobile application static files.

Note: The regex for a valid GraphQL name is [_A-Za-z][_0-9A-Za-z]*.

You can run Clairvoyance using a Docker container. Use the nikitastupin/clairvoyance image to execute the tool without local installation.

docker run --rm nikitastupin/clairvoyance --help

Install Clairvoyance using pip. Once installed, you can run it from the command line by providing the target GraphQL endpoint URL and an output file path using the -o flag. The tool will attempt to reconstruct the schema and save it in JSON format.

pip install clairvoyance
clairvoyance https://rickandmortyapi.com/graphql -o schema.json

Use the clairvoyance CLI to perform blind introspection on a GraphQL endpoint. This process attempts to reconstruct the GraphQL schema by brute-forcing field names using a wordlist, which is useful when standard introspection queries are disabled.

Key capabilities:

• Uses a wordlist to discover schema elements.
• Supports custom input documents (queries) and existing schema files.
• Supports concurrent requests for performance.
• Can output the discovered schema to a file.
• Can validate wordlist items against the GraphQL name regex ([_A-Za-z][_0-9A-Za-z]*) to ensure compatibility.

If Clairvoyance fails only when targeting a specific website, investigate these areas:

1. Scope Verification: Rule out a general tool failure by testing against a known working target. For example, try:

   clairvoyance https://rickandmortyapi.com/graphql -o schema.json

2. URI Validity: Check the endpoint URI for typos or errors introduced during copying.
3. Authorization: Ensure you are providing the correct headers, cookies, or other required authorization credentials.
4. WAF (Web Application Firewall): The target's WAF might be blocking the request. Ensure the program imitates a modern browser or a specific web client by checking that the User-Agent header matches a legitimate browser/app.

If Clairvoyance fails to run entirely, check the following:

1. Installation: Verify that the installation process completed without errors and that all dependency versions are correct.
2. Internet Connection: Ensure you have a stable internet connection and that the environment running Clairvoyance has the necessary permissions/rights to access your target URL.
3. Usage Syntax: Verify your command syntax against the instructions in the README.md.

If Clairvoyance was working but suddenly stops, determine if a restart fixes the issue:

If a restart fixes the issue (Rate Limiting)

The server may be rate-limiting requests from your IP or user identity. To mitigate this:

• Lower the number of threads used.
• Run the program in a "slow mode" (if supported).

If a restart does NOT fix the issue (Server/IP issues)

• Server Availability: The target server might be temporarily unavailable. Manually verify the endpoint using a browser or other tools.
• IP/User Ban: Your IP address or user identity may have been banned by the target server.

You can control the logging behavior of Clairvoyance using the following environment variables:

• LOG_FMT: A string format for logging.
• LOG_DATEFMT: A string format for logging the date.
• LOG_LEVEL: The logging level (e.g., INFO).

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.