/api-testing

name: api-testing
description: |
  Activate this skill whenever the user mentions API endpoint, REST API, RESTful, GraphQL, GraphQL introspection,
  GraphQL mutation, gRPC, gRPC reflection, WebSocket, WebSocket upgrade, WS endpoint,
  API security, API fuzzing, API enumeration, API versioning, API gateway, API rate limit,
  JWT, JSON Web Token, bearer token, access token, refresh token, API key, OAuth, OAuth2,
  OIDC, OpenID Connect, PKCE, authorization code, client credentials, implicit grant,
  BOLA, broken object level authorization, BFLA, broken function level authorization,
  mass assignment, parameter pollution, parameter tampering, parameter discovery,
  IDOR, insecure direct object reference, horizontal privilege escalation, vertical privilege escalation,
  authorization bypass, auth bypass, authentication bypass, token manipulation,
  content-type confusion, type confusion, deserialization, API injection,
  rate limiting, rate limit bypass, race condition, TOCTOU,
  Swagger, OpenAPI, API documentation, API specification, WSDL, WADL,
  API enumeration, endpoint discovery, hidden endpoints, undocumented API,
  GraphQL batching, query depth, nested query, introspection query,
  API gateway bypass, WAF bypass API, API fingerprinting,
  CORS misconfiguration, CORS bypass, origin header,
  HTTP method override, verb tampering, content negotiation,
  API key leakage, bearer token theft, token replay,
  server-sent events, SSE, long polling, streaming API,
  gRPC-web, protobuf, protocol buffers, service definition,
  arjun, x8, paramspider, postman, insomnia, burp repeater, burp intruder,
  comprehensive API audit, API pentest, API attack surface,
  or discusses testing API security, API hacking, API exploitation, or API reconnaissance.
version: 2.0.0

API Security Testing

API testing is the most target-rich domain in modern application security. REST, GraphQL, gRPC, and WebSocket interfaces expose business logic directly, often with weaker controls than their web UI counterparts. This skill covers the full API attack lifecycle -- from endpoint discovery and authentication analysis through injection, authorization abuse, business logic exploitation, and rate limit bypass.

Attack Surface Decision Tree

Before diving into testing, classify the API type and prioritize your approach.

Is there API documentation (Swagger/OpenAPI/GraphQL introspection)?
├── YES → Start with documented endpoints, then hunt for undocumented ones
│   ├── REST with OpenAPI → Parse spec, test every endpoint/method/parameter
│   ├── GraphQL with introspection → Dump schema, map all queries/mutations/subscriptions
│   └── gRPC with reflection → List services, extract .proto definitions
└── NO → Start with endpoint discovery and fingerprinting
    ├── Known web app → Spider + JS analysis + API path brute-force
    ├── Mobile app → Decompile APK/IPA, extract API calls and endpoints
    └── Unknown target → Port scan + service fingerprint + path fuzzing

What authentication mechanism is used?
├── JWT → jwt-attacks.md (alg:none, key confusion, claim manipulation)
├── OAuth2/OIDC → oauth-attacks.md (PKCE bypass, token theft, redirect manipulation)
├── API Key → Test key scope, rotation, leakage in logs/responses/JS
├── Session cookie → Standard session attacks (fixation, prediction, theft)
├── mTLS → Certificate validation bypass, weak CA trust
└── None / Optional → Test if auth is truly enforced on all endpoints

What is the primary risk?
├── Data exposure → Focus on BOLA/IDOR, mass data retrieval, excessive data exposure
├── Privilege escalation → Focus on auth bypass, BFLA, role manipulation
├── Injection → Focus on SQLi, NoSQLi, command injection, SSTI through API params
├── Business logic → Focus on race conditions, mass assignment, workflow bypass
└── Availability → Focus on rate limiting, GraphQL DoS, resource exhaustion

Methodology

Follow this sequence for systematic API assessment. Each phase feeds the next.

Phase 1 — Reconnaissance and Endpoint Discovery

Map the entire API attack surface before testing anything.

# Discover API endpoints — load Hexstrike tools
# ToolSearch → select:mcp__hexstrike-ai__comprehensive_api_audit

# Parameter discovery on known endpoints
# ToolSearch → select:mcp__hexstrike-ai__arjun_parameter_discovery
# ToolSearch → select:mcp__hexstrike-ai__x8_parameter_discovery
# ToolSearch → select:mcp__hexstrike-ai__paramspider_mining

# Record discovered endpoints
node ${CLAUDE_PLUGIN_ROOT}/scripts/target-intel.js add <target> endpoint "/api/v1/users" --source "api-enum"
node ${CLAUDE_PLUGIN_ROOT}/scripts/target-intel.js add <target> tech-stack "framework:express" --source "fingerprint"

Key actions: 1. Parse OpenAPI/Swagger specs if available (`/swagger.json`, `/api-docs`, `/openapi.yaml`, `/v2/api-docs`, `/v3/api-docs`) 2. Fuzz common API base paths: `/api/`, `/api/v1/`, `/api/v2/`, `/rest/`, `/graphql`, `/gql`, `/grpc` 3. Extract endpoints from JavaScript bundles, mobile apps, documentation 4. Test for API versioning — try `/api/v0/`, `/api/v1/`, `/api/v2/`, `/api/v3/`, `/api/internal/`, `/api/admin/`, `/api/debug/` 5. Check for GraphQL at `/graphql`, `/gql`, `/api/graphql`, `/graphql/console`, `/graphiql` 6. Check for gRPC reflection with `grpcurl`

See `references/api-enumeration.md` for comprehensive endpoint discovery techniques.

Phase 2 — Authentication Analysis

Test the authentication layer before anything else. A broken auth mechanism gives you access to everything.

# JWT analysis
# ToolSearch → select:mcp__hexstrike-ai__jwt_analyzer

# OAuth flow analysis
# ToolSearch → select:mcp__hexstrike-ai__bugbounty_authentication_bypass_testing

# Log auth-related findings
node ${CLAUDE_PLUGIN_ROOT}/scripts/findings-tracker.js add "/api/auth/login" auth-bypass "jwt-alg" HIGH "JWT algorithm none accepted"

Test sequence: 1. **Token analysis**: Decode JWTs, inspect session tokens, check API key formats 2. **Algorithm attacks**: a