Skip to main content

A dependency-aware GraphQL API fuzzing tool

Project description

The only dependency-aware GraphQL API testing tool!

python3.12 Maintainability lint tests_status security

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.

Video Demo

Key features

  • Dependency awareness: Run queries and mutations based on their dependencies!
  • Dynamic testing: Keep track of resources created during testing
  • Error correction: Try and fix requests so that the GraphQL API accepts them
  • Statistics collection: Shows your results in a nice file
  • Ease of use: All you need is the endpoint and the authentication token if needed

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,fuzz,idor,run} [--auth AUTH] [--version]

options:
  -h, --help            show this help message and exit
  --url URL             remote host URL
  --path PATH           directory location for files to be saved-to/used-from
  --config CONFIG       configuration file for the program
  --mode {compile,fuzz,idor,run}
                        mode to run the program in
  --auth AUTH           authentication token Example: 'Bearer arandompat-abcdefgh'
  --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:This mode is responsible for running an introspection query against the given API and generating the dependency graphh
  • Fuzzing mode: This mode is responsible for traversing the dependency graph and sending test requests to the API

A third mode is also included for ease of use, called run mode. this mode compiles both the compilation and fuzzing mode into one single command.

Compile mode

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

After compiling, you can view the compiled results in the <SAVE_PATH>/compiled. Additionally, a graph will have been generated called dependency_graph.png for inspection. 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.

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>

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

graphqler-2.1.2.tar.gz (40.4 kB view details)

Uploaded Source

Built Distribution

graphqler-2.1.2-py3-none-any.whl (57.3 kB view details)

Uploaded Python 3

File details

Details for the file graphqler-2.1.2.tar.gz.

File metadata

  • Download URL: graphqler-2.1.2.tar.gz
  • Upload date:
  • Size: 40.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.0 Linux/5.15.153.1-microsoft-standard-WSL2

File hashes

Hashes for graphqler-2.1.2.tar.gz
Algorithm Hash digest
SHA256 4e00e3cae1aa7983b153587217aab9befcec7786e576a0f6deae4207d2ce785f
MD5 6db8c0e892a0ff77a9b5f411a7fffc94
BLAKE2b-256 6c1d4cd5c189c2dc7b986f8c99acbe5779de2940f4998905321d37524a6a47ed

See more details on using hashes here.

Provenance

File details

Details for the file graphqler-2.1.2-py3-none-any.whl.

File metadata

  • Download URL: graphqler-2.1.2-py3-none-any.whl
  • Upload date:
  • Size: 57.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.0 Linux/5.15.153.1-microsoft-standard-WSL2

File hashes

Hashes for graphqler-2.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 a42927c214182157344d97fcf42f26d4eb9bd24961959aaf1563150838574550
MD5 8fe48f33c418cce124de28fc9468231c
BLAKE2b-256 64a30d21dfb1c4080f55f655c7c2094aaea054c58206c9678492d3f7fe8ef18d

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page