Vigolium Scanner

Vigolium CLI

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)
  • agent olium (alias vigolium olium / ol) — interactive TUI / one-shot olium agent
  • agent audit — unified driver dispatcher driving the embedded vigolium-audit harness and/or piolium (--driver=auto|both|audit|piolium)
  • agent session — list / inspect agent run sessions
• 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 ~/.vigolium/, config clean wipes it back to a fresh state

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:

Reference Guide

Load detailed reference based on what you need:

Scanning Strategies

Strategies control which phases run during a scan. Use --strategy <name>:

• Default strategy is set in config: scanning_strategy.default_strategy
• Balanced is the default when --strategy is not specified
• View all strategies: vigolium strategy ls
• Whitebox requires --source <path> or --source-url <git-url> to link application source code

Scan Phases

Vigolium runs up to 8 phases. Use --only <phase> to isolate one, or --skip <phase> to skip phases.

• --only and --skip are mutually exclusive
• Phase aliases work with both flags: --only deparos equals --only discovery, --only ext equals --only extension
• Run a single phase directly: vigolium run discover -t <url>

Input Formats

Use -I <format> to specify the input type. Auto-detection works for OpenAPI specs.

OpenAPI flags: --spec-url (use spec servers), --spec-header (auth headers), --spec-var (parameter values), --spec-default (fallback value).

Output and Results

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.

Workflow Recipes

1. Quick Single-URL Scan

vigolium scan -t https://example.com

2. Full Pipeline Scan (Discovery + Spidering + KnownIssueScan + Audit)

vigolium scan -t https://example.com --strategy deep

3. OpenAPI Spec Scan

# With explicit base URL
vigolium scan -I openapi -i api-spec.yaml -t https://api.example.com

# Using servers from spec
vigolium scan -I openapi -i api-spec.yaml --spec-url

# With auth header
vigolium scan -I openapi -i spec.yaml -t https://api.example.com \
  --spec-header "Authorization: Bearer <token>"

4. Burp/HAR Import and Scan

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

5. Raw HTTP Request Scan

# From file
vigolium scan-request -i raw-request.txt

# From stdin
echo -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 stdin
echo "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.

# 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

13. AI Agent Swarm (Targeted or Full-Scope)

Swarm orchestrates: normalize → source analysis (AI, --source) → code audit (AI) → SAST (native) → SAST review (AI) → discover (native, --discover) → plan (AI) → extension (Go) → native scan → triage (AI, --triage) → rescan (loop).

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.

# 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

Valid --mode values: lite, balanced, deep, revisit, confirm, merge, diff, longshot, status, smoke. Intensity presets: quick (lite + shallow clone), balanced (default), deep (deep + full clone history). Piolium passthroughs (forwarded as --plm-* to piolium itself): --plm-scan-limit, --plm-scan-since, --plm-phase-retries, --plm-command-retries, --plm-longshot-limit, --plm-longshot-timeout, --plm-longshot-langs.

13d. AI Agent Audit (Unified Driver Dispatcher)

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

14b. External-Agent Confirm Chain (Claude Code / Cursor / Pi)

External agents driving vigolium externally (Claude Code, Cursor, Pi, CI scripts) follow this discover → confirm → review chain:

1. Discover — pull what vigolium already knows in JSONL:

   vigolium traffic -j
   

…(truncated)