vigolium-scanner

Claude Code skill for operating the Vigolium web vulnerability scanner CLI. See the documentation for full details.

What is Vigolium?

Vigolium is a high-fidelity web vulnerability scanner built for security professionals. It combines traditional DAST scanning with AI-powered analysis to find vulnerabilities in web applications. Full documentation is available at docs.vigolium.com. Key capabilities:

Multi-phase scanning — discovery, spidering, SPA analysis, audit, and SAST
Flexible input — scan URLs directly, or import from OpenAPI specs, Burp exports, HAR files, cURL commands, and more
AI agent modes — autonomous scanning (autopilot, swarm), foreground vigolium-audit / piolium whitebox audits, and AI-assisted code review
Extensible — write custom scanner modules in JavaScript
Source-aware — whitebox scanning that combines static analysis with dynamic testing

Using the Vigolium Scanner Skill in Claude Code, Codex or any agents

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

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
Execute ad-hoc JavaScript with vigolium js for scripting and automation
Operate AI agent modes (query, autopilot, swarm, audit)
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

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

Installation

Option A: Native installer (recommended — version-matched to your binary)

If you have vigolium installed, install the embedded copy of the skill, which always matches your CLI version:

vigolium skills install --agent claude --scope project   # --agent claude|codex|agents, --scope project|global
vigolium skills                                          # list the bundled skills

Option B: Install via npx / bunx (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

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 with CI-friendly output (for CI/CD pipelines):

> Scan and output only JSONL findings, no color or banners

vigolium scan -t https://example.com --ci-output-format

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 dynamic-assessment -t https://example.com
# or
vigolium scan -t https://example.com --only dynamic-assessment

Run only known-issue-scan (security posture assessment via Nuclei):

> Run Nuclei-based security posture assessment, only critical and high severity

vigolium run known-issue-scan -t https://example.com --known-issue-scan-severities critical,high

Static analysis / security code audit on source code:

> Run a security code audit on my Go app

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

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-reflected,sqli-error

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 active-xss-reflected --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

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 Query (Template-Based Code Review)

Template-based code review + endpoint discovery runs through the query subcommand. The parent vigolium agent only supports --list-templates and --list-agents.

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 agent backend:

> Use the Claude backend for code review

vigolium agent query --agent claude --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 backends:

> What prompt templates and agent backends are available?

vigolium agent --list-templates
vigolium agent --list-agents

List or inspect agent sessions:

> Show all agent run sessions

vigolium agent session
vigolium agent session <session-uuid>

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

> Run a custom prompt file through Claude

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

With extended timeout:

> Run a comprehensive review with extra time

vigolium agent query --max-duration 10m 'comprehensive security review of all handlers'

Agent Autopilot (Autonomous Scanning)

Autopilot runs a single autonomous operator session that drives the vigolium CLI. When --source is set, an audit harness runs first to build whitebox context (auto-picks piolium if installed, else the embedded vigolium-audit), then the operator takes over. Use --intensity quick|balanced|deep to bundle the command budget, timeout, audit mode, and browser into one flag. Default timeout is 6h.

Basic autonomous scan:

> Let the AI autonomously scan the target

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

Natural-language prompt (target/source/focus auto-extracted):

> Scan VAmPI source at ~/src/VAmPI running on localhost:3005

vigolium agent autopilot "scan VAmPI source at ~/src/VAmPI on localhost:3005"

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"

Intensity presets (quick/balanced/deep):

> Fast autopilot for CI; deep autopilot for a pentest

vigolium agent autopilot -t https://example.com --source ./src --intensity quick   # 150 cmds, 1h
vigolium agent autopilot -t https://example.com --intensity deep                    # 1500 cmds, 12h, browser

Scan only a PR diff or recent commits:

> Scan the last 3 commits / a PR branch

vigolium agent autopilot -t https://example.com --source ./src --last-commits 3
vigolium agent autopilot -t https://example.com --source ./src --diff main...feature-branch

Browser-based auth preflight:

> Log in via the browser before autopilot starts

vigolium agent autopilot -t https://example.com "log in as admin/admin123, then hunt IDOR and privilege escalation"
vigolium agent autopilot -t https://example.com "authenticate at https://example.com/login as admin/admin123, then test the admin area"

Disable or tune the audit harness (runs by default when --source is set):

vigolium agent autopilot -t https://example.com --source ./src --audit=off
vigolium agent autopilot -t https://example.com --source ./src --audit deep
vigolium agent autopilot -t https://example.com --source ./src --piolium balanced   # force piolium harness

Cap the wall-clock budget (explicit override of presets):

> Limit the agent to 15 minutes

vigolium agent autopilot -t https://example.com --max-duration 15m

Upload results to cloud storage:

vigolium agent autopilot -t https://example.com --source ./src --upload-results

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

Override the olium provider for one run:

> Run autopilot through Anthropic

vigolium agent autopilot -t https://example.com --provider anthropic-api-key

Resume a prior durable-autopilot run (requires agent.olium.autopilot_mode != legacy):

# --resume takes the prior run's agentic-scan UUID (not a path); reuses its
# session dir, target, and durable scratchpad/candidates, skipping pre-scan + audit re-prep.
vigolium agent autopilot --resume 550e8400-e29b-41d4-a716-446655440000

Agent Swarm (Full-Scope and Targeted)

Swarm is AI-guided scanning — targeted by default, full-scope with --discover. Intensity presets (--intensity quick|balanced|deep) bundle discovery, triage, code-audit, browser, duration, and iteration defaults. Explicit flags override. Default swarm duration is 12h; set with --max-duration.

Deep analysis of a single endpoint:

> Deep scan the users API endpoint for vulnerabilities

vigolium agent swarm -t https://example.com/api/users

Natural-language prompt:

> Scan source at ~/src/app running on localhost:3005

vigolium agent swarm "scan source at ~/src/app on localhost:3005"

From a curl command:

> Analyze this curl command for vulnerabilities

vigolium agent swarm --input "curl -X POST https://example.com/api/login -d '{\"user\":\"admin\"}'"

Pipe raw HTTP from stdin (auto-detected):

> Scan this raw HTTP request

echo -e "POST /api/search HTTP/1.1\r\nHost: example.com\r\n\r\nq=test" | vigolium agent swarm

Intensity presets:

> Quick swarm for CI; deep swarm for a full pentest

vigolium agent swarm -t https://example.com/api/users?id=1 --intensity quick
vigolium agent swarm -t https://example.com --source ./src --intensity deep

Focus on a specific vulnerability:

> Focus on SQL injection in the users endpoint

vigolium agent swarm -t https://example.com/api/users --vuln-type sqli

Source-aware swarm (discovers routes from source):

> Scan my app with source code context

vigolium agent swarm -t http://localhost:3000 --source ~/projects/my-app

Source-aware with specific files:

> Analyze only the API routes and user model

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

> Just extract routes from my source code

vigolium agent swarm -t http://localhost:3000 --source ./src --source-analysis-only

Background vigolium-audit (runs in parallel, requires --source):

> Scan and audit the codebase at the same time

vigolium agent swarm -t http://localhost:3000 --source ./src --audit          # lite (bare flag)
vigolium agent swarm -t http://localhost:3000 --source ./src --audit deep     # 12-phase
vigolium agent swarm -t http://localhost:3000 --source ./src --piolium balanced   # piolium harness instead

Scan only changed code:

> Focus the swarm on the last N commits or a PR

vigolium agent swarm -t https://example.com --source ./src --last-commits 3
vigolium agent swarm -t https://example.com --source ./src --diff main...feature-branch

Browser-based auth capture:

> Swarm needs to log in through the UI first

vigolium agent swarm -t https://example.com --browser-auth \
  "log in as admin/secret before scanning"

Upload results:

vigolium agent swarm -t https://example.com --source ./src --upload-results

Custom instructions:

> Focus the agent on GraphQL parsing vulnerabilities

vigolium agent swarm -t https://example.com/graphql --prompt "Focus on GraphQL parsing"

Triage + rescan loop:

vigolium agent swarm -t https://example.com/api/users --triage --max-iterations 5

Preview prompts:

> Show me what the swarm agent would do

vigolium agent swarm -t https://example.com/api/users --dry-run

Agent Audit (Foreground Whitebox Audit)

vigolium agent audit is the unified driver dispatcher (the former agent archon command is gone). It drives the embedded vigolium-audit harness (driver audit) and/or piolium against a source tree under a single AgenticScan, imports findings into the database, and streams raw output to the console + {session}/<driver>/runtime.log. --driver=auto (default) runs vigolium-audit and only falls back to piolium when the claude/codex CLI is missing; --driver=both runs both; --driver=audit|piolium forces one.

Quick lite audit (secrets + fast SAST):

> Run a fast audit on this repo

vigolium agent audit --intensity quick --source .

Deep audit (full pass + PoC confirmation):

> Full audit of my codebase

vigolium agent audit --intensity deep --source .          # resolves to the chain deep,confirm

Audit a remote repo (auto-clones):

vigolium agent audit --driver=audit --mode lite --source https://github.com/org/repo

Balanced audit, pick the coding agent (claude or codex):

vigolium agent audit --driver=audit --mode balanced --agent codex --source ~/code/myapp

Construct PoCs for confirmed findings in a prior audit:

vigolium agent audit --driver=audit --mode confirm --source ./audit-with-findings

Stateless run into a throwaway DB + self-contained HTML report:

vigolium agent audit -S --source ./src -o audit-report.html

Read-only progress check on an in-progress run:

vigolium agent audit --driver=audit --mode status --source ./in-progress-audit

Shared modes (allowed under auto/both): lite, balanced, deep, revisit, confirm, merge. Driver-specific modes require forcing the driver (audit: reinvest/refresh/mock/diff/status; piolium: longshot/smoke/diff/status). Audit-leg agent is selected by --provider (anthropic-*→claude, openai-*→codex) or --agent {claude|codex}. Add --no-stream to suppress console output; --keep-raw is on by default (use --clean-raw to drop the source-tree copy). See references/agent-commands.md for the full flag set.

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

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 — --watch lives on the db command):

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

vigolium db ls http_records --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

Load findings from a file or stdin:

> Import findings from a JSONL file

vigolium finding load findings.jsonl
# or from stdin
cat findings.jsonl | vigolium finding load

Filter findings by severity:

> Show only high and critical findings

vigolium finding --severity high,critical

Filter findings by module type or source:

> Show only active module findings from audit

vigolium finding --module-type active --finding-source audit

View a specific finding in Burp-style format:

> Show finding #42 with full HTTP details

vigolium finding --id 42 --burp

Custom finding columns:

> Show findings with tags and confidence

vigolium finding --columns ID,SEVERITY,MODULE,MATCHED_AT,TAGS,CONFIDENCE

Search findings:

> Find SQL injection findings

vigolium finding --search "sql injection"

Watch findings in real-time (--watch lives on the db command):

> Monitor findings as they come in

vigolium db ls findings --watch 5s

Replay stored traffic (re-send requests):

> Replay login-related requests and compare responses

vigolium traffic login --replay

Replay and replace stored responses:

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

vigolium traffic --host api.example.com --replay --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 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 clean --force

Reclaim disk space: VACUUM runs automatically after every db clean delete. To clear everything and reclaim space in one step:

> Delete all records and reclaim space

vigolium db clean --all -F

Seed database with sample data (for development/testing):

> Populate the database with sample data

vigolium db seed

View the raw runtime log for a past scan or agent session:

> Show me the log for run 550e8400-...

vigolium log 550e8400-e29b-41d4-a716-446655440000
vigolium log <uuid> -f              # follow like `tail -f`
vigolium log <uuid> --tail 500      # last 500 lines
vigolium log <uuid> --full          # whole log
vigolium log <uuid> --strip-ansi    # plain text, safe for grep/pipe

List all scan + agent sessions:

> Show every scan and agent session, with log availability

vigolium log ls
vigolium log --tui                   # interactive picker

Import an audit output folder or JSONL export:

> Import these scan results into the database

vigolium import /path/to/vigolium-results/        # audit output folder (vigolium-audit or piolium)
vigolium import scan-results.jsonl                # JSONL from `vigolium export --format jsonl`
vigolium import other-vigolium-scan.sqlite        # merge an external Vigolium SQLite scan DB
vigolium import bundle.tar.gz                      # archive (.tgz/.zip) or gs://<project>/<key>

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

Lite export (omit raw HTTP data):

> 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 is an agent feature — the native scan command has no --source. Pass --source to agent autopilot, agent swarm, agent query, or agent audit. It accepts a local directory, a git URL (cloned automatically), a local .zip/.tar.gz, or a gs://<project>/<key> archive.

Source-aware agentic scan with local source:

> Whitebox scan of example.com with source code in ./src

vigolium agent autopilot -t https://example.com --source ./src

Scan with source cloned from Git:

> Clone the repo and run a source-aware scan

vigolium agent swarm -t https://example.com --source https://github.com/org/repo

Source-only audit (SAST/code review harness, no target required):

> Run a security code audit on the source in ./src

vigolium agent audit --source ./src

Code review / endpoint discovery on source only:

> Review the source code for vulnerabilities

vigolium agent query --source ./src -t code-review

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

Lint extensions for errors:

> Validate my extension files for syntax errors and unknown API calls

vigolium ext lint custom-check.js
vigolium ext lint ./my-extensions/

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().

Execute ad-hoc JavaScript with vigolium js:

> Run a JS script that queries the database and flags high-risk records

vigolium js --code 'var records = vigolium.db.records.query({ hostname: "example.com" }); records.forEach(function(r) { if (vigolium.utils.hasDynamicSegment(vigolium.parse.url(r.url).path)) vigolium.db.records.annotate(r.uuid, { risk_score: 50 }); })'

Execute a JS file with target context:

> Run my scanner script against example.com

vigolium js --target https://example.com --code-file my-scanner.js

Quick hash or encode from the terminal:

> MD5 hash the string "password"

vigolium js --format text --code 'vigolium.utils.md5("password")'

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

First-time setup (create ~/.vigolium with defaults):

> Initialize vigolium

vigolium init
vigolium init --force      # regenerate API key + re-extract preset data

Reset the installation back to a clean state:

> Wipe my vigolium installation and start over

vigolium config clean      # prompts for confirmation
vigolium config clean -F   # skip prompt

Run a health check on the installation:

> Is my vigolium install healthy?

vigolium doctor

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=my-project vigolium db stats

Authentication management utilities:

> List sessions, lint an auth file, load auth, or generate TOTP

vigolium auth list
vigolium auth lint <auth-file>
vigolium auth load <auth-file>
vigolium auth totp --secret <base32-secret>

Authenticated scanning with session config:

> Scan with authentication config

# Two flags: --auth-file for files/bare names, --auth for inline sessions:
vigolium scan -t https://example.com --auth-file auth.yaml              # bundle file
vigolium scan -t https://example.com --auth-file admin-session.yaml     # single-session file
vigolium scan -t https://example.com --auth-file <session-name>         # bare name in session_dir
vigolium scan -t https://example.com --auth "admin:Cookie:sid=abc"      # inline

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 scan"	`vigolium agent swarm --discover -t <url>`
"Deep scan this endpoint for SQLi"	`vigolium agent swarm -t <url> --vuln-type sqli`
"Scan with source code context"	`vigolium agent swarm -t <url> --source ./src`
"Run this JS script against the API"	`vigolium js --code-file script.js --target <url>`
"MD5 hash this string"	`vigolium js --format text --code 'vigolium.utils.md5("...")'`
"Show me all critical findings"	`vigolium finding --severity critical`
"Import findings from a file"	`vigolium finding load findings.jsonl`
"Show active module findings in Burp format"	`vigolium finding --module-type active --burp`
"Run scan for CI/CD pipeline"	`vigolium scan -t <url> --ci-output-format`
"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
"Lint my extension for errors"	`vigolium ext lint custom-check.js`
"Start the server with auto-scan"	`vigolium server -t <url> --scan-on-receive`
"Whitebox scan with my source code"	`vigolium agent autopilot -t <url> --source ./src`
"Security code audit on a local path"	`vigolium agent audit --source /path/to/app`
"Clean up old scan data"	`vigolium db clean --before <date> --force`
"Seed the database with sample data"	`vigolium db seed`
"List agent sessions"	`vigolium agent session`
"Show auth utilities"	`vigolium auth list`
"Scan with auth file"	`vigolium scan -t <url> --auth-file auth.yaml`
"Scan VAmPI source on localhost:3005" (natural-language)	`vigolium agent autopilot "scan VAmPI source at ~/src/VAmPI on localhost:3005"`
"Fast audit of this repo"	`vigolium agent audit --intensity quick --source .`
"Deep audit of a GitHub repo"	`vigolium agent audit --intensity deep --source https://github.com/org/repo`
"Quick swarm for CI"	`vigolium agent swarm -t <url> --intensity quick`
"Deep autopilot pentest"	`vigolium agent autopilot -t <url> --intensity deep`
"Scan the last 3 commits"	`vigolium agent autopilot -t <url> --source ./src --last-commits 3`
"Scan this PR for regressions"	`vigolium agent autopilot -t <url> --source ./src --diff main...feature-branch`
"Tail the live log for that scan"	`vigolium log <uuid> -f`
"List all scan + agent sessions"	`vigolium log ls`
"Import audit results"	`vigolium import /path/to/vigolium-results/`
"Import a JSONL scan export"	`vigolium import results.jsonl`
"Initialize vigolium"	`vigolium init`
"Reset vigolium to a clean install"	`vigolium config clean`
"Health-check my install"	`vigolium doctor`

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 the db commands (db stats, db ls http_records|findings) for real-time monitoring during long scans. (--watch lives on db, not on the standalone traffic/finding commands.)
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.
Intensity presets — Use --intensity quick for CI/PR pipelines, --intensity balanced (default) for day-to-day, --intensity deep for full pentests. Explicit flags override the preset.
Audit for whitebox — Reach for agent audit --intensity quick/balanced/deep (or --mode lite/balanced/deep) when you have source code and want a structured multi-phase audit with PoC construction (--mode confirm) and incremental runs (--mode diff).
Follow sessions live — Long-running agent runs leave a runtime.log; tail it with vigolium log <uuid> -f from another terminal instead of attaching to the process.
Start fresh between engagements — vigolium config clean wipes ~/.vigolium/ and vigolium init reinitializes it with a new API key and preset data.

Resources

Website: www.vigolium.com
Documentation: docs.vigolium.com
GitHub: github.com/vigolium/vigolium
Skills Repository: github.com/vigolium/skills

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
vigolium-scanner		vigolium-scanner
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

vigolium-scanner

What is Vigolium?

Using the Vigolium Scanner Skill in Claude Code, Codex or any agents

Table of Contents

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 Query (Template-Based Code Review)

Agent Query (Freeform Prompt)

Agent Autopilot (Autonomous Scanning)

Agent Swarm (Full-Scope and Targeted)

Agent Audit (Foreground Whitebox Audit)

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

Resources

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

vigolium-scanner

What is Vigolium?

Using the Vigolium Scanner Skill in Claude Code, Codex or any agents

Table of Contents

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 Query (Template-Based Code Review)

Agent Query (Freeform Prompt)

Agent Autopilot (Autonomous Scanning)

Agent Swarm (Full-Scope and Targeted)

Agent Audit (Foreground Whitebox Audit)

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

Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages