> ## 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.

# Agentic Scanning

> Use AI-driven scanning modes, Query, Swarm, Autopilot, and Vigolium Audit, to autonomously discover, audit, and verify vulnerabilities.

## 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

```bash theme={null}
# 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:

```bash theme={null}
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

```bash theme={null}
vigolium agent query --prompt-template security-code-review --source ./app
```

### With an Inline Prompt

```bash theme={null}
vigolium agent query -p "Find all API endpoints that accept user input without validation" --source ./app
```

### With Specific Files

```bash theme={null}
vigolium agent query \
  --prompt-template security-code-review \
  --source ./app \
  --files src/auth/login.go,src/auth/session.go
```

### Saving Output

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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.

```bash theme={null}
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.

```bash theme={null}
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      |

```bash theme={null}
vigolium agent autopilot -t https://example.com --intensity deep
```

### Browser-Assisted Auth

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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`.

```bash theme={null}
# 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:

```bash theme={null}
vigolium finding list --source audit
```

See [Agentic Security Audit](/getting-started/agentic-security-audit) for the full guide.

## Session Management

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

```bash theme={null}
# 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]`):

```bash theme={null}
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`:

```bash theme={null}
vigolium agent swarm \
  -t https://example.com \
  --plan-file context.md
```

## Dry Run and Prompt Inspection

Preview the rendered prompt without executing:

```bash theme={null}
vigolium agent swarm --dry-run \
  --input "https://example.com/api/users?id=1"
```

Print the prompt to stderr while executing:

```bash theme={null}
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                              |