Using the Vigolium Scanner Skill in Claude Code & Codex

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 — or install the copy embedded in your vigolium binary, which always matches your installed version.

Quick Install

# Install the embedded skill into the current project (recommended — always matches your binary)
vigolium skills install --agent claude --scope project

vigolium skills install (added in v0.2.1) writes the vigolium-scanner bundle straight from the binary, so it can never drift from the CLI you’re driving. Pick the agent with --agent claude|codex|agents and the location with --scope project (current folder) or --scope global (home dir). Run vigolium skills to list what’s bundled and vigolium skills get vigolium-scanner to print a bundle without installing it. Prefer to pull the latest from the repo instead? Use the external skills installer:

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:

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
Operate AI agent modes (query, autopilot, swarm)
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: vigolium skills install (recommended — embedded, version-matched)

# Default: install the vigolium-scanner bundle for Claude into the current project
vigolium skills install

# Choose the agent and scope explicitly
vigolium skills install --agent codex --scope global

# Install every bundled skill, or override the destination directory
vigolium skills install --all
vigolium skills install --dir ./.claude/skills

The bundle ships inside the vigolium binary, so vigolium skills install can never install a stale copy — it always matches the CLI version you’re driving. --agent accepts claude, codex, or agents (an agentskills.io-compatible layout); --scope is project (current folder) or global (home dir). Inspect what’s bundled first with vigolium skills (list) and vigolium skills get vigolium-scanner (print). Option B: Install via npx / bunx (pulls the 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 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:

Alias	Resolves To
`deparos`, `discover`	`discovery`
`spitolas`	`spidering`
`ext`	`extension`
`audit`, `dast`, `assessment`	`dynamic-assessment`
`cve`, `kis`, `known-issues`	`known-issue-scan`

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 \
  --prompt "focus on 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-prompt-file my-system-prompt.md

Start from project traffic, Burp history, and app docs:

> Use the traffic we already captured and the application's role documentation

vigolium agent autopilot -t https://example.com \
  --burp-bridge-url http://127.0.0.1:9009 \
  --prior-context auto --knowledge-base ./app-docs

Resume a durable run:

vigolium agent autopilot --resume <agentic-scan-uuid> \
  --prompt "finish the remaining privilege-boundary checks"

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. Common scanner, record, replay, finding, OAST, auth-session, and Burp operations are also first-class tools; the model can still shell out for uncovered CLI operations.
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.
In legacy/shadow mode, report_finding soft-warns at 50 findings and hard-caps at 200. In enforced mode, propose_candidate routes claims through fresh-context verification before promotion.
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):

native-normalize — parse --input/stdin/record-uuid into HTTP records
auth (optional) — browser-driven login, writes auth headers/cookies
source-analysis (if --source) — 4-call wave that emits routes, session-config, and source extensions
code-audit (if --code-audit) — code-level security audit, findings → DB
native-discover (if --discover) — crawl/spider/JS-scan
plan — master agent picks modules and writes an extensions spec
native-extension — compile/validate generated JS extensions (Sobek)
native-scan — runner.RunNativeScan() with the planned modules + extensions
triage (if --triage) — AI verifies findings, may request targeted rescans
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 \
  --prompt "focus on 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 -t https://example.com --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 \
  --provider google-vertex --model gemini-2.5-pro

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 replay --search login

Replay and replace stored responses:

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

vigolium 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 reset --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 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 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

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 traffic, finding, or db stats for real-time monitoring during long scans.
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.

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Using the Vigolium Scanner Skill in Claude Code & Codex

Quick Install

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

Agent Query (Freeform Prompt)

Agent Autopilot (Autonomous Scanning)

Agent Swarm (AI-Guided Multi-Phase Scan)

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

​Quick Install

​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 (Template-Based)

​Agent Query (Freeform Prompt)

​Agent Autopilot (Autonomous Scanning)

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

​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

Quick Install

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

Agent Query (Freeform Prompt)

Agent Autopilot (Autonomous Scanning)

Agent Swarm (AI-Guided Multi-Phase Scan)

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