" %}
Fuzz GraphQL APIs to find names and build a schema
{% endembed %}
$ clairvoyance --help
usage: clairvoyance [-h] [-v] [-i <file>] [-o <file>] [-d <string>] [-H <header>] [-c <int>] [-w <file>] [-wv] [-x <string>] [-k]
[-m <int>] [-b <int>] [-p {slow,fast}] [--progress]
url
positional arguments:
url
options:
-h, --help show this help message and exit
-v, --verbose
-i <file>, --input-schema <file>
Input file containing JSON schema which will be supplemented with obtained information
-o <file>, --output <file>
Output file containing JSON schema (default to stdout)
-d <string>, --document <string>
Start with this document (default query { FUZZ })
-H <header>, --header <header>
-c <int>, --concurrent-requests <int>
Number of concurrent requests to send to the server
-w <file>, --wordlist <file>
This wordlist will be used for all brute force effots (fields, arguments and so on)
-wv, --validate Validate the wordlist items match name Regex
-x <string>, --proxy <string>
Define a proxy to use for all requests. For more info, read
https://docs.aiohttp.org/en/stable/client_advanced.html?highlight=proxy
-k, --no-ssl Disable SSL verification
-m <int>, --max-retries <int>
How many retries should be made when a request fails
-b <int>, --backoff <int>
Exponential backoff factor. Delay will be calculated as: `0.5 * backoff**retries` seconds.
-p {slow,fast}, --profile {slow,fast}
Select a speed profile. fast mod will set lot of workers to provide you quick result but if the server as
some rate limit you may want to use slow mod.
--progress Enable progress bar
After running the tool and receiving an output `schema.json` file, you can upload this to *GraphiQL Explorer* together with your endpoint to receive auto-completion and view the schema while querying.
For better results, it is recommended to create a **custom wordlist** from as much information as you can find from your target. This can be as simple as running a `\w+` regex over the text to find and extract all unique words that may potentially be query names or fields. Use the `-w` option to provide it to clairvoyance.
Note that while looking at the target's JavaScript files, you can already often find some GraphQL queries stored in there as it is always the browser that requests them. Search for keywords like `query` or `mutation` .
## Features
The basic concepts of GraphQL are explained in the tutorial below:
{% embed url="" %}
Explaining how the GraphQL concepts relate to each other
{% endembed %}
In summary, you have [*types* with *fields*](https://graphql.org/learn/schema/). You can [*query*](https://graphql.org/learn/queries/) these types for exactly the fields that you require, or call specific *mutations* that have server-side logic implemented for them.
### Arguments & Variables
Fields can also have arguments, these are common for filtering results. In your query you fill in these arguments with values.
Queries can also contain arguments, and you can leave these generic to fill them with a separate `variables` parameter. In a request, this looks like:
{% code title="Query with $name variable" %}
```graphql
query ExampleQuery($name: String!) {
someQuery(arg: $name) {
id
}
}
```
{% endcode %}
POST /graphql HTTP/2
Host: example.com
Content-Type: application/json
{"query":"query ExampleQuery(...", "variables": {"name": "value"}}
This is a common pattern for applications because the query can be cached, but only the variable data is unique.
### Mutations
The server can implement functions to handle changes in data, which you can call from GraphQL. These [mutations](https://graphql.org/learn/mutations/) often also use variables as explained above, and have a very similar structure to queries:
{% code title="Mutation with $name variable" %}
```graphql
mutation ExampleMutation($name: String!) {
createUser(name: $name) {
id
name
}
}
```
{% endcode %}
{% code title="Request" %}
```http
POST /graphql HTTP/2
Host: example.com
Content-Type: application/json
{"query":"mutation ExampleMutation(...", "variables": {"name": "value"}}
```
{% endcode %}
The variables will be substituted in the query and the server will perform whatever logic it has implemented. The fields `id` and `name` specified inside the function call will be returned after it is done.
You can run multiple mutations in series by providing multiple [*aliases*](https://graphql.org/learn/queries/#aliases) for different functions calls:
{% code title="Multiple mutations" %}
```graphql
mutation {
firstUser: deleteUser(id: "42")
secondUser: deleteUser(id: "1337")
}
```
{% endcode %}
More information about the HTTP requirements for a standard server endpoint can be found in the documentation below:
{% embed url="" %}
Specification on how servers should behave over HTTP
{% endembed %}
### WebSockets
Instead of HTTP, there is also a common library that adds communication via WebSockets:
{% embed url="" %}
The structure and handlers of this are slightly different from the regular HTTP API, so you may see different behavior like one allowing introspection while the other does not.
The [WebSocket protocol](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) is very similar, apart from some protocol changes, queries are the exact same. Below is an example *client* that queries another server over WebSockets:
```html
```
## Attacks
### Data Leak & IDOR
One common mistake in GraphQL is accidentally exposing too many properties. \
**You should enumerate all fields for every object in every query**. Developers may unintentionally expose properties that should be internal, like a password hash, reset token or 2FA secret.
You can use [#introspection](#introspection "mention") to get an exhaustive list, or fuzz with [#guessing-schema-with-hints](#guessing-schema-with-hints "mention").
Your own user and another user are two very different types. You should be able to see almost all properties of your user, but only a few minimal ones of other users. A naive implementation may just return all properties for all users, potentially exposing too much information if you can get a reference to another user.
Additionally, protections may be set on certain *queries* rather than *fields*. This has the effect that maybe directly requesting something you are not authorized to won't work, but if you indirectly access the field through some other reference it may still be allowed.
This combines well with Insecure Direct Object Reference (IDOR) vulnerabilities if you need to specify an identifier of some kind in a query/mutation argument.
Lastly, it is good to know that a **mutation returns data**. This is often the object you mutated, but may also expose too many properties. The following syntax gets properties of the result of a mutation:
{% code title="Return data from mutation" %}
```graphql
mutation {
sendMessage(user_id: 1337, message: "Hi!") {
user {
password_hash
}
}
}
```
{% endcode %}
### Batching
In a single GraphQL request, you can send multiple queries and/or mutations. If they have the same name, you can differentiate them using an *alias* which is a `name:` prefix. This can be useful for bypassing per-request rate limiting because a single request may contain many actions.\
Below is an example for brute-forcing a login form, only the alias that was successful will return a valid token in the response:
{% code title="Batch with aliases" %}
```graphql
mutation {
a: login(username: "admin", password: "admin")
b: login(username: "admin", password: "123456")
c: login(username: "admin", password: "password")
}
```
{% endcode %}
### CSRF
[cross-site-request-forgery-csrf](https://book.jorianwoltjer.com/web/client-side/cross-site-request-forgery-csrf "mention") is a technique where you send a request from an attacker's site straight to the target site, which will be automatically authenticated by the browser adding cookies.
Because GraphQL mutations happen via a simple POST request to a `/graphql` endpoint, implementations of it may also be vulnerable. It is crucial to check if **only cookies provide authentication**, no need for headers. And if so, check the `SameSite=` attribute of the cookie. See the dedicated CSRF page for details on what cases are exploitable and how.
By default, the query and variables are sent with a `Content-Type: application/json` header. This is not directly allowed to be set in a cross-origin request, and the browser will first send a *Preflight* request. If the response to this OPTIONS request says that it may use the JSON content type, only then will the real `fetch()` request you set up be sent.\
There are ways around this by confusing the content type reader, especially if `SameSite=None` or empty by providing alternative headers and a cleverly set up body.
GraphQL also uses a POST request which causes `SameSite=Lax` cookies not to be sent, even in a top-level form navigation. It may however be possible to change the method to GET and write the `query` parameter in the URL, such as:
```url
GET /graphql?query=mutation%20{...
```
#### WebSocket Hijacking
If the server uses [#websockets](#websockets "mention") and only requires `SameSite=None` or empty cookies to authenticate, you can connect with it cross-site. The best thing is that CORS doesn't apply here, you can always **read the response**!
Note that if cookies are `SameSite=Strict`, they will still be sent from subdomains, an XSS or takeover would be enough to compromise the main site in such a case.
All you have to do is connect with the WebSocket, send it a query that will be authenticated as the signed-in victim, and then read the response ([more info](https://portswigger.net/web-security/websockets/cross-site-websocket-hijacking)).
#### XS-Search via Timing
If you are able to perform CSRF, but there aren't any interesting mutations, you may still get lucky if there are **queries that search private data**. These are inherently vulnerable to a [XS-Leaks](https://xsleaks.dev/docs/attacks/xs-search/) where you send a request from the attacker's site using `fetch()`, and then measure the time it took to resolve the request. The timing can be amplified by [#batching](#batching "mention") to slowly leak the data matched by a search query in GraphQL.