GraphQL Voyager as a tool for API security testing

One of Google Image results on “voyager” query. Image source.

You are facing GraphQL API and want to test its security. But introspection query gives you huge unreadable JSON, web application uses only part of GraphQL API, and of course there is no public documentation. How to understand and test GraphQL API in such case?

Luckily there is the tool called GraphQL Voyager which visualises GraphQL schema. It’s especially useful for understanding GraphQL API and finding authorization vulnerabilities.

If you are new to GraphQL here are good starting points for learning it:

1. https://www.howtographql.com/ — takes interactive approach with practical tasks and milestones. Gets you from zero to your first GraphQL application.
2. https://graphql.org/learn/ — utilises documentation approach. Good to learn specific topics on GraphQL.
3. [upd 04.07.19] https://ctf.hacker101.com — HackerOne created two tasks for GraphQL. It’s a good place to give Voyager a try. Tasks named as BugDB v1 and BugDB v2.

Why use GraphQL Voyager?

First step in testing GraphQL API is understanding what it does. Usually there is no web page with documentation since GraphQL is self-documented by design. This means you can execute specially crafted introspection query to obtain GraphQL schema. Schema contains all public information about GraphQL API.

Unfortunately schema is usually returned as huge JSON thus it’s to understand API by reading it. A visual representation of the same schema is a completely different story. Better to see once than hear a hundred times:

JSON vs IMAGE

How to use

Use of Voyager is relatively straightforward. For example let’s get visual representation of SWAPI GraphQL:

Step 1. Obtain specially crafted introspection query:

• Go to https://apis.guru/graphql-voyager/.
• Click “Custom Schema”.
• Click “Copy Introspection Query”.

Step 2. Execute introspection query agains target GraphQL endpoint:

• Go to https://graphql.github.io/swapi-graphql.
• Paste introspection query into the request.
• Issue the request.

Step 3. Copy and paste obtained GraphQL schema to Voyager.

Step 2 may vary from target to target since GraphQL requests may be implemented differently but you’ve got a general idea.

Conclusion

GraphQL Voyager is great tool which helps you understand GraphQL APIs. It gives you a full picture of what you can do with GraphQL API.

But it can be further improved by adding a “diff” feature. The idea is that you can monitor changes in target’s GraphQL API and then visualise diff of this changes. This will help you to quickly reveal new functionality and understand changes in existing one.

I’ve created an issue for the diff feature on Voyager’s GitHub. You may contribute in its development by:

1. (easy way) Voting up on issue. So developers will prioritise it.
2. (hard way) Get your hands dirty and code this feature since GraphQL Voyager is open source project.