Skip to main content
vigolium agent autopilot is the single-loop agentic scan, one long-running LLM session decides what to investigate, drives tools (bash, file I/O, web fetch, vigolium CLI commands), reports findings to the database as it confirms them, and halts on its own when it has nothing productive left to do. It is the simplest of the agentic-scan modes, there is no master/worker pipeline, no plan/triage phase split, just one engine running until it calls halt_scan.

​
Mental model

Think of it as a security analyst sitting at a terminal:
  • The analyst is given a target URL, optionally a source tree, and a focus hint.
  • They have shell access, file-read access, web access, and the vigolium CLI.
  • They poke around, follow leads, write findings to a notebook as they confirm each bug, and stop when there is nothing more worth digging into.
The autopilot is exactly that, except the analyst is an LLM and the notebook is the vigolium findings table.

​
Lifecycle (high-level)

                  ┌──────────────────────────────────────────────┐
 vigolium agent ─►│ 1. CLI flag parsing                          │
 autopilot …      │    intensity preset → max-cmds, timeout, …   │

                  │    --input → curl/HTTP/Burp/url normalize    │
                  │    --source → resolve git URL/diff/local     │
                  │    --provider/model → olium.ResolveProvider  │
                  └──────────────────────────────────────────────┘
                                       │
                                       ▼
                  ┌──────────────────────────────────────────────┐
                  │ 2. Session bootstrap                         │
                  │    EnsureSessionDir(~/.vigolium/agent-…/UUID)│
                  │    WriteRunPID, CleanupOrphanedProcesses     │
                  │    create AgenticScan row (status=running)   │
                  │    tee stdout → {session}/runtime.log        │
                  └──────────────────────────────────────────────┘
                                       │
                                       ▼
                  ┌──────────────────────────────────────────────┐
                  │ 3. autopilot.Run (pkg/olium/autopilot)       │
                  │    build system prompt + initial user prompt │
                  │    register tools: builtins + halt_scan +    │
                  │      report_finding + load_skill             │
                  │    engine.New + engine.Run(ctx, initial)     │
                  └──────────────────────────────────────────────┘
                                       │
                       ┌───────────────┴───────────────┐
                       ▼                               ▼
              ┌────────────────┐              ┌─────────────────┐
              │ provider       │  multi-turn  │ tool registry   │
              │ (codex /       │◄────────────►│ bash, read,     │
              │  anthropic /   │   tool calls │ write, edit,    │
              │  openai / …)   │              │ ls, grep, glob, │
              └────────────────┘              │ web_fetch,      │
                                              │ load_skill,     │
                                              │ halt_scan,      │
                                              │ report_finding  │
                                              └─────────────────┘
                                       │
                                       ▼
                  ┌──────────────────────────────────────────────┐
                  │ 4. Halt → finalize                           │
                  │    halt_scan called OR ctx done OR max turns │
                  │    UPDATE AgenticScan: status, duration,     │
                  │    finding_count, error_message              │
                  │    print summary, remove run.pid             │
                  └──────────────────────────────────────────────┘

​
CLI

# Basic autonomous scan
vigolium agent autopilot -t https://example.com

# With source code (auto-runs vigolium-audit first)
vigolium agent autopilot -t http://localhost:3000 --source ~/projects/my-app

# Tighter scope with intensity preset
vigolium agent autopilot -t https://example.com --intensity quick

# Deep pentest with browser-assisted auth
vigolium agent autopilot -t https://app.example.com --intensity deep \
  --browser --credentials "admin/admin123"

# Focus a specific area
vigolium agent autopilot -t https://api.example.com --focus "auth bypass"

# Pipe a curl command — target auto-derived
echo "curl -X POST https://example.com/api/login -d '{\"user\":\"admin\"}'" \
  | vigolium agent autopilot

# Raw HTTP / Burp pair input
vigolium agent autopilot --input "POST /api/search HTTP/1.1\r\nHost: example.com\r\n\r\nq=test"

# Source-aware on changed files only
vigolium agent autopilot -t https://example.com --source ./app \
  --diff main...feature/payments

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

# Use a different olium provider
vigolium agent autopilot -t https://example.com \
  --provider anthropic-api-key --model claude-opus-4-7

# Natural-language prompt (parsed by AI to extract target/source/focus)
vigolium agent autopilot "scan VAmPI source at ~/src/VAmPI on localhost:3005"

# Dry-run: preview the rendered system prompt
vigolium agent autopilot -t https://example.com --dry-run

# # CI scan with quick intensity
vigolium agent autopilot -t https://staging.example.com \
  --intensity quick --upload-results

​
Key flags

FlagDefaultDescription
-t, --target,Target URL (derived from --input if omitted)
--input,Raw input (curl, raw HTTP, Burp XML, base64, URL). Reads stdin if piped
--record-uuid,Use an HTTP record from the database as the seed input
--source,Path to application source code (or git URL, auto-cloned). Auto-runs vigolium-audit.
--files,Specific files to include (relative to --source)
--focus,Focus area hint (e.g. "auth bypass", "API injection")
--instruction / --instruction-file,Custom instruction appended to prompt
--intensitybalancedPreset bundle: quick / balanced / deep. Sets the command budget (quick=150, balanced=500, deep=1500 turns), audit mode, browser, and pre-scan strategy
--auditlite (with --source)Vigolium-audit mode: lite / balanced / deep / mock / off
--browserfalseEnable agent-browser for browser-based interactions
--credentials,Credentials for auth preflight (e.g. "admin/admin123")
--auth-requiredfalseRequire auth/session preparation before the operator starts
--requires-browserfalseRequire browser-assisted auth instead of HTTP-only preflight
--browser-start-url,Explicit browser/login start URL
--focus-routes,Protected/browser-focused routes to prioritize
--diff,Focus on changed code (PR URL, main...branch, HEAD~N)
--last-commits,Shorthand for --diff HEAD~N
--max-duration6hWall-clock cap (intensity preset sets this — quick=1h, balanced=6h, deep=12h)
--triagefalseRun an AI triage pass over findings after the scan (confirm real issues vs false positives)
--skill,Force-load these skills by name, bypassing the pre-flight selection (repeatable or comma-separated)
--skill-tag,Force-load every skill carrying one of these tags (e.g. xss,idor)
--no-skill-filterfalseLoad the full skill set; skip the pre-flight skill selection
--db-isolatefalseScan into a private temporary database, then merge results into --db at the end (lets parallel runs share one DB; SQLite only)
--plan-file,Plan file mixing free-text guidance + raw HTTP request(s); owns the instruction + seed input (mutually exclusive with --input/--instruction/--instruction-file)
--piolium,Run piolium audit instead of vigolium-audit when --source is set (lite/balanced/deep/longshot/…); empty auto-picks piolium when pi is installed
--no-prescanfalseSkip the native pre-scan that seeds http_records before the operator (target-only runs; no-op with --source)
--upload-resultsfalseUpload session bundle to cloud storage on completion
--provider(config)Olium provider override
--model(config)Model id override
--oauth-cred / --oauth-token / --llm-api-key(config)Provider credential overrides
--system,Extra text appended to the built-in system prompt
--dry-runfalseRender prompt without launching agent
--show-promptfalsePrint rendered prompt to stderr before executing

​
API

POST /api/agent/run/autopilot

{
  "target": "https://example.com",
  "source": "/home/user/src/my-app",
  "focus": "API injection",
  "intensity": "balanced",
  "audit": "balanced",
  "max_commands": 500,
  "max_duration": "6h",
  "browser": false,
  "diff": "main...feature/payments",
  "stream": true
}
EffectiveSourcePath() accepts either source or the legacy repo_path JSON field. The server resolves provider/model from agent.olium.* by default; pass api_key, oauth_token, oauth_cred_file, or oauth_cred_json on the same request to override per call. Returns 202 Accepted with {agentic_scan_uuid, status}. Set stream: true for an SSE response.

​
What the agent actually has access to

The autopilot is not restricted to the vigolium CLI. The engine ships a generic agentic toolset; security-specific behavior comes from the system prompt and skills, not from the tool surface itself.
ToolNotes
bashUnsandboxed shell. Catastrophic patterns (e.g. rm -rf /) hard-rejected.
read_fileRead-only. Parallelizable.
write_fileSide-effect; serial only.
edit_fileSide-effect; serial only.
lsParallelizable.
grepParallelizable.
globParallelizable.
web_fetchParallelizable.
load_skillPulls a skill body by name (skills are indexed in the system prompt).
halt_scanAutopilot-only. Sets HaltSignal, engine exits naturally next turn.
report_findingAutopilot-only. Writes a Finding row scoped to the AgenticScan UUID.
The model decides when to invoke vigolium scan-url, vigolium finding, etc., those are shell commands, not first-class tools. The agent runs them via bash if it judges them useful.

​
Provider selection

olium.ResolveProvider picks the backend in this order:
  1. CLI override (--provider)
  2. Config file (agent.olium.provider in vigolium-configs.yaml)
  3. Default → openai-compatible with gemma4:latest (a local Ollama endpoint)
Supported provider IDs:
ProviderTypical modelCredential
openai-codex-oauthgpt-5.5OAuth cred file (--oauth-cred / agent.olium.oauth_cred_path)
anthropic-api-keyclaude-opus-4-7--llm-api-key / $ANTHROPIC_API_KEY
anthropic-oauthclaude-opus-4-7Bearer token from claude setup-token (--oauth-token / $ANTHROPIC_API_KEY)
openai-api-keygpt-5.5--llm-api-key / $OPENAI_API_KEY
anthropic-cliclaude-opus-4-7The local claude binary on $PATH
anthropic-vertexclaude-opus-4-6GCP service-account JSON + project/location
google-vertexgemini-2.5-proSame GCP creds; routes gemini-* models
openai-compatiblegemma4:latestcustom_provider.base_url (Ollama, OpenRouter, LM Studio, vLLM, …); api_key optional
Prompt caching (EnablePromptCache: true) is set on the engine; only the Anthropic providers and the Codex OAuth provider actually emit cache markers — openai-compatible (including Ollama) and openai-api-key ignore them.

​
Intensity presets

--intensity bundles several settings; explicit flags always override.
PresetMaxCommandsTimeoutVigolium-audit modeBrowser
quick1501hliteon
balanced (default)5006hbalancedon
deep150012hdeepon
MaxCommands is the autopilot’s own turn cap (the agent’s DefaultAutopilotMaxTurns is 200; intensity overrides it). When the cap is hit the run ends with an error event — the model didn’t get to halt cleanly. agent.olium.max_turns applies to the shorter, non-autopilot engine uses (swarm phases, source analysis, query), not to autopilot.

​
Halt conditions

The autopilot exits in one of four ways:
  1. Natural halt: model calls halt_scan. The current turn is allowed to finish; the engine then sees no further tool calls on the next turn and emits EventRunDone. Result.Halted=true, HaltReason populated.
  2. Quiet halt: model finishes a turn with no tool calls and no halt_scan. Treated as a natural stop.
  3. Max turns: turn count hits MaxCommands. Engine emits an EventError; autopilot returns a non-nil error.
  4. Context cancelled: timeout or SIGINT/SIGTERM. Engine teardown cancels in-flight tools.
A separate finding rate-limit lives inside report_finding:
  • soft warning at 50 findings (still saved)
  • hard cap at 200 (rejected with an IsError result that nudges the model toward halt_scan)

​
Findings persistence

Every successful report_finding call writes a row via repo.SaveFindingDirect. Key fields:
  • ProjectUUID, ScanUUID, AgenticScanUUID, propagate the project/scan scope so vigolium finding and vigolium agent sessions can join back.
  • ModuleID = "olium-autopilot", ModuleType = "ai-agent", FindingSource = "autopilot", distinguishes agent-originated findings from scanner-module findings.
  • FindingHash: SHA-256 over (title, severity, source_file, url, description-fingerprint), or over an explicit dedup_key if the model supplies one. The DB’s ON CONFLICT handler squashes duplicates.
Because the autopilot writes findings as it confirms them, partial results survive a crash or timeout, the parent AgenticScan row is just updated to status=failed with the error message, but everything saved before that point stays in the DB.

​
Session artifacts

For each run, autopilot creates a UUID-named directory under agent.sessions_dir (default ~/.vigolium/agent-sessions/): 
~/.vigolium/agent-sessions/{run-uuid}/
  ├── run.pid          # pgid + start time; cleared on exit
  ├── runtime.log      # tee of stdout (assistant text stream)
  └── vigolium-audit/  # vigolium-audit subprocess output (when --source is provided)
The run UUID matches the AgenticScan.uuid row, so vigolium agent sessions and vigolium log <uuid> both work without extra plumbing. Stale dirs older than 48h are swept on startup; orphan PID files (from SIGKILL’d runs) are cleared via agent.CleanupOrphanedProcesses.

​
Source-aware mode

When --source is set, three things change:
  1. Source resolution: accepts local paths, git URLs (cloned to a temp dir), --diff PR-url|ref...ref|HEAD~N, and --last-commits N. The agent gets a local path and (optionally) a list of changed files.
  2. Initial prompt mode hint: the prompt switches between blackbox (“probe the live target”), whitebox (“navigate the source tree”), or a greybox blend (“read the code to find what’s risky, then probe”).
  3. Skill scope: embedded skills + ~/.vigolium/skills/ are indexed in the system prompt; scan-specific skills like audit-auth and triage-finding are loadable via load_skill.
Vigolium-audit also runs first (foreground) when --source is set, freezing its findings into vigolium-audit/ for the operator to consult.

​
Multi-app fan-out

When the positional prompt parses to multiple apps (vigolium agent autopilot "scan source at ~/src/A, ~/src/B"), the package-level autopilot flags are snapshotted and reapplied per app, then runAutopilotOlium is invoked sequentially for each. Each app gets its own session dir, AgenticScan row, and provider session. A single-app prompt re-enters runAgentAutopilot directly with the parsed flags, same code path as a flag-driven invocation.

​
REST API workflow

POST /api/agent/run/autopilot   # async kickoff, returns run UUID
GET  /api/agent/status/list     # list active/recent runs
GET  /api/agent/status/:id      # poll a single run
GET  /api/agent/sessions/:id/logs  # tail runtime.log (SSE supported)
GET  /api/agent/sessions/:id/artifacts  # browse session directory
The HTTP request body mirrors the CLI flags. The handler resolves provider/source the same way the CLI does, then enters autopilot.Run on a goroutine; the run UUID is returned immediately.

​
TL;DR

Autopilot is a single LLM agent on a leash made of MaxCommands turns and Timeout wall-clock. It gets shell, files, and the web; vigolium-specific behavior is encoded entirely in the system prompt, two custom tools (halt_scan, report_finding), and the optional skills under ~/.vigolium/skills/. Findings are written as it goes; the run ends when the model halts itself, hits the turn cap, or gets cancelled.