Agentic Scanning

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.
Vigolium Audit: 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 openai-compatible with gemma4:latest at the configured local endpoint. 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

Triage is enabled by the default balanced preset and by deep; quick leaves it off. Add --triage explicitly when needed, or use --triage=false to disable classification and 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:

Phase	Type	Description
`native-normalize`	Native	Parse and normalize input
`auth`	Native	Browser-based login (when `--browser-auth`; browser tooling is always available)
`source-analysis`	AI	Route extraction from source code (if `--source`)
`code-audit`	AI	Deep security code audit (if `--code-audit`, on by default with `--source`)
`native-discover`	Native	Discovery + spidering (if `--discover`)
`plan`	AI	Master agent plans the attack
`native-extension`	Native	Validate and write generated JS extensions
`native-scan`	Native	Execute the planned scan
`triage`	AI	Classify findings (if `--triage`)
`native-rescan`	Native	Targeted 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

# Start a new run from the plan phase using existing project data
vigolium agent swarm -t https://example.com --start-from plan

Autopilot: Autonomous AI Pentest

Autopilot is one autonomous operator with full tool access (Bash, files, web fetch, browser probes, and first-class Vigolium tools). Legacy mode uses report_finding directly. Durable modes rotate bounded sections and can gate finding promotion through an independent verifier.

vigolium agent autopilot -t https://example.com

With Source Code

When --source is provided, vigolium-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

Preset	Max commands	Timeout	Vigolium-audit mode	Browser
`quick`	150	1h	`lite`	on
`balanced` (default)	500	6h	`balanced`	on
`deep`	1500	12h	`deep`	on

vigolium agent autopilot -t https://example.com --intensity deep

Browser-Assisted Auth

vigolium agent autopilot -t https://app.example.com --intensity deep \
  --prompt "log in as admin/admin123, then test protected routes"

Existing Traffic, App Docs, and Resume

# Mine prior project data and import live Burp history first
vigolium agent autopilot -t https://app.example.com \
  --burp-bridge-url http://127.0.0.1:9009 --prior-context auto

# Index operator-supplied auth/business documentation
vigolium agent autopilot -t https://app.example.com --knowledge-base ./app-docs

# Continue a shadow/enforced durable run
vigolium agent autopilot --resume <agentic-scan-uuid> \
  --prompt "finish the authorization matrix"

Bounding a CI run

# CI scan bounded by intensity preset and wall-clock
vigolium agent autopilot -t https://example.com \
  --intensity quick --max-duration 30m

Vigolium-Audit: Source Audit

Vigolium-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 audit --source ./app --mode deep

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

# Use a different agent CLI
vigolium agent audit --source ./app --mode balanced --agent codex

Findings ingest into the same database as the rest of vigolium with finding_source: audit. Query them with:

vigolium finding list --source audit

See Agentic Security 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

Pass free-text task guidance with --prompt (or the positional [prompt]):

vigolium agent swarm \
  -t https://example.com \
  --prompt "Focus on the /api/v2 endpoints. The app uses JWT auth with RS256."

For a whole plan containing prose and raw HTTP request seeds, use --plan-file:

vigolium agent swarm \
  -t https://example.com \
  --plan-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

Mode	AI Calls	Best For
Query	1	Code review, endpoint discovery, CI checks
Swarm	2-4+	Targeted request scanning, focused testing, full-scope with `--discover`
Autopilot	Many	Deep autonomous assessment, exploratory pentest
Vigolium Audit	Multi-phase	Whitebox source-code audit (standalone or alongside swarm/autopilot)
Olium	Variable	Interactive chat, debugging, ad-hoc prompts

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Overview

Prerequisites

Query: Single-Shot Analysis

With a Built-in Template

With an Inline Prompt

With Specific Files

Saving Output

Swarm: AI-Planned Targeted Scanning

Scanning a Specific Request

Full-Scope Scanning with Discovery

Source-Aware Scanning

Focusing on a Vulnerability Type

Enabling Triage

Intensity Presets

Swarm Phases

Autopilot: Autonomous AI Pentest

With Source Code

Intensity Presets

Browser-Assisted Auth

Existing Traffic, App Docs, and Resume

Bounding a CI run

Vigolium-Audit: Source Audit

Session Management

Custom Instructions

Dry Run and Prompt Inspection

Choosing the Right Mode

​Overview

​Prerequisites

​Query: Single-Shot Analysis

​With a Built-in Template

​With an Inline Prompt

​With Specific Files

​Saving Output

​Swarm: AI-Planned Targeted Scanning

​Scanning a Specific Request

​Full-Scope Scanning with Discovery

​Source-Aware Scanning

​Focusing on a Vulnerability Type

​Enabling Triage

​Intensity Presets

​Swarm Phases

​Autopilot: Autonomous AI Pentest

​With Source Code

​Intensity Presets

​Browser-Assisted Auth

​Existing Traffic, App Docs, and Resume

​Bounding a CI run

​Vigolium-Audit: Source Audit

​Session Management

​Custom Instructions

​Dry Run and Prompt Inspection

​Choosing the Right Mode

Overview

Prerequisites

Query: Single-Shot Analysis

With a Built-in Template

With an Inline Prompt

With Specific Files

Saving Output

Swarm: AI-Planned Targeted Scanning

Scanning a Specific Request

Full-Scope Scanning with Discovery

Source-Aware Scanning

Focusing on a Vulnerability Type

Enabling Triage

Intensity Presets

Swarm Phases

Autopilot: Autonomous AI Pentest

With Source Code

Intensity Presets

Browser-Assisted Auth

Existing Traffic, App Docs, and Resume

Bounding a CI run

Vigolium-Audit: Source Audit

Session Management

Custom Instructions

Dry Run and Prompt Inspection

Choosing the Right Mode