vigolium-scanner

Coding-agent skill for operating the Vigolium web vulnerability scanner CLI. Teaches Claude Code, Codex, Cursor, Pi, or any agentskills.io-compatible agent how to pick the right command, construct correct flags, triage findings, and confirm them.

Install

The skill is embedded in the vigolium binary, so the installed copy always matches your CLI version. Prefer this over copying files by hand:

vigolium skills install --agent claude --scope project   # --agent claude|codex|agents
vigolium skills                                          # list bundled skills
vigolium skills get vigolium-scanner --full              # print SKILL.md + every reference

--agent	--scope project	--scope global
claude	.claude/skills/	~/.claude/skills/
codex | agents	.agents/skills/	~/.agents/skills/

Keeping it current

Each install writes .vigolium-skill.json beside SKILL.md: the skill name, the installing binary's binary_version and commit, the bundle_sha256, the sha256 of every file, and installed_at. Agents ignore the dotfile, and SKILL.md is copied unchanged. After upgrading vigolium:

vigolium skills ls                        # state of every install location
vigolium skills install --force           # refresh one (same --agent/--scope)
vigolium doctor --fix --only skill        # refresh every stale copy in place

skills ls checks ./.claude/skills, ~/.claude/skills, ./.agents/skills and ~/.agents/skills and reports each copy as current, stale (from another bundle, or an install that has no manifest), modified (a listed file was edited or removed) or missing. skills ls -j returns the same data under installed. A plain skills install leaves an existing copy alone and prints stale: run vigolium skills install --force when it is out of date. --force deletes the files the old manifest lists that the new bundle no longer ships and keeps files you added. An install without a manifest is moved to <dir>.bak-<timestamp> (its SKILL.md renamed to SKILL.md.bak so the agent does not load it twice) before the fresh copy is written. doctor warns about stale and modified copies. doctor --fix reinstalls only the stale ones, so your local edits are never overwritten.

Once installed it auto-triggers on mentions of scanning, vigolium, DAST, or vulnerability testing. In Claude Code you can also invoke it explicitly as /vigolium-scanner.

Alternatives (not version-matched): bunx skills add vigolium/skills --skill vigolium-scanner --agent <name> --yes, or clone vigolium/skills and copy the folder into ~/.claude/skills/ or ~/.agents/skills/.

Layout

vigolium-scanner/
├── SKILL.md                      # always loaded: contract, loop, router, rules
└── references/                   # loaded on demand, one hop from SKILL.md
    ├── agent-loop.md             # ★ driving vigolium from an agent: the -j envelope,
    │                             #   --events stream, verify/mark/diff, exports, exit codes
    ├── invariants.md             # cross-command rules -h won't tell you, by topic
    ├── recipes.md                # multi-step workflows (plan → wait → new-since, …)
    ├── scanning.md               # scan, scan-url, scan-request, run, phases, strategies,
    │                             #   pace + per-phase dials, tool shims (ffuf/nuclei/…)
    ├── fuzzing.md                # vigolium fuzz: positions, attack modes, anomaly scoring
    ├── kit.md                    # vigolium kit: secret-scan, js-beautify, oast, harvest, …
    ├── burp.md                   # Burp bridge, Repeater/Organizer/Site map, --send-via-burp
    ├── agent-modes.md            # agent query/autopilot/swarm/audit/olium/triage/session
    ├── auth.md                   # --auth-file / --auth, YAML format, extract rules
    ├── data.md                   # db, finding, traffic, module, ext, js, config, export
    ├── server.md                 # vigolium server: REST API, recording/MITM proxy, live mirror
    ├── ingest.md                 # vigolium ingest: local/remote, per-format input examples
    ├── extensions.md             # writing JS scanner modules against vigolium.*
    └── flags.generated.md        # GENERATED from the cobra tree — grep it by flag name

SKILL.md is the only file always in context; it routes to at most one reference per task. If you are building an agent integration, start with references/agent-loop.md — it documents the scope → plan → scan → watch → read → confirm → mark → diff → hand off loop, the three output channels (-j document, bulk jsonl, live --events stream), the exit-code table, and the token-bounding flags.

Maintaining

references/flags.generated.md is generated — never edit it by hand:

make skill-flags          # or: vigolium skills gen-flags

Re-run it whenever a flag is added, renamed, or given a shorthand; the file is committed so the embedded bundle stays self-contained.

Everything else is hand-written prose. Two rules keep it useful:

1. Keep SKILL.md under ~500 lines. It is loaded in full every time the skill triggers, so anything that belongs to one topic belongs in that topic's reference instead.
2. Don't restate flags. If vigolium <cmd> -h answers it, link to the generated reference rather than copying rows that will drift.

Docs

• Install & usage guide: docs/agentic-scan/using-vigolium-in-agent.md
• Driving vigolium from an agent: docs/coding-agent.md
• Full documentation: docs.vigolium.com
• Cheat sheet: docs.vigolium.com/getting-started/cheat-sheet
• Skills repository: github.com/vigolium/skills