Vigolium-Audit

vigolium-audit is an autonomous agent within Vigolium that performs comprehensive security audits on your repository, focusing on uncovering exploitable vulnerabilities with high accuracy.

[!WARNING] A full audit run can take a few hours. Go enjoy your coffee ☕ and take a walk. Don't worry, it's worth the wait.

Why?

Static analysis tools bury you in false positives. Manual audits are thorough but slow and expensive. vigolium-audit runs security audits as a multi-agent pipeline: each phase builds on the last — from gathering advisories, to flagging candidates, to proposing attack paths, to debating exploitability, to a final verification pass that kills false positives. The workflow is resumable and incremental — re-run after a code change and only affected phases re-execute.

The goal is simple: spend machine time instead of human time, and only surface findings that are real.

Install as a standalone CLI (recommended)

npm install -g @vigolium/vigolium-audit

Or via curl:

curl -fsSL https://cdn.vigolium.com/vigolium-audit/install.sh | bash

Install as a Skill

Already using the skills CLI? Add vigolium-audit as a skill so your agent learns the modes, flags, and example commands automatically:

npx skills@latest add https://github.com/vigolium/vigolium-audit --skill vigolium-audit --agent claude-code --yes

The skill teaches the agent how to install the binary, pick a mode, resume interrupted runs, and produce machine-readable output. The CLI binary itself still needs to be installed via one of the methods above.

| Vigolium Audit | Vigolium Audit in Codex | |:---:|:---:| | | |

Requirements

claude and/or codex on PATH, plus the matching API key or ambient subscription auth.

Quickstart

# just start the audit
vigolium-audit run --mode balanced --target /path/to/repo/

# Build only the reusable application knowledge base + attack surface
vigolium-audit run --mode knowledge-base --target /path/to/repo/

# Seed an audit with application docs (a file or a directory of Markdown)
vigolium-audit run --mode deep --target /path/to/repo/ --knowledge-base ./app-docs

# Run a deep audit interactively (auto-installs the harness for the session
# and removes it on exit — leave-no-trace)
vigolium-audit run --mode deep --agent claude -i

# Headless deep audit, abort if cost exceeds $20
vigolium-audit run --mode deep --agent codex --max-cost 20

# Force the Codex Agent SDK transport (Codex auto already prefers SDK)
vigolium-audit run --mode deep --agent codex --transport sdk

# Interactive Codex: submits "Full deep mode" automatically, then keeps the TUI attached
vigolium-audit run --mode deep --agent codex -i

# Preflight: binary, auth, content, real message round-trip
vigolium-audit verify claude
vigolium-audit verify codex --transport both

Agent transport

Headless runs accept --transport auto|sdk|cli. For Codex, auto prefers the Codex Agent SDK and reuses either OPENAI_API_KEY or the ambient codex login session; pass --transport cli as an explicit native codex exec fallback. Claude keeps its existing auto-selection policy (SDK with an API key, CLI with ambient subscription auth).

vigolium-audit verify codex --transport both probes both Codex paths with a real ping → pong round trip. Interactive -i always uses the native CLI, so it rejects --transport sdk. Codex interactive dispatch is available for knowledge-base, lite, balanced, deep, revisit, and confirm; run diff, merge, reinvest, and longshot without -i so the phase orchestrator handles them.

Auth overrides

Three flags on vigolium-audit run swap auth in for the lifetime of one run, then restore the original state on exit:

# Pass an API key via flag (claude → ANTHROPIC_API_KEY, codex → OPENAI_API_KEY)
vigolium-audit run --mode deep --agent claude --api-key sk-ant-...

# Set CLAUDE_CODE_OAUTH_TOKEN for the subprocess / SDK
vigolium-audit run --mode deep --agent claude --oauth-token sk-ant-oat01-...

# Temporarily replace ~/.codex/auth.json with a custom file
# (~/.claude/.credentials.json for --agent claude). The original file is moved
# to <target>.vigolium-audit-backup before the run and restored on exit.
vigolium-audit run --mode deep --agent codex --oauth-cred-file ./codex-auth.json

Secrets passed via flag are redacted in the [auth] applied: … log line. The cred-file backup is also restored on Ctrl-C / SIGTERM.

Machine-readable output

Every command supports --json for tooling. Logs stay on stderr; structured JSON goes to stdout (single object for verify/uninstall, NDJSON event stream for run).

vigolium-audit verify claude --json | jq .ok
vigolium-audit run --mode lite --agent claude --json | jq -c 'select(.kind == "phaseEnd")'

bridge — SDK sidecar for non-TS callers

vigolium-audit bridge <task> drives Claude/Codex through the Agent SDK for a single job — triage a finding, develop an exploit, or plan an attack — and streams a normalized NDJSON event stream back. It is how the Go vigolium scanner calls into the TypeScript-only Agent SDK. The vigolium-scanner skill is always loaded so the agent can operate the vigolium CLI.

vigolium-audit bridge triage --input-file finding.json --cwd ./repo --json
vigolium-audit bridge serve --cwd ./repo --json      # long-lived NDJSON daemon

See docs/bridge.md for the task presets, flags, event contract, and a Go caller example.

Audit Modes

Vigolium-Audit ships a handful of audit modes — each is a different phase graph selecting how thorough vs. fast the run is, and what it focuses on. The short version:

| Mode | Use it when | |------|-------------| | knowledge-base | You only want a reusable source-grounded application model and attack surface, with no vulnerability finding pass. | | lite | You want a fast surface scan (secrets + SAST + PoC) on a plain folder. | | balanced | You want a real audit but not the full deep pipeline — middle ground. | | deep | You want the full multi-agent pipeline: highest signal, longest run. | | revisit | You already have a complete deep result and want a second anti-anchored pass. | | reinvest | You want cross-agent re-verification of existing CRIT/HIGH findings (claude ↔ codex). | | confirm | You want findings exercised against a live or booted target. | | diff | A small change landed; re-run only deep phases the diff affects. | | merge | You ran vigolium-audit multiple times and want one normalized findings tree. | | longshot | Architecture-anchored audits feel exhausted — bottom-up file-by-file hail-mary. | | refresh | You don't want to pick: router resolves to revisit or fresh deep. |

Run vigolium-audit list for the live view — descriptions, phase counts, and observed median runtime from your prior runs. Canonical phase definitions live in src/content/command-defs/; overriding or extending them (per-user or per-project) is documented in CUSTOMIZATION.md.

Application knowledge-base input

The knowledge-base, lite, balanced, and deep modes accept application documentation through either of these mutually exclusive flags:

# One Markdown/MDX file, or a directory recursively containing Markdown/MDX
vigolium-audit run --mode deep --knowledge-base ./docs/application

# Small inline input (prefer the path form for sensitive or large content)
vigolium-audit run --mode balanced --knowledge-base-raw $'# Auth\nAdmins require WebAuthn.'

With no flag, the CLI searches the target (to a bounded depth) for directories named knowledge-base. It snapshots the selected files before any prior result is archived, enforces file/count/size limits, hashes every source, and stores an immutable copy under vigolium-results/attack-surface/knowledge-base-input/. Conditional phase KB0 converts that corpus into the cited vigolium-results/attack-surface/knowledge-base-seed.md; later phases verify its implementation claims against source code. Documentation is treated as data, never as agent instructions or by itself as a reason to suppress a finding.

Resume binds the staged copy to the exact audit record and rejects changed, missing, or cross-run input. A completed knowledge-base run can be chained directly into an audit:

vigolium-audit run --modes knowledge-base,deep --knowledge-base ./docs/application

On a Git target, a later run at the same commit also adopts the latest completed standalone knowledge-base report when it is still the live result and both the builder and consumer source snapshots have clean working trees (excluding vigolium-results/).

knowledge-base mode phases

This mode writes context only—no SAST, finding drafts, PoCs, or vulnerability report. Its graph is KB0 (conditional) → K1 → K2:

| Phase | What it does | |-------|--------------| | KB0 Knowledge Base Intake | Normalize supplied/discovered docs into a provenance-linked seed. Skipped when no input is resolved. | | K1 Intelligence and Inventory | Build advisory intelligence, component/dependency inventory, and sbom.json. | | K2 Knowledge Base and Attack Surface | Build the source-grounded architecture, roles/auth flows, DFD/CFD slices, threat model, attack surface, and unauthenticated surface. |

deep mode phases

deep has 12 audit phases plus the conditional KB0 intake node. Each phase feeds the next — intel first, then static analysis, then adversarial review, then PoC and reporting. D1/D2 run in parallel; D2 and D3 are skipped on a no-git target.

| Phase | What it does | |-------|--------------| | KB0 Knowledge Base Intake (optional) | Normalize resolved application docs into a cited seed used by later phases. | | D1 Intelligence Pass (CVE) | Collect known CVEs/advisories for the project's stack and dependencies. | | D2 Intelligence Pass (History) | Mine git history for security-relevant commits, regressions, and risky changes. (git only) | | D3 Patch Audit | Inspect prior security fixes for incomplete patches or bypasses. (git only) | | D4 Threat Model | Build the attack surface and threat model from architecture and entry points. | | D5 Code Scan | Static (SAST-style) scan for vulnerable code patterns; enumerates cross-service edges. | | D6 Deep Probe | Targeted, manual-style investigation of the most suspicious areas. | | D7 Access Audit | Authn/authz and access-control review — broken access, IDOR, privilege escalation. | | D8 Review Panel | Adversarial review chamber: debates exploitability and kills false positives (also folds in taint reasoning + variant expansion). | | D9 Intent Reconciliation | Reconcile survivors against intended behavior to drop by-design "findings". | | D10 PoC Authoring | Write concrete proof-of-concept exploits for the surviving findings. | | D11 Finding Finalize | Finalize confirmed and theoretical finding reports in their canonical buckets. | | D12 Report Compose | Assemble the final audit report. |

Deterministic completion

Core audit state is owned by the trusted CLI, not by agent prose. Each phase declares executable artifact checks (required files, sections, JSON, globs, or complete per-finding reports); the engine validates them, performs bounded artifact-only repair, and only then records completion. Finding IDs and routing are produced by the bundled consolidator, with confirmed results in findings/ and unconfirmed or intentional results retained in findings-theoretical/. Fresh runs reject untouched artifacts that predate the active audit; resumes reuse artifacts written during the original run. When prior audit state exists, fresh core runs first move phase-owned outputs to a reversible vigolium-results/.archive/pre-run/ snapshot.

Output cleanup

Completed deep/confirm runs, including successful resumes of those modes, automatically prune raw workspaces after success so the final vigolium-results/ tree contains only durable deliverables: state JSON, file-state.json, attack-surface/, finalized findings/ + findings-theoretical/, mode reports, and confirm-workspace/ for confirmation runs. Failed or aborted runs keep raw directories for resume and debugging. Use --strip-raw or vigolium-audit strip <path> for modes that do not auto-prune.

Resuming an interrupted audit

If a run is killed mid-way (quota limit, SIGINT, --max-cost cap, crash), the audit stays non-complete in vigolium-results/audit-state.json. Pick it up where it left off — completed phases are skipped, stale in_progress phases are quarantined and retried:

vigolium-audit resume ./repo                       # auto-detect mode + audit
vigolium-audit run --mode deep --resume            # explicit form

Project Structure

vigolium-audit/
├── src/
│   ├── cli/                # run / setup / verify / uninstall entry points
│   ├── engine/             # orchestrator, phase parser, state, harness, modes
│   ├── adapters/           # claude/codex CLI + SDK adapters, platform detect
│   ├── content/            # vendored audit methodology
│   │   ├── agent-defs/         # 36 specialist agent prompts (.md)
│   │   ├── command-defs/       # 11 mode workflows (knowledge-base/lite/balanced/deep/…)
│   │   ├── skills/             # 20 standalone workflow skills
│   │   ├── harnesses/          # platform-specific frontmatter (claude, codex)
│   │   ├── sdk-variants/       # generated SDK-safe variants (gitignored)
│   │   └── skills-lock.json    # skill version locks
│   ├── content-bundle.json # build-time inlined content for the compiled binary
│   ├── content-loader.ts   # resolves vendored content + per-user overrides
│   └── index.ts            # CLI entry point
├── build/                  # release packaging (build.ts, install.sh)
├── scripts/                # transform-content.ts, sync helpers
└── tests/
    └── fixtures/           # sample runtime logs (`vigolium-audit-runtime.log`, `vigolium-audit-json-output.jsonl`) captured from real runs

Audit output lands in vigolium-results/ inside the target repository (e.g. vigolium-results/audit-state.json, vigolium-results/findings/, vigolium-results/final-audit-report.md).

Per-user customization (overrides for agents, commands, skills) lives in ~/.config/vigolium-audit/. See CUSTOMIZATION.md.

Development

bun install
bun run dev -- run --mode lite --agent claude --target ./fixtures/tiny-vuln
bun test
bun run build           # current platform binary → build/dist/ + ~/.local/bin/vigolium-audit
bun run build:all       # all 4 targets (host platform also installed)
bun run npm-publish     # publish @vigolium/vigolium-audit (single bundled pkg) to npm

bun run build also copies the just-built binary to ~/.local/bin/vigolium-audit for fast local testing. Override the destination with VIGOLIUM_AUDIT_BIN_DIR=… or skip the copy with VIGOLIUM_AUDIT_BUILD_NO_INSTALL=1.

License

vigolium-audit is made with ♥ by @j3ssie and it is released under the MIT license.