Webapp API Reference¶

The Pentest Manager webapp provides both a web interface and REST APIs for managing pentests, users, and integrations.

Authentication¶

Session-Based (Web UI)¶

Used by the web interface with CSRF protection and optional MFA.

API Key Authentication¶

For programmatic access, include your API key in the header:

curl -H "X-API-Key: your-api-key" https://127.0.0.1:8000/api/...

Master API Authentication¶

Internal n8n integration requires both keys:

curl -H "X-API-Key: your-api-key" \
     -H "X-Master-Key: master-key" \
     https://127.0.0.1:8000/api/...

API Endpoints¶

User & Authentication¶

Method	Endpoint	Auth	Description
`POST`	`/login`	None	User login
`GET`	`/logout`	Session	User logout
`GET/POST`	`/mfa/setup`	Session	Configure TOTP MFA
`GET/POST`	`/mfa/verify`	Session	Verify TOTP code
`GET/POST`	`/change-password`	Session	Change password
`GET`	`/api/user/mfa-status`	Session	Get MFA status

Pentests¶

Method	Endpoint	Auth	Description
`GET`	`/pentests`	Session	List all pentests
`GET/POST`	`/pentest/new`	Session	Create new pentest
`GET`	`/pentest/<id>`	Session	View pentest details
`POST`	`/pentest/<id>/start`	Session	Start pentest execution
`POST`	`/pentest/<id>/pause`	Session	Pause running pentest
`POST`	`/pentest/<id>/continue`	Session	Resume paused pentest
`POST`	`/pentest/<id>/cancel`	Session	Cancel pentest
`POST`	`/pentest/<id>/delete`	Session	Delete pentest
`POST`	`/pentest/<id>/generate-report`	Session	Generate PDF report
`GET`	`/pentest/<id>/download`	Session	Download pentest data
`POST`	`/pentest/<id>/share`	Session	Share with another user

Vulnerabilities¶

Method	Endpoint	Auth	Description
`GET`	`/api/vulnerability/<id>`	Session	Get vulnerability details
`PUT`	`/api/vulnerability/<id>/update`	Session	Update vulnerability
`GET`	`/pentest/<id>/vulnerabilities/download`	Session	Download as CSV

Real-Time Updates (SSE)¶

Method	Endpoint	Auth	Description
`GET`	`/api/pentests/<id>/execution-updates`	Session	Execution status stream
`GET`	`/api/pentests/<id>/vulnerability-updates`	Session	New vulnerability stream

n8n Integration (Master API)¶

Method	Endpoint	Auth	Description
`POST`	`/api/validate`	Master	Validate API keys
`POST`	`/api/command/<id>`	Master	Submit command results
`POST`	`/api/command/approve/<id>`	Master	Request command approval
`POST`	`/api/command/approve/<id>/process`	Master	Process approval
`GET`	`/api/command/status/<approval_id>`	Master	Check approval status
`POST`	`/api/vulnerability/<id>`	Master	Submit vulnerability
`POST`	`/api/update/<id>`	Master	Update pentest status
`POST`	`/api/report/<id>/pdf-ready`	Master	Notify PDF ready
`POST`	`/api/pentests/<id>/vulnerabilities`	Master	Bulk import vulnerabilities

Ollama Connections¶

Method	Endpoint	Auth	Description
`POST`	`/profile/ollama/add`	Session	Add Ollama connection
`POST`	`/profile/ollama/<id>/delete`	Session	Delete connection
`POST`	`/profile/ollama/<id>/share`	Session	Share connection
`GET`	`/api/ollama/<id>/models`	API Key	List available models
`GET`	`/api/ollama/<id>/details`	API Key	Get connection details
`GET`	`/api/ollama/<id>/status`	API Key	Check Ollama status

Agents¶

Method	Endpoint	Auth	Description
`GET`	`/agents`	Session	List agents
`GET/POST`	`/agents/new`	Session	Create agent
`GET`	`/agents/<id>/view`	Session	View agent
`GET/POST`	`/agents/<id>/edit`	Session	Edit agent
`POST`	`/agents/<id>/delete`	Session	Delete agent
`GET`	`/api/agents`	API Key	List agents (JSON)
`POST`	`/agents/export`	Session	Export as template
`POST`	`/agents/import`	Session	Import template

Templates¶

Method	Endpoint	Auth	Description
`GET`	`/templates`	Session	List templates
`GET/POST`	`/templates/new`	Session	Create template
`GET/POST`	`/templates/<id>/edit`	Session	Edit template
`POST`	`/templates/<id>/delete`	Session	Delete template
`GET`	`/api/templates/<id>`	API Key	Get template JSON

Retests¶

Method	Endpoint	Auth	Description
`GET`	`/retests`	Session	List retests
`GET/POST`	`/retest/new`	Session	Create retest
`GET`	`/retest/<id>`	Session	View retest
`POST`	`/retest/<id>/start`	Session	Start retest
`POST`	`/retest/<id>/import-vulnerabilities`	Session	Import from pentest
`POST`	`/retest/create-from-pentest`	Session	Create from pentest

Teams¶

Method	Endpoint	Auth	Description
`GET`	`/teams`	Session	List teams
`GET/POST`	`/teams/new`	Session	Create team
`GET`	`/teams/<id>`	Session	Team details
`POST`	`/teams/<id>/invite`	Session	Invite user
`POST`	`/teams/invitations/<id>/<action>`	Session	Accept/decline
`POST`	`/teams/<id>/leave`	Session	Leave team

Admin¶

Method	Endpoint	Auth	Description
`GET`	`/admin`	Admin	Admin dashboard
`GET`	`/users`	Admin	User management
`GET/POST`	`/users/new`	Admin	Create user
`POST`	`/admin/reset-password`	Admin	Force password reset
`POST`	`/admin/reset-mfa`	Admin	Reset user MFA
`GET/POST`	`/settings`	Admin	Global settings

Queue¶

Method	Endpoint	Auth	Description
`GET`	`/queue`	Session	View execution queue

Request/Response Examples¶

Start a Pentest¶

curl -X POST https://127.0.0.1:8000/pentest/abc123/start \
  -H "Cookie: session=..." \
  -H "X-CSRFToken: ..."

Get Vulnerability Details¶

curl https://127.0.0.1:8000/api/vulnerability/42 \
  -H "Cookie: session=..."

Response:

{
  "id": 42,
  "pentest_id": "abc123-def456",
  "title": "SQL Injection in Login Form",
  "severity": "Critical",
  "cvss_score": 9.8,
  "description": "...",
  "impact": "...",
  "remediation": "...",
  "discovered_at": "2024-01-15T10:30:00Z"
}

Submit Command (n8n Integration)¶

curl -X POST https://127.0.0.1:8000/api/command/abc123 \
  -H "X-API-Key: user-api-key" \
  -H "X-Master-Key: master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "nmap -sV target.com",
    "output": "PORT   STATE SERVICE\n22/tcp open  ssh\n80/tcp open  http",
    "exit_code": 0
  }'

List Ollama Models¶

curl https://127.0.0.1:8000/api/ollama/conn-id/models \
  -H "X-API-Key: your-api-key"

Response:

{
  "models": [
    {"name": "qwen3:14b", "size": "8.5GB"},
    {"name": "llama3:8b", "size": "4.7GB"}
  ]
}

Error Responses¶

Status	Description
`400`	Bad request / validation error
`401`	Unauthorized (invalid/missing credentials)
`403`	Forbidden (insufficient permissions)
`404`	Resource not found
`429`	Rate limited (too many requests)
`500`	Internal server error

Rate Limiting¶

Login attempts are rate limited: - 5 failed attempts → 15 minute lockout - Applies per username - MFA attempts tracked separately

Security Headers¶

All responses include:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000
Content-Security-Policy: default-src 'self'; script-src 'self'