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

# Using the Vigolium Scanner Skill in Claude Code & Codex

> Install and use the vigolium-scanner skill with AI coding agents for web vulnerability scanning and extension authoring.

This guide explains how to install and use the `vigolium-scanner` skill with AI coding agents, Claude Code and OpenAI Codex, to operate the Vigolium CLI for web vulnerability scanning, security testing, and custom extension authoring.

**Skill repository:** [github.com/vigolium/skills](https://github.com/vigolium/skills) — or install the copy **embedded in your `vigolium` binary**, which always matches your installed version.

### Quick Install

```bash theme={null}
# Install the embedded skill into the current project (recommended — always matches your binary)
vigolium skills install --agent claude --scope project
```

`vigolium skills install` (added in v0.2.1) writes the `vigolium-scanner` bundle straight from the binary, so it can never drift from the CLI you're driving. Pick the agent with `--agent claude|codex|agents` and the location with `--scope project` (current folder) or `--scope global` (home dir). Run `vigolium skills` to list what's bundled and `vigolium skills get vigolium-scanner` to print a bundle without installing it.

Prefer to pull the latest from the repo instead? Use the external `skills` installer:

```bash theme={null}
bunx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes
```

Replace `<agent-name>` with your agent (e.g., `claude-code`, `codex`).

***

## What the Skill Does

The skill teaches the AI agent how to:

1. **Pick the right vigolium command** for any security testing task
2. **Construct correct flag combinations** with proper syntax
3. **Follow scanning workflows** end-to-end (ingest -> scan -> triage -> export)
4. **Write custom JavaScript extensions** using the `vigolium.*` API
5. **Operate AI agent modes** (query, autopilot, swarm)
6. **Manage data**: browse traffic, filter findings, export reports, clean databases

The skill uses lazy-loaded references: the main `SKILL.md` stays small, and detailed docs are loaded on demand when the agent needs deep flag information or extension authoring guidance.

***

## Skill Structure

```
public/skills/vigolium-scanner/
├── SKILL.md                              # Main skill (decision tree, recipes, flags)
└── references/
    ├── scanning-commands.md              # scan, scan-url, scan-request, run
    ├── server-and-ingestion.md           # server, ingest, traffic, traffic replay
    ├── agent-commands.md                 # agent, agent query, autopilot, swarm
    ├── data-and-management.md            # db, module, ext, config, scope, source, export
    ├── flags-reference.md                # Complete alphabetical flag index
    └── writing-extensions.md             # JS extension API and examples
```

***

## Installation

**Option A: `vigolium skills install` (recommended — embedded, version-matched)**

```bash theme={null}
# Default: install the vigolium-scanner bundle for Claude into the current project
vigolium skills install

# Choose the agent and scope explicitly
vigolium skills install --agent codex --scope global

# Install every bundled skill, or override the destination directory
vigolium skills install --all
vigolium skills install --dir ./.claude/skills
```

The bundle ships **inside** the `vigolium` binary, so `vigolium skills install` can never install a stale copy — it always matches the CLI version you're driving. `--agent` accepts `claude`, `codex`, or `agents` (an [agentskills.io](https://agentskills.io)-compatible layout); `--scope` is `project` (current folder) or `global` (home dir). Inspect what's bundled first with `vigolium skills` (list) and `vigolium skills get vigolium-scanner` (print).

**Option B: Install via npx / bunx (pulls the latest from the repo)**

```bash theme={null}
bunx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes
```

or with `npx`:

```bash theme={null}
npx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes
```

Replace `<agent-name>` with your agent (e.g., `claude-code`, `codex`). This fetches the skill from the [vigolium/skills](https://github.com/vigolium/skills) repository and registers it automatically.

**Option C: Clone and copy manually**

```bash theme={null}
git clone https://github.com/vigolium/skills.git
cd skills
```

Then copy the skill folder to your agent's configuration directory:

```bash theme={null}
# For Claude Code
cp -R vigolium-scanner ~/.claude

# For other agents
cp -R vigolium-scanner ~/.agents
```

Once installed, the skill **auto-triggers** when you mention keywords like `scan`, `vigolium`, `agent autopilot`, `vulnerability scanner`, `openapi scan`, etc. In Claude Code, you can also invoke it explicitly with `/vigolium-scanner`.

***

## Usage Examples by Category

### 1. Scanning

**Basic scan against a single target:**

```
> Scan https://example.com for vulnerabilities
```

```bash theme={null}
vigolium scan -t https://example.com
```

**Multiple targets:**

```
> Scan both https://example.com and https://api.example.com
```

```bash theme={null}
vigolium scan -t https://example.com -t https://api.example.com
```

**Targets from a file:**

```
> I have a list of URLs in targets.txt, scan all of them
```

```bash theme={null}
vigolium scan -T targets.txt
```

**Scan with a specific strategy:**

```
> Do a deep scan of https://example.com with discovery and spidering
```

```bash theme={null}
vigolium scan -t https://example.com --strategy deep
```

**Scan a single URL with custom method, headers, and body:**

```
> Test the login endpoint for vulnerabilities: POST to https://api.example.com/login with JSON credentials
```

```bash theme={null}
vigolium scan-url https://api.example.com/login \
  --method POST \
  --body '{"username":"admin","password":"test123"}' \
  -H "Content-Type: application/json"
```

**Scan a raw HTTP request from a file:**

```
> I captured a raw request in request.txt, scan it
```

```bash theme={null}
vigolium scan-request -i request.txt
```

**Scan a raw request from stdin:**

```
> Scan this raw request from the terminal
```

```bash theme={null}
echo -e "GET /api/users?id=1 HTTP/1.1\r\nHost: example.com\r\nAuthorization: Bearer tok123\r\n" | vigolium scan-request
```

**Scan with a proxy (e.g., Burp Suite):**

```
> Scan https://example.com and route traffic through Burp
```

```bash theme={null}
vigolium scan -t https://example.com --proxy http://127.0.0.1:8080
```

**High-speed scan with tuned concurrency:**

```
> Scan fast — 100 workers, 200 req/s, max 5 per host
```

```bash theme={null}
vigolium scan -t https://example.com -c 100 --rate-limit 200 --max-per-host 5
```

**Scan and output results as JSONL:**

```
> Scan and save results as JSON lines
```

```bash theme={null}
vigolium scan -t https://example.com --format jsonl -o results.jsonl
```

**Scan and generate an HTML report:**

```
> Scan and produce an interactive HTML report
```

```bash theme={null}
vigolium scan -t https://example.com --format html -o report.html
```

**Scan to a standalone SQLite file:**

```
> Run a one-off scan and give me a self-contained .sqlite I can reopen later
```

```bash theme={null}
vigolium scan -S -t https://example.com --format sqlite -o scan
```

`--format sqlite` (aliases `sqlite3`, `db`) requires `-S/--stateless` + `-o`; reopen it with `vigolium finding -S --db scan.sqlite`.

**Scan to a browsable filesystem tree (no DB needed):**

```
> Scan and give me the traffic + findings as files I can grep
```

```bash theme={null}
vigolium scan -t https://example.com --format fs -o run
```

`--format fs` writes two sibling dirs off the `-o` base — `run-traffic/` and `run-findings/` — so you can investigate with plain `ls`/`grep`/`jq`. Each `<host>/<id>.req` is the raw, replayable request (strip the leading `@target` line), `<id>.resp.headers`/`<id>.resp.body` hold the gzip-decoded response, and `<id>.md` under `-findings/` is the finding cross-linked to its `.req`. Start from `index.json` in each dir — `jq` it to map every id to its url/status/severity. Works with or without `-S`; honors `--omit-response`. See [Output and Reporting](/getting-started/output-and-reporting#filesystem-fs) for the full layout.

**Scan with custom scanning profile:**

```
> Use the aggressive scanning profile
```

```bash theme={null}
vigolium scan -t https://example.com --scanning-profile aggressive
```

**Scan with strict origin scope:**

```
> Only scan URLs on the exact same origin
```

```bash theme={null}
vigolium scan -t https://example.com --scope-origin strict
```

***

### 2. Input Formats

**OpenAPI 3.x spec with explicit base URL:**

```
> Scan my API using the OpenAPI spec
```

```bash theme={null}
vigolium scan -I openapi -i api-spec.yaml -t https://api.example.com
```

**OpenAPI spec using servers from the spec:**

```
> Use the server URLs defined in the spec itself
```

```bash theme={null}
vigolium scan -I openapi -i api-spec.yaml --spec-url
```

**OpenAPI with auth header and parameter values:**

```
> Scan the spec with bearer auth and set the user_id parameter to 42
```

```bash theme={null}
vigolium scan -I openapi -i spec.yaml -t https://api.example.com \
  --spec-header "Authorization: Bearer eyJ..." \
  --spec-var "user_id=42"
```

**Swagger 2.0 spec:**

```
> Import a Swagger 2.0 spec and scan
```

```bash theme={null}
vigolium scan -I swagger -i swagger.json -t https://api.example.com
```

**Burp Suite XML export:**

```
> I exported traffic from Burp, scan it
```

```bash theme={null}
vigolium scan -I burp -i burp-export.xml -t https://example.com
```

**HAR (HTTP Archive) file:**

```
> Scan my browser-recorded HAR file
```

```bash theme={null}
vigolium scan -I har -i traffic.har
```

**cURL commands file:**

```
> I have a file of curl commands, scan them all
```

```bash theme={null}
vigolium scan -I curl -i curl-commands.txt
```

**Postman collection:**

```
> Import and scan my Postman collection
```

```bash theme={null}
vigolium scan -I postman -i collection.json -t https://api.example.com
```

**Nuclei templates:**

```
> Run these Nuclei templates against the target
```

```bash theme={null}
vigolium scan -I nuclei -i templates/ -t https://example.com
```

**Piped URLs from stdin:**

```
> Pipe a list of URLs into the scanner
```

```bash theme={null}
cat urls.txt | vigolium scan -i -
```

***

### 3. Phase Control

**Run only discovery (content enumeration):**

```
> Just run content discovery against the target
```

```bash theme={null}
vigolium run discover -t https://example.com
# or
vigolium scan -t https://example.com --only discovery
```

**Run only spidering (headless browser crawling):**

```
> Spider the target with a headless browser
```

```bash theme={null}
vigolium run spidering -t https://example.com
```

**Run only audit (vulnerability scanning):**

```
> Skip discovery, just run the vulnerability modules
```

```bash theme={null}
vigolium run audit -t https://example.com
# or
vigolium scan -t https://example.com --only audit
```

**Run only the Nuclei known-issue scan (critical/high only):**

```
> Run Nuclei-based known-issue checks, only critical and high severity
```

```bash theme={null}
vigolium run known-issue-scan -t https://example.com --known-issue-scan-severities critical,high
```

**Run a whitebox source-code audit (SAST):**

```
> Run a security audit on my Go app's source
```

```bash theme={null}
vigolium agent audit --source /path/to/app
```

**Run only external harvest (Wayback, Common Crawl, OTX):**

```
> Gather URLs from external intelligence sources
```

```bash theme={null}
vigolium run external-harvest -t https://example.com
```

**Skip specific phases:**

```
> Scan but skip discovery and spidering
```

```bash theme={null}
vigolium scan -t https://example.com --skip discovery,spidering
```

**Run only JavaScript extensions:**

```
> Run only my custom extension, skip built-in modules
```

```bash theme={null}
vigolium scan -t https://example.com --only extension --ext ./custom-check.js
# or
vigolium run ext -t https://example.com --ext ./custom-check.js
```

**Phase aliases reference:**

| Alias                 | Resolves To |
| --------------------- | ----------- |
| `deparos`, `discover` | `discovery` |
| `spitolas`            | `spidering` |
| `dynamic-assessment`  | `audit`     |
| `ext`                 | `extension` |

***

### 4. Module Filtering

**List all available scanner modules:**

```
> Show me all scanner modules
```

```bash theme={null}
vigolium module ls
# or
vigolium scan -M
```

**Filter modules by keyword:**

```
> Show me all XSS-related modules
```

```bash theme={null}
vigolium module ls xss
```

**List only active modules with verbose details:**

```
> Show active modules with descriptions
```

```bash theme={null}
vigolium module ls --type active -v
```

**Scan with specific modules only:**

```
> Only run reflected XSS and error-based SQL injection modules
```

```bash theme={null}
vigolium scan -t https://example.com -m xss-reflected,sqli-error
```

**Filter modules by tags (OR logic):**

```
> Scan with modules tagged 'spring' or 'injection'
```

```bash theme={null}
vigolium scan -t https://example.com --module-tag spring --module-tag injection
```

**Combine module IDs and tags:**

```
> Run sqli-error plus all XSS-tagged modules
```

```bash theme={null}
vigolium scan -t https://example.com -m sqli-error --module-tag xss
```

**Enable/disable modules persistently:**

```
> Disable all SQL injection modules, enable all XSS modules
```

```bash theme={null}
vigolium module disable sqli
vigolium module enable xss
```

**Enable by exact module ID:**

```
> Enable only the reflected XSS module
```

```bash theme={null}
vigolium module enable active-xss-reflected --id
```

***

### 5. Server & Ingestion

**Start the API server (default port 9002):**

```
> Start the vigolium server
```

```bash theme={null}
vigolium server
```

**Start server on custom port without auth:**

```
> Start the server on port 8443 with no authentication
```

```bash theme={null}
vigolium server --service-port 8443 --no-auth
```

**Start server with scan-on-receive (auto-scan ingested traffic):**

```
> Start the server and auto-scan every request that comes in
```

```bash theme={null}
vigolium server -t https://example.com --scan-on-receive
```

**Start server with transparent proxy for recording:**

```
> Start server with a recording proxy on port 8080
```

```bash theme={null}
vigolium server --ingest-proxy-port 8080
```

**Mirror ingested traffic to files in real time:**

```
> Run the server and mirror everything it ingests into ./mirror so I can grep it live
```

```bash theme={null}
vigolium server --mirror-fs ./mirror
```

Every saved HTTP record and finding is written to `./mirror/traffic/<host>/…` and `./mirror/findings/<host>/…` as it lands in the DB — the same layout as `--format fs`, except the indexes are append-only `index.jsonl` (one object per line — `tail`/`grep` it live) and per-host ids resume across restarts. Point your agent at `./mirror` to read ingested Burp/proxy traffic as files while it streams in.

**High-concurrency server:**

```
> Start a high-throughput server with 200 workers
```

```bash theme={null}
vigolium server -c 200 --mem-buffer 50000
```

**Ingest an OpenAPI spec locally:**

```
> Import the spec into the database without scanning
```

```bash theme={null}
vigolium ingest -t https://api.example.com -I openapi -i spec.yaml
```

**Ingest and auto-scan:**

```
> Import the spec and scan immediately
```

```bash theme={null}
vigolium ingest -t https://api.example.com -I openapi -i spec.yaml -S
```

**Ingest Burp export:**

```
> Import Burp traffic into the database
```

```bash theme={null}
vigolium ingest -t https://example.com -I burp -i export.xml
```

**Remote ingest to a running server:**

```
> Send traffic to the vigolium server running on localhost
```

```bash theme={null}
vigolium ingest -s http://localhost:9002 -I openapi -i spec.yaml
```

**Ingest without fetching responses:**

```
> Store request-only records, don't make network requests
```

```bash theme={null}
vigolium ingest -t https://example.com -I burp -i export.xml --disable-fetch-response
```

***

### 6. AI Agent Modes

#### Agent (Template-Based)

**Security code review:**

```
> Review my source code for security vulnerabilities
```

```bash theme={null}
vigolium agent query --prompt-template security-code-review --source ./src
```

**Endpoint discovery from source:**

```
> Find all API endpoints in my source code
```

```bash theme={null}
vigolium agent query --prompt-template endpoint-discovery --source ./src
```

**Review specific files only:**

```
> Review only auth.go and middleware.go for security issues
```

```bash theme={null}
vigolium agent query --prompt-template security-code-review --source ./src \
  --files "src/auth.go,src/middleware.go"
```

**Append extra instructions to a template:**

```
> Code review, but focus on authentication and authorization
```

```bash theme={null}
vigolium agent query --prompt-template security-code-review --source ./src \
  --append "Focus specifically on authentication and authorization vulnerabilities"
```

**Use a custom prompt file:**

```
> Run the agent with my own prompt template
```

```bash theme={null}
vigolium agent query --prompt-file custom-prompt.md --source ./src
```

**Select a specific olium provider:**

```
> Use Anthropic for code review
```

```bash theme={null}
vigolium agent query --provider anthropic-api-key --prompt-template security-code-review --source ./src
```

**Dry-run to preview the rendered prompt:**

```
> Show me what prompt would be sent to the agent
```

```bash theme={null}
vigolium agent query --prompt-template security-code-review --source ./src --dry-run
```

**Save agent output to a file:**

```
> Save the review results to a JSON file
```

```bash theme={null}
vigolium agent query --prompt-template security-code-review --source ./src \
  --output review-results.json
```

**List available templates and providers:**

```
> What prompt templates and olium providers are available?
```

```bash theme={null}
vigolium agent --list-templates
vigolium agent --list-agents
```

**Built-in templates include:**

* `security-code-review`: Comprehensive security review
* `injection-sinks`: Find injection sinks
* `auth-bypass`: Auth bypass vectors
* `secret-detection`: Hardcoded secrets
* `endpoint-discovery`: API endpoints from source
* `api-input-gen`: Generate test inputs
* `curl-command-gen`: Generate cURL commands
* `attack-surface-mapper`: Map attack surface
* `nextjs-security-audit`: Next.js security review
* `react-xss-audit`: React XSS audit
* `cors-csrf-review`: CORS/CSRF config audit

#### Agent Query (Freeform Prompt)

**Inline prompt:**

```
> Ask the agent to review code for vulnerabilities
```

```bash theme={null}
vigolium agent query 'review this code for SQL injection vulnerabilities'
```

**Named prompt flag:**

```
> Analyze the authentication flow
```

```bash theme={null}
vigolium agent query --prompt 'analyze the authentication flow for bypass vectors'
```

**Pipe prompt from stdin:**

```
> Pipe a prompt to the agent
```

```bash theme={null}
echo "check for SSRF in the URL-fetching handler" | vigolium agent query --stdin
```

**Custom prompt file with a specific provider:**

```
> Run a custom prompt file through Anthropic
```

```bash theme={null}
vigolium agent query --provider anthropic-api-key --prompt-file custom-prompt.md
```

**Pick a different model:**

```
> Run the review on a frontier model
```

```bash theme={null}
vigolium agent query --provider anthropic-api-key --model claude-opus-4-7 \
  'comprehensive security review of all handlers'
```

#### Agent Autopilot (Autonomous Scanning)

**Basic autonomous scan:**

```
> Let the AI autonomously scan the target
```

```bash theme={null}
vigolium agent autopilot -t https://example.com
```

**With source code context and focus area:**

```
> Autonomous scan focused on auth bypass, with source code for context
```

```bash theme={null}
vigolium agent autopilot -t https://api.example.com --source ./src --focus "auth bypass"
```

**Custom limits (lighter intensity, shorter wall-clock):**

```
> Run a quick scan capped at 15 minutes
```

```bash theme={null}
vigolium agent autopilot -t https://example.com --intensity quick --max-duration 15m
```

**Preview the system prompt (dry run):**

```
> Show me what system prompt the autopilot agent would receive
```

```bash theme={null}
vigolium agent autopilot -t https://example.com --dry-run
```

**Custom system prompt:**

```
> Use my own system prompt for autopilot
```

```bash theme={null}
vigolium agent autopilot -t https://example.com --system my-system-prompt.md
```

**Use a different olium provider:**

```
> Run autopilot through Google Vertex
```

```bash theme={null}
vigolium agent autopilot -t https://example.com --provider google-vertex --model gemini-2.5-pro
```

**Autopilot security model:**

* Yolo-mode bash — autopilot runs the model's `bash` calls without an approval prompt. The model decides when to invoke `vigolium scan-url`, `vigolium finding`, etc. (they're shell commands, not first-class tools).
* The engine only hard-rejects catastrophic patterns (`rm -rf /`, `dd` to block devices, fork bombs, `mkfs` against real devices). There is no `vigolium`-only command allowlist.
* Per-tool timeout: 5 minutes (`ToolTimeout`).
* Intensity-driven defaults: quick=150 / balanced=500 / deep=1500 commands (`MaxCommands`), browser enabled at every intensity.
* `report_finding` soft-warns at 50 findings and hard-caps at 200, nudging the agent toward `halt_scan`.
* Run autopilot in a disposable container or VM scoped to in-scope targets — see [Security Warning](/others/security-warning).

#### Agent Swarm (AI-Guided Multi-Phase Scan)

**Basic swarm scan with discovery (all phases):**

```
> Run the full AI swarm scan
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com
```

The swarm runs ten phases in order (most are conditional — see [Swarm](/agentic-scan/swarm) for full detail):

1. **native-normalize** — parse `--input`/stdin/record-uuid into HTTP records
2. **auth** *(optional)* — browser-driven login, writes auth headers/cookies
3. **source-analysis** *(if `--source`)* — 4-call wave that emits routes, session-config, and source extensions
4. **code-audit** *(if `--code-audit`)* — code-level security audit, findings → DB
5. **native-discover** *(if `--discover`)* — crawl/spider/JS-scan
6. **plan** — master agent picks modules and writes an extensions spec
7. **native-extension** — compile/validate generated JS extensions (Sobek)
8. **native-scan** — `runner.RunNativeScan()` with the planned modules + extensions
9. **triage** *(if `--triage`)* — AI verifies findings, may request targeted rescans
10. **native-rescan** — targeted rescan loop, bounded by `--max-iterations`

**Swarm with focus area and source code:**

```
> Swarm scan focused on SQL injection, with source code
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --focus "SQL injection" --source ./src
```

**Control rescan iterations:**

```
> Allow up to 3 triage->rescan iterations
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --max-iterations 3
```

**Skip discovery and start from planning (use existing DB data):**

```
> I already have traffic in the database, start from planning
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --skip discover --start-from plan
```

**Skip triage (just discover -> plan -> scan):**

```
> Run swarm but skip triage and rescan
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --skip triage --skip rescan
```

**Use a scanning profile:**

```
> Run swarm with the deep scanning profile
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --profile deep
```

**Preview agent prompts (dry run):**

```
> Show me the prompts without executing
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --dry-run
```

**Specific source files for agent context:**

```
> Only include routes.go and handlers.go as context
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --source ./src \
  --files "routes.go,handlers.go"
```

**Use a different agent backend:**

```
> Run swarm with Gemini
```

```bash theme={null}
vigolium agent swarm --discover -t https://example.com --agent gemini
```

***

### 7. Traffic & Results Browsing

**Browse all stored HTTP traffic:**

```
> Show me the HTTP traffic in the database
```

```bash theme={null}
vigolium traffic
```

**Fuzzy search traffic:**

```
> Show traffic related to login
```

```bash theme={null}
vigolium traffic login
```

**Tree view (hierarchical URL structure):**

```
> Show traffic as a directory tree
```

```bash theme={null}
vigolium traffic --tree
```

**Burp-style colored output:**

```
> Show traffic in Burp Suite style
```

```bash theme={null}
vigolium traffic --burp
```

**Filter by host, method, status:**

```
> Show POST and PUT requests to api.example.com that returned 200
```

```bash theme={null}
vigolium traffic --host api.example.com --method POST,PUT --status 200
```

**Filter by date range:**

```
> Show traffic from January 2024
```

```bash theme={null}
vigolium traffic --from 2024-01-01 --to 2024-01-31
```

**Search in request/response body:**

```
> Find traffic containing "password" in the body
```

```bash theme={null}
vigolium traffic --body password
```

**Search in headers:**

```
> Find traffic with JWT tokens in headers
```

```bash theme={null}
vigolium traffic --header "Bearer"
```

**Custom columns:**

```
> Show host, method, path, status, and auth columns
```

```bash theme={null}
vigolium traffic --columns HOST,METHOD,PATH,STATUS,AUTH
```

**Watch mode (auto-refresh):**

```
> Monitor traffic in real-time, refresh every 5 seconds
```

```bash theme={null}
vigolium traffic --watch 5s
```

**View raw HTTP request/response:**

```
> Show raw traffic for the last 5 records
```

```bash theme={null}
vigolium traffic --raw --limit 5
```

**Browse findings:**

```
> Show all vulnerability findings
```

```bash theme={null}
vigolium finding
```

**Filter findings by severity:**

```
> Show only high and critical findings
```

```bash theme={null}
vigolium finding --severity high,critical
```

**Search findings:**

```
> Find SQL injection findings
```

```bash theme={null}
vigolium finding --search "sql injection"
```

**Watch findings in real-time:**

```
> Monitor findings as they come in
```

```bash theme={null}
vigolium finding --watch 5s
```

**Render a finding as Markdown (evidence + request/response):**

```
> Give me finding 42 as Markdown I can paste into a report
```

```bash theme={null}
vigolium finding --id 42 --markdown > finding-42.md
```

**Read a standalone export without a project DB:**

```
> Browse the high-severity findings in this scan.jsonl export
```

```bash theme={null}
vigolium finding -S --db ./scan.jsonl --min-severity high
vigolium traffic -S --db ./scan.sqlite --status 500 -n 20
```

`-S/--stateless` + `--db` reads a `--format jsonl` export or a standalone `.sqlite` directly with project scoping off, writing nothing to your project DB.

**Replay stored traffic (re-send requests):**

```
> Replay login-related requests and compare responses
```

```bash theme={null}
vigolium replay --search login
```

**Replay and replace stored responses:**

```
> Replay requests to api.example.com and update stored responses
```

```bash theme={null}
vigolium replay --host api.example.com --in-replace
```

***

### 8. Data Management

**Database statistics:**

```
> Show me database stats
```

```bash theme={null}
vigolium db stats
```

**Detailed stats with host breakdown:**

```
> Show detailed stats broken down by host
```

```bash theme={null}
vigolium db stats --detailed
```

**Stats for a specific host:**

```
> Stats for example.com only
```

```bash theme={null}
vigolium db stats --host example.com
```

**Live-updating stats:**

```
> Watch database stats, refresh every 10 seconds
```

```bash theme={null}
vigolium db stats --watch 10s
```

**List database records with filters:**

```
> Show findings table, critical and high severity
```

```bash theme={null}
vigolium db ls --table findings --severity critical,high
```

**List available tables and columns:**

```
> What tables are in the database? What columns does findings have?
```

```bash theme={null}
vigolium db ls --list-tables
vigolium db ls --list-columns --table findings
```

**Clean records by hostname:**

```
> Delete all records for old-target.com
```

```bash theme={null}
vigolium db clean --host old-target.com --force
```

**Clean old records with dry-run preview:**

```
> Preview what would be deleted before January 2024
```

```bash theme={null}
vigolium db clean --before 2024-01-01 --dry-run
```

**Clean only findings (keep HTTP records):**

```
> Delete info-severity findings but keep the HTTP records
```

```bash theme={null}
vigolium db clean --findings-only --severity info --force
```

**Clean orphaned findings:**

```
> Remove findings without associated HTTP records
```

```bash theme={null}
vigolium db clean --orphans
```

**Reset entire database:**

```
> Wipe the entire database and start fresh
```

```bash theme={null}
vigolium db clean --force
```

**Reclaim disk space after deletion:**

```
> Vacuum the database to reclaim space
```

```bash theme={null}
vigolium db clean --vacuum
```

***

### 9. Export & Reports

**Full JSONL export:**

```
> Export everything from the database as JSONL
```

```bash theme={null}
vigolium export --format jsonl -o full-export.jsonl
```

**Export only findings:**

```
> Export just the findings
```

```bash theme={null}
vigolium export --format jsonl --only findings -o findings.jsonl
```

**Export findings and HTTP records:**

```
> Export findings and associated HTTP traffic
```

```bash theme={null}
vigolium export --format jsonl --only findings,http -o results.jsonl
```

**HTML report:**

```
> Generate an interactive HTML report
```

```bash theme={null}
vigolium export --format html -o report.html
```

**Lightweight export (omit raw HTTP request/response bytes):**

```
> Export URLs only, without raw request/response data
```

```bash theme={null}
vigolium export --omit-response --only http -o urls.jsonl
```

**Export with search filter:**

```
> Export only records matching example.com
```

```bash theme={null}
vigolium export --search "example.com" -o filtered.jsonl
```

**Database-level export as CSV:**

```
> Export HTTP records as CSV
```

```bash theme={null}
vigolium db export -f csv -o records.csv
```

**Export as Markdown:**

```
> Export records as a Markdown report
```

```bash theme={null}
vigolium db export -f markdown -o report.md
```

**Export raw requests only:**

```
> Export just the raw HTTP requests
```

```bash theme={null}
vigolium db export -f raw --request-only -o requests.txt
```

**Export filtered by host and date:**

```
> Export records for example.com from 2024 onwards
```

```bash theme={null}
vigolium db export -f csv -o records.csv --host example.com --from 2024-01-01
```

**Export a single record by UUID:**

```
> Export record abc12345
```

```bash theme={null}
vigolium db export --uuid abc12345
```

**Export module registry:**

```
> Export all available scanner modules
```

```bash theme={null}
vigolium export --only modules
```

***

### 10. Whitebox / Source-Aware Scanning

Source-aware scanning runs through the agent modes via the `--source` flag — the native `vigolium scan` does not take source code. Use `agent swarm` for an AI-driven source-aware DAST scan, or `agent audit` for a source-only (SAST) review.

**Source-aware scan with local source code:**

```
> Whitebox scan with source code in ./src
```

```bash theme={null}
vigolium agent swarm --target https://example.com --source ./src
```

`--target` is required whenever `--source` is given. The source-analysis and code-audit phases run automatically when `--source` is present.

**Scan with source cloned from Git:**

```
> Clone the repo and run a source-aware scan
```

```bash theme={null}
# Clone first, then point --source at the local checkout
git clone https://github.com/org/repo /tmp/repo
vigolium agent swarm --target https://example.com --source /tmp/repo
```

**Run a source-code audit (SAST) only:**

```
> Run a security audit on the source code
```

```bash theme={null}
vigolium agent audit --source /path/to/app
```

**Deeper multi-phase audit:**

```
> Run a thorough deep-mode source audit
```

```bash theme={null}
vigolium agent audit --source /path/to/app --mode deep
```

***

### 11. JavaScript Extensions

**Install preset examples:**

```
> Install the example extension scripts
```

```bash theme={null}
vigolium ext preset
```

**View the extension API reference:**

```
> Show me the extension API docs
```

```bash theme={null}
vigolium ext docs
vigolium ext docs --example          # with code examples
vigolium ext docs http               # filter by namespace
```

**List loaded extensions:**

```
> Show currently loaded extensions
```

```bash theme={null}
vigolium ext ls
vigolium ext ls --type active        # active extensions only
```

**Quick-test JS code inline:**

```
> Test a JS expression
```

```bash theme={null}
vigolium ext eval 'vigolium.log.info("hello from extension")'
vigolium ext eval 'vigolium.utils.md5("password")'
```

**Evaluate a JS file:**

```
> Run a JS script file
```

```bash theme={null}
vigolium ext eval --ext-file script.js
```

**Run a custom extension against a target:**

```
> Run my custom scanner extension
```

```bash theme={null}
vigolium run extension -t https://example.com --ext custom-check.js
# or
vigolium run ext -t https://example.com --ext custom-check.js
```

**Run extension alongside built-in modules:**

```
> Run built-in modules plus my custom extension
```

```bash theme={null}
vigolium scan -t https://example.com --ext custom-check.js
```

**Run only extensions (skip built-in modules):**

```
> Run only my custom extensions
```

```bash theme={null}
vigolium scan -t https://example.com --only extension --ext custom-check.js
```

**Load multiple extensions:**

```
> Run three extensions together
```

```bash theme={null}
vigolium scan -t https://example.com --ext check1.js --ext check2.js --ext check3.js
```

**Load all extensions from a directory:**

```
> Run all extensions in my extensions folder
```

```bash theme={null}
vigolium scan -t https://example.com --ext-dir ./my-extensions/
```

**Ask the agent to write an extension:**

```
> Write me a passive extension that checks for missing security headers
```

The agent will generate a JS file like:

```javascript theme={null}
module.exports = {
  id: "missing-security-headers",
  name: "Missing Security Headers",
  type: "passive",
  severity: "low",
  confidence: "certain",
  scope: "response",
  tags: ["headers", "misconfiguration", "light"],
  scanTypes: ["per_request"],

  scanPerRequest: function(ctx) {
    if (!ctx.response) return null;
    var headers = ctx.response.headers;
    var missing = [];

    if (!headers["strict-transport-security"]) missing.push("HSTS");
    if (!headers["x-content-type-options"]) missing.push("X-Content-Type-Options");
    if (!headers["x-frame-options"] && !headers["content-security-policy"]) {
      missing.push("X-Frame-Options/CSP");
    }

    if (missing.length === 0) return null;

    return {
      url: ctx.request.url,
      name: "Missing Security Headers: " + missing.join(", "),
      severity: "low",
      description: "Response is missing: " + missing.join(", ")
    };
  }
};
```

**Ask the agent to write an AI-augmented extension:**

```
> Write an active extension that uses AI to generate XSS payloads
```

The agent will generate a JS file using `vigolium.agent.generatePayloads()` and `vigolium.agent.analyzeResponse()`.

**YAML extension (simple pattern matching):**

```
> Write a YAML extension that detects stack traces and SQL errors
```

```yaml theme={null}
id: error-pattern-detector
name: Verbose Error Pattern Detector
type: passive
severity: suspect
confidence: tentative
scope: response
tags: [error, information-disclosure, light]
scanTypes: [per_request]
patterns:
  - name: "Stack Trace Detected"
    regex: "(?:at\\s+[\\w.$]+\\(|Traceback \\(most recent|Exception in thread)"
    severity: suspect
  - name: "SQL Error Message"
    regex: "(?:mysql_|pg_|sqlite_|ORA-\\d{5}|SQLSTATE\\[)"
    severity: medium
```

***

### 12. Configuration & Projects

**View all configuration:**

```
> Show the current vigolium config
```

```bash theme={null}
vigolium config ls
```

**View a specific config section:**

```
> Show scope configuration
```

```bash theme={null}
vigolium config ls scope
vigolium config ls scanning_pace
vigolium config ls server
```

**Set configuration values:**

```
> Set the default strategy to deep
```

```bash theme={null}
vigolium config set scanning_strategy.default_strategy deep
```

**Set scope mode:**

```
> Set origin scope to strict
```

```bash theme={null}
vigolium config set scope.origin.mode strict
```

**Enable extensions globally:**

```
> Enable extensions in audit
```

```bash theme={null}
vigolium config set audit.extensions.enabled true
```

**View scope rules:**

```
> Show current scope rules
```

```bash theme={null}
vigolium scope view
vigolium scope view host
```

**View scanning strategies:**

```
> Show available strategies and their phases
```

```bash theme={null}
vigolium strategy ls
```

**Create and manage projects:**

```
> Create a project, then switch to it
```

```bash theme={null}
vigolium project create my-project
vigolium project list
vigolium project use my-project
```

**Scope CLI operations to a project:**

```
> Scan within a specific project
```

```bash theme={null}
vigolium scan -t https://example.com --project-name my-project
```

**Project-scoped database access:**

```
> Show stats for my-project
```

```bash theme={null}
VIGOLIUM_PROJECT=my-project vigolium db stats
```

***

## Natural Language Examples

These are examples of natural language prompts you can give to Claude Code or Codex with the skill installed. The agent will translate them into the correct vigolium commands.

| You Say                                                    | Agent Runs                                                                                 |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| "Scan example.com"                                         | `vigolium scan -t https://example.com`                                                     |
| "Deep scan with spidering"                                 | `vigolium scan -t <url> --strategy deep`                                                   |
| "Import my Burp export and scan it"                        | `vigolium scan -I burp -i export.xml`                                                      |
| "Scan my OpenAPI spec with auth"                           | `vigolium scan -I openapi -i spec.yaml -t <url> --spec-header "Authorization: Bearer ..."` |
| "Only run XSS modules"                                     | `vigolium scan -t <url> --module-tag xss`                                                  |
| "Review my code for security issues"                       | `vigolium agent query --prompt-template security-code-review --source ./src`               |
| "Autonomous scan focused on injection"                     | `vigolium agent autopilot -t <url> --focus "injection"`                                    |
| "Run the full AI pipeline"                                 | `vigolium agent swarm --discover -t <url>`                                                 |
| "Show me all critical findings"                            | `vigolium finding --severity critical`                                                     |
| "Export results as HTML report"                            | `vigolium export --format html -o report.html`                                             |
| "What traffic is in the database?"                         | `vigolium traffic`                                                                         |
| "Write me an extension that checks for exposed .env files" | Generates a JS extension file                                                              |
| "Start the server with auto-scan"                          | `vigolium server -t <url> --scan-on-receive`                                               |
| "Whitebox scan with my source code"                        | `vigolium scan -t <url> --source ./src --strategy whitebox`                                |
| "Clean up old scan data"                                   | `vigolium db clean --before <date> --force`                                                |

***

## Tips & Best Practices

1. **Start with `scan -t`**: It's the most common command. Add flags incrementally.
2. **Use strategies**: `lite` for quick checks, `balanced` for most cases, `deep` for full coverage, `whitebox` when you have source code.
3. **Phase isolation**: Use `--only` or `vigolium run <phase>` to iterate on a single phase without re-running the entire pipeline.
4. **Module tags**: Filter modules by technology (`spring`, `nodejs`) or vulnerability class (`xss`, `injection`) to reduce noise.
5. **Watch mode**: Add `--watch 5s` to `traffic`, `finding`, or `db stats` for real-time monitoring during long scans.
6. **Dry-run agents**: Always `--dry-run` first for agent commands to preview prompts before spending AI tokens.
7. **Swarm over autopilot**: Use `agent swarm --discover` for structured scans (lower cost, reproducible). Use `agent autopilot` for exploratory, creative scanning.
8. **Extensions for custom logic**: Write JS extensions instead of modifying core modules. They run alongside built-in modules with `--ext`.
9. **Projects for isolation**: Use `vigolium project create` to keep scan data separate across engagements.
10. **Export early**: Run `vigolium export --format html -o report.html` to share results as interactive reports.