Documentation

Penetra operator guide

How a run flows from click to report, which services you're running, and the endpoints you can hit directly.

Services you're running

Three FastAPI services back the dashboard. Each ships with an interactive Swagger UI at /docs — click through to inspect request/response schemas and try calls inline.

Agents API

Starts attack runs and reports their coarse status. POST /v1/attacks kicks off one run; the response's attack_run_id routes the operator into the live console.

Open Agents API /docs →
override via NEXT_PUBLIC_AGENTS_API_BASE_URL

Reporting API

Owns traces, ingest, reports, analytics, and the SSE stream that feeds the live dashboard. /docs lists every endpoint with its request/response schema.

Open Reporting API /docs →
override via NEXT_PUBLIC_REPORTING_API_BASE_URL

Sandbox Service

Spawns and tears down per-run isolated workspaces (via Daytona in prod, in-memory in dev). Proxies agent HTTP calls to the actual target.

Open Sandbox Service /docs →

User flow

  1. 1

    Operator clicks Start

    Dashboard posts to Agents API /v1/attacks with the target URL + notes. Response includes a fresh attack_run_id; the browser navigates to /attack/{id}.

  2. 2

    Sandbox provisioned

    Agents service asks the Sandbox Client factory for a per-run client. In dev the client points straight at DEMO_TARGET_URL; in prod it spawns a Daytona workspace.

  3. 3

    Opus leader plans

    Claude Opus 4.7 receives the target descriptor + sandbox policy and decides the probing strategy (N agents, N focus areas). Every leader call is prompt-cached so phase 2+ is ~10× cheaper.

  4. 4

    Sonnet swarm attacks

    Claude Sonnet 4.6 probing agents map surfaces; attack agents exploit them. Both share a toolbox: HTTP proxy, prompt-injection payloads, Nmap/Nikto/SQLmap/Metasploit adapters.

  5. 5

    Live trace streams

    Every event (agent.spawned, surface.discovered, breach.recorded, vulnerability.found) flows over SSE to the dashboard. Gemini narrates the live sidebar in 1–2 sentence summaries.

  6. 6

    Opus writes the report

    At REPORTING phase the leader composes the natural-language summary + breach markers; vulnerabilities are enriched with risk scores and replication steps, then persisted on the Reporting API.

Common commands

Boot the stack
./scripts/demo.sh up

Starts Juice Shop + agents + reporting + frontend in one process group. Ctrl-C tears everything down.

Trigger a run via curl
curl -X POST http://localhost:8001/v1/attacks \
  -H 'content-type: application/json' \
  -d '{"display_name": "demo", "target_url": "https://your-authorized-target.example.com"}'

Same shape the dashboard POSTs. The run executes in the background; poll GET /v1/attacks/{id} or subscribe to the SSE feed for progress.

Tail the live event stream
curl -N http://localhost:8000/runs/<attack_run_id>/stream

SSE format: one event per newline-separated frame. Useful when debugging frontend rendering or confirming the backend emits the expected events.

Deeper reference

The PRD + implementation plan live in the repo root. The per-service Swagger pages above are always the source of truth for request/response shapes.

Open dashboard →