Skip to content

Home

Jump to bottom
Omar Tsai edited this page Jul 3, 2024 · 3 revisions

Home

Getting started

Quick installation can be done using pip:

pip install GraphQLer

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

Usage

❯ python -m graphqler --help
usage: __main__.py [-h] [--compile] [--fuzz] [--idor] [--run] --path PATH [--auth AUTH] --url URL

options:
  -h, --help   show this help message and exit
  --compile    runs on compile mode
  --fuzz       runs on fuzzing mode
  --idor       run on IDOR checking mode
  --run        run both the compiler and fuzzer (equivalent of running --compile then running --fuzz)
  --path PATH  directory location for saved files and files to be used from
  --auth AUTH  authentication token Example: 'Bearer arandompat-abcdefgh'
  --url URL    remote host URL

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 --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 --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 --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 --run --url <URL> --path <SAVE_PATH>

Advanced features

There are also varaibles that can be modified in the constants.py file. 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
Clone this wiki locally