Using the Vigolium Scanner Skill in Claude Code & Codex

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 — or install the copy embedded in your vigolium binary, which always matches your installed version.

Quick Install

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

bunx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes

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

The three machine contracts

Whether or not you install the skill, these are the interfaces a program drives Vigolium through. They are additive — default human output is unchanged.

Contract	What it is	When to use it
`-j` / `--json`	One compact envelope per command, with token-bounded bodies	Triage: survey findings, pull one in detail
`--format jsonl` / `vigolium export`	Bulk, full-fidelity stream, one object per line	Archival, handing a whole run to another tool
`--events ndjson`	A live stream while a scan runs	Watching progress, reacting to a WAF block mid-run

`--events ndjson`: watch a scan while it runs

Don’t poll the database and don’t invent a patience message — ask for the stream. One JSON object per line on stdout, flushed per event, while the human console stays on stderr:

vigolium scan -t https://target.example --events ndjson 2>/dev/null | jq -c .

Available on scan, run, scan-url, scan-request. Types: scan.started, phase.started|progress|finished, waf.block, waf.pacing, finding.new, error, scan.finished. The three you should actually branch on:

waf.block — the edge started filtering. Results for that host are incomplete; do not read a thin surface as a clean target.
error — a phase failed and the scan carried on. Non-fatal by construction, so this is never a reason to abandon a run that is still producing findings. A failure that ends the run rides on scan.finished{status:"failed"} instead.
scan.finished — always last, including status:"interrupted" on SIGINT/SIGTERM. Its absence means the process was killed outright (SIGKILL can’t be caught), so treat a stream that stops without it as a hard kill, not a completed scan.

Every line carries scan_uuid (a sweep is several invocations) and v, the event-schema version. This replaces scraping vigolium log for [waf-block-detected] markers. Full event table: CLI References.

`-j`: one envelope, every command

{ "schema_version": 1, "command": "traffic", "project_uuid": "…",
  "db_path": "/home/me/.vigolium/database-vgnm.sqlite",
  "total": 39, "offset": 0, "limit": 100,
  "items": [ … ],
  "query": "vigolium replay -u <uuid>",
  "generated_at": "2026-09-04T10:11:12.345Z", "generated_at_ms": 1788453072345 }

Parse items — it is the row array, and since v0.4.6 the only one. The historical row keys (records, findings, scans, rows, stats) are gone from the default output: they shipped a second full copy of every row, 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) restores the alias for a caller still migrating, at that cost. Assert db_path: the database open order ends at one shared default file, so a fall-through silently mixes engagements. Run the query field rather than composing your own follow-up.

query is a ready-to-run follow-up pinned to the same store and scope, correctly shell-quoted:

q=$(vigolium --db ./run.sqlite -S finding --limit 1 --json | jq -r .query)
eval "$q"    # reaches the same finding in the same database

Finding IDs are per-database autoincrement integers, so the --db / --stateless / --project-uuid flags inside that string are load-bearing. Under --glob-db the field is absent, because the merged source is a temporary database that no argument list can reopen.

Gate on the contract once at startup with vigolium version --json, which reports schema_version and db_schema_version.

Exit codes

0 success · 1 error · 2 usage error · 3 fuzz --fail-on-match · 4 --fail-on gate tripped. 3 and 4 are completed results, not failures: the output was written before the code was chosen. When it was not written, the run is 1 with error.code: "export_failed", and that outranks the gate. 3 and 4 are completed results, not failures. The output was written before the code was chosen. --soft-fail forces the process status to 0 for all of them while leaving the output intact — under --json the error object still reports the code that would have been used, plus "soft_fail": true. See the full table.

One document per invocation

Under --json you get exactly one document, whatever happens:

Flag order does not matter. traffic --bad --json and traffic --json --bad both emit one usage_error object.
A command that already wrote its result does not get an error object appended to it — the exit code carries the outcome.
Nothing else is ever written to stdout. Banners, prompts, progress, and warnings all go to stderr.

Error codes worth branching on: usage_error, source_missing, source_unreadable, source_incompatible (a valid SQLite file that is not a Vigolium store — you are pointed at the wrong file), export_failed (the run finished but a requested artifact was not written — retry the export, not the scan), gate_tripped, failed. traffic body and traffic headers add four of their own: record_not_found, body_unavailable, body_decode_failed, body_incomplete.

A requested artifact that was not written is exit 1, code export_failed (v0.5.0) — even when the scan itself ran clean, and even when it would otherwise have tripped the --fail-on gate. The gate’s whole premise is that the output was written before the code was chosen; when it wasn’t, exit 4 would send you to read a file that does not exist.Retry the export, not the scan: the findings reached the database, they just did not reach your -o. Formats are attempted independently, so with --format jsonl,sqlite one of them may well be on disk — the Exports summary on stderr lists what actually landed. Before v0.5.0 this state was exit 0 with scan.finished status=completed and no file.

A wrong --db path errors as of v0.4.7 — it no longer reads as empty. A pure read (traffic, finding, db ls, db stats, db export, export, log, traffic body/headers) against an explicitly pinned --db or $VIGOLIUM_DB_PATH that is not there now fails source_missing (exit 1) and creates nothing; another tool’s SQLite file fails source_incompatible (exit 1) without Vigolium’s tables being written into it. Before v0.4.7 both returned {"total":0,"items":[]} with exit 0, so “the path is wrong” and “nothing was captured here” were the same answer — and the wrong one looked like a finished task.The built-in default database is still created on first use, and replay/fuzz are exempt because they record the traffic they send. If you must support older builds, keep asserting db_path and sanity-check total against a query you know matches.

Confirmation for a destructive command requires a terminal. Without one it refuses immediately with exit 2 rather than blocking or reading your data stream as the answer; pass --force to authorize it non-interactively. --json is not authorization. Reading stdin is bounded by --input-read-timeout (default 3m, 0 disables), so a producer that never closes its end will not hang the process.

Discovering the interface

Don’t parse help text. Every registry that validates a flag can print itself:

vigolium strategy --json    # strategies, phase names + aliases, intensities,
                            # agent modes, installed profiles
vigolium config ls --json   # every setting (credentials redacted)
vigolium scope view --json  # scope rules
vigolium module ls --json   # module catalog
vigolium doctor --json      # environment readiness

strategy --json is generated from the same registries the flags are validated against, so phases[].canonical and phases[].aliases are exactly what --only, --skip, and run <phase> accept.

Credentials

auth list and config ls redact secrets by default — session tokens, auth headers, stored login requests, and login bodies. This applies under --json too, because --json output is the output most likely to end up in a transcript. --show-secrets reveals them and prints a warning to stderr. Redacted rows keep has_session_token, header_names, and a session_token_fingerprint (a short stable digest), so you can still tell two sessions apart or confirm a rotation landed without ever reading the secret.

What the Skill Does

The skill teaches the AI agent how to:

Pick the right vigolium command for any security testing task
Construct correct flag combinations with proper syntax
Follow scanning workflows end-to-end (ingest -> scan -> triage -> export)
Write custom JavaScript extensions using the vigolium.* API
Operate AI agent modes (query, autopilot, swarm)
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, routing)
└── references/
    ├── scanning.md              # scan, scan-url, scan-request, run
    ├── agent-modes.md           # agent query/autopilot/swarm/audit/olium/triage/session
    ├── agent-loop.md            # the -j JSON contracts, triage, replay, exit-code gating
    ├── fuzzing.md               # vigolium fuzz: positions, payloads, matchers, anomaly
    ├── burp.md                  # Burp bridge: send-via-burp, Repeater/Organizer staging
    ├── auth.md                  # --auth-file / --auth, YAML format, extract rules
    ├── data.md                  # db, finding, traffic, module, ext, js, config, export
    ├── server.md                # vigolium server: REST API, recording/MITM proxy, live mirror
    ├── ingest.md                # vigolium ingest: local/remote, per-format input examples
    ├── kit.md                   # vigolium kit: the standalone stateless primitives
    ├── extensions.md            # writing JS scanner modules against vigolium.*
    └── flags.generated.md       # generated from the command tree — grep by flag name

These filenames changed in v0.3.7–v0.3.9: the references were renamed to shorter stems, flags-reference.md became the generated flags.generated.md, server-and-ingestion.md split into server.md + ingest.md, and fuzzing and the Burp bridge moved out of agent-loop.md into their own files. A separate agent-browser skill was dropped. Re-run vigolium skills install to pick up the current layout.

Installation

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

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

bunx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes

or with npx:

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 repository and registers it automatically. Option C: Clone and copy manually

git clone https://github.com/vigolium/skills.git
cd skills

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

# 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

vigolium scan -t https://example.com

Multiple targets:

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

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

vigolium scan -T targets.txt

Do not pre-prefix a hostname list. Since v0.4.8 a schemeless target — example.com, example.com:8443, or a whole -T file of bare hostnames — is normalized to http:// at every entry point (CLI, REST API, agent swarm, scan-url), before the dedup, so example.com and http://example.com count as one target. Before v0.4.8 such lists scanned fine under probe, discovery and known-issue-scan but silently produced zero spidering records, and --only spidering --soft-fail still exited 0. See Schemeless targets.

Scan with a specific strategy:

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

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

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

vigolium scan-request -i request.txt

Scan a raw request from stdin:

> Scan this raw request from the terminal

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

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

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

vigolium scan -t https://example.com --format jsonl -o results.jsonl

Scan and generate an HTML report:

> Scan and produce an interactive HTML report

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

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

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 for the full layout. Scan to SARIF (for GitHub code scanning / DefectDojo):

> Scan and produce a SARIF file I can upload to code scanning

vigolium scan -S -t https://example.com --format sarif -o results.sarif

--format sarif writes a SARIF 2.1.0 log; it also works on vigolium export --format sarif and vigolium import --format sarif (the path for publishing an agentic source audit). Code findings anchor to file:line so a consumer can annotate a diff; HTTP findings anchor to their URL and carry the evidence exchange in webRequest/webResponse. See Output and Reporting. Scan with custom scanning profile:

> Use the aggressive scanning profile

vigolium scan -t https://example.com --scanning-profile aggressive

Scan with strict origin scope:

> Only scan URLs on the exact same origin

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

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

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

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

vigolium scan -I swagger -i swagger.json -t https://api.example.com

Burp Suite XML export:

> I exported traffic from Burp, scan it

vigolium scan -I burp -i burp-export.xml -t https://example.com

HAR (HTTP Archive) file:

> Scan my browser-recorded HAR file

vigolium scan -I har -i traffic.har

cURL commands file:

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

vigolium scan -I curl -i curl-commands.txt

Postman collection:

> Import and scan my Postman collection

vigolium scan -I postman -i collection.json -t https://api.example.com

Nuclei templates:

> Run these Nuclei templates against the target

vigolium scan -I nuclei -i templates/ -t https://example.com

Piped URLs from stdin:

> Pipe a list of URLs into the scanner

cat urls.txt | vigolium scan -i -

3. Phase Control

Run only discovery (content enumeration):

> Just run content discovery against the target

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

vigolium run spidering -t https://example.com

Run only audit (vulnerability scanning):

> Skip discovery, just run the vulnerability modules

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

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

vigolium agent audit --source /path/to/app

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

> Gather URLs from external intelligence sources

vigolium run external-harvest -t https://example.com

Skip specific phases:

> Scan but skip discovery and spidering

vigolium scan -t https://example.com --skip discovery,spidering

Run only JavaScript extensions:

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

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`
`ext`	`extension`
`audit`, `dast`, `assessment`	`dynamic-assessment`
`cve`, `kis`, `known-issues`	`known-issue-scan`

4. Module Filtering

List all available scanner modules:

> Show me all scanner modules

vigolium module ls
# or
vigolium scan -M

Filter modules by keyword:

> Show me all XSS-related modules

vigolium module ls xss

List only active modules with verbose details:

> Show active modules with descriptions

vigolium module ls --type active -v

Scan with specific modules only:

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

vigolium scan -t https://example.com -m xss-light-url-params,sqli-error-based

Filter modules by tags (OR logic):

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

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

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

vigolium module disable sqli
vigolium module enable xss

Enable by exact module ID:

> Enable only the reflected XSS module

vigolium module enable xss-light-url-params --id

5. Server & Ingestion

Start the API server (default port 9002):

> Start the vigolium server

vigolium server

Start server on custom port without auth:

> Start the server on port 8443 with no authentication

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

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

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

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

vigolium server -c 200 --mem-buffer 50000

Ingest an OpenAPI spec locally:

> Import the spec into the database without scanning

vigolium ingest -t https://api.example.com -I openapi -i spec.yaml

Ingest and auto-scan:

> Import the spec and scan immediately

vigolium ingest -t https://api.example.com -I openapi -i spec.yaml -S

Ingest Burp export:

> Import Burp traffic into the database

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

vigolium ingest -s http://localhost:9002 -I openapi -i spec.yaml

Ingest without fetching responses:

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

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

vigolium agent query --prompt-template security-code-review --source ./src

Endpoint discovery from source:

> Find all API endpoints in my source code

vigolium agent query --prompt-template endpoint-discovery --source ./src

Review specific files only:

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

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

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

vigolium agent query --prompt-file custom-prompt.md --source ./src

Select a specific olium provider:

> Use Anthropic for code review

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

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

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?

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

vigolium agent query 'review this code for SQL injection vulnerabilities'

Named prompt flag:

> Analyze the authentication flow

vigolium agent query --prompt 'analyze the authentication flow for bypass vectors'

Pipe prompt from stdin:

> Pipe a prompt to the agent

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

vigolium agent query --provider anthropic-api-key --prompt-file custom-prompt.md

Pick a different model:

> Run the review on a frontier model

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

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

vigolium agent autopilot -t https://api.example.com --source ./src \
  --prompt "focus on auth bypass"

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

> Run a quick scan capped at 15 minutes

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

vigolium agent autopilot -t https://example.com --dry-run

Custom system prompt:

> Use my own system prompt for autopilot

vigolium agent autopilot -t https://example.com --system-prompt-file my-system-prompt.md

Start from project traffic, Burp history, and app docs:

> Use the traffic we already captured and the application's role documentation

vigolium agent autopilot -t https://example.com \
  --burp-bridge-url http://127.0.0.1:9009 \
  --prior-context auto --knowledge-base ./app-docs

Resume a durable run:

vigolium agent autopilot --resume <agentic-scan-uuid> \
  --prompt "finish the remaining privilege-boundary checks"

Use a different olium provider:

> Run autopilot through Google Vertex

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. Common scanner, record, replay, finding, OAST, auth-session, and Burp operations are also first-class tools; the model can still shell out for uncovered CLI operations.
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.
In legacy/shadow mode, report_finding soft-warns at 50 findings and hard-caps at 200. In enforced mode, propose_candidate routes claims through fresh-context verification before promotion.
Run autopilot in a disposable container or VM scoped to in-scope targets — see Security Warning.

Agent Swarm (AI-Guided Multi-Phase Scan)

Basic swarm scan with discovery (all phases):

> Run the full AI swarm scan

vigolium agent swarm --discover -t https://example.com

The swarm runs ten phases in order (most are conditional — see Swarm for full detail):

native-normalize — parse --input/stdin/record-uuid into HTTP records
auth (optional) — browser-driven login, writes auth headers/cookies
source-analysis (if --source) — 4-call wave that emits routes, session-config, and source extensions
code-audit (if --code-audit) — code-level security audit, findings → DB
native-discover (if --discover) — crawl/spider/JS-scan
plan — master agent picks modules and writes an extensions spec
native-extension — compile/validate generated JS extensions (Sobek)
native-scan — runner.RunNativeScan() with the planned modules + extensions
triage (if --triage) — AI verifies findings, may request targeted rescans
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

vigolium agent swarm --discover -t https://example.com \
  --prompt "focus on SQL injection" --source ./src

Control rescan iterations:

> Allow up to 3 triage->rescan iterations

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

vigolium agent swarm -t https://example.com --start-from plan

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

> Run swarm but skip triage and rescan

vigolium agent swarm --discover -t https://example.com --skip triage --skip rescan

Use a scanning profile:

> Run swarm with the deep scanning profile

vigolium agent swarm --discover -t https://example.com --profile deep

Preview agent prompts (dry run):

> Show me the prompts without executing

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

vigolium agent swarm --discover -t https://example.com --source ./src \
  --files "routes.go,handlers.go"

Use a different agent backend:

> Run swarm with Gemini

vigolium agent swarm --discover -t https://example.com \
  --provider google-vertex --model gemini-2.5-pro

7. Traffic & Results Browsing

Browse all stored HTTP traffic:

> Show me the HTTP traffic in the database

vigolium traffic

Fuzzy search traffic:

> Show traffic related to login

vigolium traffic login

Tree view (hierarchical URL structure):

> Show traffic as a directory tree

vigolium traffic --tree

Burp-style colored output:

> Show traffic in Burp Suite style

vigolium traffic --burp

Filter by host, method, status:

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

vigolium traffic --host api.example.com --method POST,PUT --status 200

Filter by date range:

> Show traffic from January 2024

vigolium traffic --from 2024-01-01 --to 2024-01-31

Search in request/response body:

> Find traffic containing "password" in the body

vigolium traffic --body password

Since v0.4.7, --body searches only the body and --header only the header block; --search is the one that spans the whole exchange. Terms are matched literally, so % and _ are ordinary characters (--body 'api_key' no longer also matches api-key). --host/--path stay patterns, where * is the wildcard.

Select one exact URL (not a substring):

> Show the record for exactly https://api.example.com/v1/me

vigolium traffic --url 'https://api.example.com/v1/me'

--url is equality, repeatable and OR-ed, and applied before pagination — the positional term is a substring search, and --uuid is identity. Extract one message without re-sending it:

> Save the response body of that record to a file

vigolium traffic body --uuid <uuid> -o response.json          # exact bytes, gzip-decoded
vigolium traffic body --uuid <uuid> --representation stored -o body.gz
vigolium traffic body --uuid <uuid> -j                        # receipt only: bytes, sha256, complete
vigolium traffic headers --uuid <uuid> --name set-cookie -j   # ordered array, every match

This is the answer to a decoder_capped: true body: pull it whole in one call rather than concluding a string is absent. Four failure states are distinguishable — record_not_found, body_unavailable (that side was never captured), body_decode_failed, body_incomplete (a prefix; --allow-incomplete writes it anyway) — and a captured, genuinely empty body succeeds with empty: true. Keep a large result out of your context:

> Save all high-severity findings to a file

vigolium finding -j -n 500 --min-severity high -o findings.json

-o works on traffic, finding and db ls under -j. The file is byte-identical to what would have been printed; stdout gets {"artifact":"json_result","output":…,"bytes":…,"sha256":…,"complete":true}. complete: false means it holds one page. Search in headers:

> Find traffic with JWT tokens in headers

vigolium traffic --header "Bearer"

Custom columns:

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

vigolium traffic --columns HOST,METHOD,PATH,STATUS,AUTH

Watch mode (auto-refresh):

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

vigolium traffic --watch 5s

View raw HTTP request/response:

> Show raw traffic for the last 5 records

vigolium traffic --raw --limit 5

Browse findings:

> Show all vulnerability findings

vigolium finding

Filter findings by severity:

> Show only high and critical findings

vigolium finding --severity high,critical

Search findings:

> Find SQL injection findings

vigolium finding --search "sql injection"

Watch findings in real-time:

> Monitor findings as they come in

vigolium finding --watch 5s

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

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

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

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

vigolium replay --search login

Replay and replace stored responses:

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

vigolium replay --host api.example.com --in-replace

8. Data Management

Database statistics:

> Show me database stats

vigolium db stats

Detailed stats with host breakdown:

> Show detailed stats broken down by host

vigolium db stats --detailed

Stats for a specific host:

> Stats for example.com only

vigolium db stats --host example.com

Live-updating stats:

> Watch database stats, refresh every 10 seconds

vigolium db stats --watch 10s

List database records with filters:

> Show findings table, critical and high severity

vigolium db ls --table findings --severity critical,high

List available tables and columns:

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

vigolium db ls --list-tables
vigolium db ls --list-columns --table findings

Clean records by hostname:

> Delete all records for old-target.com

vigolium db clean --host old-target.com --force

Clean old records with dry-run preview:

> Preview what would be deleted before January 2024

vigolium db clean --before 2024-01-01 --dry-run

Clean only findings (keep HTTP records):

> Delete info-severity findings but keep the HTTP records

vigolium db clean --findings-only --severity info --force

Clean orphaned findings:

> Remove findings without associated HTTP records

vigolium db clean --orphans

Reset entire database:

> Wipe the entire database and start fresh

vigolium db reset --force

Reclaim disk space after deletion:

> Delete last month's records and reclaim the space

vigolium db clean --before 2026-07-01     # VACUUM runs automatically after a delete

9. Export & Reports

Full JSONL export:

> Export everything from the database as JSONL

vigolium export --format jsonl -o full-export.jsonl

Export only findings:

> Export just the findings

vigolium export --format jsonl --only findings -o findings.jsonl

Export findings and HTTP records:

> Export findings and associated HTTP traffic

vigolium export --format jsonl --only findings,http -o results.jsonl

HTML report:

> Generate an interactive HTML report

vigolium export --format html -o report.html

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

> Export URLs only, without raw request/response data

vigolium export --omit-response --only http -o urls.jsonl

Export with search filter:

> Export only records matching example.com

vigolium export --search "example.com" -o filtered.jsonl

Database-level export as CSV:

> Export HTTP records as CSV

vigolium db export -f csv -o records.csv

Export as Markdown:

> Export records as a Markdown report

vigolium db export -f markdown -o report.md

Export raw requests only:

> Export just the raw HTTP requests

vigolium db export -f raw --request-only -o requests.txt

Export filtered by host and date:

> Export records for example.com from 2024 onwards

vigolium db export -f csv -o records.csv --host example.com --from 2024-01-01

Export a single record by UUID:

> Export record abc12345

vigolium db export --uuid abc12345

Export module registry:

> Export all available scanner modules

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

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

# 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

vigolium agent audit --source /path/to/app

Deeper multi-phase audit:

> Run a thorough deep-mode source audit

vigolium agent audit --source /path/to/app --mode deep

11. JavaScript Extensions

Install preset examples:

> Install the example extension scripts

vigolium ext preset

View the extension API reference:

> Show me the extension API docs

vigolium ext docs
vigolium ext docs --example          # with code examples
vigolium ext docs http               # filter by namespace

List loaded extensions:

> Show currently loaded extensions

vigolium ext ls
vigolium ext ls --type active        # active extensions only

Quick-test JS code inline:

> Test a JS expression

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

vigolium ext eval --ext-file script.js

Run a custom extension against a target:

> Run my custom scanner extension

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

vigolium scan -t https://example.com --ext custom-check.js

Run only extensions (skip built-in modules):

> Run only my custom extensions

vigolium scan -t https://example.com --only extension --ext custom-check.js

Load multiple extensions:

> Run three extensions together

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

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:

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

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

vigolium config ls

View a specific config section:

> Show scope configuration

vigolium config ls scope
vigolium config ls scanning_pace
vigolium config ls server

Set configuration values:

> Set the default strategy to deep

vigolium config set scanning_strategy.default_strategy deep

Set scope mode:

> Set origin scope to strict

vigolium config set scope.origin.mode strict

Enable extensions globally:

> Enable extensions in audit

vigolium config set audit.extensions.enabled true

View scope rules:

> Show current scope rules

vigolium scope view
vigolium scope view host

View scanning strategies:

> Show available strategies and their phases

vigolium strategy

Create and manage projects:

> Create a project, then switch to it

vigolium project create my-project
vigolium project list
vigolium project use my-project

Scope CLI operations to a project:

> Scan within a specific project

vigolium scan -t https://example.com --project-name my-project

Project-scoped database access:

> Show stats for my-project

VIGOLIUM_PROJECT_UUID=a1b2c3d4-... 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> --prompt "focus on 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

Start with scan -t: It’s the most common command. Add flags incrementally.
Use strategies: lite for quick checks, balanced for most cases, deep for full coverage, whitebox when you have source code.
Phase isolation: Use --only or vigolium run <phase> to iterate on a single phase without re-running the entire pipeline.
Module tags: Filter modules by technology (spring, nodejs) or vulnerability class (xss, injection) to reduce noise.
Watch mode: Add --watch 5s to traffic, finding, or db stats for real-time monitoring during long scans. Under --json it switches to NDJSON — one compact document per line, no clear-screen, no heading — and it is rejected on a command that writes.
Triage at scale first: vigolium run probe -T hosts.txt sweeps thousands of hosts with one request each. Rank by surface_score, then point a real scan at the top of that list — don’t send a full scan at a list you haven’t triaged.
Count, don’t dump: vigolium traffic --group-by status_code runs the same filters the listing would and returns buckets. Never pull rows into your context just to count them.
Route bulk output to disk: -o findings.json on a -j read puts the document in a file and a receipt on stdout. For one message, traffic body/traffic headers beat exporting a whole record tree.
Dry-run agents: Always --dry-run first for agent commands to preview prompts before spending AI tokens.
Swarm over autopilot: Use agent swarm --discover for structured scans (lower cost, reproducible). Use agent autopilot for exploratory, creative scanning.
Extensions for custom logic: Write JS extensions instead of modifying core modules. They run alongside built-in modules with --ext.
Projects for isolation: Use vigolium project create to keep scan data separate across engagements.
Export early: Run vigolium export --format html -o report.html to share results as interactive reports.

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Using the Vigolium Scanner Skill in Claude Code & Codex

Quick Install

The three machine contracts

`--events ndjson`: watch a scan while it runs

`-j`: one envelope, every command

Exit codes

One document per invocation

Discovering the interface

Credentials

What the Skill Does

Skill Structure

Installation

Usage Examples by Category

1. Scanning

2. Input Formats

3. Phase Control

4. Module Filtering

5. Server & Ingestion

6. AI Agent Modes

Agent (Template-Based)

Agent Query (Freeform Prompt)

Agent Autopilot (Autonomous Scanning)

Agent Swarm (AI-Guided Multi-Phase Scan)

7. Traffic & Results Browsing

8. Data Management

9. Export & Reports

10. Whitebox / Source-Aware Scanning

11. JavaScript Extensions

12. Configuration & Projects

Natural Language Examples

Tips & Best Practices

​Quick Install

​The three machine contracts

​--events ndjson: watch a scan while it runs

​-j: one envelope, every command

​Exit codes

​One document per invocation

​Discovering the interface

​Credentials

​What the Skill Does

​Skill Structure

​Installation

​Usage Examples by Category

​1. Scanning

​2. Input Formats

​3. Phase Control

​4. Module Filtering

​5. Server & Ingestion

​6. AI Agent Modes

​Agent (Template-Based)

​Agent Query (Freeform Prompt)

​Agent Autopilot (Autonomous Scanning)

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

​7. Traffic & Results Browsing

​8. Data Management

​9. Export & Reports

​10. Whitebox / Source-Aware Scanning

​11. JavaScript Extensions

​12. Configuration & Projects

​Natural Language Examples

​Tips & Best Practices

Quick Install

The three machine contracts

`--events ndjson`: watch a scan while it runs

`-j`: one envelope, every command

Exit codes

One document per invocation

Discovering the interface

Credentials

What the Skill Does

Skill Structure

Installation

Usage Examples by Category

1. Scanning

2. Input Formats

3. Phase Control

4. Module Filtering

5. Server & Ingestion

6. AI Agent Modes

Agent (Template-Based)

Agent Query (Freeform Prompt)

Agent Autopilot (Autonomous Scanning)

Agent Swarm (AI-Guided Multi-Phase Scan)

7. Traffic & Results Browsing

8. Data Management

9. Export & Reports

10. Whitebox / Source-Aware Scanning

11. JavaScript Extensions

12. Configuration & Projects

Natural Language Examples

Tips & Best Practices