Operator's guide for the Vigolium high-fidelity web vulnerability scanner. Covers every command, flag, workflow pattern, scanning strategy, AI agent modes, and JavaScript extension authoring. Full documentation at docs.vigolium.com.
Role Definition
Vigolium is a CLI-first vulnerability scanner that operates in multiple modes:
Standalone scanner: scan, scan-url, scan-request, run
REST API server with traffic ingestion: server, ingest
AI agent integration (all dispatch flows through the in-process olium engine — no subprocess SDK backends):
agent query — single-shot prompt (template-based or inline) for code review / endpoint discovery
agent autopilot — autonomous AI-driven scanning that drives the vigolium CLI
agent swarm — AI-guided targeted or full-scope scanning (add --discover for full-scope)
Extension runner: run extension --ext custom-check.js for custom JS scanning logic
JavaScript executor: js for ad-hoc scripting with full vigolium.* API access
Session log viewer: log <uuid> streams runtime.log for native + agentic sessions (tail / follow / DB fallback)
Data import: import <path> ingests audit output folders (vigolium-results/) and JSONL exports
Cloud storage: storage ls/upload/download/rm/presign/results manages per-project objects in the configured bucket
Lifecycle: init sets up , wipes it back to a fresh state
~/.vigolium/
config clean
Olium provider drivers (set via agent.olium.provider or --provider):
openai-compatible (default): any OpenAI Chat-Completions-compatible endpoint via agent.olium.custom_provider.base_url / model_id (default points at a local Ollama at http://localhost:11434/v1, model gemma4:latest)
openai-codex-oauth: OpenAI Codex via ~/.codex/auth.json (ChatGPT subscription)
anthropic-api-key: Anthropic Messages API via $ANTHROPIC_API_KEY / --llm-api-key
anthropic-oauth: Anthropic Claude via Claude Code OAuth bearer token (claude setup-token)
openai-api-key: OpenAI Chat Completions via $OPENAI_API_KEY / --llm-api-key
anthropic-cli: Shells out to the local claude CLI binary (Claude Max subscribers)
anthropic-vertex: Anthropic Claude on GCP Vertex AI via service-account JSON (--oauth-cred / $GOOGLE_APPLICATION_CREDENTIALS); requires a claude-* model (e.g. claude-opus-4-6)
google-vertex: Gemini-native on GCP Vertex AI via service-account JSON; requires a gemini-* model (e.g. gemini-3.1-pro)
This skill helps you pick the right command, flags, and workflow for any security testing task.
Command Decision Tree
Use this to find the right command quickly:
I need to...
Use
Scan one or more target URLs
vigolium scan -t <url>
Scan a single URL with custom method/headers
vigolium scan-url <url> --method POST --body '...'
Scan a raw HTTP request from file/stdin
vigolium scan-request -i request.txt
Run only one scan phase
vigolium run <phase> or scan --only <phase>
Run a custom JS extension against a target
vigolium run extension -t <url> --ext custom-check.js
Machine-readable bulk stream, one {"type":...,"data":{...}} envelope per line
HTML report
--format html -o report.html
Interactive ag-grid report, requires -o
SQLite
--format sqlite -S -o run.sqlite
Dumps the run's standalone temp DB via VACUUM INTO. Requires -S/--stateless + -o. Aliases: sqlite3, db. Reopen with vigolium finding/traffic -S --db run.sqlite
Filesystem tree
--format fs -o run
Browsable flat tree: run-traffic/ + run-findings/ with per-host .req / .resp.headers / .resp.body / .md files + index.json. No -o → vigolium-traffic/ + vigolium-findings/. See recipe 16b
Multiple formats can be combined: --format jsonl,html -o report.html
Export from database: vigolium export --format jsonl -o full-export.jsonl
Export specific data: vigolium export --only findings,http
Export HTML report: vigolium export --format html -o report.html
Export a browsable filesystem tree: vigolium export --format fs -o run
DB export with filters: vigolium db export -f csv -o records.csv --host example.com
-j/--json vs --format jsonl. On the read/query commands (finding, traffic, db), -j/--json emits a single compact, token-aware object built for driving vigolium from a coding agent (bodies header-kept + preview-capped, binary/static stubbed, findings get a windowed evidence snippet) — different from the bulk --format jsonl stream of full {"type":...,"data":{...}} envelopes. See recipe 14c.
# From file
vigolium scan-request -i raw-request.txt
# From stdinecho -e "GET /api/users HTTP/1.1\r\nHost: example.com\r\n" | vigolium scan-request
# With custom method and body
vigolium scan-url https://api.example.com/login \
--method POST --body '{"user":"admin","pass":"test"}' \
-H "Content-Type: application/json"
6. Extensions-Only Phase
# Run only JS extension modules against DB records
vigolium scan -t https://example.com --only extension
# With a specific extension script
vigolium scan -t https://example.com --only ext --ext ./my-scanner.js
# With a custom extensions directory
vigolium scan -t https://example.com --only ext --ext-dir ./extensions/
# Run via the run command (recommended for single extensions)
vigolium run extension -t https://example.com --ext ./custom-check.js
# Run via the run command alias
vigolium run ext -t https://example.com --ext ./custom-check.js
7. Discovery-Only Phase
vigolium run discover -t https://example.com
# or
vigolium scan -t https://example.com --only discovery
8. Targeted Modules
# Run only specific modules by ID
vigolium scan -t https://example.com -m xss-reflected,sqli-error
# Filter modules by tag (OR condition — matches any tag)
vigolium scan -t https://example.com --module-tag spring --module-tag injection
# Combine -m and --module-tag (union of both)
vigolium scan -t https://example.com -m sqli-error --module-tag xss
# List available modules first
vigolium module ls
vigolium module ls xss # filter by keyword
9. Server Mode
# Basic server
vigolium server
# Custom host/port with no auth
vigolium server --host 0.0.0.0 --service-port 8443 -A
# With transparent proxy for recording traffic
vigolium server --ingest-proxy-port 8080
# Mirror every ingested record + finding to a live browsable file tree# (<dir>/traffic + <dir>/findings, in addition to the DB — readable with ls/grep/jq)
vigolium server --ingest-proxy-port 8080 --mirror-fs ./mirror
--mirror-fs <dir> (config server.mirror_fs_path) mirrors each saved HTTP record and finding to <dir>/traffic/ + <dir>/findings/ as they are persisted — the same per-host .req/.resp.*/.md layout as --format fs, but with an append-only index.jsonl (vs the one-shot export's index.json array). It runs on a background goroutine that never blocks the DB save, resumes per-host id numbering across restarts, and is server-ingestion-only (CLI scans are unaffected).
10. Scan-on-Receive (Ingest + Auto-Scan)
# Server mode: auto-scan every ingested request
vigolium server -t https://example.com --scan-on-receive
# Local ingest + scan
vigolium ingest -t https://example.com -I openapi -i spec.yaml -S
11. AI Agent Code Review (agent query)
# Security code review (SDK protocol by default — full tool access)
vigolium agent query --prompt-template security-code-review --source ./src
# Endpoint discovery from source
vigolium agent query --prompt-template endpoint-discovery --source ./src
# List available templates / backends (parent command helpers)
vigolium agent --list-templates
vigolium agent --list-agents
# Custom prompt with inline text
vigolium agent query 'review this code for vulnerabilities'# Pipe a prompt from stdinecho"check for SSRF in the URL-fetching handler" | vigolium agent query --stdin
# Custom prompt file with a specific backend
vigolium agent query --agent claude --prompt-file custom-prompt.md
# With custom instruction appended to the rendered template
vigolium agent query --prompt-template security-code-review --source ./src \
--instruction "Focus on authentication and session management"# Dry-run to preview the rendered prompt
vigolium agent query --prompt-template security-code-review --source ./src --dry-run
# Save output to a file
vigolium agent query --prompt-template security-code-review --source ./src \
--output review-results.json
12. AI Agent Autopilot (Autonomous Scanning)
Autopilot runs a single autonomous operator session that drives the vigolium CLI (Read/Grep/Glob/Bash/Edit/Write tools via the in-process olium engine). When --source is set, an audit harness runs first and the prepared whitebox context is fed to the operator.
Audit-harness auto-pick: when neither --audit nor --piolium is set, autopilot picks piolium if pi + the piolium extension are installed, otherwise falls back to the embedded vigolium-audit at its lite default. Pass --piolium <mode> to force piolium (auto-disables vigolium-audit for the run); pass --audit <mode> to force vigolium-audit; pass --audit=off to disable both.
Intensity presets (--intensity) bundle the operator command budget, audit mode, browser, and pre-scan strategy into a single flag. Explicit flags always override. The Command Budget is internal — there is no --max-commands flag.
Preset
Command Budget
Timeout
Audit Mode
Browser
quick
150
1h
lite
on
balanced (default)
500
6h
balanced
on
deep
1500
12h
deep
on
# Basic autonomous scan (balanced by default)
vigolium agent autopilot -t https://example.com
# Natural-language prompt — target, source, focus are auto-extracted
vigolium agent autopilot "scan VAmPI source at ~/src/VAmPI on localhost:3005"
vigolium agent autopilot "test auth bypass on https://app.example.com"# With source code context (triggers the audit harness automatically)
vigolium agent autopilot -t https://example.com --source ./src
# Specific files + custom instruction
vigolium agent autopilot -t https://example.com --source ./src \
--files "routes/api.js,controllers/auth.js" \
--instruction "Focus on the new payment endpoint"# Intensity presets
vigolium agent autopilot -t https://example.com --source ./src --intensity quick # CI/PR
vigolium agent autopilot -t https://example.com --intensity deep # full pentest# Override a specific setting within a preset
vigolium agent autopilot -t https://example.com --intensity deep --max-duration 4h
# Scan only a PR diff or recent commits
vigolium agent autopilot -t https://example.com --source ./src --diff main...feature-branch
vigolium agent autopilot -t https://example.com --source ./src --last-commits 3
# Cap the wall-clock budget (explicit override)
vigolium agent autopilot -t https://example.com --max-duration 15m
# Pipe a curl command (target auto-derived)echo"curl -X POST https://example.com/api/login -d '{\"user\":\"admin\"}'" | vigolium agent autopilot
# Browser-based auth preflight
vigolium agent autopilot -t https://example.com --browser --credentials "admin/admin123"
vigolium agent autopilot -t https://example.com --browser --auth-required \
--browser-start-url https://example.com/login
# Disable the audit harness when source is provided
vigolium agent autopilot -t https://example.com --source ./src --audit=off
# Choose a specific vigolium-audit mode
vigolium agent autopilot -t https://example.com --source ./src --audit deep
# Force piolium as the audit harness (auto-disables vigolium-audit for this run)
vigolium agent autopilot -t https://example.com --source ./src --piolium balanced
# Run an AI triage pass over findings after the scan
vigolium agent autopilot -t https://example.com --triage
# Skip the prompt-safety classifier on the natural-language prompt (only when refusing a known-good prompt)
vigolium agent autopilot "scan this internal app at https://app.test" --disable-guardrail
# Upload results to cloud storage after completion
vigolium agent autopilot -t https://example.com --source ./src --upload-results
# Preview rendered system prompt without launching the agent
vigolium agent autopilot -t https://example.com --dry-run
# Override the olium provider for a single run
vigolium agent autopilot -t https://example.com --provider anthropic-api-key
# Drive autopilot through anthropic-vertex (Claude on Vertex; requires a claude-* model)
vigolium agent autopilot -t https://example.com \
--provider anthropic-vertex --gcp-project my-gcp --gcp-location us-east5 --model claude-opus-4-6
Intensity presets (--intensity) bundle multiple defaults — explicit flags always override. The preset applies even without --intensity (balanced is the implicit default). Code Audit only takes effect with --source; Auth only with the browser enabled.
Preset
Discover
Triage
Code Audit
Browser
Auth
Swarm Duration
Max Iterations
quick
on
off
off
on
off
2h
1
balanced (default)
on
on
on
on
off
12h
3
deep
on
on
on
on
on
24h
5
# Target a URL for deep analysis
vigolium agent swarm -t https://example.com/api/users
# Natural-language prompt — target, source, focus auto-extracted
vigolium agent swarm "scan source at ~/src/app on localhost:3005"
vigolium agent swarm "scan all source code from ~/src/crAPI, ~/src/DVWA"# Full-scope scan with discovery
vigolium agent swarm -t https://example.com --discover
# Analyze a curl command
vigolium agent swarm --input "curl -X POST https://example.com/api/login -d '{\"user\":\"admin\"}'"# Pipe raw HTTP request from stdin (auto-detected)echo -e "POST /api/search HTTP/1.1\r\nHost: example.com\r\n\r\nq=test" | vigolium agent swarm
# Scan a record from the database
vigolium agent swarm --record-uuid 550e8400-e29b-41d4-a716-446655440000
# Focus on a specific vulnerability type
vigolium agent swarm -t https://example.com/api/users --vuln-type sqli
# Source-aware swarm (route extraction + code audit + SAST + scanning)
vigolium agent swarm -t http://localhost:3000 --source ./src
# Full-scope source-aware scan
vigolium agent swarm -t http://localhost:3000 --source ~/projects/express-app --discover
# Source-aware with specific files
vigolium agent swarm -t http://localhost:8080 --source ./backend \
--files src/routes/api.js,src/models/user.js
# Source analysis only (extract routes, no scan)
vigolium agent swarm -t http://localhost:3000 --source ./src --source-analysis-only
# Intensity presets
vigolium agent swarm -t https://example.com/api/users?id=1 --intensity quick
vigolium agent swarm -t https://example.com --source ./src --intensity deep
# Override a specific setting within a preset
vigolium agent swarm -t https://example.com --intensity deep --triage=false# Run a background vigolium-audit in parallel (requires --source). Bare --audit = lite.
vigolium agent swarm -t http://localhost:3000 --source ./src --audit
vigolium agent swarm -t http://localhost:3000 --source ./src --audit deep
# Or run piolium as the background audit harness (Pi runtime; requires --source)
vigolium agent swarm -t http://localhost:3000 --source ./src --piolium balanced
# Pull HTTP records from the active project as input
vigolium agent swarm --all-records
vigolium agent swarm --records-from "host=example.com,status=200,method=GET,path=/api,since=2026-04-01"
vigolium agent swarm --record-uuid 550e8400-...,7c9b1a2d-... # repeatable / comma-separated# Force the extension agent to run even when the planner picks built-in modules
vigolium agent swarm -t https://example.com/api --with-extensions
# Tune master-agent batching and probing
vigolium agent swarm --all-records --master-batch-size 10 --batch-concurrency 4 \
--probe-concurrency 20 --probe-timeout 15s --max-plan-records 25
# Scan only changed code
vigolium agent swarm -t https://example.com --source ./src --diff main...feature-branch
vigolium agent swarm -t https://example.com --source ./src --last-commits 3
# Skip SAST tools during source analysis
vigolium agent swarm -t http://localhost:3000 --source ./src --skip-sast
# Disable code audit (still runs source analysis + SAST)
vigolium agent swarm -t http://localhost:3000 --source ./src --code-audit=false# Enable triage and rescan loop
vigolium agent swarm -t https://example.com/api/users --triage --max-iterations 5
# Browser automation + auth capture
vigolium agent swarm -t https://example.com --browser --browser-auth \
--credentials "username=admin,password=secret"# Upload results to cloud storage
vigolium agent swarm -t https://example.com --source ./src --upload-results
# Custom instructions to guide the agent
vigolium agent swarm -t https://example.com/api/users --instruction "Focus on GraphQL parsing"# Instructions from a file
vigolium agent swarm -t https://example.com/api/users --instruction-file hints.txt
# Resume from a specific phase
vigolium agent swarm -t https://example.com --start-from plan
# Specify modules explicitly
vigolium agent swarm -t https://example.com/api/search -m xss-reflected,xss-stored
# Control scanning phases
vigolium agent swarm -t https://example.com --only dynamic-assessment
vigolium agent swarm -t https://example.com --skip discovery,spidering
# Custom overall duration
vigolium agent swarm -t https://example.com --max-duration 24h
# Preview master agent prompt (no execution)
vigolium agent swarm -t https://example.com/api/users --dry-run
# Show rendered prompts during execution
vigolium agent swarm -t https://example.com/api/users --show-prompt
13b. AI Agent Audit — vigolium-audit harness (Foreground Whitebox Audit)
Drive the embedded vigolium-audit harness directly with vigolium agent audit --driver=audit (--driver=audit pins the single harness; the dispatcher in §13d covers auto/both).
# Deep audit of a local repo
vigolium agent audit --driver=audit --mode deep --source .
# Fast lite audit of a remote repo (clones automatically)
vigolium agent audit --driver=audit --mode lite --source https://github.com/org/repo
# Balanced audit
vigolium agent audit --driver=audit --mode balanced --source ~/code/myapp
# Second pass on a prior audit tree (revisit with new context)
vigolium agent audit --driver=audit --mode revisit --source ./prior-audit-tree
# PoC construction for previously confirmed findings
vigolium agent audit --driver=audit --mode confirm --source ./audit-with-findings
# Chain modes back-to-back (audit runs them natively as one row)
vigolium agent audit --driver=audit --modes deep,refresh,confirm --source .
# Read-only progress check (no agent launched)
vigolium agent audit --driver=audit --mode status --source ./in-progress-audit
# Pick the coding agent (claude or codex) — provider implies one, --agent overrides
vigolium agent audit --driver=audit --agent codex --source .
# Drive the audit yourself interactively, then import the on-disk results
vigolium agent audit -i --source ./src
vigolium import ./src/vigolium-results --format html -o audit-report.html
# List the audit mode graph (phases, time estimates) and exit
vigolium agent audit --list-modes
Valid --mode values (audit leg): lite, balanced, deep, revisit, confirm, merge (shared) plus reinvest, refresh, mock, diff, status (audit-specific). The audit leg drives the claude or codex CLI directly (selected by --provider/--agent). --no-preflight and --preflight-timeout skip / tune the pre-launch CLI roundtrip; --show-thinking surfaces the agent's thinking blocks; --keep-raw preserves raw scanner output under <source>/vigolium-results/.
13c. AI Agent Piolium (Pi-Native Foreground Audit)
Drives the user's installed piolium Pi extension via pi --mode json -p /piolium-<mode>. Requires pi in PATH and piolium registered (install via pi install git:git@github.com:vigolium/piolium.git). Same on-disk schema as vigolium-audit (audit-state.json + findings-draft/), tagged separately in the DB.
# Balanced 9-phase audit of a local repo
vigolium agent audit --driver=piolium --mode balanced --source .
# Quick lite audit of a remote git URL (auto-clones)
vigolium agent audit --driver=piolium --mode lite --source https://github.com/org/repo
# Hail-mary file-by-file vulnerability hunt over Python+Go files only
vigolium agent audit --driver=piolium --mode longshot --source ./src \
--plm-longshot-langs python,go --plm-longshot-limit 200
# Use a specific Pi provider/model for this run (overrides ~/.pi defaults)
vigolium agent audit --driver=piolium --pi-provider vertex-anthropic --pi-model claude-opus-4-6 --source .
# Full clone history (commit archaeology) via intensity preset
vigolium agent audit --driver=piolium --intensity deep --source https://github.com/org/repo
# Cap commit-history scan to last 60 days
vigolium agent audit --driver=piolium --mode balanced --source . --plm-scan-since "60 days ago"# Resume / re-audit an existing tree (anti-anchored second pass)
vigolium agent audit --driver=piolium --mode revisit --source ./prior-piolium-tree
# Read-only progress check on an in-progress run
vigolium agent audit --driver=piolium --mode status --source ./in-progress-piolium
# Skip the pre-audit pi roundtrip check (auth + model availability)
vigolium agent audit --driver=piolium --mode balanced --source . --no-preflight
Drives the embedded vigolium-audit harness (driver name audit) and/or piolium against the same source tree under a single parent AgenticScan UUID. Default --driver=auto runs vigolium-audit and only falls back to piolium when the resolved claude/codex CLI is missing from PATH — a clean audit run never consults piolium, and a mid-run audit failure surfaces directly rather than silently retrying. --driver=both runs audit then piolium unconditionally. A project-wide post-pass findings dedup runs after the drivers finish. Per-driver child rows + session subdirs ({session}/audit/, {session}/piolium/) keep them separated on disk and in the DB while still scoring as one logical audit.
# Default: run vigolium-audit, fall back to piolium only if claude/codex CLI is missing
vigolium agent audit --source .
# Run both drivers back-to-back, unconditionally
vigolium agent audit --driver=both --source .
# Force a single driver
vigolium agent audit --driver=audit --source .
vigolium agent audit --driver=piolium --source ./src
# Driver-specific modes are only allowed when --driver is forced to that driver
vigolium agent audit --driver=piolium --source . --mode longshot
vigolium agent audit --driver=audit --source . --mode mock
# Audit from a gs:// archive (downloaded + extracted once, shared by both drivers)
vigolium agent audit --source gs://my-project/snapshots/app.tar.gz
# Skip the post-pass project-wide findings dedup
vigolium agent audit --source . --no-dedup
# Pin the audit leg's agent + provider (anthropic-* → claude, openai-* → codex)
vigolium agent audit --source . --provider anthropic-oauth
vigolium agent audit --source . --agent codex
# BYOK auth for the run (literal, $ENV_NAME, or @path)
vigolium agent audit --source . --oauth-token "$(cat ~/.config/claude-token)"# Override piolium's Pi defaults
vigolium agent audit --driver=piolium --source . --pi-provider google-vertex --pi-model gemini-3.1-pro
# Pass piolium-only knobs through (ignored on the audit leg)
vigolium agent audit --driver=piolium --source . --plm-scan-since "30 days ago" --plm-longshot-langs python
Under --driver=auto/both, --mode is restricted to the shared set: lite, balanced, deep, revisit, confirm, merge. Driver-specific modes (piolium's longshot/smoke/diff/status, audit's reinvest/refresh/mock/diff/status) require forcing --driver=piolium or --driver=audit. --intensity deep resolves to the chain deep,confirm; --modes a,b,c chains modes back-to-back. Under --driver=both, if one driver fails the other still runs — the parent run reports per-driver status.
14. Results Inspection
# Browse HTTP traffic
vigolium traffic
vigolium traffic login # fuzzy search
vigolium traffic --tree # hierarchical view
vigolium traffic --burp # Burp-style colored output
vigolium traffic --host api.example.com --method POST
# JSONL output for agent / CI consumption (one JSON object per line)
vigolium traffic -j --host api.example.com
vigolium finding -j --severity high,critical
vigolium db ls -j --table findings
vigolium db stats -j
# Browse findings
vigolium finding
vigolium finding --severity high,critical
vigolium finding --module-type active
vigolium finding --finding-source audit
vigolium finding --burp # Burp-style format
vigolium finding --id 42 # specific finding by ID
vigolium finding --columns ID,SEVERITY,MODULE,MATCHED_AT,TAGS
vigolium db ls --table findings --severity critical
# Database stats
vigolium db stats
vigolium db stats --detailed # includes top hosts breakdown# Watch mode (auto-refresh)
vigolium traffic --watch 5s
vigolium db stats --watch 10
Each line is one record/finding; pipe through jq to filter.
Confirm — mutate one request and diff the result:
vigolium replay --record-uuid <uuid> -m 'name=id,payload=1 OR 1=1' \
--session-id login # persist cookies between calls
vigolium replay is the CLI surface for the in-process replay_request
tool. Accepts every input shape the agents accept — --record-uuid,
--finding-id, or --input for curl / raw HTTP / Burp XML / base64 /
URL / stdin (-). Output is stable JSON: result.baseline,
result.replay, result.diff (status delta, length delta,
content-hash, payload reflection, interpretation). Use --pretty for a
human summary. For many requests at once, see the bulk mode in
step 7 below.
Persist auth state — multi-step flows (login → CSRF → action) need
cookies between calls:
vigolium replay --session-id login -i curl-login.sh # sets cookies
vigolium replay --session-id login --record-uuid <action> # uses cookies
Jar lives at ~/.vigolium/replay-jars/<session-id>.json; pass
--no-cookies to opt out.
Replay a finding's evidence — when a finding came from an
imported source (audit, JSONL) with no linked record, --finding-id
falls back to the finding's stored Request/Response bytes:
Bulk replay — pass --all (or any record filter: --host,
--method, --status, --path, --source, --search, --body) to
run every matched stored record through the same engine instead of a
single source. This mirrors traffic --replay, but each record goes
through the mutation/diff engine and results stream as JSONL (one
result object per line; single-source mode keeps its one indented
object). Any --mutate is applied to every record that has that
insertion point — a batch fuzz primitive — and without --mutate each
record is re-sent verbatim. Throttle with -c/--concurrency (default
10), cap with -n/--limit (default 100; --all lifts it), and read a
standalone export with -S --db:
# Re-send ALL stored traffic through Burp, 5 at a time
vigolium replay --all --proxy http://127.0.0.1:8080 -c 5
# From a standalone .sqlite / .jsonl export (project scoping off)
vigolium replay -S --db scan.sqlite --all --proxy http://127.0.0.1:8080 -c 5
# Fuzz an 'id' param across every matching GET record
vigolium replay --method GET --host api.example.com -m 'name=id,payload=1 OR 1=1'
Bulk selection flags are mutually exclusive with --record-uuid /
--finding-id / --input. --with-browser is not on replay —
for browser-driven bulk replay use traffic --replay --with-browser.
Pipe the JSONL through jq to filter (e.g. only records whose status
changed).
Routes through HTTP_PROXY / HTTPS_PROXY (or --proxy) for Burp
inspection. Honors --project-uuid / --project-name for project
scoping. Mutations support both forms: --mutate 'name=id,payload=1 OR 1=1'
or shorthand --mutate 'id:URL_PARAM:1 OR 1=1'.
For driving vigolium from a coding agent, -j/--json on the read commands (finding, traffic, db ls) emits one token-aware object — not the bulk export stream. Bodies are header-kept and preview-capped (request 1 KiB, response 2 KiB), gzip is decoded transparently, binary/static-asset bodies are stubbed as body_omitted:"binary" + body_sha256, truncated bodies carry body_truncated:true + body_sha256, and each finding gets a ±240-char response_evidence snippet windowed on the match. -j and --json are the same flag.
# Compact JSON for a filtered finding set
vigolium finding -j --severity high,critical
# Self-contained triage bundle: finding + its linked HTTP records embedded
vigolium finding -j --id 42 --with-records
# Findings at/above a severity (threshold expands upward: high → high+critical)
vigolium finding -j --min-severity high
# Every finding from an agent run (one root UUID expands to the whole run tree)
vigolium finding -j --agentic-scan <uuid> --with-records
# Shape the payload
vigolium finding -j --compact # metadata only — drop bodies + evidence
vigolium finding -j --fields id,severity,module_id,url,response_evidence
vigolium finding -j --full-body # complete bodies, no caps or stubbing# Same compact contract on traffic and db ls
vigolium traffic -j --host api.example.com --method POST
vigolium db ls -j --compact # default table = http_records
Shaping flags shared by finding / traffic / db ls: --compact (metadata only), --fields a,b,c (project top-level keys), --full-body (complete bodies). --with-records, --min-severity, and --agentic-scan are finding-only. Note: db stats -j is the exception — it emits its raw stats struct, not the compact view.
16. Export and Reports
# Full JSONL export
vigolium export --format jsonl -o full-export.jsonl
# Export only findings
vigolium export --only findings -o findings.jsonl
# HTML report
vigolium export --format html -o report.html
vigolium scan -t https://example.com --format html -o report.html
# Multiple output formats at once
vigolium scan -t https://example.com --format jsonl,html -o report.html
# Database-level export
vigolium db export -f csv -o records.csv
vigolium db export -f markdown -o report.md
vigolium db export --host example.com --from 2024-01-01
16b. Filesystem Export (--format fs)
--format fs writes a flat, browsable tree so a coding agent (or anyone with ls/grep/jq) can investigate a scan with no database. It writes two sibling dirs off the -o base — -o run yields run-traffic/ + run-findings/; with no -o it defaults to vigolium-traffic/ + vigolium-findings/ in the cwd.
# Scan and write the tree (works with or without -S)
vigolium scan -t https://example.com --format fs -o run
# Alongside other formats
vigolium scan -t https://example.com --format jsonl,fs -o run
# From the database, honoring export filters
vigolium export --format fs -o run
vigolium db export --format fs -o run --host example.com
# Request-only tree (drop the .resp.* files)
vigolium scan -t https://example.com --format fs -o run --omit-response
Layout per host (ids are zero-padded, assigned in sent_at order so re-exports are reproducible):
run-traffic/
index.json # flat jq-friendly array: id → method/url/status/content_type/bytes/finding
<host>/0001.req # "@target <scheme>://<authority>" line, then the raw request verbatim
<host>/0001.resp.headers # status line + response headers
<host>/0001.resp.body # response body, gzip-decoded so it greps clean
run-findings/
index.json # flat array: id → severity/confidence/module/title/url/linked-traffic
<host>/0001.md # finding rendered + cross-linked to its ../run-traffic/<host>/*.req
Notes: the .req file is directly replayable by stripping line 1 (@target …). --omit-response drops the .resp.* files. --split-by-host is a no-op here — the fs layout already splits by host. For scan-url/scan-request, pass -o, -S, or a phase flag so the request routes through the runner that writes the tree.
16c. Standalone SQLite Export (--format sqlite)
--format sqlite dumps the run's standalone per-run database to <output>.sqlite via VACUUM INTO (fully checkpointed, no WAL/SHM sidecars). It requires -S/--stateless (it exports the temp per-run DB; for the persisted DB use vigolium export) and -o/--output. Aliases: sqlite3, db.
# Dump the run to a self-contained .sqlite
vigolium scan -t https://example.com -S --format sqlite -o run.sqlite
# Per-host files under stateless multi-target split (base-<host>.sqlite)
vigolium scan -T targets.txt -S --split-by-host --format sqlite -o run
# The exported file reopens directly, no server needed
vigolium finding -S --db run.sqlite
vigolium traffic -S --db run.sqlite --host example.com
16d. CI Exit-Code Gating (--fail-on / --soft-fail)
--fail-on <severity> makes scan / run / scan-url / scan-request exit non-zero when the scan produced at least one finding at or above that severity — output is always written first, then the gate fires. Accepted severities (ascending): info, suspect, low, medium, high, critical.
# Fail the pipeline on any high/critical finding
vigolium scan -t https://example.com --fail-on high
# Combine with a shareable artifact
vigolium scan -t https://example.com -S --format jsonl -o out.jsonl --fail-on medium
# Never break the wrapping script even on error (global; overrides --fail-on)
vigolium scan -t https://example.com --fail-on high --soft-fail
--soft-fail is a global flag that forces exit 0 even when the gate (or any other error) trips. Under -P/--split-by-host the gate is evaluated per child; the parent batch only exits non-zero when every target fails.
17. Whitebox Scanning (Source-Aware)
# Link source code and scan
vigolium scan -t https://example.com --source ./src --strategy whitebox
# Clone from git URL and scan
vigolium scan -t https://example.com --source-url https://github.com/org/repo --strategy whitebox
# Or link first, then scan
vigolium source add --hostname example.com --path ./src
vigolium scan -t https://example.com --strategy whitebox
# SAST-only phase
vigolium run sast --sast-adhoc /path/to/app
vigolium run sast --sast-adhoc /path/to/app --rule gin
# SAST from git URL (clones automatically)
vigolium run sast --sast-adhoc https://github.com/org/repo
18. Configuration Tuning
# View all config
vigolium config ls# View specific section
vigolium config ls scope
vigolium config ls scanning_pace
# Set values
vigolium config set scanning_strategy.default_strategy deep
vigolium config set scope.origin.mode strict
vigolium config set audit.extensions.enabled true# Speed tuning
vigolium scan -t https://example.com -c 100 -r 200 --max-per-host 5
# Scope tuning
vigolium scan -t https://example.com --scope-origin strict
# Scanning profile
vigolium scan -t https://example.com --scanning-profile aggressive
18b. Cloud Storage (vigolium storage)
Manage cloud-storage objects scoped to the active project (mirrors /api/storage/*). Requires storage.enabled: true plus driver, bucket, access_key, secret_key in vigolium-configs.yaml (or VIGOLIUM_STORAGE_ENABLED=true).
# List all objects under the active project
vigolium storage ls
vigolium storage ls --prefix ugc/ # scope to a sub-path
vigolium storage ls --tree # render as a directory tree
vigolium storage ls --json # machine-readable# Upload a single file
vigolium storage upload ./report.pdf # → ugc/report.pdf
vigolium storage upload ./report.pdf --key reports/q4.pdf # explicit key
vigolium storage upload ./report.pdf --content-type application/pdf
# Download an object (streams to stdout by default)
vigolium storage download ugc/report.pdf -o report.pdf
# Download a scan's result bundle (tries native-scans/ then agentic-scans/)
vigolium storage results 550e8400-e29b-41d4-a716-446655440000
# Generate a presigned GET or PUT URL for direct upload/download
vigolium storage presign --key ugc/foo.tar.gz --method GET --expiry 1h
vigolium storage presign --key ugc/foo.tar.gz --method PUT --expiry 30m --json
# Delete one or more objects (prompts unless -F)
vigolium storage rm ugc/foo.tar.gz
vigolium storage rm ugc/a.pdf ugc/b.pdf -F
Many agent and scan commands accept a --source gs://<project>/<key> URL for source archives — they're downloaded, extracted (.zip / .tar.gz / .tar.bz2 / .tar.xz), and cleaned up automatically. Use --upload-results on scan, agent autopilot, agent swarm, agent audit, and agent query to bundle the session/output and push it to storage at the end of the run.
19. Project Management
# Create a project
vigolium project create my-project
# List projects
vigolium project list
# Use a project (sets default for subsequent commands)
vigolium project use my-project
# Scope CLI operations to a project
vigolium scan -t https://example.com --project-name my-project
# Project-scoped database access
VIGOLIUM_PROJECT=my-project vigolium db stats
20. Writing and Running Custom Extensions
# Install preset examples
vigolium ext preset
# View API reference
vigolium ext docs
vigolium ext docs --example
# Quick-test JS code inline
vigolium ext eval'vigolium.log.info("hello")'
vigolium ext eval --ext-file script.js
# Run a custom extension against a target
vigolium run extension -t https://example.com --ext custom-check.js
# Run during a full scan (extensions run alongside built-in modules)
vigolium scan -t https://example.com --ext custom-check.js
# Run only extensions, skip built-in modules
vigolium scan -t https://example.com --only extension --ext custom-check.js
21. JavaScript Execution (vigolium js)
# Execute inline JS with full vigolium.* API access
vigolium js --code 'vigolium.http.get("https://example.com/api/health")'# Execute JS from a file
vigolium js --code-file scanner-script.js
# TypeScript auto-transpilation
vigolium js --code-file scanner.ts
# From stdin (ideal for agent/pipe workflows)echo'vigolium.utils.md5("password123")' | vigolium js
# With target context (accessible as TARGET variable)
vigolium js --target https://example.com --code 'vigolium.http.get(TARGET + "/api/users")'# Custom timeout and text output format
vigolium js --timeout 60s --format text --code 'vigolium.utils.sha256("hello")'# Complex scripting: ingest, query, and annotate
vigolium js --code-file <<'EOF' > /dev/null
var records = vigolium.db.records.query({ hostname: "example.com", limit: 10 });
for (var i = 0; i < records.length; i++) {
var parsed = vigolium.parse.url(records[i].url);
if (vigolium.utils.hasDynamicSegment(parsed.path)) {
vigolium.db.records.annotate(records[i].uuid, { risk_score: 50 });
vigolium.log.info("Flagged: " + records[i].url);
}
}
EOF
22. Session Logs (vigolium log)
# List all native + agentic sessions with log status
vigolium logls
vigolium log# same as `log ls` when no UUID is given# View a session's runtime.log (auto-follows if the session is still running)
vigolium log <scan-or-agent-uuid>
# Tail last N lines
vigolium log <uuid> --tail 500
# Show the full log
vigolium log <uuid> --full
# Follow live output (tail -f)
vigolium log <uuid> -f
# Strip ANSI color codes (useful when piping to a file)
vigolium log <uuid> --strip-ansi > run.txt
# Interactive TUI picker
vigolium log --tui
Log lookup order: agentic session ~/.vigolium/agent-sessions/<uuid>/runtime.log → native session ~/.vigolium/native-sessions/<uuid>/runtime.log → scan_logs DB table (fallback when scanning_strategy.scan_logs.persist_logs is disabled). The legacy run.log filename is still resolved for older sessions.
23. Data Import (vigolium import)
# Import an audit output folder (contains audit-state.json + findings-draft/)
vigolium import /path/to/vigolium-results/
# Import a JSONL export (supports http_record and finding envelopes)
vigolium import scan-results.jsonl
vigolium import /tmp/demo/juice-shop.jsonl
Audit output folders (produced by vigolium agent audit — vigolium-audit or piolium leg) create a new agentic_scan row plus findings. JSONL imports accept {"type": "http_record", "data": {...}} and {"type": "finding", "data": {...}} envelopes — the format produced by vigolium export --format jsonl.
24. Initialization & Reset
# Create ~/.vigolium with defaults (config, DB schema, profiles, prompts, extensions, SAST rules)
vigolium init
# Regenerate the API key and re-extract all preset data
vigolium init --force
# Wipe ~/.vigolium entirely and reinitialize (prompts for confirmation; use -F/--force to skip)
vigolium config clean
# Diagnose installation health (binaries, paths, permissions)
vigolium doctor
Key Global Flags
These flags are available on all commands (persistent flags on root):
Flag
Short
Default
Description
--target
-t
—
Target URL (repeatable)
--target-file
-T
—
File containing target URLs
--input
-i
- (stdin)
Input file path
--input-mode
-I
urls
Input format (openapi, burp, curl, har, etc.)
--input-read-timeout
—
3m
Timeout for reading input from stdin or file
--concurrency
-c
50
Concurrent scan workers
--rate-limit
-r
100
Max requests per second
--max-per-host
—
30
Max concurrent requests per host
--max-host-error
—
30
Skip host after this many consecutive errors
--max-findings-per-module
—
10
Stop reporting after N findings per module (0 = unlimited)
--timeout
—
15s
HTTP request timeout
--scanning-max-duration
—
—
Maximum total scan duration (e.g. 1h, 30m)
--proxy
—
—
HTTP/SOCKS5 proxy URL
--modules
-m
all
Scanner modules to enable (fuzzy match on ID/name)
Continuously scan new HTTP records as they arrive in the database
--full-native-scan-on-receive
—
false
Run the full native scan pipeline (discovery + spidering + dynamic-assessment) continuously on received records
--source
—
—
Path to application source code
--source-url
—
—
Git URL to clone for source-aware scanning
--scan-id
—
—
Label for grouping scan session results
--scope-origin
—
—
Origin scope: all, relaxed, balanced, strict
--project-id
—
—
Project UUID to scope all operations to
--project-name
—
—
Project name to scope all operations to
--verbose
-v
false
Verbose logging
--silent
—
false
Suppress all output except findings
--json
-j
false
On scan: JSONL findings. On finding/traffic/db: a single compact, token-aware agent JSON object (see recipe 14c)
--soft-fail
—
false
Always exit 0 even on error (keeps CI/wrappers from breaking); overrides --fail-on
--ci-output-format
—
false
CI-friendly output: JSONL findings only, no color, no banners
--debug
—
false
Dump raw HTTP traffic
--dump-traffic
—
false
Print every HTTP request/response pair to stderr (Burp-style)
--log-file
—
—
Write all log output to this file (JSON format)
--db
—
~/.vigolium/database-vgnm.sqlite
SQLite database path
--config
—
~/.vigolium/vigolium-configs.yaml
Config file path
--stateless
—
false
Use a temporary database, export results to --output, then discard
--no-clustering
—
false
Disable de-duplication of identical concurrent HTTP requests
--force
-F
false
Skip confirmation prompts
--list-modules
-M
false
List all scanner modules
--list-input-mode
—
false
List all supported input modes with examples
--watch
—
—
Re-run on interval (e.g. 10s, 1m, 5m)
--width
—
70
Max column width for tables
--ext
—
—
Load JavaScript extension script (repeatable)
--ext-dir
—
—
Override extension scripts directory
--full-example
—
false
Show full example commands organized by section
Scan-Specific Flags
These flags apply to scan, scan-url, scan-request, and run commands:
Flag
Short
Default
Description
--output
-o
—
Write findings / reports to this file path
--stats
—
false
Show live progress stats during scanning
--include-response
—
false
Include full HTTP response body in output
--omit-response
—
false
Omit raw HTTP request/response bytes from the output file (keeps metadata, smaller files; drops the .resp.* files under --format fs)
--fail-on
—
—
Exit non-zero when a finding at/above this severity is present (info,suspect,low,medium,high,critical). Output is written first; --soft-fail overrides; per-child under -P
--split-by-host
—
false
In stateless multi-target mode (-S -T file), write a separate per-host output file (base-<host>.<ext>) instead of one unified file (scan/run only; no-op for --format fs)
--retries
—
1
Number of retry attempts for failed requests
--stream
—
false
Process targets as a stream without buffering or deduplication
--header
-H
—
Add custom HTTP header (repeatable, e.g. -H 'Auth: Bearer tok')
--advanced-options
-a
—
Module-specific options as key=value (e.g. -a xss.dom=true)
--required-only
—
false
Parse only required fields from input format (ignore optional)
--skip-format-validation
—
false
Skip validation of input file format
--upload-results
—
false
Upload scan results to cloud storage after completion (requires storage config)
--stateless
—
false
Use a temporary database, export to --output, then discard
--auth-file
—
—
Path to auth file (YAML/JSON: single session or sessions: bundle), or bare name resolved against scanning_strategy.session.session_dir. Repeatable.
--auth
—
—
Inline session in name:Header:value format. Repeatable.
--oast-url
—
—
Fixed out-of-band callback URL
--discover
—
false
Enable content discovery phase before scanning
--discover-max-time
—
1h
Max time for content discovery per target
--fuzz-wordlist
—
—
Custom fuzz wordlist path (enables fuzzing during discovery)
--no-prefix-breaker
—
false
Disable per-prefix circuit breaker that stops trap-directory recursion
--spider
—
false
Enable browser-based spidering phase before scanning
--spider-max-time
—
30m
Max time for spidering per target
--browser-engine
-E
chromium
Browser engine: chromium, ungoogled, fingerprint
--browsers
-b
1
Number of parallel browser instances for spidering
Local path or git URL for ad-hoc SAST scan (auto-detected)
--rule
—
—
Filter SAST rules by fuzzy name match
Constraints
--only and --skip are mutually exclusive
--format html requires -o/--output; multiple --format values also require -o/--output
--format html is only supported for the discovery and spidering phases when combined with --only
--format sqlite requires -S/--statelessand-o/--output (it dumps the standalone per-run DB via VACUUM INTO); aliases sqlite3/db. Reopen with vigolium finding/traffic -S --db <file>.sqlite
--format fs writes two sibling dirs (<base>-traffic/ + <base>-findings/); with no -o it defaults to vigolium-traffic/+vigolium-findings/ in the cwd. Available on scan/scan-url/scan-request/run, export, and db export. --omit-response drops the .resp.* files; --split-by-host is a no-op (fs already splits by host)
--fail-on <sev> gates the exit code (scan/run/scan-url/scan-request); output is written first, --soft-fail (global) forces exit 0, and under -P/--split-by-host it is evaluated per child (the parent batch fails only when every target fails)
--split-by-host only takes effect in stateless multi-target mode (-S -T <file>); it is required for -P > 1 parallel fan-out and ignored for a single target or under --db-isolate
Server --mirror-fs <dir> (config server.mirror_fs_path) mirrors ingested traffic + findings to a live <dir>/traffic+<dir>/findings tree (append-only index.jsonl); it is server-ingestion-only and never blocks the DB save — CLI scans are unaffected
--target/-t and --spec-url are mutually exclusive for ingest
--source and --source-url are mutually exclusive
--stateless requires -o/--output; --stateless and --db are mutually exclusive
--ci-output-format sets JSONL output, suppresses banners and color (implies --json --silent)
--skip-heuristics is equivalent to --heuristics-check=none
Server mode requires API key auth by default (use -A/--no-auth to disable, or set VIGOLIUM_API_KEY)
Agent commands route every dispatch through the in-process olium engine; configure under agent.olium.* in vigolium-configs.yaml. Default provider openai-compatible points at a local Ollama (http://localhost:11434/v1, model gemma4:latest) via custom_provider. openai-codex-oauth reads ~/.codex/auth.json; anthropic-cli needs claude in PATH; anthropic-vertex (Claude, claude-* model) and google-vertex (Gemini, gemini-* model) need a GCP service-account JSON via --oauth-cred or $GOOGLE_APPLICATION_CREDENTIALS
The --provider, --model, --oauth-cred, --oauth-token, --llm-api-key, --gcp-project, --gcp-location flags override agent.olium.* for one run on agent query, agent autopilot, agent swarm, and agent olium (and the top-level vigolium olium / ol alias)
--scan-on-receive/-S is ignored in remote ingest mode (server handles scanning)
db clean --all requires --force for safety
db clean --force with no filter flags resets the entire database (SQLite only)
Whitebox/SAST phases require --source <path> or --source-url <git-url> to link application source code
Phase aliases: deparos/discover = discovery, spitolas = spidering, ext = extension. The legacy alias dynamic-assessment is accepted for audit
--module-tag uses OR logic: modules matching any specified tag are included
-m and --module-tag merge results (union)
Use agent swarm --discover for full-scope AI-guided scanning
Agent swarm: --source-analysis-only requires --source; --browser-auth requires --browser; --audit requires --source; --target is required when --source is used with a remote target
Agent autopilot: when --source is set, an audit harness runs automatically — auto-picks piolium if pi+piolium are installed, otherwise the embedded vigolium-audit at lite. Force with --piolium <mode> (auto-disables vigolium-audit) or --audit <mode>; disable with --audit=off. --max-duration default is 6h (there is no --max-commands/--token-budget flag — the command budget is set by --intensity). --triage runs an AI triage pass after the scan; --disable-guardrail skips the prompt-safety classifier on the natural-language prompt
Agent audit: --driver must be auto (default), both, audit, or piolium. auto runs vigolium-audit and only falls back to piolium when the resolved claude/codex CLI is missing; both runs audit then piolium unconditionally. Under auto/both, --mode is restricted to the shared set (lite, balanced, deep, revisit, confirm, merge); driver-specific modes (audit's reinvest/refresh/mock/diff/status, piolium's longshot/smoke/diff/status) require forcing --driver=audit|piolium. --intensity deep resolves to the chain deep,confirm; --modes a,b,c chains modes. Audit-leg agent is selected by --provider (anthropic-→claude, openai-→codex) and --agent {claude|codex}, with BYOK via --api-key/--oauth-token/--oauth-cred-file. -i/--interactive hands you the audit harness (audit-only). --driver=audit\|piolium hard-errors on a missing runtime; under both a missing runtime is dropped with a warning. Post-pass project-wide findings dedup runs when a project UUID is set; suppress with --no-dedup
Agent audit --driver=piolium: --mode must be one of lite, balanced, deep, revisit, confirm, merge, diff, longshot, status, smoke. Requires pi in PATH and the piolium Pi extension installed. --no-preflight skips the pre-audit pi roundtrip
Intensity presets (--intensity quick|balanced|deep) are shared across scan, agent autopilot, agent swarm, agent audit; explicit flags always override the preset
vigolium storage * commands require storage.enabled: true (or VIGOLIUM_STORAGE_ENABLED=true) plus driver/bucket/access-key/secret-key configured. They scope to the active project (--project-id / --project-name / VIGOLIUM_PROJECT)
--source accepts a local path, a git URL (auto-cloned with --commit-depth), a local archive (.zip / .tar.gz / .tar.bz2 / .tar.xz — auto-extracted), or a gs://<project>/<key> URI (downloaded + extracted). Applies to agent audit
vigolium init is a no-op on an existing installation unless --force is passed (regenerates API key + re-extracts preset data)
vigolium config clean prompts for confirmation unless -F/--force is passed; it wipes the entire ~/.vigolium/ directory
