Skip to main content
This guide explains how to install and use the vigolium-scanner skill with AI coding agents, Claude Code and OpenAI Codex, to operate the Vigolium CLI for web vulnerability scanning, security testing, and custom extension authoring. Skill repository: github.com/vigolium/skills

​
Quick Install

bunx skills add vigolium/skills --skill vigolium-scanner --agent <agent-name> --yes
Replace <agent-name> with your agent (e.g., claude-code, codex).

​
What the Skill Does

The skill teaches the AI agent how to:
  1. Pick the right vigolium command for any security testing task
  2. Construct correct flag combinations with proper syntax
  3. Follow scanning workflows end-to-end (ingest -> scan -> triage -> export)
  4. Write custom JavaScript extensions using the vigolium.* API
  5. Operate AI agent modes (query, autopilot, swarm)
  6. Manage data: browse traffic, filter findings, export reports, clean databases
The skill uses lazy-loaded references: the main SKILL.md stays small, and detailed docs are loaded on demand when the agent needs deep flag information or extension authoring guidance.

​
Skill Structure

public/skills/vigolium-scanner/
├── SKILL.md                              # Main skill (decision tree, recipes, 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
    ├── data-and-management.md            # db, module, ext, config, scope, source, export
    ├── flags-reference.md                # Complete alphabetical flag index
    └── writing-extensions.md             # JS extension API and examples

​
Installation

Option A: Install via npx / bunx (recommended) 
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 B: 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 to a standalone SQLite file: 
> Run a one-off scan and give me a self-contained .sqlite I can reopen later

vigolium scan -S -t https://example.com --format sqlite -o scan
--format sqlite (aliases sqlite3, db) requires -S/--stateless + -o; reopen it with vigolium finding -S --db scan.sqlite. Scan to a browsable filesystem tree (no DB needed): 
> Scan and give me the traffic + findings as files I can grep

vigolium scan -t https://example.com --format fs -o run
--format fs writes two sibling dirs off the -o base — run-traffic/ and run-findings/ — so you can investigate with plain ls/grep/jq. Each <host>/<id>.req is the raw, replayable request (strip the leading @target line), <id>.resp.headers/<id>.resp.body hold the gzip-decoded response, and <id>.md under -findings/ is the finding cross-linked to its .req. Start from index.json in each dir — jq it to map every id to its url/status/severity. Works with or without -S; honors --omit-response. See Output and Reporting for the full layout. Scan with custom scanning profile: 
> Use the aggressive scanning profile

vigolium scan -t https://example.com --scanning-profile aggressive
Scan with strict origin scope: 
> Only scan URLs on the exact same origin

vigolium scan -t https://example.com --scope-origin strict

​
2. Input Formats

OpenAPI 3.x spec with explicit base URL: 
> Scan my API using the OpenAPI spec

vigolium scan -I openapi -i api-spec.yaml -t https://api.example.com
OpenAPI spec using servers from the spec: 
> Use the server URLs defined in the spec itself

vigolium scan -I openapi -i api-spec.yaml --spec-url
OpenAPI with auth header and parameter values: 
> Scan the spec with bearer auth and set the user_id parameter to 42

vigolium scan -I openapi -i spec.yaml -t https://api.example.com \
  --spec-header "Authorization: Bearer eyJ..." \
  --spec-var "user_id=42"
Swagger 2.0 spec: 
> Import a Swagger 2.0 spec and scan

vigolium scan -I swagger -i swagger.json -t https://api.example.com
Burp Suite XML export: 
> I exported traffic from Burp, scan it

vigolium scan -I burp -i burp-export.xml -t https://example.com
HAR (HTTP Archive) file: 
> Scan my browser-recorded HAR file

vigolium scan -I har -i traffic.har
cURL commands file: 
> I have a file of curl commands, scan them all

vigolium scan -I curl -i curl-commands.txt
Postman collection: 
> Import and scan my Postman collection

vigolium scan -I postman -i collection.json -t https://api.example.com
Nuclei templates: 
> Run these Nuclei templates against the target

vigolium scan -I nuclei -i templates/ -t https://example.com
Piped URLs from stdin: 
> Pipe a list of URLs into the scanner

cat urls.txt | vigolium scan -i -

​
3. Phase Control

Run only discovery (content enumeration): 
> Just run content discovery against the target

vigolium run discover -t https://example.com
# or
vigolium scan -t https://example.com --only discovery
Run only spidering (headless browser crawling): 
> Spider the target with a headless browser

vigolium run spidering -t https://example.com
Run only audit (vulnerability scanning): 
> Skip discovery, just run the vulnerability modules

vigolium run audit -t https://example.com
# or
vigolium scan -t https://example.com --only audit
Run only the Nuclei known-issue scan (critical/high only): 
> Run Nuclei-based known-issue checks, only critical and high severity

vigolium run known-issue-scan -t https://example.com --known-issue-scan-severities critical,high
Run a whitebox source-code audit (SAST): 
> Run a security audit on my Go app's source

vigolium agent audit --source /path/to/app
Run only external harvest (Wayback, Common Crawl, OTX): 
> Gather URLs from external intelligence sources

vigolium run external-harvest -t https://example.com
Skip specific phases: 
> Scan but skip discovery and spidering

vigolium scan -t https://example.com --skip discovery,spidering
Run only JavaScript extensions: 
> Run only my custom extension, skip built-in modules

vigolium scan -t https://example.com --only extension --ext ./custom-check.js
# or
vigolium run ext -t https://example.com --ext ./custom-check.js
Phase aliases reference:
AliasResolves To
deparos, discoverdiscovery
spitolasspidering
dynamic-assessmentaudit
extextension

​
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
Mirror ingested traffic to files in real time: 
> Run the server and mirror everything it ingests into ./mirror so I can grep it live

vigolium server --mirror-fs ./mirror
Every saved HTTP record and finding is written to ./mirror/traffic/<host>/… and ./mirror/findings/<host>/… as it lands in the DB — the same layout as --format fs, except the indexes are append-only index.jsonl (one object per line — tail/grep it live) and per-host ids resume across restarts. Point your agent at ./mirror to read ingested Burp/proxy traffic as files while it streams in. High-concurrency server: 
> Start a high-throughput server with 200 workers

vigolium server -c 200 --mem-buffer 50000
Ingest an OpenAPI spec locally: 
> Import the spec into the database without scanning

vigolium ingest -t https://api.example.com -I openapi -i spec.yaml
Ingest and auto-scan: 
> Import the spec and scan immediately

vigolium ingest -t https://api.example.com -I openapi -i spec.yaml -S
Ingest Burp export: 
> Import Burp traffic into the database

vigolium ingest -t https://example.com -I burp -i export.xml
Remote ingest to a running server: 
> Send traffic to the vigolium server running on localhost

vigolium ingest -s http://localhost:9002 -I openapi -i spec.yaml
Ingest without fetching responses: 
> Store request-only records, don't make network requests

vigolium ingest -t https://example.com -I burp -i export.xml --disable-fetch-response

​
6. AI Agent Modes

​
Agent (Template-Based)

Security code review: 
> Review my source code for security vulnerabilities

vigolium agent query --prompt-template security-code-review --source ./src
Endpoint discovery from source: 
> Find all API endpoints in my source code

vigolium agent query --prompt-template endpoint-discovery --source ./src
Review specific files only: 
> Review only auth.go and middleware.go for security issues

vigolium agent query --prompt-template security-code-review --source ./src \
  --files "src/auth.go,src/middleware.go"
Append extra instructions to a template: 
> Code review, but focus on authentication and authorization

vigolium agent query --prompt-template security-code-review --source ./src \
  --append "Focus specifically on authentication and authorization vulnerabilities"
Use a custom prompt file: 
> Run the agent with my own prompt template

vigolium agent query --prompt-file custom-prompt.md --source ./src
Select a specific olium provider: 
> Use Anthropic for code review

vigolium agent query --provider anthropic-api-key --prompt-template security-code-review --source ./src
Dry-run to preview the rendered prompt: 
> Show me what prompt would be sent to the agent

vigolium agent query --prompt-template security-code-review --source ./src --dry-run
Save agent output to a file: 
> Save the review results to a JSON file

vigolium agent query --prompt-template security-code-review --source ./src \
  --output review-results.json
List available templates and providers: 
> What prompt templates and olium providers are available?

vigolium agent --list-templates
vigolium agent --list-agents
Built-in templates include:
  • security-code-review: Comprehensive security review
  • injection-sinks: Find injection sinks
  • auth-bypass: Auth bypass vectors
  • secret-detection: Hardcoded secrets
  • endpoint-discovery: API endpoints from source
  • api-input-gen: Generate test inputs
  • curl-command-gen: Generate cURL commands
  • attack-surface-mapper: Map attack surface
  • nextjs-security-audit: Next.js security review
  • react-xss-audit: React XSS audit
  • cors-csrf-review: CORS/CSRF config audit

​
Agent Query (Freeform Prompt)

Inline prompt: 
> Ask the agent to review code for vulnerabilities

vigolium agent query 'review this code for SQL injection vulnerabilities'
Named prompt flag: 
> Analyze the authentication flow

vigolium agent query --prompt 'analyze the authentication flow for bypass vectors'
Pipe prompt from stdin: 
> Pipe a prompt to the agent

echo "check for SSRF in the URL-fetching handler" | vigolium agent query --stdin
Custom prompt file with a specific provider: 
> Run a custom prompt file through Anthropic

vigolium agent query --provider anthropic-api-key --prompt-file custom-prompt.md
Pick a different model: 
> Run the review on a frontier model

vigolium agent query --provider anthropic-api-key --model claude-opus-4-7 \
  'comprehensive security review of all handlers'

​
Agent Autopilot (Autonomous Scanning)

Basic autonomous scan: 
> Let the AI autonomously scan the target

vigolium agent autopilot -t https://example.com
With source code context and focus area: 
> Autonomous scan focused on auth bypass, with source code for context

vigolium agent autopilot -t https://api.example.com --source ./src --focus "auth bypass"
Custom limits (lighter intensity, shorter wall-clock): 
> Run a quick scan capped at 15 minutes

vigolium agent autopilot -t https://example.com --intensity quick --max-duration 15m
Preview the system prompt (dry run): 
> Show me what system prompt the autopilot agent would receive

vigolium agent autopilot -t https://example.com --dry-run
Custom system prompt: 
> Use my own system prompt for autopilot

vigolium agent autopilot -t https://example.com --system my-system-prompt.md
Use a different olium provider: 
> Run autopilot through Google Vertex

vigolium agent autopilot -t https://example.com --provider google-vertex --model gemini-2.5-pro
Autopilot security model:
  • Yolo-mode bash — autopilot runs the model’s bash calls without an approval prompt. The model decides when to invoke vigolium scan-url, vigolium finding, etc. (they’re shell commands, not first-class tools).
  • The engine only hard-rejects catastrophic patterns (rm -rf /, dd to block devices, fork bombs, mkfs against real devices). There is no vigolium-only command allowlist.
  • Per-tool timeout: 5 minutes (ToolTimeout).
  • Intensity-driven defaults: quick=150 / balanced=500 / deep=1500 commands (MaxCommands), browser enabled at every intensity.
  • report_finding soft-warns at 50 findings and hard-caps at 200, nudging the agent toward halt_scan.
  • Run autopilot in a disposable container or VM scoped to in-scope targets — see Security Warning.

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

Basic swarm scan with discovery (all phases): 
> Run the full AI swarm scan

vigolium agent swarm --discover -t https://example.com
The swarm runs ten phases in order (most are conditional — see Swarm for full detail):
  1. native-normalize — parse --input/stdin/record-uuid into HTTP records
  2. auth (optional) — browser-driven login, writes auth headers/cookies
  3. source-analysis (if --source) — 4-call wave that emits routes, session-config, and source extensions
  4. code-audit (if --code-audit) — code-level security audit, findings → DB
  5. native-discover (if --discover) — crawl/spider/JS-scan
  6. plan — master agent picks modules and writes an extensions spec
  7. native-extension — compile/validate generated JS extensions (Sobek)
  8. native-scan — runner.RunNativeScan() with the planned modules + extensions
  9. triage (if --triage) — AI verifies findings, may request targeted rescans
  10. native-rescan — targeted rescan loop, bounded by --max-iterations
Swarm with focus area and source code: 
> Swarm scan focused on SQL injection, with source code

vigolium agent swarm --discover -t https://example.com --focus "SQL injection" --source ./src
Control rescan iterations: 
> Allow up to 3 triage->rescan iterations

vigolium agent swarm --discover -t https://example.com --max-iterations 3
Skip discovery and start from planning (use existing DB data): 
> I already have traffic in the database, start from planning

vigolium agent swarm --discover -t https://example.com --skip discover --start-from plan
Skip triage (just discover -> plan -> scan): 
> Run swarm but skip triage and rescan

vigolium agent swarm --discover -t https://example.com --skip triage --skip rescan
Use a scanning profile: 
> Run swarm with the deep scanning profile

vigolium agent swarm --discover -t https://example.com --profile deep
Preview agent prompts (dry run): 
> Show me the prompts without executing

vigolium agent swarm --discover -t https://example.com --dry-run
Specific source files for agent context: 
> Only include routes.go and handlers.go as context

vigolium agent swarm --discover -t https://example.com --source ./src \
  --files "routes.go,handlers.go"
Use a different agent backend: 
> Run swarm with Gemini

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

​
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): 
> Monitor traffic in real-time, refresh every 5 seconds

vigolium traffic --watch 5s
View raw HTTP request/response: 
> Show raw traffic for the last 5 records

vigolium traffic --raw --limit 5
Browse findings: 
> Show all vulnerability findings

vigolium finding
Filter findings by severity: 
> Show only high and critical findings

vigolium finding --severity high,critical
Search findings: 
> Find SQL injection findings

vigolium finding --search "sql injection"
Watch findings in real-time: 
> Monitor findings as they come in

vigolium finding --watch 5s
Render a finding as Markdown (evidence + request/response): 
> Give me finding 42 as Markdown I can paste into a report

vigolium finding --id 42 --markdown > finding-42.md
Read a standalone export without a project DB: 
> Browse the high-severity findings in this scan.jsonl export

vigolium finding -S --db ./scan.jsonl --min-severity high
vigolium traffic -S --db ./scan.sqlite --status 500 -n 20
-S/--stateless + --db reads a --format jsonl export or a standalone .sqlite directly with project scoping off, writing nothing to your project DB. Replay stored traffic (re-send requests): 
> Replay login-related requests and compare responses

vigolium traffic replay login
Replay and replace stored responses: 
> Replay requests to api.example.com and update stored responses

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

​
8. Data Management

Database statistics: 
> Show me database stats

vigolium db stats
Detailed stats with host breakdown: 
> Show detailed stats broken down by host

vigolium db stats --detailed
Stats for a specific host: 
> Stats for example.com only

vigolium db stats --host example.com
Live-updating stats: 
> Watch database stats, refresh every 10 seconds

vigolium db stats --watch 10s
List database records with filters: 
> Show findings table, critical and high severity

vigolium db ls --table findings --severity critical,high
List available tables and columns: 
> What tables are in the database? What columns does findings have?

vigolium db ls --list-tables
vigolium db ls --list-columns --table findings
Clean records by hostname: 
> Delete all records for old-target.com

vigolium db clean --host old-target.com --force
Clean old records with dry-run preview: 
> Preview what would be deleted before January 2024

vigolium db clean --before 2024-01-01 --dry-run
Clean only findings (keep HTTP records): 
> Delete info-severity findings but keep the HTTP records

vigolium db clean --findings-only --severity info --force
Clean orphaned findings: 
> Remove findings without associated HTTP records

vigolium db clean --orphans
Reset entire database: 
> Wipe the entire database and start fresh

vigolium db clean --force
Reclaim disk space after deletion: 
> Vacuum the database to reclaim space

vigolium db clean --vacuum

​
9. Export & Reports

Full JSONL export: 
> Export everything from the database as JSONL

vigolium export --format jsonl -o full-export.jsonl
Export only findings: 
> Export just the findings

vigolium export --format jsonl --only findings -o findings.jsonl
Export findings and HTTP records: 
> Export findings and associated HTTP traffic

vigolium export --format jsonl --only findings,http -o results.jsonl
HTML report: 
> Generate an interactive HTML report

vigolium export --format html -o report.html
Lightweight export (omit raw HTTP request/response bytes): 
> Export URLs only, without raw request/response data

vigolium export --omit-response --only http -o urls.jsonl
Export with search filter: 
> Export only records matching example.com

vigolium export --search "example.com" -o filtered.jsonl
Database-level export as CSV: 
> Export HTTP records as CSV

vigolium db export -f csv -o records.csv
Export as Markdown: 
> Export records as a Markdown report

vigolium db export -f markdown -o report.md
Export raw requests only: 
> Export just the raw HTTP requests

vigolium db export -f raw --request-only -o requests.txt
Export filtered by host and date: 
> Export records for example.com from 2024 onwards

vigolium db export -f csv -o records.csv --host example.com --from 2024-01-01
Export a single record by UUID: 
> Export record abc12345

vigolium db export --uuid abc12345
Export module registry: 
> Export all available scanner modules

vigolium export --only modules

​
10. Whitebox / Source-Aware Scanning

Source-aware scanning runs through the agent modes via the --source flag — the native vigolium scan does not take source code. Use agent swarm for an AI-driven source-aware DAST scan, or agent audit for a source-only (SAST) review. Source-aware scan with local source code: 
> Whitebox scan with source code in ./src

vigolium agent swarm --target https://example.com --source ./src
--target is required whenever --source is given. The source-analysis and code-audit phases run automatically when --source is present. Scan with source cloned from Git: 
> Clone the repo and run a source-aware scan

# Clone first, then point --source at the local checkout
git clone https://github.com/org/repo /tmp/repo
vigolium agent swarm --target https://example.com --source /tmp/repo
Run a source-code audit (SAST) only: 
> Run a security audit on the source code

vigolium agent audit --source /path/to/app
Deeper multi-phase audit: 
> Run a thorough deep-mode source audit

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

​
11. JavaScript Extensions

Install preset examples: 
> Install the example extension scripts

vigolium ext preset
View the extension API reference: 
> Show me the extension API docs

vigolium ext docs
vigolium ext docs --example          # with code examples
vigolium ext docs http               # filter by namespace
List loaded extensions: 
> Show currently loaded extensions

vigolium ext ls
vigolium ext ls --type active        # active extensions only
Quick-test JS code inline: 
> Test a JS expression

vigolium ext eval 'vigolium.log.info("hello from extension")'
vigolium ext eval 'vigolium.utils.md5("password")'
Evaluate a JS file: 
> Run a JS script file

vigolium ext eval --ext-file script.js
Run a custom extension against a target: 
> Run my custom scanner extension

vigolium run extension -t https://example.com --ext custom-check.js
# or
vigolium run ext -t https://example.com --ext custom-check.js
Run extension alongside built-in modules: 
> Run built-in modules plus my custom extension

vigolium scan -t https://example.com --ext custom-check.js
Run only extensions (skip built-in modules): 
> Run only my custom extensions

vigolium scan -t https://example.com --only extension --ext custom-check.js
Load multiple extensions: 
> Run three extensions together

vigolium scan -t https://example.com --ext check1.js --ext check2.js --ext check3.js
Load all extensions from a directory: 
> Run all extensions in my extensions folder

vigolium scan -t https://example.com --ext-dir ./my-extensions/
Ask the agent to write an extension: 
> Write me a passive extension that checks for missing security headers
The agent will generate a JS file like: 
module.exports = {
  id: "missing-security-headers",
  name: "Missing Security Headers",
  type: "passive",
  severity: "low",
  confidence: "certain",
  scope: "response",
  tags: ["headers", "misconfiguration", "light"],
  scanTypes: ["per_request"],

  scanPerRequest: function(ctx) {
    if (!ctx.response) return null;
    var headers = ctx.response.headers;
    var missing = [];

    if (!headers["strict-transport-security"]) missing.push("HSTS");
    if (!headers["x-content-type-options"]) missing.push("X-Content-Type-Options");
    if (!headers["x-frame-options"] && !headers["content-security-policy"]) {
      missing.push("X-Frame-Options/CSP");
    }

    if (missing.length === 0) return null;

    return {
      url: ctx.request.url,
      name: "Missing Security Headers: " + missing.join(", "),
      severity: "low",
      description: "Response is missing: " + missing.join(", ")
    };
  }
};
Ask the agent to write an AI-augmented extension: 
> Write an active extension that uses AI to generate XSS payloads
The agent will generate a JS file using vigolium.agent.generatePayloads() and vigolium.agent.analyzeResponse(). YAML extension (simple pattern matching): 
> Write a YAML extension that detects stack traces and SQL errors

id: error-pattern-detector
name: Verbose Error Pattern Detector
type: passive
severity: suspect
confidence: tentative
scope: response
tags: [error, information-disclosure, light]
scanTypes: [per_request]
patterns:
  - name: "Stack Trace Detected"
    regex: "(?:at\\s+[\\w.$]+\\(|Traceback \\(most recent|Exception in thread)"
    severity: suspect
  - name: "SQL Error Message"
    regex: "(?:mysql_|pg_|sqlite_|ORA-\\d{5}|SQLSTATE\\[)"
    severity: medium

​
12. Configuration & Projects

View all configuration: 
> Show the current vigolium config

vigolium config ls
View a specific config section: 
> Show scope configuration

vigolium config ls scope
vigolium config ls scanning_pace
vigolium config ls server
Set configuration values: 
> Set the default strategy to deep

vigolium config set scanning_strategy.default_strategy deep
Set scope mode: 
> Set origin scope to strict

vigolium config set scope.origin.mode strict
Enable extensions globally: 
> Enable extensions in audit

vigolium config set audit.extensions.enabled true
View scope rules: 
> Show current scope rules

vigolium scope view
vigolium scope view host
View scanning strategies: 
> Show available strategies and their phases

vigolium strategy ls
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

​
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 SayAgent 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> --focus "injection"
”Run the full AI pipeline”vigolium agent swarm --discover -t <url>
”Show me all critical findings”vigolium finding --severity critical
”Export results as HTML report”vigolium export --format html -o report.html
”What traffic is in the database?”vigolium traffic
”Write me an extension that checks for exposed .env files”Generates a JS extension file
”Start the server with auto-scan”vigolium server -t <url> --scan-on-receive
”Whitebox scan with my source code”vigolium scan -t <url> --source ./src --strategy whitebox
”Clean up old scan data”vigolium db clean --before <date> --force

​
Tips & Best Practices

  1. Start with scan -t: It’s the most common command. Add flags incrementally.
  2. Use strategies: lite for quick checks, balanced for most cases, deep for full coverage, whitebox when you have source code.
  3. Phase isolation: Use --only or vigolium run <phase> to iterate on a single phase without re-running the entire pipeline.
  4. Module tags: Filter modules by technology (spring, nodejs) or vulnerability class (xss, injection) to reduce noise.
  5. Watch mode: Add --watch 5s to traffic, finding, or db stats for real-time monitoring during long scans.
  6. Dry-run agents: Always --dry-run first for agent commands to preview prompts before spending AI tokens.
  7. Swarm over autopilot: Use agent swarm --discover for structured scans (lower cost, reproducible). Use agent autopilot for exploratory, creative scanning.
  8. Extensions for custom logic: Write JS extensions instead of modifying core modules. They run alongside built-in modules with --ext.
  9. Projects for isolation: Use vigolium project create to keep scan data separate across engagements.
  10. Export early: Run vigolium export --format html -o report.html to share results as interactive reports.