Clarence

A Python-based GraphQL schema recovery tool that reconstructs GraphQL schemas through alternative discovery techniques when introspection is unavailable or restricted.

Clarence is a security research tool designed to assist application security researchers and bug bounty hunters in analyzing GraphQL APIs. It automates multiple schema recovery techniques to infer types, fields, and relationships without relying solely on GraphQL introspection, making it useful for assessing GraphQL implementations where introspection has been disabled.

The project was developed as part of independent GraphQL security research and is intended for authorized security testing and educational purposes.

Why Clarence Exists

During independent GraphQL security research, I encountered an application where introspection was disabled. Although several GraphQL operations could be identified from JavaScript files, understanding the overall schema remained difficult.

Existing schema recovery tools relied heavily on verbose GraphQL validation errors and generated significant network noise during testing. Clarence was developed to reduce unnecessary requests by adapting to server capabilities and analyzing response behavior instead of relying solely on descriptive error messages.

The result is a practical research tool that helps reconstruct GraphQL schemas when introspection is unavailable, making subsequent manual security testing more effective.

Features

• Recover GraphQL schemas when introspection is disabled or restricted.
• Discover GraphQL Queries, Mutations, object types, fields, and arguments.
• Detect valid GraphQL operations through server response analysis, even when verbose validation errors are unavailable.
• Optimize schema recovery by adapting to server capabilities such as request size limits and validation error limits.
• Generate graphql-path-enum commands and custom wordlists to support further manual security testing.

Example Schema Recovery

Discovering Root Queries

Clarence identifies valid GraphQL Query operations by analyzing differences in server responses rather than relying solely on verbose validation errors.

---

Recovering Object Types

After discovering root operations, Clarence recursively recovers object types and nested fields, progressively reconstructing the GraphQL schema.

---

Generating Security Testing Resources

Once recovery is complete, Clarence generates graphql-path-enum commands that can be used directly during manual GraphQL security assessments.

Workflow Diagram

flowchart TD

A[Target GraphQL Endpoint]

A --> B[Check Batching Support]
B --> C[Find Maximum POST Size]
C --> D[Find Validation Error Limit]

D --> E[Create Empty Introspection File]

E --> F[Recover Root Queries]
F --> G[Recover Query Types]

G --> H[Recover Root Mutations]
H --> I[Recover Mutation Types]

I --> J[Recover Query Arguments]
J --> K[Recover Mutation Arguments]

K --> L[Generate Sensitive Type Paths]
L --> M[Generate Recovery Wordlist]

M --> N[Recovered GraphQL Schema]

Loading

Installation

git clone https://github.com/soham23/clarence.git
cd clarence
pip install -r requirements.txt

Configuration

Clarence is configured through constants.py.

Setting	Description
PROXY_MODE	Enable or disable HTTP proxying (e.g. Burp Suite).
HEADERS	HTTP headers sent with every GraphQL request. Authentication headers can be added here if required.
PROXIES	Proxy configuration used when PROXY_MODE is enabled.
MAX_POST_SIZE	Maximum POST body size accepted by the target server. Usually determined automatically using find_max_data_size.
MAX_ERRORS_LIMIT	Maximum number of GraphQL validation errors returned by the server. Usually determined automatically using find_validation_errors_limit.
DEFAULT_WORDLIST	Default wordlist used during schema discovery.
TIMEOUT	HTTP request timeout in seconds.

Available Operations

Operation	Purpose
check_batching_support	Determine whether GraphQL batching is supported.
find_max_data_size	Estimate the maximum POST request size accepted by the server.
find_validation_errors_limit	Determine the GraphQL validation error limit.
create_introspection_file	Create an empty introspection JSON file.
find_root_queries	Recover root Query operations.
find_all_query_types	Recursively recover Query object types and fields.
find_root_mutations	Recover root Mutation operations.
find_all_mutation_types	Recursively recover Mutation object types and fields.
find_query_args	Recover Query arguments.
find_mutation_args	Recover Mutation arguments.
generate_wordlist	Generate a discovery wordlist from the recovered schema.
find_sensitive_types	Generate graphql-path-enum commands for sensitive object types.

Documentation

For a more detailed explanation of Clarence and its recovery process, see:

• docs/algorithm.md — Schema recovery methodology and design decisions.
• docs/workflow.md — Recommended recovery workflow and generated outputs.
• docs/limitations.md — Current limitations and recovery constraints.

Limitations

• Wordlist dependent.
• Some GraphQL implementations suppress distinguishing responses.
• Does not infer business logic or authorization.
• Intended to assist manual testing rather than replace it.

---

Disclaimer

Clarence is intended for educational purposes and authorized security testing only.

Always obtain explicit permission before testing systems that you do not own or have authorization to assess. The author is not responsible for any misuse of this software.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

• GraphQL Specification
• GraphQL Documentation
• graphql-path-enum
• Clairvoyance