Graphicator: Brute-Force GraphQL Enumeration Through Introspection

Hook

Most GraphQL security tools stop at visualization. Graphicator asks: what if we just executed every single query the schema allows and saved the results?

Context

GraphQL introspection is a double-edged sword. While it enables powerful developer tooling and self-documenting APIs, it also hands potential attackers a complete map of your data structure. Traditional reconnaissance requires manually crafting queries based on schema analysis—tedious work that involves understanding type relationships, identifying queryable fields, and constructing syntactically valid requests. Tools like GraphiQL and GraphQL Playground help developers explore schemas interactively, but they're designed for development, not systematic enumeration.

Penetration testers face a specific problem: given a GraphQL endpoint with introspection enabled, how do you quickly determine what data is actually accessible? You could spend hours manually writing queries, or you could attempt to script something custom for each engagement. Graphicator emerged from this gap—a purpose-built tool that treats GraphQL enumeration as a solved problem. Point it at an endpoint, and it automatically generates every possible query combination from the introspection schema, executes them, and organizes the results. It's the difference between manual reconnaissance and automated discovery, turning a multi-hour task into a minutes-long operation.

Technical Insight

Graphicator's architecture follows a three-phase pipeline: introspection retrieval, query generation, and systematic execution with caching. When you target an endpoint, it first sends the standard GraphQL introspection query to retrieve the complete schema definition. This JSON response contains all types, fields, arguments, and their relationships—essentially the API's blueprint.

The query generation phase is where Graphicator differentiates itself. Rather than building a graph visualization or stopping at schema analysis, it programmatically constructs every valid query combination. For a simple schema with a User type containing id, name, and email fields, it generates individual queries for each field, then combinations of fields, handling nested types recursively. Here's what the execution flow looks like:

# Simplified conceptual example of query generation
def generate_queries(schema):
    queries = []
    for query_type in schema['queryType']['fields']:
        field_name = query_type['name']
        return_type = query_type['type']
        
        # Generate base query
        query = f"query {{ {field_name} {{"
        
        # Recursively add fields from return type
        fields = get_fields_for_type(return_type, schema)
        for field in fields:
            query += f" {field['name']}"
        
        query += " }}"
        queries.append(query)
    
    return queries

The caching mechanism uses SHA-1 hashing to prevent redundant requests. Before executing a query, Graphicator hashes the combination of the query string and target URL, checking if that hash already exists in the reqcache directory. This design decision is particularly clever for iterative testing—if you're testing an endpoint across multiple sessions, adding custom headers, or adjusting parameters, you won't re-execute queries that have already succeeded. The tool maintains three separate cache directories:

• reqcache/: Stores actual response data with SHA-1 filenames
• reqcache-intro/: Saves introspection schema responses
• reqcache-queries/: Contains the query text that generated each response

The matching filenames across directories make correlation trivial. If you find sensitive data in reqcache/abc123.txt, you can immediately check reqcache-queries/abc123.txt to see which query produced it.

Proxy integration is first-class, designed specifically for penetration testing workflows. The tool supports Burp Suite integration (--proxy http://127.0.0.1:8080), Tor routing for anonymity, and custom proxy configurations. This means you can pipe all GraphQL traffic through Burp to analyze requests, modify them with match-and-replace rules, or build a complete audit trail:

# Route through Burp Suite for request inspection
python graphicator.py --url https://api.example.com/graphql --proxy http://127.0.0.1:8080

# Add custom authorization headers
python graphicator.py --url https://api.example.com/graphql --header "Authorization: Bearer eyJ..."

# Process multiple targets from file
python graphicator.py --file targets.txt --threads 5

The multi-threading implementation allows concurrent execution across multiple targets, though queries against a single endpoint remain sequential to avoid overwhelming the server or triggering rate limits. This design choice reflects the tool's focus on stealth and reliability over raw speed—it's built for thorough enumeration, not denial of service.

One particularly useful feature for large engagements is the file-based target input. You can feed Graphicator a list of GraphQL endpoints discovered through subdomain enumeration or content discovery, and it will systematically process each one, maintaining separate caches and organizing results by target. This transforms Graphicator from a single-endpoint tool into a scalable reconnaissance platform for organizations with multiple GraphQL services.

Gotcha

Graphicator's laser focus on query enumeration means it completely ignores mutations, subscriptions, and actual GraphQL vulnerabilities. If you're expecting a comprehensive security scanner that tests for authorization bypasses, injection flaws, or batching attacks, you'll be disappointed. The tool retrieves data through queries—that's it. It won't test whether you can modify data through unauthorized mutations, won't check if field-level authorization is properly implemented, and won't attempt any of the OWASP GraphQL-specific attack vectors.

The brute-force query generation approach can also create problems with large or deeply nested schemas. If a GraphQL API has hundreds of types with complex relationships, Graphicator will attempt to generate and execute an enormous number of queries. There's no intelligent filtering, depth limiting, or complexity analysis—it just generates everything and fires away. On production APIs with rate limiting, this can trigger protection mechanisms or generate enough traffic to alert security teams. The tool also has no built-in authentication flow handling beyond static headers. If you're testing an API that requires OAuth token refresh, session management, or multi-step authentication, you'll need to handle that externally and provide a valid token via the --header flag. There's no support for CSRF tokens, no cookie jar management, and no way to automatically handle authentication challenges. Finally, if introspection is disabled—an increasingly common security practice—Graphicator is completely useless. It depends entirely on introspection being enabled to function.

Verdict

Use if: You're conducting penetration tests or security assessments against GraphQL APIs with introspection enabled, need to quickly map all accessible data without manual query construction, want results organized and cached for iterative analysis, or need to process multiple GraphQL endpoints at scale with proxy integration for traffic inspection. Use if: You value thoroughness over speed and can tolerate the traffic volume from exhaustive query generation. Skip if: You need comprehensive GraphQL security testing including mutations and vulnerability detection, the target API has introspection disabled, you're testing production systems with strict rate limiting where brute-force enumeration would be problematic, or you need sophisticated authentication flow handling beyond static bearer tokens. Skip if: You want a general-purpose GraphQL client rather than a specialized reconnaissance tool. Graphicator does one thing exceptionally well—automated query enumeration—but that narrow focus means it's a complement to other tools, not a replacement for comprehensive GraphQL security testing.