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

# Vigolium Cheat Sheet

> A one-page, copy-paste reference for the workflows you reach for most: live traffic mirroring, replaying through Burp or Caido, passive/secret scanning of forwarded traffic, importing external data, parallel fan-out, resuming, spec-driven scans, single-request scans, content discovery, filtering to one vulnerability class or technology, browsing recorded traffic in the database, triaging findings with a coding agent, reproducing an exploit, setting up the AI agent, exporting stored data to a browsable filesystem tree, and inspecting or editing config.

A fast, copy-paste reference for Vigolium's most common real-world workflows. Each block is self-contained, adjust hosts, ports, and file paths to your environment. For the full explanation behind any command, follow the cross-links into the rest of the docs.

Every command here works against the open-source binary. `vigolium <command> -h` prints the full flag list for any subcommand.

***

## 1. Mirror ingested traffic + findings to a live filesystem tree

Run the ingestion server with `--mirror-fs` to write every saved HTTP record and finding to a **flat, browsable directory tree** as it is persisted, in addition to the database. This pairs perfectly with the **Vigolium Burp extension**: as you browse, requests/responses and findings land on disk where your coding agent can read them with plain `ls` / `grep` / `jq`.

```bash theme={null}
# Mirror ingested traffic + findings to a live filesystem tree.
# Writes <dir>/traffic and <dir>/findings as records arrive.
vigolium server --mirror-fs output-dir -A
```

What you get under `output-dir/`:

| Path | Contents |
| - | - |
| `traffic/<host>/<id>.req` | Raw request (leading `@target <scheme>://<authority>` line, then the request verbatim, replayable by stripping line 1) |
| `traffic/<host>/<id>.resp.headers` | Status line + response headers |
| `traffic/<host>/<id>.resp.body` | Response body (gzip-decoded so it greps clean) |
| `traffic/<host>/index.jsonl` | Append-only, jq-friendly map of ids → method/url/status/content-type |
| `findings/<host>/<id>.md` | Each finding, cross-linked to its `.req` file |

Mirroring never blocks the database save path (it runs on a background writer) and resumes per-host id numbering across server restarts. Config equivalent: `server.mirror_fs_path`. Add `-S`/`--scan-on-receive` to also scan the traffic as it arrives (see [section 3](#3-passive-secret-scan-on-forwarded-traffic)).

Read it back from an agent or shell:

```bash theme={null}
# List every request Vigolium has ingested for a host
ls output-dir/traffic/example.com/

# Find all findings mentioning "token"
grep -ril token output-dir/findings/

# Pull the method/url/status of every record as JSON
jq . output-dir/traffic/example.com/index.jsonl
```

***

## 2. Replay ALL stored traffic through Burp Suite

Re-send stored records through an intercepting proxy so you can inspect and manipulate them manually in Burp. Keep concurrency low (`-c`) so you don't overwhelm the proxy.

```bash theme={null}
# Replay every stored record in your project DB through Burp
vigolium replay --all --proxy http://127.0.0.1:8080 -c 5
```

Replay directly from a standalone export (project scoping off, nothing written to your project DB):

```bash theme={null}
# BULK: replay every record from a standalone .sqlite export
vigolium replay -S --db scan.sqlite --all --proxy http://127.0.0.1:8080 -c 5
```

`--all` lifts the default `-n/--limit` cap (100). Instead of `--all` you can narrow the bulk set with a positional fuzzy term (`vigolium replay admin`) or the full `traffic`-style selectors — `--search`/`--exclude-search`, `--host`, `--method`, `--status`, `--path`, `--source`, `--body`/`--exclude-body`, `--from`/`--to`, and `--sort`/`--asc`/`--offset` (see [Bulk replay](https://docs.vigolium.com/others/cli-references.md#bulk-replay)). `-S/--stateless` reads records from a `.jsonl` export **or** a standalone `.sqlite` with project scoping off, it never writes to your project DB.

***

## 3. Passive / secret scan on forwarded traffic

When you forward traffic into Vigolium from another source (the Burp extension, a proxy, or the `vigolium ingest` client), start the **server in scan-on-receive mode**. Use `--passive-only` to run passive modules **only**, no active scan traffic is sent, and secret detection is included.

```bash theme={null}
# Passive-only, continuously scan forwarded traffic as it arrives.
# No active requests are sent; secret detection runs.
vigolium server -S --passive-only -A

# Same, but also mirror everything to disk for your agent to read
vigolium server -S --passive-only --mirror-fs output-dir -A

# Record + passively scan HTTP(S) through the transparent ingest proxy
vigolium server -S --passive-only --ingest-proxy-port 9003 -A
```

Scan-on-receive modes at a glance:

| Flag | Behavior |
| - | - |
| `-S` / `--scan-on-receive` | Continuously scans new records with the **dynamic-assessment** phase (active + passive modules). |
| `-S --passive-only` | Passive modules only, **no active traffic**. Includes secret detection, security headers, cookie flags, disclosure, etc. |
| `-S --full-native-scan-on-receive` | Runs the **full native pipeline** (discovery + spidering + dynamic-assessment) on received records. |

Server mode always enables **every** passive module. `--passive-only` simply zeroes the active modules so the scanner analyzes forwarded request/response pairs without sending any new requests, ideal for scanning traffic you've captured elsewhere. Point the Burp extension (or `vigolium ingest`) at the server's ingestion endpoint and findings appear as traffic flows in. See [Server & Ingestion](https://docs.vigolium.com/getting-started/server-and-ingestion.md).

***

## 4. Import external scan data into the database

Use `vigolium import` to pull existing data, **JSONL exports**, **audit output folders**, and **archives**, into your database. It auto-detects the input by inspecting the path.

```bash theme={null}
# JSONL export (http_record + finding envelopes, e.g. from `vigolium export --format jsonl`)
vigolium import data.jsonl

# Audit output folder (contains audit-state.json + findings-draft/)
vigolium import ./audit-output/

# Merge an external vigolium scan DB into the default database
vigolium import other-vigolium-scan.sqlite

# Compressed archive of either of the above
vigolium import bundle.tar.gz      # also .tgz, .zip

# Remote object in cloud storage (downloaded, then imported)
vigolium import gs://<project-uuid>/<key>

# Import and emit a branded HTML report in one step
vigolium import ./audit-output/ --format html -o report.html --report-title "My Report"
```

Imported findings are scoped to the active project (`--project-uuid` / `VIGOLIUM_PROJECT_UUID`). `import` initializes the schema on a fresh `--db` path, so it's safe as the first command against a brand-new database. Supported JSONL types are `http_record` and `finding`; other envelope types are counted and skipped.

### Merging a standalone SQLite database

`vigolium import` detects a SQLite result database by its magic header (works for `.sqlite`, `.sqlite3`, `.db`, or no extension) and performs a **lossless, idempotent SQLite→SQLite merge** of the scan-result tables (http\_records, findings, scans, agentic\_scans, oast\_interactions, projects), deduping on natural keys:

```bash theme={null}
# Merge an external scan DB into the default database
vigolium import other-vigolium-scan.sqlite

# Merge into a specific destination DB
vigolium import other-vigolium-scan.sqlite --db team.sqlite

# Merge several scans at once — pass them positionally…
vigolium import --db combined.sqlite scan-a.sqlite scan-b.sqlite scan-c.sqlite

# …or expand a glob with --glob-db (idempotent, so re-runs are no-ops)
vigolium import --db combined.sqlite --glob-db 'scans/*.sqlite'

# --glob-db also works for JSONL exports (use one format per run)
vigolium import --glob-db '*.jsonl'
```

If you'd rather **read** a colleague's export without merging it into your own DB, open it in place with project scoping off. Point `-S` at a single file with `--db`, or read across **many** files at once with `--glob-db` (they're merged into one throwaway scratch DB, so `--glob-db` implies `-S`):

```bash theme={null}
# A single standalone export
vigolium finding -S --db scan.sqlite
vigolium traffic -S --db scan.sqlite

# Across a whole directory of exports (.sqlite and/or .jsonl)
vigolium finding --glob-db 'scans/*.sqlite'
vigolium traffic --glob-db 'scans/*.sqlite'
vigolium export --glob-db 'scans/*.sqlite' --format jsonl -o all.jsonl
```

**Large globs are fine.** `--glob-db` is routinely pointed at hundreds of files — a per-host bug-bounty run of \~854 databases, 16 GB, 290k HTTP records. At that size the *merge*, not the query, is the whole cost: it runs before the first `WHERE`, so anything copied in is resident before any filter narrows it. **v0.4.4** made that bounded:

* The scratch database is a temp **file**, not `:memory:` — its working set pages against the OS cache instead of competing with the process heap (an `export` that previously reached 18.7 GB RSS and 149s of kernel paging without finishing).
* `finding` no longer copies every matched file's record corpus just to hydrate the findings on screen (20.4 GB). `--raw` / `--burp` / `--markdown` / `--with-records` / `--push-to-burp` / `--to-repeater` fetch evidence afterwards by UUID from each finding's own source file.
* `traffic --save-to-burp --glob-db` streams file-by-file instead of merging — it's the one mode that can't drop the bodies, since they're what gets sent (16 GB → 417 MB peak).
* A single-format `export` streams envelopes instead of materializing the whole set (6.1 GB).
* Scratch databases stranded by a killed run are reaped on the next open.

Merged rows keep their **original** `project_uuid`, so imported data stays scoped to whatever project it was scanned under. Importing the same database twice adds nothing the second time (dedup on natural keys). Requires a SQLite destination — a Postgres destination returns a clear error. To merge many **parallel** scans into one shared DB during scanning instead, use `--db-isolate` (see [section 5](#5-scan-a-large-list-of-targets-in-parallel)).

***

## 5. Scan a large list of targets in parallel

Point Vigolium at a large target list and use `-P/--parallel N` to scan several hosts at once. Each target runs in its own **isolated child process**, so there is no cross-contamination between workers, and each child keeps its own `--concurrency`, meaning real in-flight requests are roughly `N × --concurrency`.

`-P` requires one of two output strategies so results never collide:

* **`--stateless --split-by-host`** — each target runs against its own temporary database and writes a separate per-host output file (`base-<host>.<ext>`). Nothing is persisted. Best for stateless, fire-and-forget batches.
* **`--db-isolate`** — each worker scans into a private temporary SQLite database, then merges its results into the shared `--db` (or the default DB) at the end. This lets many parallel scans share one database without write contention, and you export one unified report from the merged DB afterward.

```bash theme={null}
# Stateless fan-out: per-host JSONL + HTML files, 3 targets at a time
vigolium scan -T list-of-targets.txt -P 3 \
  --stateless --split-by-host \
  --format jsonl,html --output prefix-output \
  --discovery-wordlist ~/Tools/contents/fast.txt

# Shared-DB fan-out: 4 targets at a time merged into one local.db, one unified output
vigolium scan -T list-of-targets.txt -P 4 \
  --db-isolate --db local.db \
  --format jsonl,html --output report \
  --discovery-wordlist ~/Tools/contents/fast.txt
```

`--db-isolate` is SQLite-only. Passing it alongside `--stateless` is **not** an error: `-S` wins and `--db-isolate` is ignored with a warning, since a stateless run keeps no database to merge from (before v0.4.8 the pair aborted the run). A `--db` you name by hand stays a hard conflict with `-S`. Pressing `Ctrl-C` during a `-P` batch is treated as an operator stop: un-started and cut-short targets are reported as "not scanned" rather than failures.

***

## 5a. Sweep thousands of hosts before committing to a scan

`vigolium run probe` is the triage pass: **one request per target**, passive technology fingerprinting and attack-surface scoring, no content discovery and no fuzzing. `run discover` would spend its whole budget on the first handful of hosts; a sweep answers shallowly about all of them, so you can pick the few worth a real scan.

```bash theme={null}
# Host sweep, JSONL on stdout (progress stays on stderr)
vigolium run probe -T hosts.txt --json --no-response -c 20

# Add TLS certificates (version, cipher, subject/SANs, issuer, validity, fingerprints)
vigolium run probe -T hosts.txt --json --tls-probe -c 50

# Keep the database, then rank what answered by attackable surface
vigolium run probe -T hosts.txt -S --format sqlite -o sweep
vigolium traffic -S --db ./sweep.sqlite --source probe --sort surface_score -n 50

# Feed the top of that list into a real scan
vigolium run probe -T hosts.txt --json --no-response 2>/dev/null \
  | jq -r 'select(.surface_score >= 40) | .url' > worth-scanning.txt
vigolium scan -T worth-scanning.txt -P 4 --db-isolate --db local.db
```

The aliases `httpx`, `alive`, `sweep`, and `probing` all reach the same phase, and the JSONL field names match httpx's (`a` / `aaaa` / `cname` / `tls`) so an existing consumer reads them unmodified.

**A sweep produces records, not findings** — a `0 findings` summary is the expected result. The answer is in `surface_score` (0-100, the percentage of a 17-signal set present), `technology`, and `status_code`. `a`/`aaaa`/`cname`/`tls` are reported inline but **not stored**; only `ip` is. See [Probe](https://docs.vigolium.com/native-scan/phases/probe.md).

**Bare hostnames need no pre-processing (since v0.4.8).** A `hosts.txt` straight out of a subdomain tool — `api.example.com`, `example.com:8443` — is normalized to `http://` per line before anything runs, and the normalization happens before the dedup, so `example.com` and `http://example.com` are one target rather than two. Before v0.4.8 those lists scanned fine under probe and discovery but silently produced **zero** crawl results under `--only spidering`. See [Schemeless targets](https://docs.vigolium.com/others/cli-references.md#schemeless-targets).

***

## 5b. Ask an origin what it is, and read the answer back later

Added in v0.5.5. Where probe answers *which* hosts are alive, `vigolium fingerprint` answers what **one origin is** — and stores it per `host:port` so every later command and run can read it without sending anything again.

```bash theme={null}
# Fingerprint and store (reads only: GET, OPTIONS, one GraphQL introspection POST)
vigolium fingerprint https://app.example -j
vigolium fingerprint -T hosts.txt --depth light -j --compact

# Resolve names into the same store (no zone transfer, no brute force)
vigolium dns -T hosts.txt --type a,cname --format tsv

# Read the facts back — zero requests
vigolium hosts -j --compact
vigolium hosts '*.example.com' --format tsv --fields hostname,port,title,server,favicon_mmh3
vigolium hosts --has tls --sans > more-hosts.txt      # certificate SANs: a ready -T list
vigolium hosts --soft-404 -j                          # origins that answer 200 to anything

# Then drop every stored not-found page out of a traffic read
vigolium traffic --exclude-not-found --format tsv --fields status,method,url
```

`--depth light` (\~9 reads per origin), `standard` (\~60, the default up to 50 targets) or `full` (adds sensitive paths, `OPTIONS` on everything that answered, source maps). Beyond 50 targets the default drops to `light` on its own.

**The not-found baseline is the payoff.** Fingerprint records how an origin answers three random paths; afterwards `traffic --exclude-not-found` can drop that origin's soft-404 pages and `hosts --soft-404` can list the origins where a `200` means nothing. No status filter can do either, because those pages *are* `200`s. `favicon_mmh3` is Shodan/FOFA's hash format, so a hash here is a query you can paste into either.

Every fingerprint request goes **through the scan engine** — scope, `--rate-limit`, `--max-per-host`, `--max-requests` and WAF pacing all apply, and each request lands as an `http_record` with `source: fingerprint`. It is also a phase: `vigolium run fingerprint` (`--fingerprint-depth`), and `fingerprint` in `--only` / `--skip`. See [Host facts](https://docs.vigolium.com/others/cli-references.md#host-facts-fingerprint-hosts-dns).

***

## 6. Resume a large parallel scan

A stateless parallel fan-out (`-S -T --split-by-host -P`) writes a tiny line-cursor manifest, `<output>.progress.json`, tracking the targets that completed cleanly. If the batch is interrupted (Ctrl-C, a crash, a CI timeout), re-run it with `--resume` to skip the finished targets and scan only the remainder, Vigolium also prints a copy-pasteable resume command on Ctrl-C/failure:

```bash theme={null}
# Original run
vigolium scan -T targets.txt -P 4 --stateless --split-by-host --format jsonl -o results

# Resume only the targets that didn't finish
vigolium scan -T targets.txt -P 4 --stateless --split-by-host --format jsonl -o results --resume
```

Run `vigolium scan --resume` bare, with no other flags, and it auto-discovers the `*.progress.json` in the current directory and relaunches the saved run from it (pass `-o <prefix>` to disambiguate when several manifests exist).

`--resume` currently applies only to the parallel fan-out (`-S -T --split-by-host -P > 1`). Resuming a plain sequential scan re-runs it in full.

***

## 7. Scan from an OpenAPI / Swagger / WSDL / Postman / Burp / HAR input

Feed a spec or capture with `-i <file>` and select the format with `-I <format>`. Auto-discovery/crawling is skipped, Vigolium scans exactly the endpoints defined in the input.

```bash theme={null}
# OpenAPI / Swagger spec
vigolium scan --stateless -i api.yaml -I openapi \
  -t https://api.example.com --format jsonl -o results

# WSDL / SOAP service (or a live .svc/.asmx URL, which fetches its own WSDL)
vigolium scan --stateless -i service.wsdl -I wsdl \
  -t https://soap.example.com --format jsonl -o results

# Postman collection
vigolium scan --stateless -i collection.json -I postman \
  -t https://api.example.com --format jsonl -o results

# Burp Suite XML export
vigolium scan --stateless -i export.xml -I burpxml --format jsonl -o results

# HAR capture
vigolium scan --stateless -i traffic.har -I har --format jsonl -o results

# Nuclei JSONL
vigolium scan --stateless -i nuclei.jsonl -I nuclei --format jsonl -o results

# Burp Suite scope export — the JSON a bug-bounty program hands you
vigolium scan --stateless -T scope.json --format jsonl -o results
```

`burpscope` parses a Burp **project-config scope export** (`{"target":{"scope":{"include":[…],"exclude":[…]}}}` — not the binary `.burp` project file) and expands its include rules into seed URLs. It is content-sniffed, so `-T scope.json` works with no `-I`. A wildcard host like `^.*\.example\.com$` is reported rather than scanned — it names a set, not a server, and synthesizing the apex would hit a host the scope never listed. `http://` candidates collapse into their `https://` twins, and exclude rules are applied before anything is emitted.

> [!WARNING]
>
> **`-i/--input` and `-T/--target-file` are not interchangeable.** `-T` reads its file as one target URL per line, so pointing it at a spec makes every line of that file a target (and under `-S`, one child scan per line). Specs and exports go through `-i`. The two exceptions are the formats that genuinely *are* target lists: `urls` and `burpscope`.

Format aliases: `openapi`/`swagger`, `wsdl`/`soap`/`svc`, `postman`, `burpxml`/`burp`/`burp-xml`, `burpraw`/`raw`, `burpscope`/`burp-scope`, `har`/`http-archive`, `nuclei`/`nuclei-output`, `deparos`. Run `vigolium scan --list-input-mode` for the full list. Use `-t/--target` to supply the base URL when a spec carries only paths.

***

## 8. Scan a single request, no crawling or discovery

`scan-request` runs scanner modules against exactly one raw HTTP request, keeping all its parameters, cookies, and headers, with no crawling or discovery.

```bash theme={null}
# From a file containing a raw HTTP request
vigolium scan-request -i request.txt

# From stdin
printf 'GET /api/users?id=1 HTTP/1.1\r\nHost: example.com\r\n\r\n' \
  | vigolium scan-request

# From a curl command (auto-detected)
echo "curl -X POST -d 'user=admin' https://example.com/login" \
  | vigolium scan-request
```

Override the host when the request file has only a path:

```bash theme={null}
vigolium scan-request -i request.txt --target https://staging.example.com
```

### Piping from stdin

Both `scan-url` and `scan-request` auto-detect the stdin format, plain URL, curl command, or raw HTTP request:

```bash theme={null}
# Plain URL
echo 'https://example.com/search?q=test' | vigolium scan-url

# Curl command
echo "curl -H 'Content-Type: application/json' -d '{\"id\":1}' https://example.com/api" \
  | vigolium scan-url

# Raw HTTP request (keeps the cookie + body verbatim)
printf 'POST /api/login HTTP/1.1\r\nHost: example.com\r\nContent-Type: application/x-www-form-urlencoded\r\nCookie: session=abc123\r\n\r\nuser=admin&pass=secret' \
  | vigolium scan-request

# Scan whatever is on your clipboard (macOS)
pbpaste | vigolium scan-url -j
```

### Fuzz one request with a custom payload set

Where `scan-request` runs opinionated, confirmation-backed **modules**, `vigolium fuzz` is a low-level **primitive**: it injects a payload set into an exact position of one request and streams raw response signals (status, size, words, lines, time, reflection, baseline-delta) with match/exclude gating — no findings, no verdicts. It's built to be driven by a coding agent. Reach for it when you need a custom wordlist, an exact insertion point, or wordlist-scale discovery the modules can't express; reach for `scan-request -m ...` when you want a confirmed detection.

```bash theme={null}
# Wordlist into a FUZZ marker, keep only 200s (builtin lists: fuzz, dir-short/long, file-short/long)
vigolium fuzz 'https://example.com/api/FUZZ' -w dir-short --match-status-code 200

# A built-in payload class into one parameter (classes: xss, sqli, ssti, ssrf, lfi, cmdi, xxe, …)
vigolium fuzz 'https://example.com/item?id=1' --point URL_PARAM:id --class sqli,xss

# Raw request on stdin, inline payloads, drop 404s and auto-calibrated catch-all noise
cat req.txt | vigolium fuzz -p "' OR 1=1--" -p '<svg/onload=alert(1)>' --exclude-status-code 404

# Agent handle: JSONL to stderr, ONE summary object (ranked anomalies + a ready confirm query) to stdout
vigolium fuzz 'https://example.com/api?id=FUZZ' -w ~/wordlists/ids.txt -j

# CI/agent gate: exit non-zero (3) if anything matches
vigolium fuzz 'https://example.com/admin/FUZZ' -w dir-short --match-status-code 200,301 --fail-on-match
```

**Don't know what "interesting" looks like yet?** `-a/--anomaly` replaces hand-written matchers. Each response is scored against the baseline *and* against the run's own population, so a status change that every payload triggers reads as the endpoint's normal behaviour rather than a signal:

```bash theme={null}
vigolium fuzz 'https://example.com/api/FUZZ' -w dir-short --anomaly
vigolium fuzz 'https://example.com/api/FUZZ' -w dir-short --anomaly --anomaly-threshold high
```

Every result carries `anomaly_score` and `anomaly_reasons` (leaked SQL/stack error, 4xx→2xx flip, size/time outlier, rare status, unencoded reflection, …). It reports **where to look**, never a verdict — confirm the lead with `scan-request -m ...`.

Three more things worth knowing:

```bash theme={null}
# Numeric matchers take predicates, not just equality: N, N-M, >N, >=N, <N, <=N, !N
vigolium fuzz 'https://example.com/api/FUZZ' -w dir-short --match-size '>1000' --match-status-code '!404'

# Credential PAIRS across two markers (sniper | batteringram | pitchfork | clusterbomb)
vigolium fuzz 'https://example.com/login' -X POST -d 'u=FUZZ&p=FUZZ2' \
  --mode pitchfork -w users.txt:FUZZ -w passwords.txt:FUZZ2

# Pre-flight: print the exact bytes each payload would send, with ZERO network traffic
vigolium fuzz 'https://example.com/api/FUZZ' -w dir-long --dry-run
```

`fuzz` also accepts curl's **long-form** flags (`--cookie`, `--data-urlencode`, `--form`, `--compressed`, `--resolve`, …), so a request pasted from DevTools works with minimal editing. Long forms only: the short spellings are taken by vigolium meanings (`-u` record UUID, `-i` input, `-w` wordlist).

See the [Fuzz CLI reference](https://docs.vigolium.com/others/cli-references.md#fuzz) for the full flag set (positions, matchers, anomaly scoring, attack modes, calibration, and sending payloads through Burp's engine).

***

## 9. Target one vulnerability class or technology

Every scan command (`scan`, `scan-url`, `scan-request`, `run`, `ingest`) accepts two module filters. Use `-m/--modules` to enable a subset by **fuzzy match on module ID/name**, or `--module-tag` to select by **tag** (repeatable, OR-combined). Both default to "all" when omitted; when you pass both, the results are **merged** (union).

```bash theme={null}
# Only run the XSS modules against a single URL
vigolium scan-url -t 'https://example.com/search?q=1' -m xss

# Technology-scoped scans by tag — GraphQL, Adobe AEM, or IIS only
vigolium scan -t https://example.com --module-tag graphql
vigolium scan -t https://example.com --module-tag aem
vigolium scan -t https://example.com --module-tag iis

# Combine tags (OR): run every AEM or GraphQL module
vigolium scan -t https://example.com --module-tag aem --module-tag graphql

# Pin an exact module by its ID (repeatable)
vigolium scan -t https://example.com -m graphql-scan
vigolium scan-url -t 'https://example.com/p?id=1' -m xss-light-url-params -m sqli
```

Discover what's available before you filter:

```bash theme={null}
# List modules whose id/name/description/tag matches a term
vigolium module ls xss
vigolium module ls aem

# Dump every unique tag you can pass to --module-tag
vigolium module ls --tags

# Full descriptions + confirmation criteria for matched modules
vigolium module ls graphql -v
```

By default a module only fires when the target's detected tech stack matches it (so the GraphQL, AEM, and IIS modules stay dormant on unrelated hosts). If auto-detection misses the stack, add `--no-tech-filter` to run the selected modules regardless (this is auto-enabled by `--intensity=deep`). `-m` matches loosely (`-m xss` selects every XSS module); pass a full ID like `-m xss-light-url-params` to pin exactly one. See [Modules](https://docs.vigolium.com/native-scan/modules-reference.md).

***

## 10. Run only specific phases (or skip some)

Use `--only` to run a subset of phases, or `--skip` to exclude phases from an otherwise-full scan. Both accept comma-separated phase names and aliases.

```bash theme={null}
# Phase isolation: run only one phase
vigolium scan -t https://example.com --only discovery
vigolium scan -t https://example.com --only known-issue-scan
vigolium scan -t https://example.com --only dynamic-assessment

# Skip specific phases (aliases like kis = known-issue-scan are accepted)
vigolium scan -t https://example.com --skip discovery,spidering,kis
```

Canonical phase names and their accepted aliases:

| Phase | Aliases |
| - | - |
| `discovery` | `deparos`, `discover` |
| `spidering` | `spitolas` |
| `known-issue-scan` | `cve`, `kis`, `known-issues` |
| `dynamic-assessment` | `audit`, `dast`, `assessment` |
| `extension` | `ext` |
| `external-harvest`, `ingestion` | — |

`dynamic-assessment` is the canonical name for the module-based vulnerability-scanning phase (formerly `audit`). The same phase names work as the argument to `vigolium run <phase>`, e.g. `vigolium run cve`.

***

## 11. Run a JavaScript extension only

Load one or more custom JS extensions with `--ext` (repeatable) and restrict the run to the extension phase with `--only extension`, no built-in modules, just your script.

```bash theme={null}
# Run only your extension against the target
vigolium scan -t https://example.com --only extension --ext custom-check.js

# Load several extensions
vigolium scan -t https://example.com --only extension \
  --ext custom-check.js --ext another-check.js
```

`--ext` is a global flag, so it works on any scan command. Drop `--only extension` to run your extension **alongside** the built-in modules. See [Writing Extensions](https://docs.vigolium.com/customization/writing-extensions.md) for the `vigolium.*` API.

***

## 12. Content discovery only

Run **only** the discovery/fuzzing phase, no crawling, no vulnerability modules. The most direct way is `vigolium run discover`, the phase runner: it executes a single named phase and nothing else. Point it at a wordlist with `--discovery-wordlist`.

```bash theme={null}
# Discovery-only against a whole host (brute-force paths from a wordlist)
vigolium run discover -S -t https://example.com --discovery-wordlist ~/Tools/contents/fast.txt

# Fuzz a SPECIFIC insertion point with an inline FUZZ marker in the URL —
# each word replaces FUZZ (here: /api/<word>/users)
vigolium run discover -S --discovery-wordlist ~/Tools/contents/fast.txt \
  -t 'https://example.com/api/FUZZ/users'
```

The **`FUZZ` marker** works anywhere in the target path: put it where you want the wordlist injected. With no marker, vigolium fuzzes off the target's directory (equivalent to appending `/FUZZ`). You can get the same discovery-only behavior on the full `scan` command with `--only discovery --discover`:

```bash theme={null}
# Same idea via `scan`: run every phase-gate off except discovery
vigolium scan -t https://example.com --only discovery \
  --discover --discovery-wordlist ~/.vigolium/wordlists/fuzz.txt

# Discovery as part of a full scan (fuzz, then keep going into vuln scanning)
vigolium scan -t https://example.com --discover --discovery-wordlist ~/.vigolium/wordlists/fuzz.txt
```

Separately from path fuzzing, `scan` can sweep **alternate HTTP(S) ports** on the target hosts so a service on a non-standard port is discovered and scanned. The sweep runs at `--intensity deep` or with `--follow-subdomains`; `--port-sweep-ports` overrides which ports it probes (comma-separated, in addition to the standard `80`/`443`):

```bash theme={null}
# Discover and scan services on alternate ports (deep intensity)
vigolium scan -t https://example.com --intensity deep --port-sweep-ports 80,443,8080,8443
```

`vigolium run <phase>` runs one phase in isolation (`discover` is an alias for `discovery`; see [section 10](#10-run-only-specific-phases-or-skip-some) for the full phase/alias list). `-S/--stateless` keeps it throwaway (nothing written to your project DB); combine with `--format fs` or `-o` to persist the discovered surface for later scans. `--discovery-wordlist` enables on-the-fly fuzzing; the `FUZZ` marker pins the exact insertion point. See [Discovery phase](https://docs.vigolium.com/native-scan/phases/discovery.md).

***

## 13. Add custom HTTP headers

Inject headers, such as auth tokens or cookies, with `-H/--header` (repeatable). Works on `scan`, `scan-url`, and `scan-request`.

```bash theme={null}
# One or more custom headers on every request
vigolium scan -t https://example.com \
  -H 'Authorization: Bearer eyJhbGciOi...' \
  -H 'X-Api-Key: secret' \
  -H 'Cookie: session=abc123'
```

`-H/--header` — like the other repeatable value flags (`-t/--target`, `-T/--target-file`, `--auth`, `--auth-file`, `--spec-header`, `--cookie`) — takes each value **verbatim**: commas are **literal**, so a comma-bearing header/cookie value or a `?ids=1,2,3` URL survives intact. Pass multiple values by **repeating the flag**, never by comma-joining them.

For richer authenticated scans (login flows, token refresh, multi-step sessions), use an auth session file instead, see [Authentication](https://docs.vigolium.com/native-scan/authentication.md) and the `vigolium auth` command.

***

## 14. Control scan speed & duration

Cap the wall-clock time with `--scanning-max-duration`, and tune throughput with `-c/--concurrency`, `-r/--rate-limit`, and `--max-per-host`.

```bash theme={null}
# Override max scan duration
vigolium scan -t https://example.com --scanning-max-duration 2h

# Adjust concurrency and rate limit
vigolium scan -T targets.txt -c 100 --rate-limit 200 --max-per-host 5
```

| Flag | Default | Effect |
| - | - | - |
| `--scanning-max-duration` | `0` (use config) | Hard cap on total scan wall-clock time (e.g. `30m`, `1h`, `2h`) |
| `-c` / `--concurrency` | `25` | Number of concurrent scan workers |
| `-r` / `--rate-limit` | `100` | Maximum HTTP requests per second (global) |
| `--max-per-host` | `50` | Maximum concurrent requests to any single host |
| `--no-waf-pacing` | `false` (pacing on) | Disable proactive WAF/CDN pre-throttling (reactive back-off after a confirmed block still applies) |

Lower `--rate-limit` and `--max-per-host` to stay gentle on fragile targets; raise `-c` and `--rate-limit` to go faster against robust infrastructure. Under `-P/--parallel`, each child keeps its own `--concurrency`, so real in-flight requests are roughly `P × --concurrency`.

**The default concurrency changed to `25` in v0.4.7.** It now comes from one shared constant; the CLI, the `scanning_pace` config, the REST API and the discovery source had drifted to 50/40/50/50, so the same scan ran at a different speed depending on which one started it. Pass `-c 50` to keep the old CLI pace.

**Trust the banner's per-phase budget (since v0.4.8).** `--spider-max-time` and `--discover-max-time` now win on the pre-scan `Phases:` line exactly as they win in the phase. Before v0.4.8 the banner rendered the `scanning_pace` slice instead, so `--spider-max-time 5m` printed `6m0s` next to **Spidering** while the phase crawled for the 5m you asked for.

**WAF-aware pacing.** The first time earlier-phase traffic fingerprints a host behind a recognized CDN/WAF edge (CloudFront, Cloudflare, Akamai, Imperva/Incapsula, Sucuri, or Azure Front Door — detected from headers on ordinary `200`s), the per-host rate limiter **proactively** drops that host's concurrency to `MaxPerHost/4` and ramps back up on healthy responses, so an aggressive active phase can't burst the edge into a rate-based block that hides findings. A one-time-per-host `[waf-pacing-armed]` notice prints the drop (e.g. `40→10`) to stderr and the session log. Pass `--no-waf-pacing` to turn off this proactive pre-throttle — the reactive back-off after a *confirmed* WAF block still applies. Global flag on `scan` / `scan-url` / `scan-request` / `run` / `ingest`.

***

## 15. Inspect & change any config value

Vigolium settings live in `~/.vigolium/vigolium-configs.yaml`. Read them with `vigolium config view` (alias for `config ls`) and write them with `vigolium config set <key> <value>` using dot-notation — no need to hand-edit the YAML.

```bash theme={null}
# View everything, or filter by a substring / fuzzy key match
vigolium config view
vigolium config view notify
vigolium config view database.sqlite

# Filter with a glob pattern (matches the full key or any dot-segment)
vigolium config view 'oast*'
vigolium config view 'kno*'          # → known_issue_scan.*

# Reveal redacted secrets (tokens, API keys) in plaintext with --show-secrets
vigolium config view notify --show-secrets
```

Set values with dot-notation keys — the three forms below are equivalent, so you can copy a line straight out of `config view` output:

```bash theme={null}
vigolium config set notify.enabled true
vigolium config set database.driver postgres
vigolium config set server.service_port 8080

# List-valued keys take comma-separated values
vigolium config set notify.severities high,critical

# 'key = value' and 'key=value' also work (paste-friendly)
vigolium config set 'oast.server_url = your-oast-domain.com'
```

`config view` sorts keys and prints the active config file path at the bottom. Sensitive values (API keys, tokens, credentials) show as `[redacted]` unless you pass `--show-secrets`, which reveals them in plaintext and prints a warning to stderr (the generic `-F/--force` no longer reveals secrets). `config set` validates the key and writes it back to the same file. Reset everything to clean defaults with `vigolium config clean`. See [Configuration](https://docs.vigolium.com/getting-started/configuration.md) for the full key reference.

***

## 16. Set a custom OAST domain

Out-of-band callback detection (SSRF, blind RCE, OOB SQLi, etc.) uses an [interactsh](https://github.com/projectdiscovery/interactsh) server, `oast.pro` by default. Point Vigolium at your own server with the `oast.server_url` / `oast.token` config keys:

```bash theme={null}
# Point Vigolium at your own interactsh / OAST server
vigolium config set oast.server_url your-oast-domain.com
vigolium config set oast.token your-oast-token
```

Or set it directly in `~/.vigolium/vigolium-configs.yaml`:

```yaml theme={null}
oast:
  enabled: true
  server_url: your-oast-domain.com
  token: your-oast-token
```

Config values support `${VAR}` / `${VAR:-default}` expansion, so you can keep the domain and token in environment variables instead of writing them into the file:

```yaml theme={null}
oast:
  server_url: ${VIGOLIUM_OAST_DOMAIN:-oast.pro}
  token: ${VIGOLIUM_OAST_TOKEN}
```

OAST is enabled by default (`oast.enabled: true`). The token is optional (only needed by servers that require auth). See the full field list, poll interval, grace period, and blind-XSS payload source, in [Configuration → `oast`](https://docs.vigolium.com/getting-started/configuration#oast).

***

## 17. Generate a static HTML report

Add `--format html` with `-o/--output` to render a self-contained, ag-grid HTML report. You can produce it **during a scan**, or after the fact from data already stored or imported.

```bash theme={null}
# During a scan (combine formats, e.g. jsonl,html)
vigolium scan -t https://example.com --format html -o report.html

# From data already in the database
vigolium export --format html -o report.html --report-title "Acme Q3 Scan"

# From an imported audit / JSONL / SQLite, in one step
vigolium import ./audit-output/ --format html -o report.html

# One consolidated report across many standalone scan files (no import needed)
vigolium export --glob-db 'scans/*.sqlite' --format html -o report.html
```

Brand and filter the report with the same flags across `export` / `import`:

```bash theme={null}
vigolium export --format html -o report.html \
  --report-title "Acme External Scan" \
  --report-target https://acme.example.com \
  --severity critical,high \
  --search sqli
```

Need several formats? `--format` is a comma-separated list, and the database is read **once** for all of them:

```bash theme={null}
vigolium export --format html,markdown,bundle -o acme-q3
# → acme-q3.html   acme-q3.md   acme-q3.tar.gz
```

With more than one format, `-o` is a shared **base path** (each format appends its own extension) and becomes required — one `-o` can't name three files. A single format still uses `-o` verbatim. `{ts}` expands once for the whole run, so a slow `pdf` render lands on the same timestamp as its siblings, and if one format fails the others are still written.

HTML requires `-o/--output`. Other report formats: `report`, `pdf` (rendered via headless Chrome), and `markdown` (alias `md`). The output path accepts `gs://<project>/<key>` URLs and a `{ts}` timestamp placeholder. See [Output & Reporting → HTML](https://docs.vigolium.com/getting-started/output-and-reporting.md#html).

***

## 18. Notify (webhook) when a scan completes

The `webhook` notify provider fires **one POST per scan** when it reaches a terminal state (completed or failed), regardless of severity, perfect for CI pipelines and dashboards.

```bash theme={null}
# Fire a webhook POST when each scan finishes
vigolium config set notify.enabled true
vigolium config set notify.provider webhook
vigolium config set notify.webhook.url https://hooks.example.com/vigolium
```

Or configure it in `~/.vigolium/vigolium-configs.yaml`:

```yaml theme={null}
notify:
  enabled: true
  provider: webhook               # webhook | telegram | discord ("" = all configured)
  webhook:
    url: https://hooks.example.com/vigolium
    authorization: "Bearer xxx"   # optional Authorization header
    timeout_sec: 10
  severities: [high, critical]    # gate the per-finding telegram/discord alerts
```

`webhook` fires once per scan regardless of severity; `telegram` and `discord` instead fire **per finding**, gated by `notify.severities`. Telegram/Discord also honor env-var fallbacks (`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `DISCORD_WEBHOOK_URL`), so you can keep tokens out of the config file. See [Configuration → `notify`](https://docs.vigolium.com/getting-started/configuration#notify).

***

## 19. Update Vigolium

`vigolium update` re-runs the official installer to fetch the latest release binary, then refreshes the local nuclei-templates checkout used by the known-issue scan.

```bash theme={null}
# Update the binary + nuclei templates to the latest release
vigolium update

# Only refresh nuclei templates (skip the binary)
vigolium update --skip-binary

# Only reinstall the binary (skip templates)
vigolium update --skip-templates

# Check the version you're running
vigolium version
```

`vigolium update` runs the same installer as `curl -fsSL https://vigolium.com/install.sh | bash`, installing to `~/.local/bin/vigolium` (checksum-verified). **Homebrew, npm, and Docker** installs upgrade through their own tooling instead: `brew upgrade vigolium`, `npm update -g @vigolium/vigolium`, or `docker pull j3ssie/vigolium:latest`. Vigolium also checks for a newer release on startup (at most once/day); silence it with `VIGOLIUM_DISABLE_UPDATE_CHECK=1`, or auto-apply and re-exec with `VIGOLIUM_AUTO_UPDATE=1`.

***

## 20. How do I use Burp Suite with Vigolium?

The **Vigolium Burp Suite extension** turns Burp into a front-end for a running Vigolium server: as you browse, requests/responses forward into Vigolium (and, with `--mirror-fs`, onto disk), you launch native and agentic scans straight from Burp's right-click menu, and findings stream back into both Burp and the Web UI. It doesn't run the scanner inside Burp's JVM — it forwards traffic and polls the server, so scans keep running even after Burp closes.

**1. Start a Vigolium server**

```bash theme={null}
# The ingestion server the extension talks to (add --mirror-fs to also write traffic to disk)
export VIGOLIUM_API_KEY=my-secret-key
vigolium server --mirror-fs output-dir
```

**2. Load the JAR into Burp**

Grab `burp-vigolium.jar` from [github.com/vigolium/burp-vigolium](https://github.com/vigolium/burp-vigolium), then **Extensions → Installed → Add → Extension type: Java**. A **Vigolium** tab appears.

**3. Point it at your server**

Open **Vigolium → Settings**, enter the **Server URL** (default `http://127.0.0.1:9002`) and **API Key**, then click **Test Connection**.

What the extension can do:

| Feature | How |
| - | - |
| **Send one request** to ingestion / native scan / agentic scan | Right-click in Proxy History or Repeater — or the `Ctrl+Alt+V` / `Ctrl+Alt+N` / `Ctrl+Alt+A` hotkeys |
| **Forward everything** through Burp Proxy automatically | **Bridge → Proxy Interception → Turn ON** (pair with **In-scope only** + filter rules) |
| **Snapshot the whole Target Site map** into Vigolium | **Bridge → Target Site Map Snapshot** (`Ctrl+Alt+S`, or auto every N minutes) |
| **Bidirectional live bridge** — read Burp history from the CLI, or push Vigolium traffic back into Burp's Site map | Enable **Bridge → Enable live bridge** (loopback `http://127.0.0.1:9009`), then drive it from the CLI |
| **Send exact bytes through Burp's engine**, or stage traffic into Repeater / Organizer | `replay` / `fuzz` / `finding` with `--send-via-burp`, `--to-repeater`, `--to-organizer`, or `--push-to-burp` (all need `--burp-bridge-url`) |
| **Do all of the above from Caido** | Install the [Caido plugin](https://docs.vigolium.com/getting-started/caido-plugin.md) — same protocol, same flags, `--caido-bridge-url` alias |

Once the loopback bridge is enabled in Burp, drive it from Vigolium with the `--burp-bridge-url` flag (export `VIGOLIUM_BURP_BRIDGE_URL` only if you'd rather not repeat the flag):

```bash theme={null}
# Merge live Burp Proxy history into the local traffic view
vigolium traffic --burp-bridge-url http://127.0.0.1:9009

# Persist the traffic selected by the active filters into Vigolium's DB
vigolium traffic --burp-bridge-url http://127.0.0.1:9009 --save-to-vigolium-db

# Copy the selected Vigolium DB traffic back into Burp's Target Site map
vigolium traffic --burp-bridge-url http://127.0.0.1:9009 --save-to-burp

# Save a mutated replay + its fresh response straight into Burp's Site map
vigolium replay --finding-id 42 --burp-bridge-url http://127.0.0.1:9009 --save-to-burp

# Send a replay through Burp's OWN HTTP engine — exact bytes (--http-mode http1 for desync)
vigolium replay -i req.txt --burp-bridge-url http://127.0.0.1:9009 --send-via-burp --http-mode http1

# Push a finding's evidence request+response into Burp's Organizer for manual confirmation
vigolium finding xss --burp-bridge-url http://127.0.0.1:9009 --push-to-burp
```

Pairs naturally with [section 1 (live filesystem mirror)](#1-mirror-ingested-traffic-findings-to-a-live-filesystem-tree) and [section 3 (passive/secret scan on forwarded traffic)](#3-passive-secret-scan-on-forwarded-traffic): run `vigolium server -S --passive-only --mirror-fs output-dir -A` and the extension feeds it while findings and readable request/response files appear in real time. **Full walkthrough** — install, connect, the three dispatch workflows, proxy forwarding, site-map snapshots, and the live bridge: [Using Vigolium with Burp Suite](https://docs.vigolium.com/getting-started/burp-suite.md).

### Using Caido instead

The [**Vigolium Caido plugin**](https://github.com/vigolium/caido-vigolium) does everything above from Caido: install `caido-vigolium.zip` via **Plugins → Install Package → From File**, set the server URL + API key under **Vigolium → Settings**, and dispatch with `⌘⌃V` / `⌘⌃N` / `⌘⌃A` (`Ctrl+Alt+…` on Windows/Linux) or the `⌘K` palette. The live bridge is on by default on the same loopback port, so every bridge command works unchanged — `--caido-bridge-url` is an alias for `--burp-bridge-url`:

```bash theme={null}
# Merge live Caido traffic into the local traffic view, then keep only the Caido rows
vigolium traffic --caido-bridge-url http://127.0.0.1:9009
vigolium traffic --caido-bridge-url http://127.0.0.1:9009 --source caido

# One-shot persist of everything the bridge exposes
vigolium import --caido-bridge-url http://127.0.0.1:9009

# Issue exact bytes through Caido's HTTP stack, staged into a Replay session
vigolium replay -i req.txt --caido-bridge-url http://127.0.0.1:9009 --send-via-burp --to-repeater
```

Bridge rows are labelled by the vendor that actually answered (`source: caido` vs `burp`), so one `--source` filter separates them — including traffic the plugin *pushed* to the server, which sets `X-Vigolium-Source: caido`. Record UUIDs keep the `burp:` prefix for both, since that names the bridge route rather than the vendor. **Full walkthrough:** [Using Vigolium with Caido](https://docs.vigolium.com/getting-started/caido-plugin.md).

***

## 21. Triage findings with a coding agent (Claude, Codex)

Vigolium is built to be shelled out to by an LLM/coding agent. The `finding` and `traffic` read commands emit **compact, token-aware** output under `-j/--json` (headers kept, bodies bounded to \~1–2 KB with `body_size`/`body_sha256`/`body_truncated`, binary bodies stubbed, findings windowed to a `response_evidence` snippet), so an agent can survey dozens of findings without blowing its context window and pull full detail only for the ones worth confirming.

Teach your agent to drive Vigolium by installing the **`vigolium-scanner` skill**. The copy embedded in your binary always matches the CLI version, so prefer the native installer:

```bash theme={null}
# Install the embedded skill (recommended — version-matched to your binary)
vigolium skills install --agent claude --scope project   # --agent claude|codex|agents, --scope project|global
vigolium skills                                          # list what's bundled

# Or pull the latest from the repo (github.com/vigolium/skills)
bunx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes
```

A two-pass triage loop that keeps tokens in check:

```bash theme={null}
# Pass 1 — cheap survey: rank many findings, only the fields you need.
vigolium finding --min-severity high --json --compact \
  --fields id,severity,module_id,url,matched_at

# Pass 2a — deep-read one finding as a self-contained, parseable bundle
# (finding + linked request/response embedded, bodies still bounded).
vigolium finding --id 42 --json --with-records

# Pass 2b — deep-read as Markdown (verbatim request/response in fenced http blocks,
# plus the What/Exploit/Fix prose) — often the nicest format for an agent or a
# human to judge a single finding. Window it with -S --compact so a big page
# doesn't flood the context.
vigolium finding -S --db ./scan.jsonl --id 42 --markdown --compact
```

Output-shaping flags on `finding` / `traffic` / `db ls`:

| Flag | Effect |
| - | - |
| `-j`/`--json` | machine-readable compact output (the entry point) |
| `--compact` | metadata only, drop bodies — cheapest survey pass |
| `--fields a,b,c` | project to just these top-level keys, cuts tokens hard |
| `--with-records` | *(finding)* embed the linked HTTP records → self-contained triage bundle |
| `--full-body` | complete decoded bodies (use when writing an exploit — see [section 22](#22-show-how-to-exploit-a-finding)); also un-compacts `--markdown` response bodies |
| `--markdown` | render the finding with request/response in fenced `http` blocks (response bodies compacted to a preview by default) |
| `--tree` *(finding / traffic)* | host/path hierarchy view; recurring findings collapse by title + severity into one `×N` node |
| `--pick 2-4` *(finding)* | narrow to specific 1-based positions after filters + sort (`2`, `1,3`, `2-4`); composes with `--raw`/`--burp`/`--markdown`/`--json` |
| `--search a --search b` | repeatable, AND-combined — each added term further narrows the match |
| `--exclude-search x` | *(finding / traffic)* repeatable inverse of `--search` — drop a row if **any** term appears (also `--exclude-header` / `--exclude-body`) |
| `--severity crit,high` / `--sev h,c` | *(finding; `--severity` on `db ls`)* explicit severity **set** — single-letter shorthands + unambiguous prefixes (`crit`, `me`, `info`) |
| `--min-severity high` | severity **floor** — `high` expands to `high,critical` (contrast the explicit `--severity` set; `--severity` wins if both are set) |
| `--record-kind finding,candidate` | *(finding / `db list`)* filter by record kind — `finding` (default), `candidate`, `observation` (comma-separated) |
| `--module-type active,passive` | *(finding / `db list`)* filter by producing module type — `active`, `passive`, `nuclei`, `agent`, `source-tools`, `oast`, `extension` |
| `--agentic-scan <uuid>` | only findings from a given agent run (expands to the whole run tree) |

Under `--json`, bodies are **always** bounded regardless of `-S`. As of v0.2.1, `--markdown` also **compacts response bodies by default** — the response renders as a window around the finding's `matched_at`/evidence (or a leading preview) rather than a whole page, regardless of `-S`/`--compact`; pass `--full-body` to render bodies whole. The request is always shown whole (it carries the payload). On an interactive terminal the Markdown is syntax-highlighted; piped/redirected output stays plain, greppable Markdown. An agent run (`agent autopilot|swarm|audit`) under `--json` even prints a ready-made follow-up command in its summary: `vigolium finding --agentic-scan <uuid> --json --with-records`. Full guide: [Using Vigolium in your agent](https://docs.vigolium.com/agentic-scan/using-vigolium-in-your-agent.md).

### The JSON envelope

Since **v0.4.5** every `-j/--json` command emits the *same* outer object, so one parser handles all of them. Don't write key fallbacks. **v0.5.3 finished the job** — every remaining command moved onto the envelope and `schema_version` went to `2`.

```jsonc theme={null}
{
  "schema_version": 2,
  "command": "traffic",
  "kind": "read",
  "ok": true,
  "project_uuid": "…",
  "project_scoped": true,
  "project_source": "flag",
  "db_path": "/home/me/.vigolium/database-vgnm.sqlite",
  "total": 39,
  "offset": 0,
  "limit": 100,
  "items": [ … ],
  "query": "vigolium replay -u <uuid>",
  "query_argv": ["vigolium", "replay", "-u", "<uuid>"],
  "generated_at": "2026-09-04T10:11:12.345Z",
  "generated_at_ms": 1788453072345
}
```

| Field | Why it is there |
| - | - |
| `schema_version` | Gate on it. Bumped on any breaking field change — `2` since v0.5.3 |
| `kind` | The document's shape: `read` (a row list, or a one-object answer wrapped as `items: [obj]` with `total: 1`), `mutation` or `scan`. A `mutation` adds `changed`, `action` (`"compact"`, `"push_to_burp"`, …) and `dry_run: true` on a dry run |
| `ok` | `true` on every result document; the error object carries `false`. So `.ok` is a valid branch on **anything** `-j` prints |
| `items` | **The** row array, and the only one — `[]` when empty, never `null`, never an object. Since v0.4.6 the historical keys (`records`, `findings`, `scans`, `rows`, `stats`) are **gone from the default output**: they shipped a second full copy of every row on the wire, which on a 20-record compact read was 19,983 bytes against 7,884 of actual rows. `--json-legacy-keys` (or `VIGOLIUM_JSON_LEGACY_KEYS=1`) brings the alias back, at that cost, for a caller still migrating |
| `project_scoped` | Whether a project filter was applied **at all**, so "no filter" is explicit rather than inferred from an absent `project_uuid` |
| `project_source` | Where the project selection came from: `flag`, `env`, `active_file` (`~/.vigolium/active-project`) or `default`. `active_file` is shared by every shell and agent on the machine, so a document resolved from it also carries a `warnings` entry saying so — pin `--project-uuid` or `VIGOLIUM_PROJECT_UUID` and both go away |
| `db_path` | The database this command actually opened. **Assert it**: the open order ends at one shared default file, so a silent fall-through mixes engagements. Absent for a non-SQLite driver |
| `query` / `query_argv` | A ready follow-up command for the obvious next step, and the same thing pre-split as argv. Run it rather than composing your own. Absent together under `--glob-db` |
| `generated_at` / `_ms` | RFC3339 with **exactly 3** fractional digits, plus an epoch-millisecond sibling. Both compare safely against a JS `toISOString()`; the old microsecond form sorted `…785113Z` *before* `…785Z` |

Commands attach their own keys alongside these (`glob_sources`, `output_budget`, `targets_not_scanned`, …). A key that collides with one of the envelope's own is **dropped** rather than shadowing it.

`db stats -j` uses this envelope too — it used to be the documented exception that dumped its raw struct, and a contract with a hole in it is one consumers special-case forever. Its single-object answer arrives as `items: [obj]` (read `.items[0]`), and `items[0].database` names the file actually opened plus its on-disk size (WAL siblings included).

> [!WARNING]
>
> **Three v0.5.3 changes a v1 parser will notice.**
>
> 1. **`-j` on a scan no longer implies `--format jsonl`.** `scan -j` prints one [scan document](#the-scan-document); for the bulk `{type,data}` stream pass `--format jsonl -o <file>` explicitly.
> 2. **`-j` is compact by default** — one line, no indentation. Pass the global `--pretty` (or set `VIGOLIUM_JSON_PRETTY=1`) when a human is reading it.
> 3. **`command` is always the cobra path** of what ran (`"db list"`, `"extensions lint"`, `"scan status"`), not a hand-typed label. `db list -j` used to say `traffic`.

Validate rather than trust this table: `vigolium schema command traffic` prints the generated JSON Schema for exactly this document.

**Saving it instead of reading it.** `traffic`, `finding` and `db ls` take `-o <path>` alongside `-j`: the document goes to the file, byte-identical to what would have been printed, and stdout gets a receipt instead — `{"artifact":"json_result","output":…,"bytes":…,"sha256":…,"complete":true}`. `complete: false` means the file holds one page, so raise `-n/--limit` (or `-a`) for the whole set; `-o -` forces stdout. The receipt never echoes the document, which is the point of the flag.

```bash theme={null}
vigolium finding -j -n 500 -o findings.json   # ~65 KB to disk, a few lines to stdout
```

Check the contract once at startup, so drift is a startup failure rather than a parse error in production:

```bash theme={null}
vigolium schema command finding   # the generated JSON Schema for what you're about to parse
vigolium version --json           # the cheap form: {version, commit, schema_version, db_schema_version}
```

### The scan document

`scan`, `run`, `scan-url` and `scan-request` under `-j` print **one scan document** when the scan ends — `kind: "scan"`, findings as `items`. This replaced the old `--format jsonl` stream on stdout; ask for the stream explicitly with `--format jsonl -o <file>`.

```jsonc theme={null}
{
  "schema_version": 2, "command": "scan-url", "kind": "scan", "ok": true,
  "scan_uuid": "9551f38a-…",
  "persisted": true, "stateless": false,
  "status": "completed", "completeness": "complete", "reasons": [],
  "targets": [
    { "target": "https://target.example/login", "admitted": true, "reached": true,
      "resolved_target": "https://target.example:443", "findings": 2, "duration_ms": 1840 }
  ],
  "targets_not_scanned": [],
  "phase_outcomes": [],
  "modules": { "selected": 334, "executed": 41 },
  "counts_by_severity": { "critical": 0, "high": 1, "medium": 1, "low": 0, "suspect": 0, "info": 0 },
  "candidates": 3, "observations": 7,
  "errors": [],
  "total": 2, "items": [ /* finding rows, highest severity first */ ],
  "items_truncated": false,
  "plan": null,
  "query": "vigolium finding --scan-uuid 9551f38a-… -j",
  "duration_ms": 1840
}
```

| Field | Read it for |
| - | - |
| `status` | `completed`, `curtailed` (finished but partial — see `reasons`), `failed` or `interrupted` |
| `completeness` / `reasons` / `stop_reason` | **Whether the scan actually covered what you asked for.** A `curtailed` scan still exits `0`, so this is the only place the shortfall shows |
| `items` | Finding rows in the `finding -j` shape, highest severity first, capped at `-n/--limit` (default 200; `0` = no cap). `items_truncated` says the cap bit. `--fields`, `--compact`, `--full-body` and `--max-output-bytes` shape them as on `finding` |
| `total` / `counts_by_severity` | **Exact**, regardless of the `items` cap |
| `targets[]` | Per-target `admitted`, `reached` (`null` when not checked), and `reason` / `code` / `detail` when one was refused or unreachable |
| `modules` | `selected` is what the scan was handed, `executed` how many ran at least once. (`scan-url` used to report `modules_run`, which counted *loaded* modules) |
| `phase_outcomes` | Per-phase status, so one failed phase is visible without reading the log |
| `plan` | The resolved plan the runner stored on the row, verbatim — the same object [`--dry-run`](#planning-a-scan-without-sending-anything) prints. `null` on a direct `scan-url` / `scan-request` run, which resolves no plan |
| `persisted` | `false` under `-S` (the temp store is gone when the process exits, so `db_path` and `query` are omitted too) |

A scan that **fails** still prints this document, with `status: "failed"` and `errors: [{code, message, target?}]`; `ok` stays `true` because it is a result document, and the exit code carries the failure. Only a failure *before any scan existed* — bad config, an unopenable `--db` — prints the error envelope instead.

> [!NOTE]
>
> **A persisted finding has a store `id`; an unpersisted one (`-S`, or a direct run with no store) does not.** Use `finding_hash` as the identity in that case — it is the stable dedup key, and what SARIF fingerprints use.

### Planning a scan without sending anything

```bash theme={null}
vigolium scan -t https://target.example --dry-run -j
vigolium run discovery -t https://target.example --dry-run
```

`--dry-run` resolves the whole plan and prints it, then exits: phases (with *why* each disabled one is off), budgets, pace, modules, scope, auth session names, scope admission and a rough request estimate. It **mints no scan UUID, writes no output file or scan row, materializes no wordlist, runs no login and registers no OAST** — an existing database is only read. Under `-j` the document carries `items` (phases), `plan` (the full object) and `dry_run: true`.

The same object rides the event stream as `scan.plan`, always the second line of a real run, and is stored on the scan row — so `scan status` and the scan document can hand it back afterwards. `vigolium schema plan` prints its schema.

***

## 22. Show how to exploit a finding

Once a finding is confirmed, pull the exact request that triggered it, then re-fire it — verbatim, or with an iterated payload — to build a reproducible proof-of-concept. Start by fetching the finding with full, decoded bodies so you have the complete request to work from:

```bash theme={null}
# Self-contained bundle with COMPLETE bodies — everything needed to write an exploit.
vigolium finding --id 42 --json --with-records --full-body

# Or as a report-ready Markdown PoC (request/response in fenced http blocks).
# --markdown compacts response bodies by default; add --full-body for the whole page.
vigolium finding --id 42 --markdown --full-body > finding-42.md
```

Reproduce the finding by replaying its linked record: `vigolium replay --finding-id` re-sends the exact request behind a finding. To iterate a payload at one insertion point, drive [`vigolium fuzz`](#fuzz-one-request-with-a-custom-payload-set); to override the exact bytes, use `--raw-request`/`--raw-request-file`:

```bash theme={null}
# Re-fire the exact request that produced finding 42, human-readable summary.
vigolium replay --finding-id 42 --pretty

# Prove the injection: iterate one insertion point with a payload class or wordlist.
# (Grab the linked record UUID from `vigolium finding --id 42 --json --with-records`.)
vigolium fuzz -u <record-uuid> --point URL_PARAM:id --class sqli

# Override the reproduction request's exact bytes (e.g. a hand-built PoC).
vigolium replay --finding-id 42 --pretty --raw-request-file exploit.txt

# Send the reproduction through Burp so you can inspect/step it manually.
vigolium replay --finding-id 42 --proxy http://127.0.0.1:8080

# Point the same request at a staging host, carrying an auth session.
vigolium replay --finding-id 42 --pretty \
  --target https://staging.example.com --auth-session my-session
```

If you mirrored traffic to disk ([section 1](#1-mirror-ingested-traffic-findings-to-a-live-filesystem-tree)) or used `--format fs`, each `<id>.req` file is **directly replayable**: its leading `@target <scheme>://<authority>` line names the destination, so strip line 1 to get raw HTTP you can hand to `curl`, an agent, or feed back into `vigolium replay --raw-request-file <file>` (pass the target from that first line with `-t`).

With the [`vigolium-scanner` skill](#21-triage-findings-with-a-coding-agent-claude-codex) installed, you can ask your agent in plain language — *"confirm finding 42 is exploitable and give me a PoC"* — and it will run the `finding`, `fuzz`, and `replay` commands above, iterate the payload, and compare responses for you. Use `vigolium fuzz` for payload / insertion-point work; use `--raw-request`/`--raw-request-file`/`-i` to replace the whole request when you need full control. Only test targets you are authorized to assess.

***

## 23. Run an exact set of modules (passive-only, JS beautify)

[Section 9](#9-target-one-vulnerability-class-or-technology)'s `-m/--modules` is a **fuzzy** filter that only narrows the **active** modules (passive modules always stay "all"). When you want to run a **precise** set — including passive modules on their own — reach for `--module-id` (exact match against **both** the active and passive registries, repeatable) and `--passive-only`.

```bash theme={null}
# Run EXACTLY these modules and nothing else (repeatable, or comma-separated)
vigolium scan-url -S -t https://example.com --module-id js-beautify --module-id secret-detect
vigolium scan-url -S -t https://example.com --module-id js-beautify,secret-detect

# JavaScript beautify only — unminify/unpack a bundle into readable modules
vigolium scan-url -S -t https://example.com/app.min.js --module-id js-beautify

# Passive modules only — no active traffic is sent (secrets, headers, disclosure, ...)
vigolium scan-url -S -t https://example.com --passive-only

# Passive-only, narrowed to a specific passive module
vigolium scan-url -S -t https://example.com --passive-only --module-id secret-detect
```

`-m` vs `--module-id`, side by side:

| Flag | Matching | Registries it selects from | Repeatable |
| - | - | - | - |
| `-m` / `--modules` | fuzzy (substring on id/name) | **active** only (passive stays "all") | yes |
| `--module-id` | **exact** module ID | **both** active **and** passive | yes |

`--module-id` requires an **exact** id — an unknown value warns (`does not match any known module`) rather than silently matching nothing, so reach for `-m` when you want loose matching. Find exact ids with `vigolium module ls <term>`. `--passive-only` and `--no-passive` are mutually exclusive (nothing would run). Available on `scan`, `scan-url`, and `scan-request`. For fuzzy `-m` / `--module-tag` filtering, see [section 9](#9-target-one-vulnerability-class-or-technology).

***

## 24. Scan a URL and print findings to the console

For a quick single-URL scan where you just want the results on screen, add `--print-finding`. After the scan it renders each finding to stdout as **Markdown** — description, matched evidence, and the raw request/response in fenced `http` blocks — exactly like `vigolium finding --markdown` ([section 21](#21-triage-findings-with-a-coding-agent-claude-codex)), with no follow-up command and nothing persisted. Pair it with `-S` (throwaway database) and `--silent` (drop the banner and progress noise) for clean output.

```bash theme={null}
# Quick scan → findings printed inline as Markdown, nothing persisted
vigolium scan-url -S -t https://example.com -m js-beautify -m secret-detect --silent --print-finding

# Same, but pin the EXACT modules (--module-id also restricts passive; see section 23)
vigolium scan-url -S -t https://example.com \
  --module-id js-beautify --module-id secret-detect \
  --silent --print-finding

# Passive-only sweep of one URL, printed to the console
vigolium scan-url -S -t https://example.com --passive-only --silent --print-finding

# Also dump the scan's HTTP traffic — as a host/path tree, or raw request/response pairs
vigolium scan-url -S -t https://example.com --silent --print-traffic-tree
vigolium scan-url -S -t https://example.com --silent --print-traffic
```

`--print-finding` works on `scan`, `scan-url`, `scan-request`, and `run`. It prints **nothing** when the scan finds nothing, so `--silent --print-finding` yields either the findings or an empty screen — ideal for a fast triage loop. The Markdown is identical to `vigolium finding --markdown` ([section 21](#21-triage-findings-with-a-coding-agent-claude-codex)); to save it, redirect stdout (`... --print-finding > findings.md`). Enabling it routes the scan through the full runner so each finding's linked request/response is available to render, which is why it pairs naturally with `-S`. The same commands take **`--print-traffic-tree`** (host/path hierarchy, like `traffic --tree`) and **`--print-traffic`** (raw request/response pairs, like `traffic --raw`) to dump the run's traffic after it finishes — set both to print the tree first, then the raw pairs.

***

## 25. View HTTP traffic in the database

Everything Vigolium scans, ingests, or records lands in the database. Browse it with `vigolium traffic` (aliases `tf`, and `vigolium db ls http_records` — `db ls` takes a positional table name; the old `--table` form is deprecated). With no flags it shows the 100 most recent records, newest first; add filters, search, or a display format to narrow and shape the output.

```bash theme={null}
# Browse recent traffic (newest first, capped at 100)
vigolium traffic

# List EVERY stored record (lift the -n/--limit cap), or page through
vigolium traffic --all
vigolium traffic -n 50 --offset 100

# Host/path hierarchy tree
vigolium traffic tree
```

Search and filter to find the records you care about:

```bash theme={null}
# Fuzzy search across the full request/response — URL, path, headers, and body (positional term or --search)
vigolium traffic admin
vigolium traffic --search "/api/users"

# Search within header names/values, or request/response body content
vigolium traffic --header "Authorization"
vigolium traffic --body "password"

# Exclude (inverse of --search/--header/--body): drop rows where the term appears
vigolium traffic --search api --exclude-search "/health"     # keep api traffic, drop the health checks
vigolium traffic --exclude-search .css --exclude-search .js  # repeatable — drop if ANY term matches
vigolium traffic --exclude-header Authorization              # drop rows carrying an Authorization header

# Filter by host, status, method, path, source, or date range
vigolium traffic --host "*.example.com"
vigolium traffic --status 401,403,500 --method POST
vigolium traffic --source ingest-proxy
vigolium traffic --from 2026-01-01 --to 2026-02-01

# Relative offsets and named days work too (aliases: --since / --until)
vigolium traffic --since 2d              # last two days
vigolium traffic --since today           # since local midnight
vigolium traffic --since '1h30m ago'
vigolium finding --since yesterday --min-severity high

# Combine filters: POSTs to the API that returned 200 and leaked a token
vigolium traffic --host api.example.com --method POST --body "token" --status 200

# COUNT instead of listing — same filters, a dozen integers back
vigolium traffic --group-by status_code --host api.example.com
vigolium traffic --group-by host --group-limit 10
vigolium traffic -j --group-by response_content_type

# Rank by attackable surface (0-100, reproducible — unlike --min-risk's batch rank)
vigolium traffic --sort surface_score -n 50
vigolium db ls --min-surface 50 --sort surface_score -n 20

# Select one exact URL — equality, repeatable, applied before pagination
vigolium traffic --url 'https://api.example.com/v1/me'

# Extract one stored message (no re-send) and save a -j result to disk
vigolium traffic body --uuid <uuid> -o response.json
vigolium traffic headers --uuid <uuid> --name set-cookie -j
vigolium finding -j -n 500 -o findings.json
```

**`--header` and `--body` each search only their own half of the message** (since v0.4.7) — `--header password` no longer matches a response body. `--search` spans the whole exchange. And every search term is matched **literally**: `%` and `_` are ordinary characters, so `--body 'api_key'` does not also match `api-key`. `--host`/`--path` stay patterns, where `*` is the wildcard. See [What each search flag actually searches](https://docs.vigolium.com/others/cli-references.md#what-each-search-flag-actually-searches).

**Pull one message instead of a whole record.** `vigolium traffic body --uuid <uuid> -o resp.json` writes the exact bytes (gzip-decoded by default; `--representation stored` keeps them compressed), and `traffic headers --uuid <uuid> -j` returns an **ordered array** so duplicate `Set-Cookie` headers survive. Neither re-sends anything — that is `replay`. See [Extracting one message](https://docs.vigolium.com/others/cli-references.md#extracting-one-message-traffic-body-traffic-headers).

**Never dump rows just to count them.** `--group-by <field>` runs the same filters the listing would (`host`, `method`, `status_code`, `response_content_type`, `source`, `scan_uuid`, `ip`, `is_authenticated`), so the buckets describe exactly the rows `traffic` would have shown. Under `-j`, `items` is the bucket list (`{value, count}`) and `total_records` / `other_groups` / `other_records` say what was counted and what `--group-limit` left out.

`--from`/`--to` (aliases `--since`/`--until`) work the same on `finding`, `traffic`, `db ls`, `db export`, and `replay`. Bare dates and wall-clock times resolve in your **local** zone, and a bare date on the upper bound snaps to end-of-day — so `--from 2026-08-01 --to 2026-08-01` is the whole of Aug 1, not an empty range. See [Date filtering](https://docs.vigolium.com/others/cli-references.md#date-filtering).

Choose how each record is rendered:

```bash theme={null}
# Burp Suite-style colored request/response, or full raw HTTP
vigolium traffic --burp --host example.com -n 5
vigolium traffic --raw --host example.com -n 5

# Pick / drop columns
vigolium traffic --columns host,method,path,status,size
vigolium traffic --exclude-columns source,words

# Machine-readable JSON for scripting / jq (compact, token-aware bodies)
vigolium traffic -j
vigolium traffic --host api.example.com --status 200 -j
```

Read a colleague's standalone export without touching your own DB by pointing `-S` at the file (a `.jsonl` export or a standalone `.sqlite`), or read across many at once with `--glob-db`:

```bash theme={null}
vigolium traffic -S --db scan.sqlite
vigolium traffic --glob-db 'scans/*.sqlite'
```

All filter flags (`--host`, `--status`, `--method`, `--path`, `--source`, `--search`, `--header`, `--body`, `--exclude-search`, `--exclude-header`, `--exclude-body`, `--from`/`--to`) stack, and `--sort` + `--asc` control ordering. `--search` spans the **full request/response** — URL, path, headers, and body (for `finding` it also covers module metadata and linked records); repeated `--search` terms AND-narrow, while repeated `--exclude-search` terms drop a row if **any** matches. Add `--replay` to re-send the matched records instead of listing them (see [section 2](#2-replay-all-stored-traffic-through-burp-suite)). The compact `-j/--json` output is the same agent-friendly serializer described in [section 21](#21-triage-findings-with-a-coding-agent-claude-codex).

Prune the database when you're done — a selector is always required, so a bare `db clean` is rejected:

```bash theme={null}
vigolium db clean --scan-uuid my-scan        # delete one scan's records
vigolium db clean --host api.example.com     # delete by host
vigolium db clean --all --force              # empty every data table
vigolium db reset --force                    # delete + recreate the DB file (SQLite; VACUUMs automatically)
```

***

## 26. Set up the AI agent (Codex or Claude CLI)

Vigolium's AI features (autopilot, swarm, source-code audit, query) all run through one in-process runtime called **olium**, which talks to a provider. Pick one provider and give it credentials. The two most common setups are below; verify any of them with `vigolium ol -p 'what model are you running'`.

**Method 1 — Codex (cheapest, with a ChatGPT subscription).** If you already use OpenAI's **Codex CLI**, vigolium reuses the same OAuth credential file, no API key, refresh handled automatically. This is the recommended default.

```bash theme={null}
# 1. Install the Codex CLI (one-time) and log in.
codex login
codex exec 'hello'             # sanity check — should print a model name

# 2. Pin vigolium to it (defaults already match; this just makes it explicit).
vigolium config set agent.olium.provider openai-codex-oauth
vigolium config set agent.olium.oauth_cred_path ~/.codex/auth.json
vigolium config set agent.olium.model gpt-5.5

# 3. Verify.
vigolium ol -p 'what model are you running'
```

**Method 2 — Claude CLI (`claude` shell-out).** Delegate to the `claude` binary on your `$PATH`, so olium uses whatever auth `claude` itself is configured with (plus your personal `CLAUDE.md`, MCP servers, and installed skills).

```bash theme={null}
which claude   # must resolve

vigolium config set agent.olium.provider anthropic-cli   # alias: anthropic-claude-cli
vigolium config set agent.olium.model claude-opus-4-7

vigolium ol -p 'what model are you running'
```

Once `vigolium ol` returns a model name, every agent command works: `vigolium agent autopilot`, `vigolium agent swarm`, `vigolium agent query`, and `vigolium agent audit`.

These are two of several providers, olium also supports the Claude Code Agent SDK bridge, Anthropic OAuth/API-key, and any OpenAI-compatible backend (Ollama, OpenRouter, LM Studio, vLLM). If you already pay for a coding agent (Codex, Claude, Grok, …), the recommended path is to route it through a local OpenAI-compatible proxy instead of buying a new key: [Set up the agent → reuse your subscription](https://docs.vigolium.com/getting-started/setup-agent.md#recommended-reuse-the-coding-agent-subscription-you-already-have). For the full provider matrix, credential handling, and the source-code audit drivers, see the [setup guide](https://docs.vigolium.com/getting-started/setup-agent.md).

***

## 27. Export existing SQLite data to a browsable `fs` tree

Already have a scan sitting in a `.sqlite` database (your project DB or a standalone export)? Turn it into the same **flat, browsable filesystem tree** the live mirror produces ([section 1](#1-mirror-ingested-traffic-findings-to-a-live-filesystem-tree)), so a coding agent (or plain `ls`/`grep`/`jq`) can investigate it with no DB. Use `--format fs` on `export` or `db export`, it writes two sibling directories off the `-o` base (defaulting to `vigolium` in the cwd when no `-o` is given, so `-o run` yields `run-traffic/` + `run-findings/`).

```bash theme={null}
# Whole project DB → run-traffic/ + run-findings/
vigolium export --format fs -o run

# A standalone .sqlite export, read-only (project scoping off, nothing written back)
vigolium export -S --db scan.sqlite --format fs -o run

# Many standalone exports merged into one tree (--glob-db implies -S)
vigolium export --glob-db 'scans/*.sqlite' --format fs -o run

# Filtered export via `db export` — honors --host/--status/--method/--severity/--search/--limit
vigolium db export --format fs -o run --severity high,critical --host api.example.com

# Drop the .resp.* files (request-only tree)
vigolium export --format fs -o run --omit-response
```

What you get under each `<base>-traffic/<host>/` and `<base>-findings/<host>/`:

| Path | Contents |
| - | - |
| `<base>-traffic/<host>/<id>.req` | Raw request (leading `@target <scheme>://<authority>` line, then the request verbatim, replayable by stripping line 1) |
| `<base>-traffic/<host>/<id>.resp.headers` | Status line + response headers |
| `<base>-traffic/<host>/<id>.resp.body` | Response body (gzip-decoded so it greps clean) |
| `<base>-traffic/<host>/index.json` | Flat, jq-friendly array of ids → method/url/status/content-type (+ top severity) |
| `<base>-findings/<host>/<id>.md` | Each finding, cross-linked to its `.req` file |

Ids are zero-padded and assigned in `sent_at` order, so re-exports are reproducible. This is the one-shot counterpart to the server's live `--mirror-fs` ([section 1](#1-mirror-ingested-traffic-findings-to-a-live-filesystem-tree)): `export` writes a one-shot `index.json` array, the mirror appends to `index.jsonl`. `export` honors `--search`/`--severity`/`--limit`; `db export` adds the full `--host`/`--status`/`--method`/`--path`/`--scan-uuid`/`--from`/`--to` filter set (scoped to the active project). `--split-by-host` is a no-op here, `fs` already splits by host. To read a colleague's export without merging it into your DB first, see [section 4](#4-import-external-scan-data-into-the-database).

***

## 28. "Where did my missing-security-header findings go?"

As of **v0.5.0** the 14 modules tagged `hygiene` do not run below `--intensity deep`. They report a *missing best-practice control* rather than an exploitable condition — absent security headers, weak TLS protocol and cipher policy, cookie and session-cookie attributes, the CSP / HSTS / SRI / Permissions-Policy / COOP audits — and they fire on nearly every response, so on a crawl of any size they contributed one near-identical Info/Low row per URL and buried the findings worth triaging.

```bash theme={null}
# Turn them back on, three ways
vigolium scan -t https://example.com --intensity deep          # per scan
vigolium scan -t https://example.com --module-tag hygiene      # just this family
vigolium config set dynamic-assessment.hygiene_modules true    # every scan

# One of them, by name
vigolium scan -t https://example.com --module-id security-headers-missing
```

`--module-tag hygiene` is usually what you want for a compliance-shaped report: it turns this family back on **without** also raising every other module's aggressiveness tier the way `--intensity deep` does. `dynamic-assessment.hygiene_modules: false` suppresses them even at `deep`. The scan banner reports how many were suppressed, and the [full list](https://docs.vigolium.com/native-scan/modules-reference.md#hardening-advisories-hygiene) is in the module reference. The Info-tier fingerprints, endpoint/param observers, `surface-scoring` and `clickjacking-detect` are **not** in this set and still run at every intensity.

***

## 29. Reclaim disk from interrupted scans

Every scan allocates its scratch under one root and removes the whole thing on exit, so a run that finishes — or is interrupted — cleans up after itself. `vigolium kit tmp-clean` (**v0.5.0**) collects what is *already* there: scratch from runs that were killed, and the loose per-store directories earlier versions wrote straight into the system temp directory.

```bash theme={null}
vigolium kit tmp-clean                   # collect scratch idle for 6h or more
vigolium kit tmp-clean --max-age 0       # collect everything not currently held
vigolium kit tmp-clean -j                # the same, as JSON
```

The backlog gets large: one workstation had 71,614 leftover dedup directories totalling 108 GB, plus 3,384 stranded Chromium profiles worth 104 GB from the spidering browser. It was also a **startup cost** — Vigolium's dependencies used to sweep the whole temp directory on every invocation, so the litter slowed down every command in proportion to how much of it there was. Only names Vigolium itself allocates are touched, and only entries untouched for `--max-age`, so a scan running right now never loses its scratch. See [the toolbox](https://docs.vigolium.com/others/kit.md#tmp-clean).

***

**Oh dear, you actually read to the end.** Here's the secret the config file
kept nudging you toward: by default every Vigolium request announces itself
with a `Vigolium/<version>` User-Agent, so a friendly blue team can spot your
authorized scan in their logs in seconds. Go full ninja only when you *mean*
to be sneaky:

```bash theme={null}
# Persist it in your config
vigolium config set scanning_strategy.http.user_agent random

# Or a one-off via env var (overrides the config value for that run)
export VIGOLIUM_DEFAULT_UA=random
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.