vigolium-scanner

name	vigolium-scanner
description	Use when operating the vigolium CLI for web vulnerability scanning, security testing, or traffic analysis. Covers scanning a URL/spec/raw request, running AI agent scans (autopilot, swarm, audit, query), triaging findings, confirming them with replay/fuzz, handing off to Burp, browsing stored traffic, writing JavaScript scanner extensions, and managing projects, exports, and config.
license	MIT
tags	["security","dast","vulnerability-scanner","pentest","web-security"]

Vigolium

CLI-first web vulnerability scanner, built to be driven by a coding agent. Full docs: docs.vigolium.com.

TL;DR

Five commands cover most work:

vigolium scan -t https://target.example --fail-on high   # scan into the DB, gate CI
vigolium finding -j --min-severity high --compact        # read what it found
vigolium replay --finding-id 42                          # confirm one finding
vigolium agent autopilot -t https://target.example       # let AI drive the whole scan
vigolium traffic -j --host target.example --compact      # browse stored requests

Anything not listed here: vigolium <command> -h is authoritative for the version you have installed. vigolium --full-example prints worked examples by section.

Mental model

• The database is the state. Scans write findings + HTTP records; query commands read them back. Commands compose through the DB, not through pipes.
• Two JSON contracts — don't confuse them:
  • -j/--json on finding/traffic/db → one compact, token-bounded object. Parse this during triage.
  • --format jsonl / export → bulk {"type":…,"data":{…}} stream, one per line, full fidelity. Archival, not triage.
• Non-interactive by default. TUI is opt-in (--tui). Destructive commands need --force. Use --no-color (or NO_COLOR=1) for clean text.
• Everything is project-scoped — --project-name, --project-uuid, or VIGOLIUM_PROJECT.
• JSON summaries hand you the next command. Agentic scans and fuzz emit a query field with a ready follow-up. Run that rather than composing your own.

The agent loop

scope → scan → read → confirm → hand off

Step	Command	Notes
Scope	vigolium doctor --json / db stats --json	environment + what's already stored
Scan	scan, scan-url, scan-request, run, or agent …	add --fail-on high to gate
Read	finding -j --compact --fields …	survey first, then drill with --id --with-records
Confirm	replay --finding-id <id>	re-sends and diffs against the baseline
Hand off	finding --markdown, --push-to-burp, export --format html	report or escalate to a human

Full walkthrough with output shapes, filters, and exit codes: references/agent-loop.md — read this first if you are driving vigolium from an agent.

Command router

I need to…	Use
Scan one or more target URLs	vigolium scan -t <url>
Scan a single URL with custom method/headers	vigolium scan-url <url> --method POST --body '...'
Scan a raw HTTP request from file/stdin	vigolium scan-request -i request.txt
Run only one scan phase	vigolium run <phase> or scan --only <phase>
Tune scan aggressiveness (phases + profile)	vigolium scan -t <url> --intensity quick|balanced|deep
Content discovery with a custom wordlist	vigolium scan -t <url> --discover --fuzz-wordlist ./words.txt
Import an OpenAPI/Swagger spec and scan	vigolium scan -I openapi -i spec.yaml -t <base-url>
Import Burp/HAR/cURL traffic	vigolium scan -I burp -i export.xml
Filter modules by tag	vigolium scan -t <url> --module-tag spring --module-tag injection
Ingest traffic without scanning	vigolium ingest -t <url> -I openapi -i spec.yaml
Start the API server	vigolium server
Start server and auto-scan new traffic	vigolium server -t <url> -S
Mirror ingested traffic to a live file tree	vigolium server --mirror-fs ./mirror
Autonomous AI-driven scan	vigolium agent autopilot -t <url>
Autopilot from a natural-language prompt	vigolium agent autopilot "scan VAmPI at ~/src/VAmPI on localhost:3005"
Full-scope AI scan (discover → plan → scan → triage)	vigolium agent swarm -t <url> --discover
Deep AI scan of one endpoint	vigolium agent swarm -t <url>
Whitebox source audit (no target needed)	vigolium agent audit --source .
AI code review, one shot

Reference router

Load the file that matches the task — don't read them all.

Topic	Reference	Load when
Driving vigolium from an agent	references/agent-loop.md	triage, -j contracts, replay, exports, exit codes
Scanning commands	references/scanning.md	scan / scan-url / scan-request / run flags, phases, strategies, output formats
Fuzzing	references/fuzzing.md	vigolium fuzz — positions, markers, attack modes, payload classes, anomaly scoring, matchers
Utility toolbox	references/kit.md	vigolium kit — secret-scan, js-beautify, oast, harvest, jwt-crack, wordlist, payload
Burp Suite	references/burp.md	bridge setup, live history, Repeater/Organizer/Site map handoff, --send-via-burp, proxy channel
AI agent modes	references/agent-modes.md	agent query / autopilot / swarm / audit / olium / triage / session, intensities, providers, templates
Auth & sessions	references/auth.md	--auth-file / --auth, YAML format, extract rules, authenticated scanning
Data & management	references/data.md	db, finding, traffic, module, extensions, js, config, scope, export, import, log, project, storage
Server mode	references/server.md	vigolium server — REST API, recording/MITM proxy, scan-on-receive, live mirror, endpoints
Ingesting traffic	references/ingest.md	vigolium ingest — local/remote, per-format input examples, spec flags
Writing extensions	references/extensions.md	custom JS scanner modules, vigolium.* API
Any specific flag	references/flags.generated.md	generated from the command tree — grep it by flag name

Not covered? vigolium <command> -h is the authoritative, version-matched flag list. Then search docs.vigolium.com — start with the cheat sheet. This skill is a curated subset; the docs are the source of truth.

Token discipline

The single most important habit when driving vigolium from an agent: survey cheap, drill narrow.

# 1. Survey — metadata only, chosen fields.
vigolium finding -j --min-severity high --compact --fields id,severity,module_id,url

# 2. Drill — one finding, self-contained with its HTTP records.
vigolium finding -j --id 42 --with-records

Flag	Effect
--compact	metadata only, drop bodies
--fields a,b,c	project to just these top-level keys
--full-body	complete decoded bodies (exploit writing)
--with-records	(finding) embed linked HTTP records
--min-severity	(finding) threshold expands upward
--pick N	(finding) keep the Nth result — 2, 1,3, 2-4
--markdown	(finding/traffic) render as Markdown instead of JSON

Under --json, bodies are preview-capped with body_size/body_sha256/ body_truncated, binaries are stubbed body_omitted:"binary", and findings get a ±240-char response_evidence snippet windowed on the match.

Invariants

Things -h won't tell you:

• -S is two different flags. --stateless on scan/export/finding/ replay/agent audit; --scan-on-receive on server/ingest.
• Which DB a command opens: --db → $VIGOLIUM_DB_PATH → database.sqlite.path in config → the built-in default. Pinning $VIGOLIUM_DB_PATH also makes read commands (finding/traffic/fuzz -u) treat that file as a stateless source — project scoping off — so an agent can export it once and every read/write lands in the same session DB. It never turns a scan stateless (that would clash with --db).
• --only and --skip are mutually exclusive.
• --format html, --format sqlite, and any multi-value --format need a file destination: pass -o/--output or --split-by-host (which names per-host files from the hostname instead).
• --format sqlite additionally requires -S — it exports the standalone per-run DB. For the persisted DB use vigolium export.
• --format fs writes two sibling dirs (<base>-traffic/, <base>-findings/); --split-by-host is a no-op for it.
• --stateless on a scan is mutually exclusive with --db and with --db-isolate; -o is optional (without it results are simply discarded). On read commands (finding/traffic/replay) -S reads from --db.
• --fail-on writes output first, then sets the exit code. --soft-fail (global) overrides it. Under -P it is evaluated per child.
• --split-by-host only applies in stateless multi-target mode (), and is required for .

Scanning strategies

Strategies control which phases run. Use --strategy <name>.

Strategy	ExtHarvest	Discovery	Spidering	KnownIssueScan	Assessment	Source-Aware
lite	no	no	no	no	yes	no
balanced (default)	no	yes	yes	yes	yes	no
deep	yes	yes	yes	yes	yes	no
whitebox	no	yes	no	yes	yes	yes

Default lives in scanning_strategy.default_strategy. Print the table with vigolium strategy (no ls subcommand).

Intensity is the one-flag shortcut on top of strategies: --intensity quick|balanced|deep maps to a scanning profile and strategy in a single flag (also honored by agent autopilot/swarm). Explicit flags always override it — --intensity deep --scanning-profile foo keeps deep's strategy but your profile. Full precedence: references/scanning.md.

Scan phases

Use --only <phase> to isolate one or --skip <phase> to drop some.

Phase	Aliases	Description
ingestion	—	Parse and store input into the database
discovery	deparos, discover	Adaptive content discovery
external-harvest	—	Wayback / Common Crawl / OTX URL aggregation
spidering	spitolas	Headless-browser crawling for JS-driven routes
known-issue-scan	cve, kis, known-issues	Nuclei templates + Kingfisher secrets
dynamic-assessment	audit, dast, assessment	Core active + passive vulnerability scanning
extension	ext	JavaScript extension modules only

Run one directly: vigolium run discover -t <url>.

Input formats

-I <format> selects the input type; OpenAPI and WSDL auto-detect from content.

Format	Flag	Example
URLs (default)	-I urls	-t https://target.example or -T targets.txt
OpenAPI 3.x	-I openapi	-I openapi -i spec.yaml -t https://api.target.example
Swagger 2.0	-I swagger	-I swagger -i swagger.json
WSDL / SOAP	-I wsdl	-I wsdl -i service.wsdl -t https://soap.target.example — one SOAP POST per operation; a .svc/.asmx URL auto-fetches its WSDL
Burp XML	-I burp	-I burp -i burp-export.xml
cURL commands	-I curl	-I curl -i requests.txt
Nuclei templates	-I nuclei	-I nuclei -i templates/
HAR archive	-I har	-I har -i traffic.har
Postman collection	-I postman	-I postman -i collection.json
Burp scope export	-I burpscope	-I burpscope -i burp-scope.json — expands a program's scope into seed URLs (content-sniffed on -T too)
stdin	—	cat urls.txt | vigolium scan -i -

OpenAPI extras: --spec-url (use servers from the spec), --spec-header (auth), --spec-var (parameter values), --spec-default (fallback). WSDL reuses --spec-header (auth) and --spec-var (override a body element by its local name); -t overrides only the endpoint host, keeping the WSDL path.

Output formats

Format	Flag	Notes
Console (default)	--format console	human-readable tables to stderr
JSONL	--format jsonl	bulk {"type":…,"data":{…}} stream
HTML	--format html -o report.html	interactive ag-grid report; requires -o
SQLite	--format sqlite -S -o run.sqlite	standalone per-run DB via VACUUM INTO; requires -S + -o; aliases sqlite3, db
Filesystem tree	--format fs -o run	browsable run-traffic/ + run-findings/; see references/agent-loop.md

Combine with commas: --format jsonl,html -o report.html.

Utility toolbox (vigolium kit)

Stateless one-shot primitives — no DB, no project scope, no scan pipeline. Each reads -/stdin and takes -j/--json; nothing is persisted, so pipe the output. Details and JSON shapes: references/kit.md.

Command	Does
kit secret-scan <files|dirs|->	scan bytes for leaked credentials (embedded catalog); --fail-on-match exits 3
kit js-beautify <file|url|->	unminify + unpack a JS bundle (webcrack); --extract for endpoints
kit oast new / kit oast poll	mint OOB callback URLs (session file) and drain DNS/HTTP/SMTP hits
kit harvest <domain…>	collect known URLs from Wayback/CommonCrawl/OTX/Arquivo (same set as external-harvest)
kit jwt-crack <token>	recover a JWT's HMAC secret from a wordlist (+ alg-confusion); --fail-on-crack exits 3
kit wordlist [name]	list or print the built-in wordlists (also feeds jwt-crack -w)
kit payload --class <c>	emit built-in payloads by class (same catalog as fuzz --class)

Recipes

Multi-step workflows only — single commands are in the router above.

1. Spec scan with auth

vigolium scan -I openapi -i spec.yaml -t https://api.target.example \
  --spec-header "Authorization: Bearer <token>" --fail-on high

2. CI gate with a shareable artifact

vigolium scan -t https://target.example \
  -S --format jsonl,html -o report.html --fail-on medium

Output is written before the gate fires, so the artifact exists even on failure. --soft-fail forces exit 0 if the pipeline must not break.

3. Parallel fan-out across many targets

vigolium scan -T targets.txt -S --split-by-host -P 4 \
  --format sqlite -o run --fail-on high

# Merge the per-host databases back into one and query across all of them.
vigolium import --db combined.sqlite --glob-db 'run-*.sqlite'
vigolium finding --db combined.sqlite --min-severity high

-P requires -S -T --split-by-host (or --db-isolate -T). The gate is evaluated per child; the batch fails only when every target fails.

4. Triage loop: survey → drill → confirm → report

vigolium finding -j --min-severity high --compact --fields id,severity,module_id,url
vigolium finding -j --id 42 --with-records
vigolium replay --finding-id 42 --pretty
vigolium finding --id 42 --markdown > finding-42.md

See references/agent-loop.md for the full contract.

5. Authenticated scan

# Inline session
vigolium scan -t https://target.example --auth "admin:Cookie:session=abc123"

# From an auth file (YAML/JSON, single session or a `sessions:` bundle)
vigolium scan -t https://target.example --auth-file ./auth.yaml

# Multi-session auth-diff testing (IDOR / BFLA)
vigolium scan -t https://target.example --auth-file ./sessions.yaml

Format, extract rules, and multi-step login flows: references/auth.md.

6. Whitebox: source + running app

# Autopilot runs an audit harness over the source, then scans the live target.
vigolium agent autopilot -t http://localhost:3000 --source ./src

# Source-only audit, no target required.
vigolium agent audit --source . --intensity balanced

# Only the changed code in a PR.
vigolium agent autopilot -t http://localhost:3000 --source ./src \
  --diff main...feature-branch

--source accepts a local path, git URL, .zip/.tar.gz archive, or gs:// object. Modes, intensities, and drivers: references/agent-modes.md.

7. Capture traffic from a proxy, then scan it

# Terminal 1 — capture, mirroring to a live file tree an agent can grep.
vigolium server --ingest-proxy-port 8080 --mirror-fs ./mirror

# Terminal 2 — scan what was captured.
vigolium scan --only dynamic-assessment -t https://target.example

Or auto-scan each request as it arrives: vigolium server -t <url> -S.

8. Custom detection logic in JavaScript

vigolium ext preset                                   # install examples
vigolium ext docs                                     # API reference
vigolium ext lint --ext ./custom-check.js             # validate
vigolium run extension -t https://target.example --ext ./custom-check.js

Writing modules against the vigolium.* API: references/extensions.md.

Escape hatches

vigolium <command> -h          # authoritative flags for your installed version
vigolium --full-example        # worked examples grouped by section
vigolium doctor --json         # environment readiness (binaries, providers, templates)
vigolium module ls <keyword>   # find a module by topic
vigolium skills get --full     # print this skill and every reference

Resources

• Website: www.vigolium.com
• Documentation: docs.vigolium.com
• GitHub: github.com/vigolium/vigolium