Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt

Use this file to discover all available pages before exploring further.

Architecture series: Overview · Native Scan · Agentic Scan · Data & Storage · Server & API
Vigolium runs as a long-lived service via vigolium server, a Fiber REST API that ingests traffic, triggers native and agentic scans, and serves results, all sharing the same project-scoped persistence layer as the CLI. This document explains the service’s shape and request lifecycle. For curl-by-curl recipes see Server & Ingestion; for the full endpoint catalogue see API Overview and the API Reference.

​
1. Process model

                         vigolium server
   ┌───────────────────────────────────────────────────────────┐
   │  Fiber HTTP server            :9002 (0.0.0.0 default)       │
   │    middleware: CORS → auth (Bearer) → project resolve       │
   │                                                             │
   │  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
   │  │ Ingestion   │  │ Scan control │  │ Agent run API     │  │
   │  │ handlers    │  │ handlers     │  │ handlers_agent.go │  │
   │  └──────┬──────┘  └──────┬───────┘  └─────────┬─────────┘  │
   │         └──────────┬─────┴────────────────────┘            │
   │                    ▼                                        │
   │            shared Repository (SQLite / PostgreSQL)          │
   └───────────────────────────────────────────────────────────┘
            ▲                                  ▲
            │ optional transparent proxy       │ vigolium-ingestor
            │ (--ingest-proxy-port :9003)      │ (remote client)
The server is pkg/server/ (Fiber). It owns no scan logic of its own, it wraps the same internal/runner native pipeline and the same pkg/agent orchestrators the CLI uses, so behavior is identical whichever entry point launches a scan. Three traffic sources feed the same RecordWriter → repository path: the /api/ingest-http endpoint, the optional transparent HTTP proxy, and the standalone vigolium-ingestor client.

​
Middleware chain

Every request (except /, /health, /metrics, /swagger/*) passes:
  1. CORS: server.cors_allowed_origins, reflect-origin (default, credentialed echo), * (wildcard, no credentials), explicit comma-separated allowlist, or empty (disabled).
  2. Auth: Authorization: Bearer <key>; key resolves VIGOLIUM_API_KEY env > server.auth_api_key config. vigolium server -A disables auth (development only).
  3. Project resolution: X-Project-UUID header selects the tenant (default project if absent); X-User-Email drives optional per-project access control (403 on denial). See Data & Storage.

​
2. Traffic ingestion

POST /api/ingest-http is the universal entry point. A single endpoint accepts many input_modes, normalizes them into HttpRequestResponse items, and hands them to the async RecordWriter:
input_modePayload fieldSource
url / url_filecontentOne URL / newline-separated list
curlcontent or content_base64A curl command string
burp_base64http_request_base64 (+ optional http_response_base64, url hint)Raw HTTP request
openapi / swaggercontent or content_base64OpenAPI/Swagger spec
postman_collectioncontent_base64Postman collection
Large payloads should use the *_base64 fields to avoid JSON escaping. The same parsers back the vigolium ingest CLI, which runs in two modes: remote (-s http://server → POSTs to /api/ingest-http) or local (--server omitted → fetches and writes straight to the DB).

​
Transparent proxy

vigolium server --ingest-proxy-port 9003 opens a recording HTTP proxy. Plain HTTP traffic routed through it is captured into the DB; HTTPS CONNECT tunnels pass through without recording. This is the zero-instrumentation path for capturing traffic from arbitrary tools (curl -x, httpx -proxy, nuclei -proxy).

​
3. The REST surface

Endpoints group by concern; each group has a dedicated page under the API Reference.
GroupRepresentative endpointsPurpose
Meta (no auth)GET /, /health, /metrics, /swagger/*, /server-infoLiveness, Prometheus, OpenAPI UI
Auth/userPOST /api/auth/login, GET /api/user/infoToken issue, identity
IngestionPOST /api/ingest-httpTraffic in (see §2)
HTTP recordsGET/DELETE /api/http-records[/:uuid]Query/inspect captured traffic
FindingsGET /api/findings, PATCH /api/findings/:id/statusQuery/triage results
Scan controlPOST /api/scan-url, /api/scan-request, /api/scans/run, /api/scans/:uuid/{stop,pause,resume}Trigger & manage native scans
Scope / configGET/POST /api/scope, /api/configLive scope & config
ProjectsGET/POST/PUT/DELETE /api/projects[/:uuid], /domain-mapMulti-tenancy management
Storage/api/storage/{source,results,upload-source,presign}Cloud bundles (storage enabled)
DB browse/api/db/tables/...Generic table inspection (admin)
AgentPOST /api/agent/run/{query,autopilot,swarm,vigolium-audit,audit}, sessions/statusAI runs (see §4)

​
Asynchronous job pattern

Scan and agent runs are long-lived, so the API is launch-and-poll, not request/response:
  1. POST /api/scans/run or /api/agent/run/* → 202 Accepted with a UUID (409 Conflict if one is already active, only one agent run at a time).
  2. Poll GET /api/scan/status or GET /api/agent/status/:id until status leaves running.
  3. Fetch artifacts: GET /api/agent/sessions/:id/{logs,artifacts,artifacts/*} (logs SSE-capable; artifact reads support nested paths and a ?max_bytes= cap).
Opting into "stream": true on a run endpoint switches to Server-Sent Events instead, data: lines carrying {"type":"chunk|phase|done|error", …}. Most consumers should prefer the async poll-and-tail flow to keep warm sessions and prompt caches stable.

​
4. Agent run API

pkg/server/handlers_agent.go mirrors the vigolium agent subcommands over HTTP. It does not re-implement agent logic, it invokes the same orchestrators documented in Agentic Scan, with one deliberate constraint:
  • Provider is server-config only. The CLI’s per-invocation provider flags (--provider, --model, --oauth-token, …) are not mirrored on the REST schemas. The server resolves the provider once from agent.olium.* in vigolium-configs.yaml and reuses it, keeping warm sessions and prompt caches stable. Switching providers means editing YAML and reloading.
  • Backward-compatible source field. Request types expose EffectiveSourcePath() to accept both source and legacy repo_path JSON keys.
  • Audit driver dispatch. POST /api/agent/run/audit takes driver: "auto"|"both"|"vigolium-audit"|"piolium"; multi-driver modes run sequentially and multiplex SSE chunks with a driver field when streaming.

Server & Ingestion

Startup flags, curl recipes per input mode.

API Overview

Full endpoint catalogue and request/response schemas.

Agentic Scan

The orchestrators the agent endpoints invoke.

Data & Storage

Project scoping and the persistence layer the handlers share.