Guide · Agent skill
How to use the Offensive GraphQL Testing agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The offensive-graphql skill is a security testing playbook that you add to an AI agent, such as Claude, so the agent can work through a GraphQL API assessment step by step. It covers endpoint discovery, schema reconstruction, authorization checks, injection, batching, denial-of-service checks, subscriptions and file uploads, and suggests tools such as graphql-cop, InQL and clairvoyance. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what to check before you use it.
Offensive GraphQL TestingSnailSploit/Claude-Red · MIT Download the skill Quick start
- 1Download the ZIP. Download the offensive-graphql ZIP from this page. It contains the SKILL.md file that defines the skill.
- 2Unzip into a skills folder. Unzip the package so the offensive-graphql folder sits in ~/.claude/skills/ for a personal install or in .claude/skills/ inside a project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- 4Install the tools you need. Install Python 3 and the tools you plan to use, such as graphql-cop, clairvoyance, InQL or BatchQL. The skill references these but does not install them.
- 5Confirm your scope. Make sure you have written permission for the target and, for authorization tests, authorised test accounts.
- 6Ask for a phase. Start a new session and describe the task, for example asking for endpoint discovery on a named target within your scope.
- 7Work through the phases. Follow the agent's phase-by-phase plan, running each suggested request and recording the results for your report.
What the offensive-graphql skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's triggers. This skill gives the agent a structured methodology for attacking GraphQL APIs during penetration tests and bug bounty engagements.
The methodology follows the full attack lifecycle: endpoint discovery, introspection abuse and blind schema reconstruction when introspection is disabled, authentication and authorization bypass through Relay node IDs and nested object traversal, injection via variables and directives, query batching, denial of service through depth and alias abuse, WebSocket subscription abuse, information disclosure through verbose errors and field suggestions, and file upload abuse via the multipart GraphQL specification.
- Walks the agent through each phase with concrete queries and suggested tools
- Covers InQL, graphql-cop, CrackQL, BatchQL, Altair, GraphQL Voyager and clairvoyance
- Acts as a methodology, not an attack tool: the agent suggests and explains, and you run the tools
How to install the offensive-graphql skill
Download the ZIP for the skill from this page. The skill package contains SKILL.md. Unzip it so the skill folder sits in one of the locations below, then start a new agent session so it is picked up.
For a personal install, put the folder in ~/.claude/skills/. For a single project, put it in the project's .claude/skills/ folder. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/offensive-graphql/
- Project install: .claude/skills/offensive-graphql/ inside your project
- App install: Settings → Capabilities → Skills, then upload the skill
How to trigger the skill with natural requests
You do not need to name the skill. The agent loads it when your request matches its trigger terms. Describe the task in plain words and include the target and your scope. Terms that trigger the skill include GraphQL, introspection query, batching attack, GraphQL IDOR, field suggestion, graphql-cop, InQL, CrackQL, BatchQL, Relay node, alias amplification, subscription abuse, multipart upload GraphQL, schema enumeration, __schema and __type.
Good requests state the goal and the authorisation. For example, ask the agent to plan discovery for a GraphQL endpoint in a signed scope, or to check whether introspection is disabled and how to reconstruct the schema if it is.
- Plan discovery: "I'm authorised to test api.example.com. Help me find and fingerprint its GraphQL endpoint."
- Schema work: "Introspection looks disabled on this GraphQL API. What is the next step to rebuild the schema?"
- Authorization: "Using two test accounts, check whether the Order customer field leaks another user's data."
Example: a first GraphQL assessment
A typical first session starts with a light probe. The skill suggests sending a minimal __typename query to common paths such as /graphql, /graphiql and /api/graphql. A response containing __typename confirms a live GraphQL endpoint.
Next, the skill suggests running graphql-cop for a one-pass configuration audit. According to the skill, it reports introspection status, field suggestion leaks, GET-based query acceptance and unrestricted batching. If introspection is blocked, the skill points to clairvoyance, which builds a schema from field suggestions using a wordlist.
python3 graphql-cop.py -t https://target.com/graphqlWhat you need before you start
The skill needs Python 3 for graphw00f, graphql-cop and clairvoyance. Other tools it references, including InQL, Burp Suite, GraphQL Voyager, Altair, CrackQL and BatchQL, are installed separately. The skill does not install them for you.
If you test authorization, you need authorised test accounts for the target, such as a low-privilege account and a second account to check cross-user access. Without written permission for the system, do not use the skill against it.
- Python 3 for graphw00f, graphql-cop and clairvoyance
- Burp Suite, InQL, GraphQL Voyager, Altair, CrackQL and BatchQL, installed separately
- Authorised test accounts, if you are testing authorization
- A signed scope or bug bounty programme that allows GraphQL testing
Safety notes: scripts and network access
The skill itself does not run scripts. It uses the network, though, because the methodology sends requests to the target GraphQL endpoint. Its content describes active exploitation, so the agent's suggested requests can cause harm or service disruption if run against systems you are not allowed to test.
Keep depth, alias and batching tests within your scope and agreed rate limits. Treat denial-of-service checks with particular care, since the skill covers depth bombs and alias amplification.
- Scripts: none bundled with the skill; the tools you install separately are the ones that execute code
- Network: yes, requests go to the target you name
- Only test systems you own or have written permission to assess
Tips for better results
Give the agent the endpoint, the scope and what you already know, such as whether introspection is enabled. The skill is organised by phase, so telling the agent which phase you are on keeps its output focused.
Ask for proof-of-concept queries alongside findings, and keep notes of each request and response so the findings are reproducible for a report.
- State the phase you are in: discovery, schema, authorization, batching and so on
- Provide two test accounts when checking access control
- Ask the agent to explain why each query is useful before you run it
What people use it for
- Planning endpoint discovery and fingerprinting for a GraphQL API in a signed penetration test
- Checking whether introspection is disabled and rebuilding the schema with clairvoyance
- Testing whether nested fields in a GraphQL API return data belonging to other users
- Learning how GraphQL misconfigurations are found and exploited as a security student
Frequently asked questions
How do I install the offensive-graphql agent skill?
Download the ZIP from this page and unzip it so the offensive-graphql folder is in ~/.claude/skills/ for a personal install or in a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
Is the offensive-graphql skill free to use?
The skill is published under the MIT licence. The tools it references, such as InQL, Burp Suite and graphql-cop, are installed separately and have their own licences.
What do I need to run this GraphQL security skill?
You need Python 3 for graphw00f, graphql-cop and clairvoyance, plus the other tools you choose to use, installed separately. If you test authorization, you also need authorised test accounts for the target.
Does the skill run scripts on my computer?
No, the skill does not run scripts itself. It does use the network, because the requests it describes are sent to the GraphQL endpoint you name.
Can I use this skill on any website?
No. The skill is for penetration tests and bug bounty engagements, and it describes active exploitation. Only test systems you own or have written permission to assess.
How does this compare with graphql-cop or Burp Suite on their own?
The skill is a methodology for an AI agent, not a scanner. It suggests and explains tools such as graphql-cop, InQL and clairvoyance and the order to use them in, while the tools themselves do the testing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits penetration testers working under a signed scope, bug bounty hunters on programmes that allow GraphQL testing, and security students learning how GraphQL misconfigurations are found. It is not suited to testing systems without permission, and developers who want only a hardening checklist should choose a defensive guide, since this one is written from an attacker's perspective.
Download the skill