GraphQLer 2.3.8

A cutting edge context aware GraphQL API fuzzing tool!

The only dependency-aware GraphQL API testing tool

GraphQLer is a cutting-edge tool designed to dynamically test GraphQL APIs with a focus on awareness. It offers a range of sophisticated features that streamline the testing process and ensure robust analysis of GraphQL APIs such as being able to automatically read a schema and run tests against an API using the schema. Furthermore, GraphQLer is aware of dependencies between objects queries and mutations which is then used to perform security tests against APIs.

Key features

• Request generation: Automatically generate valid queries and mutations based on the schema (supports fragments, unions, interfaces, and enums based on the latest GraphQL-spec)
• Dependency awareness: Run queries and mutations based on their natural dependencies
• Resource tracking: Keep track of any objects seen in the API for future use and reconnaisance
• Error correction: Try and fix requests so that the GraphQL API accepts them
• Statistics collection: Shows your results in a easy-to-read file
• Ease of use: All you need is the endpoint and the authentication token if needed
• Customizability: Change the configuration file to suit your needs, proxy requests through Burp or ZAP if you want

Getting started

Quick installation can be done either with pip:

pip install GraphQLer
python -m graphqler --help

or docker:

docker pull omar2535/graphqler:latest
docker run --rm omar2535/graphqler --help

For a more in-depth guide, check out the installation guide.

Usage

❯ python -m graphqler --help
usage: __main__.py [-h] [--url URL] [--path PATH] [--config CONFIG] --mode {compile,compile-graph,compile-chains,fuzz,idor,run,single} [--auth AUTH] [--proxy PROXY] [--node NODE] [--plugins-path PLUGINS_PATH] [--disable-mutations] [--version]

options:
  -h, --help            show this help message and exit
  --url URL             remote host URL (required for all modes except compile-chains)
  --path PATH           directory location for files to be saved-to/used-from. Defaults to graphqler-output
  --config CONFIG       configuration file for the program
  --mode {compile,compile-graph,compile-chains,fuzz,idor,run,single}
                        mode to run the program in
  --auth AUTH           authentication token Example: 'Bearer arandompat-abcdefgh'
  --proxy PROXY         proxy to use for requests (ie. http://127.0.0.1:8080)
  --node NODE           node to run (only used in single mode)
  --plugins-path PLUGINS_PATH
                        path to plugins directory
  --disable-mutations   only generate and run Query chains — all Mutation nodes are excluded from fuzzing
  --version             display version

Below will be the steps on how you can use this program to test your GraphQL API. The usage is split into 2 phases, compilation and fuzzing.

• Compilation mode: Responsible for running an introspection query against the given API, resolving dependencies between objects/queries/mutations, generating the dependency graph, and pre-generating fuzzing chains.
• Fuzzing mode: Responsible for executing the pre-generated chains against the API and collecting results.

The compile step can be broken into two finer sub-modes:

• compile-graph: Runs only the introspection, parsing, and dependency-resolution steps — stops before chain generation.
• compile-chains: (Re-)generates fuzzing chains from an already-compiled graph without making any network requests. Useful when you want to tweak DISABLE_MUTATIONS or the chain strategy without re-running introspection.

A third mode is also included for ease of use, called run mode — this runs both compilation and fuzzing in a single command.

A mode in development right now is known as the idor mode, which will look for re-used objects that are accessible using another access token. This is in trial right now and requires the user to have run the compile and fuzzing mode first.

Compile mode

python -m graphqler --mode compile --url <URL> --path <SAVE_PATH>

Runs the full compilation pipeline: introspection → parsing → dependency resolution → dependency graph → fuzzing chains. After compiling, you can view the compiled results in <SAVE_PATH>/compiled. A dependency graph image (dependency_graph.png) is also generated for inspection. Fuzzing chains are saved to <SAVE_PATH>/compiled/chains.yml — this file is human-readable and can be edited before fuzzing. Any UNKNOWNS in the compiled .yaml files can be manually marked; however, if not marked the fuzzer will still run them but just without using a dependency chain.

Compile-graph mode

python -m graphqler --mode compile-graph --url <URL> --path <SAVE_PATH>

Runs only the introspection, parsing, and dependency-resolution steps. Stops before chain generation. Use this when you only want to refresh the schema and graph, then run compile-chains separately (e.g. to experiment with different chain settings without hitting the API again).

Compile-chains mode

python -m graphqler --mode compile-chains --path <SAVE_PATH>

(Re-)generates fuzzing chains from an already-compiled dependency graph. No --url is required — all data is read from disk. Run this after compile or compile-graph to regenerate compiled/chains.yml with different settings (e.g. --disable-mutations or a custom CHAINS_FILE_NAME in your config).

Fuzz mode

python -m graphqler --mode fuzz --url <URL> --path <SAVE_PATH>

While fuzzing, statistics related to the GraphQL API and any ongoing request counts are logged in the console. Any request return codes are written to <SAVE_PATH>/stats.txt. All logs during fuzzing are kept in <SAVE_PATH>/logs/fuzzer.log. The log file will tell you exactly which requests are sent to which endpoints, and what the response was. This can be used for further result analysis. A copy of the objects bucket can be found in objects_bucket.pkl as well.

IDOR Checking mode

python -m graphqler --mode idor --url <URL> --path <SAVE_PATH>

The insecure direct object reference (IDOR) mode can be run after compile mode and fuzz mode is complete. It requires the objects_bucket.pkl file to already exist as it uses the objects bucket from a previous run to see if information found/created from a previous run is also reference-able in a new run.

Run mode

Runs both the Compile mode and Fuzz mode

python -m graphqler --mode run --url <URL> --path <SAVE_PATH>

Single mode

Runs a single node (make sure it exists in the list of queries or mutations)

python -m graphqler --url <URL> --path <SAVE_PATH> --config <CUSTOM_CONFIG>> --proxy <CUSTOM_PROXY> --mode single --node <NODE_NAME>

Advanced features

There are also varaibles that can be modified with the --config flag as a TOML file (see /examples/config.toml for an example). These correspond to specific features implemented in GraphQLer, and can be tuned to your liking.

Variable Name	Variable Description	Variable Type	Default
MAX_LEVENSHTEIN_THRESHOLD	The levenshtein distance between objects and object IDs	Integer	20
MAX_OBJECT_CYCLES	Max number of times the same object should be materialized in the same query/mutation	Integer	3
MAX_OUTUPT_SELECTOR_DEPTH	Max depth the query/mutation's output should be expanded (such as the case of infinitely recursive selectors)	Integer	3
USE_OBJECTS_BUCKET	Whether or not to store object IDs for future use	Boolean	True
USE_DEPENDENCY_GRAPH	Whether or not to use the dependency-aware feature	Boolean	True
ALLOW_DELETION_OF_OBJECTS	Whether or not to allow deletions from the objects bucket	Boolean	False
MAX_FUZZING_ITERATIONS	Maximum number of fuzzing payloads to run on a node	Integer	5
MAX_TIME	The maximum time to run in seconds	Integer	3600
TIME_BETWEEN_REQUESTS	Max time to wait between requests in seconds	Integer	0.001
DEBUG	Debug mode	Boolean	False
Custom Headers	Custom headers to be sent along with each request	Object	Accept = "application/json"
SKIP_MAXIMAL_PAYLOADS	Whether or not to send a payload with all the possible outputs	Boolean	False
SKIP_DOS_ATTACKS	Whether or not to skip DOS attacks(defaults to true to not DOS the service)	Boolean	True
SKIP_INJECTION_ATTACKS	Whether or not to skip injection attacks	Boolean	False
SKIP_MISC_ATTACKS	Whether or not to skip miscillaneous attacks	Boolean	False
SKIP_NODES	Nodes to skip (query or mutation names)	List	[]
DISABLE_MUTATIONS	Only generate and run Query chains — all Mutation nodes are excluded from chain generation and fuzzing. Can also be set via --disable-mutations CLI flag.	Boolean	False

AI Features

LLM Enabled compilation (using ollama as an example):

uv run graphqler --url http://localhost:4000/graphql --mode run --use-llm --llm-model ollama/qwen3.5:9b --llm-base-url http://localhost:11434

Plugins

You can also implement your own plugins for custom authentication (ie. short token lifetimes). See more in the docs.