Agents API

Base URL: https://app.pentestas.com/api/agents. Requires authenticated user (JWT or API key) — not an agent key.

Create an agent

POST /api/agents
{
  "name": "corp-fra-01",
  "allowed_ips": ["203.0.113.5", "203.0.113.6"]
}

Response (agent key shown once — save it):

{
  "id": "uuid",
  "name": "corp-fra-01",
  "agent_key": "pa_AbC123…",
  "allowed_ips": ["203.0.113.5", "203.0.113.6"],
  "status": "pending",
  "install_command":        "curl -fsSL https://app.pentestas.com/agent/install.sh | sudo bash -s -- --key pa_AbC123…",
  "install_command_windows":"iwr -useb https://app.pentestas.com/agent/install.ps1 | iex; Install-PentestasAgent -Key pa_AbC123…"
}

List agents

GET /api/agents

Returns array with live connection state (connected: true/false), capabilities advertised at connect, hostname, OS, internal networks observed.

Update

PUT /api/agents/{agent_id}
{
  "allowed_ips": ["203.0.113.5"],
  "enabled": true
}

Setting enabled: false immediately disconnects the agent and refuses further connects until re-enabled.

Delete

DELETE /api/agents/{agent_id}

Cascade: disconnects the agent, purges the key, audit-logged.

Dispatch — web scan

POST /api/agents/{agent_id}/scan
{
  "target_url": "https://internal-admin.corp.local",
  "scan_types": ["web", "api"],
  "config": {...}   // same shape as /api/scans
}

The scan runs on the agent (so traffic originates inside your network). Findings stream back over the agent WebSocket; readable via /api/scans/{scan_id}/findings as usual.

Dispatch — network scan

POST /api/agents/{agent_id}/server-scan
{
  "targets": ["10.0.0.0/24", "fileserver.corp.local"],
  "config": {
    "ports": "common",
    "brute_force": false,
    "cve_check": true,
    "protocol_checks": true
  }
}

Dispatch — browser capture session

POST /api/agents/{agent_id}/browser-session
{
  "target_url": "https://app.example.com",
  "scope": ["example.com"],
  "browser_preference": ["chrome", "edge", "firefox"]
}

Used with the browser-launcher-capable agent (Linux + mitmproxy, or the .NET Windows agent). The agent opens a browser pointed at target_url; captured requests flow back as browser_request WebSocket frames.

Errors:

• 400 — agent lacks browser_launcher capability (check GET /api/agents for the agent's capabilities list).
• 502 — agent is not currently receiving frames (possibly just disconnected).

WebSocket (agent-side — not for HTTP clients)

WS /api/agents/ws/{agent_key}

Protocol documented in scanner/agent/protocol.py in the repo. Summary:

• Client → server: hello, heartbeat, pong, log, progress, finding, findings_batch, scan_complete, scan_failed, browser_session_*, browser_request.
• Server → client: welcome, ping, disconnect, scan, server_scan, browser_launch, finding_notify.

Users don't connect to this directly; it's used by installed agents. Reference the Linux agent and .NET agent docs for install.

See also

• Agents overview
• Authentication