Running the Server

What is Server Mode

Vigolium can run as a persistent REST API server, accepting traffic ingestion, scan triggers, and agent runs via HTTP endpoints. Server mode is useful for team workflows where multiple users share a scanning backend, CI/CD integration where automated pipelines submit traffic and retrieve findings, and building custom tooling on top of Vigolium’s API.

Starting the Server

# Start with an API key
export VIGOLIUM_API_KEY=my-secret-key
vigolium server

# Custom host and port
export VIGOLIUM_API_KEY=my-secret-key
vigolium server --host 127.0.0.1 --service-port 9002

# With an upstream proxy for outgoing scanner traffic
export VIGOLIUM_API_KEY=my-secret-key
vigolium server --proxy http://corporate-proxy:8080

# Without authentication (development only)
vigolium server -A

# Mirror every ingested record + finding to a browsable filesystem tree
vigolium server --mirror-fs ./mirror

# Passively scan every ingested request as it arrives (no active traffic)
vigolium server --scan-on-receive --passive-only

# Merge live Burp Proxy history into GET /api/http-records
vigolium server --burp-bridge-url http://127.0.0.1:9009

The server listens on 0.0.0.0:9002 by default.

Live Filesystem Mirror

vigolium server --mirror-fs <dir> (config server.mirror_fs_path) mirrors every saved HTTP record and finding to a flat filesystem tree as it is persisted, in addition to the database. This lets an external tool or coding agent read ingested Burp/proxy traffic as plain files in real time:

vigolium server --mirror-fs ./mirror

Every record and finding lands under ./mirror/traffic/<host>/… and ./mirror/findings/<host>/… using the same layout as the fs export format — per-host <id>.req, <id>.resp.headers, <id>.resp.body, and finding <id>.md files cross-linked to the request that produced them.

The mirror’s indexes are append-only index.jsonl (one JSON object per line — tail -f/grep it live), as opposed to the one-shot export’s index.json array.
Per-host id numbering resumes from the existing tree across server restarts.
The writer runs on a background goroutine and never blocks the database save path, so mirroring adds no latency to ingestion.

The mirror is opt-in and server-only — CLI scans are unaffected. To produce the same tree as a one-shot export from a finished scan or the database, use --format fs (see Output and Reporting).

Scan on Receive

-S/--scan-on-receive runs the scanner against every ingested request as it is persisted, so forwarded Burp/proxy traffic is analyzed in place without a separate scan command:

# Full active + passive assessment on every ingested request
vigolium server --scan-on-receive

# Passive modules only — no active scan traffic is ever sent (secret detection still runs)
vigolium server --scan-on-receive --passive-only

--passive-only restricts scan-on-receive to passive modules only — the safest way to analyze forwarded traffic in place.
Combining --passive-only with --full-native-scan-on-receive still crawls (discovery + spidering send requests); for zero active traffic, use --scan-on-receive without the full-native flag.

Live Burp Bridge

--burp-bridge-url <url> connects the server to a running Burp Suite through the burp-vigolium extension’s loopback live-bridge listener. Live Burp Proxy history rows are merged into GET /api/http-records on the fly, so the Web UI and API see current Burp traffic alongside the database without a separate ingest step:

vigolium server --burp-bridge-url http://127.0.0.1:9009

The listener is a loopback-only address the extension exposes; http://127.0.0.1:9009 is the default. Enable it under Vigolium → Bridge → Enable live bridge in Burp.
Live rows are labelled source: burp, and the usual /api/http-records filters, sorting, and pagination continue to apply.
The VIGOLIUM_BURP_BRIDGE_URL env var supplies the same URL as a fallback; the flag overrides it.

See the Burp Suite guide for the full bidirectional bridge workflow.

Authentication

All API requests except the public meta endpoints (/, /health, /metrics, /server-info, /swagger/*, and POST /api/auth/login) require a Bearer token:

Authorization: Bearer my-secret-key

API key resolution order: VIGOLIUM_API_KEY env var > server.auth_api_key in config file (~/.vigolium/vigolium-configs.yaml).

CORS Configuration

The server’s CORS behavior is controlled by cors_allowed_origins in ~/.vigolium/vigolium-configs.yaml:

server:
  cors_allowed_origins: reflect-origin

Value	Behavior
`reflect-origin` (default)	Echoes the requesting `Origin` header back. Allows credentials.
`*`	Allows all origins without credentials (standard wildcard).
(empty string)	Disables CORS middleware entirely.
`https://app.example.com, https://admin.example.com`	Comma-separated allowlist. Allows credentials.

Project Scoping

All server operations are scoped to a project via the X-Project-UUID request header. If omitted, the default project is used.

curl -X POST http://localhost:9002/api/ingest-http \
  -H "Authorization: Bearer my-secret-key" \
  -H "X-Project-UUID: a1b2c3d4-..." \
  -H "Content-Type: application/json" \
  -d '{"input_mode": "url", "content": "https://example.com"}'

All queries (findings, HTTP records, stats, scans) return data scoped to the project specified in the header. See Projects for the full multi-tenancy reference.

API Endpoint Overview

A condensed view — see the API References index for the full surface.

Method	Path	Description
GET	`/`	Static UI (no auth required)
GET	`/health`	Health check (no auth required)
GET	`/metrics`	Prometheus metrics (no auth required)
GET	`/swagger/*`	Swagger UI and OpenAPI spec (no auth required)
GET	`/server-info`	Server status (no auth required)
POST	`/api/auth/login`	File-based login → bearer token
GET	`/api/info`	App info / build metadata
GET	`/api/user/info`	Current user
GET	`/api/projects`	List projects
GET	`/api/modules`	List available scanner modules
GET	`/api/http-records`	Query stored HTTP records
GET	`/api/findings`	Query scan findings
PATCH	`/api/findings/:id/status`	Update finding status (open/triaged/closed)
POST	`/api/ingest-http`	Ingest HTTP traffic into the database
POST	`/api/burp/sitemap/snapshot`	Ingest a chunked Burp Target Site map snapshot
POST	`/api/import`	Bulk import scans/records/findings
GET	`/api/stats`	Aggregated scan statistics
GET	`/api/oast-interactions`	List OAST callbacks
GET, POST	`/api/scope`	View/update scope configuration
GET, POST	`/api/config`	View/update server configuration
POST	`/api/scans/run`	Trigger a background scan
POST	`/api/scan-url`	Scan a single URL
POST	`/api/scan-request`	Scan a single raw request
POST	`/api/scan-records`	Scan specific record UUIDs
POST	`/api/scan-all-records`	Scan filtered records
GET	`/api/scans`	List scans
GET	`/api/scans/:uuid`	Scan status
GET	`/api/scans/:uuid/logs`	Scan logs (SSE supported)
POST	`/api/scans/:uuid/stop`	Cancel a running scan
POST	`/api/scans/:uuid/pause`	Pause a scan
POST	`/api/scans/:uuid/resume`	Resume a scan
POST	`/api/scans/:uuid/update`	Adjust scan parameters mid-run
GET	`/api/scan/status`	Latest scan status (legacy/global)
POST	`/api/agent/run/query`	Single-shot agent prompt execution
POST	`/api/agent/run/autopilot`	Autonomous AI-driven scanning session
POST	`/api/agent/run/swarm`	AI-guided multi-phase vulnerability scan
POST	`/api/agent/run/audit`	Audit/piolium driver dispatcher (`driver: auto\|both\|audit\|piolium`)
GET	`/api/agent/status/list`	List agent runs
GET	`/api/agent/status/:id`	Get agent run status (includes full result when completed)
GET	`/api/agent/sessions`	Paginated session history
GET	`/api/agent/sessions/:id/logs`	Tail or read `runtime.log` (SSE supported)
GET	`/api/agent/sessions/:id/artifacts[/:filename]`	Browse / fetch agent session artifacts
POST	`/api/agent/chat/completions`	OpenAI-compatible chat completions
POST	`/api/storage/upload-source`	Upload source archive to cloud storage
POST	`/api/storage/presign`	Pre-signed upload/download URLs
GET	`/api/storage/source/:key`	Download a stored source archive
GET	`/api/diagnostics`	System readiness check
GET	`/api/db/tables`	List database tables
GET, POST	`/api/db/tables/:name/records`	Generic table browser (read / queries)
GET	`/api/extensions`	List loaded extensions
PUT, POST	`/api/extensions/:name`	Upload / enable extension

Scan Management via API

After ingesting HTTP records, trigger a vulnerability scan via the API.

Trigger a Scan

curl -s -X POST http://localhost:9002/api/scans/run \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

Force re-scan with specific modules:

curl -s -X POST http://localhost:9002/api/scans/run \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "force": true,
    "enable_modules": ["xss-scanner", "sqli-error-based"]
  }' | jq .

Returns 202 Accepted with a scan_uuid on success, 409 Conflict if a scan is already running.

Check Scan Status

# Latest scan, legacy/global endpoint
curl -s http://localhost:9002/api/scan/status \
  -H "Authorization: Bearer my-secret-key" | jq .

# Specific scan
curl -s http://localhost:9002/api/scans/SCAN-UUID \
  -H "Authorization: Bearer my-secret-key" | jq .

Cancel a Running Scan

curl -s -X POST http://localhost:9002/api/scans/SCAN-UUID/stop \
  -H "Authorization: Bearer my-secret-key" | jq .

See the API Reference for full request/response details.

Running AI Agents via API

The server exposes agent endpoints that mirror the vigolium agent CLI subcommands (query, autopilot, swarm, audit). The audit dispatcher accepts driver: "auto"|"both"|"audit"|"piolium" to drive the embedded vigolium-audit harness and/or piolium. Concurrency is bounded by a global heavy/light semaphore plus a per-project heavy cap; new heavy runs return 409 Conflict when the cap is reached. Set "stream": true for real-time SSE output (multi-driver audit streams add a driver field per chunk). For full details on agent modes, prompt templates, and API request/response schemas, see the Agent Mode documentation and the Agent API Reference.

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

What is Server Mode

Starting the Server

Live Filesystem Mirror

Scan on Receive

Live Burp Bridge

Authentication

CORS Configuration

Project Scoping

API Endpoint Overview

Scan Management via API

Trigger a Scan

Check Scan Status

Cancel a Running Scan

Running AI Agents via API

​What is Server Mode

​Starting the Server

​Live Filesystem Mirror

​Scan on Receive

​Live Burp Bridge

​Authentication

​CORS Configuration

​Project Scoping

​API Endpoint Overview

​Scan Management via API

​Trigger a Scan

​Check Scan Status

​Cancel a Running Scan

​Running AI Agents via API

What is Server Mode

Starting the Server

Live Filesystem Mirror

Scan on Receive

Live Burp Bridge

Authentication

CORS Configuration

Project Scoping

API Endpoint Overview

Scan Management via API

Trigger a Scan

Check Scan Status

Cancel a Running Scan

Running AI Agents via API