> ## 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.

# Transparent Proxy

> Use Vigolium's built-in HTTP proxy to passively record traffic for scanning, including HTTPS via optional MITM interception.

## 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:

```bash theme={null}
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).

## 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.

```bash theme={null}
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:

```bash theme={null}
# curl trusting the CA explicitly
curl --cacert ~/.vigolium/ca/vigolium-ca.pem -x http://localhost:9003 https://example.com/api/users
```

| Flag                 | Description                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--proxy-mitm`       | Intercept HTTPS through `--ingest-proxy-port` using a generated CA so TLS traffic is recorded (and scanned with `-S`).                                |
| `--proxy-insecure`   | When 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. |

```bash theme={null}
# Export the CA without starting the proxy, then trust it on your clients
vigolium server --export-ca ./vigolium-ca.pem
```

<Callout icon="triangle-alert" color="#F59E0B" iconType="regular">
  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.
</Callout>

## Usage Examples

### curl

```bash theme={null}
curl -x http://localhost:9003 https://example.com/api/users
```

### httpx

```bash theme={null}
echo "https://example.com" | httpx -proxy http://localhost:9003
```

### nuclei

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
curl -s http://localhost:9002/server-info | jq .
```

`/server-info` is public — no `Authorization` header needed. Response:

```json theme={null}
{
  "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"
}
```