TapWire

API pen testing agent. Browse normally in Chrome while TapWire captures every API request. Then use the pentest CLI (or point an AI agent at it) to inspect, probe, and exploit endpoints.

---

Setup

1. Install dependencies

cd /path/to/tapwire
npm install

2. Register the CLI globally

npm link

This makes pentest available as a shell command.

3. Start the local server

npm start

Runs on http://localhost:3000. Leave this running in the background.

4. Load the Chrome extension

1. Open Chrome → chrome://extensions
2. Enable Developer mode (top right)
3. Click Load unpacked
4. Select the chrome-extension/ folder

The TapWire icon will appear in the toolbar. It's active immediately.

---

Usage

Check current mode

cat .pentest-config.json

• dry-run — inspect only, no request firing
• autonomous — fire requests freely

Change mode

pentest mode dry-run
pentest mode autonomous

List captured requests

pentest list
pentest list --method POST
pentest list --search "user|billing|plan|admin"

Returns a JSON array of lightweight pointers (no payloads).

Inspect a full request

pentest inspect <id>

Returns full details: headers, body, response, cookies, timing.

Fire a modified request

Only works in autonomous mode. Uses stored cookies from the original request.

pentest fire <id> --body '{"plan":"enterprise"}'
pentest fire <id> --header 'X-Role: admin'
pentest fire <id> --body '{"user_id":1}' --header 'X-Role: admin'

Save a working exploit

pentest save <id> \
  --description "Upgrades plan without payment by sending arbitrary plan name" \
  --result "Server accepted 'enterprise' plan, account upgraded without charge"

Writes a .js file to /exploits/ with a comment block, curl command, and async JS function.

---

Directory structure

tapwire/
  chrome-extension/
    manifest.json       MV3 extension manifest
    interceptor.js      Patches fetch/XHR — runs in page's MAIN world
    content.js          Tracks DOM interactions, relays to background — ISOLATED world
    background.js       Service worker, POSTs captured requests to localhost:3000
    popup.html          Toolbar icon popup
  node-app/
    index.js            Express server (npm start)
    db.js               Flat-file data store
    data/               One JSON file per captured request (created on first run)
    requests.log        Append-only JSON-lines pointer file
  cli/
    index.js            pentest CLI entrypoint
    commands/
      list.js           pentest list [--method] [--search]
      inspect.js        pentest inspect <id>
      fire.js           pentest fire <id> [--body] [--header]
      save.js           pentest save <id> --description --result
      mode.js           pentest mode dry-run|autonomous
  exploits/             Saved exploit .js files (gitignored)
  AGENT.md              AI agent instructions — give this to your agent to start
  .pentest-config.json  Current mode (gitignored)
  .gitignore

---

AI agent workflow

Point an AI agent (Claude Code, etc.) at this repo and tell it to read AGENT.md. The agent operates entirely through the pentest CLI.

# Agent reads mode
cat .pentest-config.json

# Agent scans for interesting endpoints
pentest list --search "user|billing|plan|credits|admin|role|upgrade|payment"

# Agent inspects a target
pentest inspect abc123

# Agent fires (autonomous mode only)
pentest fire abc123 --body '{"plan":"enterprise"}'

# Agent saves working exploit
pentest save abc123 --description "..." --result "..."

---

Notes

• requests.log is append-only JSON-lines — one object per line
• All CLI output is clean JSON — no color codes, parseable by AI agents
• Exploit filenames: METHOD_endpoint_path.js (e.g. POST_api_user_upgrade.js)
• The server only binds to 127.0.0.1 — not exposed to the network