Metadata-Version: 2.1
Name: GraphQLer
Version: 2.1.5
Summary: A dependency-aware GraphQL API fuzzing tool
License: MIT
Author: Omar2535
Author-email: omar2535@alumni.ubc.ca
Requires-Python: >=3.12,<3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: aiodns (==3.2.0)
Requires-Dist: aiohttp (==3.9.5)
Requires-Dist: aiosignal (==1.3.1)
Requires-Dist: astroid (==2.15.8)
Requires-Dist: asttokens (==2.4.0)
Requires-Dist: asyncio (==3.4.3)
Requires-Dist: attrs (==23.1.0)
Requires-Dist: autopep8 (==2.0.4)
Requires-Dist: backcall (==0.2.0)
Requires-Dist: backports-entry-points-selectable (==1.2.0)
Requires-Dist: black (==24.3.0)
Requires-Dist: brotli (==1.1.0)
Requires-Dist: certifi (==2024.7.4)
Requires-Dist: cffi (==1.16.0)
Requires-Dist: cfgv (==3.4.0)
Requires-Dist: charset-normalizer (==3.2.0)
Requires-Dist: clairvoyance (==2.5.2)
Requires-Dist: click (==8.1.7)
Requires-Dist: colorama (==0.4.6)
Requires-Dist: colorclass (==2.2.2)
Requires-Dist: contourpy (==1.1.1)
Requires-Dist: coverage (==7.3.1)
Requires-Dist: cycler (==0.12.1)
Requires-Dist: decorator (==5.1.1)
Requires-Dist: dill (==0.3.7)
Requires-Dist: distlib (==0.3.7)
Requires-Dist: docopt (==0.6.2)
Requires-Dist: executing (==2.0.0)
Requires-Dist: filelock (==3.12.4)
Requires-Dist: fonttools (==4.43.1)
Requires-Dist: frozenlist (==1.4.1)
Requires-Dist: graphql-core (==3.2.3)
Requires-Dist: identify (==2.5.29)
Requires-Dist: idna (==3.7)
Requires-Dist: importlib-metadata (==6.8.0)
Requires-Dist: iniconfig (==2.0.0)
Requires-Dist: ipython (==8.16.1)
Requires-Dist: isort (==5.12.0)
Requires-Dist: jedi (==0.19.1)
Requires-Dist: jinja2 (==3.1.4)
Requires-Dist: jsonpickle (==3.0.2)
Requires-Dist: kiwisolver (==1.4.5)
Requires-Dist: lazy-object-proxy (==1.9.0)
Requires-Dist: levenshtein (==0.23.0)
Requires-Dist: markdown-it-py (==3.0.0)
Requires-Dist: markupsafe (==2.1.3)
Requires-Dist: matplotlib (==3.8.0)
Requires-Dist: matplotlib-inline (==0.1.6)
Requires-Dist: mccabe (==0.7.0)
Requires-Dist: mdurl (==0.1.2)
Requires-Dist: multidict (==6.0.5)
Requires-Dist: mypy-extensions (==1.0.0)
Requires-Dist: networkx (==3.1)
Requires-Dist: nodeenv (==1.8.0)
Requires-Dist: num2words (==0.5.12)
Requires-Dist: numpy (==1.26.0)
Requires-Dist: packaging (==23.1)
Requires-Dist: parso (==0.8.3)
Requires-Dist: pathspec (==0.11.2)
Requires-Dist: pexpect (==4.8.0)
Requires-Dist: pickleshare (==0.7.5)
Requires-Dist: pillow (==10.3.0)
Requires-Dist: pip-upgrader (==1.4.15)
Requires-Dist: platformdirs (==3.10.0)
Requires-Dist: pluggy (==1.3.0)
Requires-Dist: pre-commit (==3.4.0)
Requires-Dist: prompt-toolkit (==3.0.39)
Requires-Dist: ptyprocess (==0.7.0)
Requires-Dist: pure-eval (==0.2.2)
Requires-Dist: pycares (==4.4.0)
Requires-Dist: pycodestyle (==2.11.0)
Requires-Dist: pycparser (==2.22)
Requires-Dist: pyflakes (==3.1.0)
Requires-Dist: pygments (==2.16.1)
Requires-Dist: pylint (==2.17.6)
Requires-Dist: pyparsing (==3.1.1)
Requires-Dist: python-dateutil (==2.8.2)
Requires-Dist: python-levenshtein (==0.23.0)
Requires-Dist: pyyaml (==6.0.1)
Requires-Dist: rapidfuzz (==3.4.0)
Requires-Dist: requests (==2.32.2)
Requires-Dist: rich (==13.7.1)
Requires-Dist: setuptools (==69.2.0)
Requires-Dist: six (==1.16.0)
Requires-Dist: stack-data (==0.6.3)
Requires-Dist: terminaltables (==3.1.10)
Requires-Dist: tomli (==2.0.1)
Requires-Dist: tomlkit (==0.12.1)
Requires-Dist: traitlets (==5.11.2)
Requires-Dist: typed-ast (==1.5.5)
Requires-Dist: typing-extensions (==4.8.0)
Requires-Dist: urllib3 (==2.2.2)
Requires-Dist: virtualenv (==20.24.5)
Requires-Dist: wcwidth (==0.2.8)
Requires-Dist: wrapt (==1.15.0)
Requires-Dist: yarl (==1.9.4)
Requires-Dist: zipp (==3.19.1)
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/omar2535/GraphQLer/main/docs/images/logo.png" />
  <p align="center">The <strong>only</strong> dependency-aware GraphQL API testing tool!</p>
</p>

<p align="center">
<a href="https://hub.docker.com/repository/docker/omar2535/graphqler"><img src="https://img.shields.io/docker/image-size/omar2535/graphqler/latest?style=flat&logo=docker"></a>
<a href="https://pypi.org/project/GraphQLer/"><img src="https://img.shields.io/pypi/v/GraphQLer?style=flat&logo=pypi"/></a>
<a href="https://www.python.org/downloads/" target="_blank"><img src="https://img.shields.io/badge/python-3.12-blue" alt="python3.12"/></a>
<a href="https://codeclimate.com/github/omar2535/GraphQLer/maintainability" target="_blank"><img src="https://api.codeclimate.com/v1/badges/a34db44e691904955ded/maintainability" alt="Maintainability" /></a>
<a href="https://github.com/omar2535/GraphQLer/actions/workflows/lint.yml" target="_blank"><img src="https://github.com/omar2535/GraphQLer/actions/workflows/lint.yml/badge.svg" alt="lint" /></a>
<a href="https://github.com/omar2535/GraphQLer/actions/workflows/tests.yml" target="_blank"><img src="https://github.com/omar2535/GraphQLer/actions/workflows/tests.yml/badge.svg?branch=main" alt="tests_status" /></a>
<a href="https://sonarcloud.io/summary/new_code?id=omar2535_GraphQLer" target="_blank"><img src="https://sonarcloud.io/api/project_badges/measure?project=omar2535_GraphQLer&metric=security_rating" alt="security" /></a>
<!-- <a href="https://codeclimate.com/github/omar2535/GraphQLer/test_coverage" target="_blank"><img src="https://api.codeclimate.com/v1/badges/a34db44e691904955ded/test_coverage" alt="coverage" /></a> -->
</p>

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](https://github.com/omar2535/GraphQLer/raw/main/docs/demo.gif)

## 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](https://pypi.org/project/GraphQLer/):

```sh
pip install GraphQLer
python -m graphqler --help
```

or [docker](https://hub.docker.com/repository/docker/omar2535/graphqler/general):

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

For a more in-depth guide, check out the [installation guide](./docs/installation.md).

## Usage

```sh
❯ python -m graphqler --help
usage: __main__.py [-h] --url URL --path PATH [--config CONFIG] --mode {compile,fuzz,idor,run} [--auth AUTH] [--proxy PROXY] [--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'
  --proxy PROXY         proxy to use for requests (ie. http://127.0.0.1:8080)
  --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

```sh
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

```sh
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

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

The [insecure direct object reference (IDOR)](https://portswigger.net/web-security/access-control/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

```sh
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 |
| DEBUG | Debug mode | Boolean | False |
| Custom Headers| Custom headers to be sent along with each request | Object | `Accept = "application/json"` |

