traversal

REST API exploratory testing agent for Claude Code. Point it at an OpenAPI spec; it generates test cases using standard design techniques, fires the requests, and logs every finding as a reproducible curl command.

No runtime code. The whole thing is a set of .claude/agents/ skill files — Claude Code agents that use bash, curl, and JSON files to coordinate.

---

How it works

/orchestrator openapi.yaml https://api.example.com "Authorization: Bearer token"

1. Orchestrator parses the spec, groups endpoints by priority (writes first, then parameterized reads, then static reads), and spawns parallel Explorer agents — one per group.

2. Explorers run 4–7 test charters per endpoint using these techniques:

   • Boundary value analysis and equivalence partitioning on every parameter
   • Auth bypass: omit or corrupt the token, cross-user token swap
   • IDOR: use resource IDs discovered from earlier responses
   • Mass assignment: inject undocumented fields (role, is_admin, balance)
   • Injection: SQL, XSS, path traversal, null bytes
   • State machine: create → verify → update → delete → verify gone

3. Session memory (session-memory.json) accumulates resource IDs from POST responses so IDOR tests use real IDs and created resources can be cleaned up after.

4. Findings go into issues.md — each one has severity, observation, the exact curl command, request body, and response.

Architecture

orchestrator
  │
  ├─ parse spec
  ├─ write test-ledger.json + session-memory.json
  │
  └─ fork × N ──────────────────────────────────────┐
       explorer (group A)                            │
       explorer (group B)    ── shared state ──► test-ledger.json
       explorer (group C)                       session-memory.json
                                                issues.md

Explorers mark endpoints in_progress before starting — forks don't duplicate work. After all forks complete, the orchestrator calls /coverage-report.

Skills

Skill	Invoke	Purpose
orchestrator	/orchestrator <spec> [base_url] [auth]	Full run — parse, fork, report
explorer	spawned by orchestrator	Explores an endpoint group, logs issues
design-charters	/design-charters	Generate test charters for one endpoint
analyze-response	/analyze-response	Analyze a request/response pair
bootstrap-ledger	/bootstrap-ledger <spec> [base_url] [auth]	Initialize test-ledger.json without running
auth-probe	/auth-probe	Sweep all explored endpoints for auth issues
session	/session	View and edit session-memory.json
cleanup	/cleanup	Delete resources created during testing
replay-issue	/replay-issue <ISSUE-NNN>	Re-run an issue's curl and compare
coverage-report	/coverage-report	Summary from ledger + issues

State files

All written to the working directory (your project root).

test-ledger.json — coverage tracker. Endpoints move through unexplored → in_progress → explored. Stores charter history and issue counts per endpoint.

session-memory.json — session state. Auth header, user context, resource IDs extracted from POST responses (used for IDOR tests and cleanup).

issues.md — append-only issue log. Each entry has severity, endpoint, observation, curl, and response.

coverage-report.md — generated by /coverage-report. Summary table, issue breakdown, gaps list, recommendations.

Importing

Copy the skills into your project:

cp -r /path/to/traversal/.claude/agents/* .claude/agents/

Or via npm (once published):

npm install --save-dev @traversal/api-explorer

Then in .claude/settings.json:

{ "plugins": ["@traversal/api-explorer"] }

Requirements

• Claude Code with Bash, Read, Write, Edit, and Agent tools permitted
• curl in the shell
• python3 + pyyaml — only needed for YAML specs; JSON specs work without it
• The API must be reachable from the machine running Claude Code