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.

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: agent (template-based), agent query (inline prompt), agent autopilot (autonomous), agent pipeline (multi-phase), agent swarm (targeted single-request)
• 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

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
• 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

• 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
• DB export with filters: vigolium db export -f csv -o records.csv --host example.com

Workflow Recipes

1. Quick Single-URL Scan

vigolium scan -t https://example.com

2. Full Pipeline Scan (Discovery + Spidering + SPA + Dynamic)

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 --no-auth

# With transparent proxy for recording traffic
vigolium server --ingest-proxy-port 8080

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

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

# Endpoint discovery from source
vigolium agent --prompt-template endpoint-discovery --source ./src

# List available templates
vigolium agent --list-templates

# Custom prompt with inline text
vigolium agent query 'review this code for vulnerabilities'

# Custom prompt file
vigolium agent query --agent claude --prompt-file custom-prompt.md

12. AI Agent Autopilot (Autonomous Scanning)

# Basic autonomous scan
vigolium agent autopilot -t https://example.com

# With source code context and focus area
vigolium agent autopilot -t https://api.example.com --source ./src --focus "auth bypass"

# Custom limits
vigolium agent autopilot -t https://example.com --max-commands 50 --timeout 15m

# Preview system prompt
vigolium agent autopilot -t https://example.com --dry-run

13. AI Agent Pipeline (Multi-Phase)

# Basic pipeline scan (source-analysis → discover → plan → scan → triage → rescan → report)
vigolium agent pipeline -t https://example.com

# With focus and source code (enables Phase 0: source analysis)
vigolium agent pipeline -t https://example.com --focus "SQL injection" --source ./src

# Control rescan iterations
vigolium agent pipeline -t https://example.com --max-rescan-rounds 3

# Skip discovery and start from planning (use existing DB data)
vigolium agent pipeline -t https://example.com --skip-phase discover --start-from plan

# Use a scanning profile
vigolium agent pipeline -t https://example.com --profile deep

# Preview agent prompts
vigolium agent pipeline -t https://example.com --dry-run

14. AI Agent Swarm (Targeted Single-Request)

# Target a URL for deep analysis
vigolium agent swarm -t https://example.com/api/users

# 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
echo -e "POST /api/search HTTP/1.1\r\nHost: example.com\r\n\r\nq=test" | vigolium agent swarm --input -

# 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 (discovers routes from source code)
vigolium agent swarm -t http://localhost:3000 --source ./src

# 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

# 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

# Custom ACP agent command
vigolium agent swarm -t https://example.com/api/users --agent-acp-cmd "traecli acp"

# 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 audit
vigolium agent swarm -t https://example.com --skip discovery,spidering

# Preview master agent prompt
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

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

# 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

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

# 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

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 --rate-limit 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

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

Key Global Flags

These flags are available on all commands (persistent flags on root):

Constraints

• --only and --skip are mutually exclusive
• --format html requires -o/--output and is only supported for discovery/spidering phases (in scan mode)
• --target/-t and --spec-url are mutually exclusive for ingest
• --source and --source-url are mutually exclusive
• --repo is deprecated — use --source for agent modes and --sast-adhoc for ad-hoc SAST scans
• --ci-output-format sets JSONL output, suppresses banners and color (implies --json --silent)
• Server mode requires API key auth by default (use --no-auth to disable, or set VIGOLIUM_API_KEY)
• Agent commands require agent backends configured in vigolium-configs.yaml
• --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)