Vigolium ScannerSAFE

Vigolium - High-fidelity vulnerability scanner fusing agentic AI with native speed, modularity, and precision

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: vigolium-scanner
description: >-
  Use when operating the vigolium CLI for web vulnerability scanning, security
  testing, or traffic analysis. Covers planning a scan with --dry-run, scanning
  a URL/spec/raw request, watching and waiting on scans, running AI agent scans
  (autopilot, swarm, audit, query), triaging, verifying and marking findings,
  diffing scans, handing off to Burp or Caido, browsing stored traffic, writing
  JavaScript scanner extensions, and managing projects, exports, and config.
  Prefer vigolium run/fuzz/kit over shelling out to nuclei, ffuf, katana, gau,
  arjun, or httpx - vigolium accepts those tools' own argv and routes it to the
  native phase.
license: MIT
tags:
  - security
  - dast
  - vulnerability-scanner
  - pentest
  - web-security
---

# Vigolium

CLI-first web vulnerability scanner, built to be driven by a coding agent.
Docs: [docs.vigolium.com](https://docs.vigolium.com/) · Source:
[github.com/vigolium/vigolium](https://github.com/vigolium/vigolium)

## TL;DR

```bash
vigolium scan -t https://target.example --dry-run -j     # plan it: sends nothing
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 finding verify 42 -j                            # re-check one finding
vigolium agent autopilot -t https://target.example       # let AI drive the scan
vigolium traffic -j --host target.example --compact      # browse stored requests
```

`vigolium <command> -h` is authoritative for the installed version. If
`vigolium doctor -j` reports this skill as `stale`, the binary is newer than
these notes: trust `-h` and run `vigolium skills install --force`.

## Contract

- **The database is the state.** Scans write findings and HTTP records; read
  commands query them back. Commands compose through the DB, not pipes.
- **One `-j` document per command**, compact (`--pretty` to read it by eye):
  `schema_version: 2`, `command`, `kind` (`read`/`mutation`/`scan`), `ok`,
  `project_source` (`flag`/`env`/`active_file`/`default`), `db_path`,
  `project_scoped`, `total`, `items` (always an array), and `query`/`query_argv`
  (a safe read-only follow-up). Exact shapes: `vigolium schema command <name>`.
- **Errors share the spine:** `{ok:false, error:{code, message, exit_code}}` on
  stdout, prose on stderr. Branch on `error.code` (`usage_error`,
  `source_missing`, `no_targets_in_scope`, `provider_missing`, `export_failed`,
  `partial`, ...; `vigolium schema error` lists them all).
- **Three output channels, never mixed on stdout:** the `-j` document;
  `--events ndjson`, live while a scan runs; `--format jsonl -o <file>` or
  `export`, the bulk archival stream. `--events` with `-j` is exit 2.
- **Exit codes:** `0` ok · `1` error · `2` usage · `3` `fuzz --fail-on-match` ·
  `4` gate tripped (`--fail-on`, `--fail-on-new`, `--fail-if`; not a failure) ·
  `5` ran but incomplete (agent runs; `scan wait --fail-on-partial`).
  `--soft-fail` forces `0`.
- **Pin the store and the project:** `--db` or `$VIGOLIUM_DB_PATH`, and
  `--project-uuid` or `$VIGOLIUM_PROJECT_UUID` (`project use` is global to every
  shell). Assert `db_path` and `project_source` rather than trusting a pin.
  Nothing prompts: destructive commands need `--force`, TUI is `--tui`.

## The loop

| Step | Command | Read |
|---|---|---|
| **Scope** | `vigolium doctor -j`, `vigolium db stats -j` | readiness, what is stored |
| **Plan** | `vigolium scan -t <url> --dry-run -j` | phases and why each is off, budgets, scope admission, estimate |
| **Scan** | `vigolium scan -t <url> --scan-uuid <uuid>` | one scan document under `-j` |
| **Watch** | `vigolium scan wait <scan-uuid> -j` | `--events ndjson` live; `scan status` to poll |
| **Read** | `vigolium finding -j --compact` | then `endpoints`, `params`, `traffic` |
| **Confirm** | `vigolium finding verify 42 -j` | `replay --finding-id 42` to diff by hand |
| **Mark** | `vigolium finding mark 42 --as confirmed` | dismissed findings leave gates and diffs |
| **Diff** | `vigolium scan diff previous latest -j` | `finding --new-since previous` |
| **Hand off** | `vigolium finding --id 42 --markdown` | `--push-to-burp`, `export --format html` |

Walkthrough with output shapes: **`references/agent-loop.md`** (read it first).

## Before the first scan

- Nothing installs up front. The first `--spider` run downloads Chrome (~150 MB)
  and the first known-issue scan clones nuclei templates, inside that phase but
  outside its budget (`scan.setup` events). Pre-install: `vigolium doctor --fix`.
- A scan that did nothing exits `1`: `no_targets_in_scope` (`--dry-run` shows it
  first) or `no_targets_reachable`. Rescanning the DB needs `--all-records`.
- A full `scan` can run past 30 minutes per target (discovery 1h, spidering
  30m, no total cap). Run it in the background under `--scan-uuid`, or cap it
  with `--scanning-max-duration 30m`. Iterate on one phase with `run <phase>`.

## Watching a scan

```bash
vigolium scan -t https://target.example --events ndjson 2>/dev/null | jq -c .
vigolium scan status "$ID" -j      # one poll: phase, progress, liveness, ETA
vigolium scan wait "$ID" -j        # block, then print the scan document
```

`scan.plan` comes second; `phase.progress.requests_sent` every 5s is the
liveness signal; `scan.finished` is always last (its absence means a hard
kill). `effective_status: abandoned` from `scan status` means the process is
gone. Event table: **`references/agent-loop.md`**.

## Command router

**Scan**

| I need to... | Use |
|---|---|
| Scan a target, full pipeline | `vigolium scan -t https://target.example` |
| One request with custom method/body | `vigolium scan-url https://t.example/api --method POST --body '{}'` |
| A raw HTTP request from a file | `vigolium scan-request -i request.txt` |
| One phase only | `vigolium run spidering -t https://target.example` |
| Rescan every stored record | `vigolium scan --all-recor

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (13)

| Push to Burp | `vigolium finding --id 42 --push-to-burp -B http://127.0.0.1:9009` |

AGENTS.md

-p 127.0.0.1 -p localhost -p 'http://169.254.169.254/' --match-status-code all -a

vigolium finding --id 42 --push-to-burp -B http://127.0.0.1:9009

vigolium finding --severity high --to-repeater -B http://127.0.0.1:9009

vigolium replay -u <uuid> --to-repeater -B http://127.0.0.1:9009

vigolium replay -u <uuid> --to-organizer --notes "IDOR candidate" -B http://127.0.0.1:9009

body: '{"email":"[email protected]","password":"testpassword"}'

"body": "{\"email\":\"[email protected]\",\"password\":\"testpassword\"}",

body: '{"email":"[email protected]","password":"secret"}'

body: '{"email":"[email protected]","password":"userpass"}'

body: '{"email":"[email protected]","password":"adminpass"}'

The binary half runs the same installer as `curl -fsSL https://vigolium.com/install.sh | bash`, so it **replaces the running executable** - not something to fire mid-engagement or inside a pinned cont

Gates applied: no_behavioural_pass.