Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Vigolium’s agent mode uses AI to drive vulnerability scanning. Five subcommands cover the full spectrum:
  • Query — single-shot prompt; code review, endpoint discovery, secret hunt.
  • Swarm — AI-guided multi-phase scan that drives the native scanner (plan → modules → triage).
  • Autopilot — autonomous AI pentest; the agent drives bash, files, and the vigolium CLI itself.
  • Archon — multi-phase whitebox security audit (lite / balanced / deep).
  • Olium — interactive TUI / one-shot prompt; the underlying agent runtime, also used by every mode above.
All AI dispatch goes through the in-process olium engine. Configure the provider once in agent.olium.*; per-run flags can override.

​
Prerequisites

# List configured providers and the credentials they need
vigolium agent --list-agents

# List available prompt templates
vigolium agent --list-templates

# Check provider readiness (auth, API key, model)
vigolium doctor
Default provider is codex-oauth (uses ~/.codex/auth.json). Switch to Anthropic: 
export ANTHROPIC_API_KEY=sk-ant-...
vigolium config set agent.olium.provider anthropic-api-key
vigolium config set agent.olium.model claude-opus-4-7
Or override per run with --provider, --model, --llm-api-key, --oauth-cred, --oauth-token.

​
Query: Single-Shot Analysis

Query runs a single AI prompt and returns structured output. No network scanning — useful for code review, endpoint discovery, and secret detection.

​
With a Built-in Template

vigolium agent query --prompt-template security-code-review --source ./app

​
With an Inline Prompt

vigolium agent query -p "Find all API endpoints that accept user input without validation" --source ./app

​
With Specific Files

vigolium agent query \
  --prompt-template security-code-review \
  --source ./app \
  --files src/auth/login.go,src/auth/session.go

​
Saving Output

vigolium agent query \
  --prompt-template endpoint-discovery \
  --source ./app \
  --output endpoints.json

​
Swarm: AI-Planned Targeted Scanning

Swarm is the primary agentic scan mode. A master AI agent analyzes your input, selects scanner modules, generates custom JavaScript extensions, and executes the scan.

​
Scanning a Specific Request

Pass a target request via --input (accepts URLs, curl commands, raw HTTP, Burp XML, or base64). Auto-detected: 
# From a URL
vigolium agent swarm --input "https://example.com/api/users?id=1"

# From a curl command (target auto-derived)
vigolium agent swarm --input "curl -X POST -H 'Content-Type: application/json' -d '{\"user\":\"admin\"}' https://example.com/api/login"

# From a stored DB record
vigolium agent swarm --record-uuid 550e8400-e29b-41d4-a716-446655440000

# From stdin
echo -e "POST /api/search HTTP/1.1\r\nHost: example.com\r\n\r\nq=test" | vigolium agent swarm

​
Full-Scope Scanning with Discovery

Add --discover to run content discovery and spidering before the AI planning phase: 
vigolium agent swarm --discover -t https://example.com

​
Source-Aware Scanning

Provide application source code for deeper analysis. The AI agent analyzes routes, auth flows, and generates targeted extensions: 
vigolium agent swarm --source ./app -t https://example.com --discover
--code-audit is on by default when --source is set; the AI runs a deep security code audit on top of scanning. Disable with --code-audit=false.

​
Focusing on a Vulnerability Type

vigolium agent swarm \
  --input "https://example.com/api/users?id=1" \
  --vuln-type sqli

​
Enabling Triage

By default, swarm outputs raw findings. Add --triage for AI-powered true/false-positive classification with automatic rescan: 
vigolium agent swarm \
  --input "https://example.com/api/users?id=1" \
  --triage \
  --max-iterations 3

​
Intensity Presets

--intensity bundles many flags into a single knob: 
vigolium agent swarm -t https://example.com --intensity quick      # CI-friendly
vigolium agent swarm -t https://example.com --intensity balanced   # default
vigolium agent swarm -t https://example.com --intensity deep       # thorough audit

​
Swarm Phases

The swarm pipeline runs these phases in order:
PhaseTypeDescription
native-normalizeNativeParse and normalize input
authNativeBrowser-based login (when --browser-auth + --browser)
source-analysisAIRoute extraction from source code (if --source)
code-auditAIDeep security code audit (if --code-audit, on by default with --source)
native-discoverNativeDiscovery + spidering (if --discover)
planAIMaster agent plans the attack
native-extensionNativeValidate and write generated JS extensions
native-scanNativeExecute the planned scan
triageAIClassify findings (if --triage)
native-rescanNativeTargeted rescan on follow-ups
Skip or start from a specific phase: 
# Skip code audit
vigolium agent swarm -t https://example.com --source ./app --skip code-audit

# Resume from the plan phase
vigolium agent swarm -t https://example.com --start-from plan

​
Autopilot: Autonomous AI Pentest

Autopilot is a single long-running olium engine with full tool access (bash, files, web fetch, vigolium CLI). The agent decides what to investigate, reports findings as it confirms them via report_finding, and halts on its own via halt_scan. 
vigolium agent autopilot -t https://example.com

​
With Source Code

When --source is provided, archon-audit runs first (foreground), prepares a frozen whitebox context bundle, and the autonomous operator launches against that context. 
vigolium agent autopilot -t https://example.com --source ./app

# Source from a remote repo
vigolium agent autopilot -t https://example.com --source https://github.com/org/app.git

# Focus on changed code from a PR
vigolium agent autopilot -t https://example.com --source ./app \
  --diff https://github.com/org/app/pull/42

# Last N commits
vigolium agent autopilot -t https://example.com --source ./app --last-commits 5

​
Intensity Presets

PresetMax commandsTimeoutArchon modeBrowser
quick301hliteoff
balanced (default)1006hbalancedoff
deep30012hdeepon
vigolium agent autopilot -t https://example.com --intensity deep

​
Browser-Assisted Auth

vigolium agent autopilot -t https://app.example.com --intensity deep \
  --browser --credentials "admin/admin123"

​
Halt and Token Budget

# CI scan with a token budget cap
vigolium agent autopilot -t https://example.com \
  --intensity quick --token-budget 200000 --max-duration 30m

​
Archon: Source Audit

Archon-audit is the dedicated whitebox audit mode. It runs as a foreground command on its own, or as a background prep step when swarm/autopilot are invoked with --source. 
# Standalone — multi-phase audit
vigolium agent archon --source ./app --mode deep

# Lite mode (CI-friendly, 3 phases)
vigolium agent archon --source ./app --mode lite

# Use a different agent CLI
vigolium agent archon --source ./app --mode balanced --agent codex
Findings ingest into the same database as the rest of vigolium with finding_source: archon. Query them with: 
vigolium finding list --source archon
See Archon Audit for the full guide.

​
Session Management

All agent runs create session directories under ~/.vigolium/agent-sessions/. Browse past sessions: 
# List all sessions
vigolium agent session

# Filter by mode
vigolium agent session --mode swarm

# View a specific session
vigolium agent session <uuid>

# Tail the live console log
vigolium log <uuid>

​
Custom Instructions

Append custom guidance to any agent prompt: 
vigolium agent swarm \
  -t https://example.com \
  --instruction "Focus on the /api/v2 endpoints. The app uses JWT auth with RS256."
Or load from a file: 
vigolium agent swarm \
  -t https://example.com \
  --instruction-file context.md

​
Dry Run and Prompt Inspection

Preview the rendered prompt without executing: 
vigolium agent swarm --dry-run \
  --input "https://example.com/api/users?id=1"
Print the prompt to stderr while executing: 
vigolium agent swarm --show-prompt \
  --input "https://example.com/api/users?id=1"

​
Choosing the Right Mode

ModeAI CallsBest For
Query1Code review, endpoint discovery, CI checks
Swarm2-4+Targeted request scanning, focused testing, full-scope with --discover
AutopilotManyDeep autonomous assessment, exploratory pentest
ArchonMulti-phaseWhitebox source-code audit (standalone or alongside swarm/autopilot)
OliumVariableInteractive chat, debugging, ad-hoc prompts