Skip to main content

​
Overview

Vigolium’s server mode includes a built-in transparent HTTP proxy that passively records all traffic flowing through it. This lets you point any HTTP-capable tool at Vigolium and have its traffic automatically ingested for scanning.

​
Starting the Proxy

Start the server with --ingest-proxy-port to enable the transparent proxy alongside the REST API: 
export VIGOLIUM_API_KEY=my-secret-key
vigolium server --ingest-proxy-port 9003
This starts two listeners:
  • REST API on port 9002 (default)
  • HTTP proxy on port 9003

​
How It Works

The proxy sits between your tools and the target. All HTTP traffic passing through is automatically recorded in the database as HTTP records, ready for scanning. By default, HTTPS CONNECT tunneling is passed through without recording — the proxy cannot inspect encrypted traffic without acting as a MITM, so TLS tunnels are forwarded transparently. To record HTTPS too, enable MITM interception.

​
HTTPS Interception (MITM)

Add --proxy-mitm to intercept HTTPS through the ingest proxy using a generated CA. TLS traffic is decrypted, recorded as HTTP records, and (with -S) scanned — just like plain HTTP. 
vigolium server --ingest-proxy-port 9003 --proxy-mitm

# Intercept and continuously scan decrypted HTTPS traffic
vigolium server --ingest-proxy-port 9003 --proxy-mitm -S
On startup the server prints the path to the generated CA certificate (default ~/.vigolium/ca/vigolium-ca.pem). Your client must trust this CA or HTTPS requests will fail certificate validation. Install it into your OS/browser trust store, or point your tool at it directly: 
# curl trusting the CA explicitly
curl --cacert ~/.vigolium/ca/vigolium-ca.pem -x http://localhost:9003 https://example.com/api/users
FlagDescription
--proxy-mitmIntercept HTTPS through --ingest-proxy-port using a generated CA so TLS traffic is recorded (and scanned with -S).
--proxy-insecureWhen intercepting HTTPS, skip verification of the upstream server’s TLS certificate (useful for self-signed targets).
--export-ca <path>Write the ingest-proxy MITM CA certificate to <path> and exit (generates the CA if needed). Use this to distribute the CA to clients ahead of time.
# Export the CA without starting the proxy, then trust it on your clients
vigolium server --export-ca ./vigolium-ca.pem
Only trust the Vigolium MITM CA on machines you control during testing, and remove it afterward — any party holding the CA private key can forge TLS certificates for those clients.

​
Usage Examples

​
curl

curl -x http://localhost:9003 https://example.com/api/users

​
httpx

echo "https://example.com" | httpx -proxy http://localhost:9003

​
nuclei

nuclei -u https://example.com -proxy http://localhost:9003

​
Browser

Configure your browser’s HTTP proxy to localhost:9003. In most browsers this is under network or proxy settings. For Firefox, go to Settings > Network Settings > Manual proxy configuration and set the HTTP Proxy to localhost with port 9003.

​
Querying Ingested Data

After routing traffic through the proxy, use the REST API to inspect what was recorded and view any scan findings.

​
List HTTP Records

# All records (paginated, default limit=50)
curl -s http://localhost:9002/api/http-records \
  -H "Authorization: Bearer my-secret-key" | jq .

# Filter by domain
curl -s "http://localhost:9002/api/http-records?domain=example.com" \
  -H "Authorization: Bearer my-secret-key" | jq .

# Filter by status code and method
curl -s "http://localhost:9002/api/http-records?status_code=200,302&method=GET,POST" \
  -H "Authorization: Bearer my-secret-key" | jq .

# Search across URLs and headers
curl -s "http://localhost:9002/api/http-records?search=admin&limit=10" \
  -H "Authorization: Bearer my-secret-key" | jq .

# Pagination
curl -s "http://localhost:9002/api/http-records?limit=20&offset=40" \
  -H "Authorization: Bearer my-secret-key" | jq .

​
List Findings

# All findings
curl -s http://localhost:9002/api/findings \
  -H "Authorization: Bearer my-secret-key" | jq .

# Filter by severity
curl -s "http://localhost:9002/api/findings?severity=high,critical" \
  -H "Authorization: Bearer my-secret-key" | jq .

# Filter by module
curl -s "http://localhost:9002/api/findings?module_name=xss-reflected" \
  -H "Authorization: Bearer my-secret-key" | jq .

# Filter by domain
curl -s "http://localhost:9002/api/findings?domain=example.com" \
  -H "Authorization: Bearer my-secret-key" | jq .

​
Server Info

curl -s http://localhost:9002/server-info | jq .
/server-info is public — no Authorization header needed. Response: 
{
  "name": "vigolium",
  "version": "v0.1.8-alpha",
  "author": "vigolium",
  "docs": "https://docs.vigolium.com",
  "uptime": "2h15m30s",
  "service_addr": "0.0.0.0:9002",
  "proxy_addr": "0.0.0.0:9003",
  "queue_depth": 0,
  "total_records": 1542,
  "total_findings": 23,
  "license_spdx": "AGPL-3.0",
  "source": "https://github.com/vigolium/vigolium"
}