> ## 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.
# Architecture Overview
> The Vigolium system at a glance, operating modes, the two scanning paradigms, and how the pieces fit together.
This is the entry point to Vigolium's architecture documentation. This page covers the system at a glance, operating modes, the two scanning paradigms, and how the pieces fit together. The sibling documents drill into each subsystem.
The deterministic Go scan pipeline, end to end.
The AI agent engine, orchestrators, and olium runtime.
Multi-tenancy, the database model, and cloud storage.
The REST server, traffic ingestion, and the API surface.
Vigolium is a high-fidelity web vulnerability scanner written in Go. It combines deterministic, module-based scanning with AI-driven agentic analysis to provide broad and deep coverage of web application security issues. The scanner ships 313 modules (198 active, 115 passive) covering injection flaws, misconfigurations, information disclosure, authentication issues, and more.
Vigolium can operate as a CLI tool for one-off scans, as a persistent REST API server that ingests live traffic, or as a standalone ingestor client that forwards traffic to a running server. All scan data is project-scoped for multi-tenancy support. Module: `github.com/vigolium/vigolium`, requires Go 1.26+.
## Operating Modes
| Mode | Binary | Description |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **CLI Scanner** | `vigolium scan` | Run scans directly from the command line against targets, input files (OpenAPI, Postman, Burp, cURL, HAR), or source code paths. |
| **Server Mode** | `vigolium server` | Launch a REST API server with Swagger UI. Ingest traffic, trigger scans, query findings, and run agent sessions over HTTP. |
| **Ingestor Client** | `vigolium ingest` | Lightweight client that captures and forwards HTTP traffic to a running Vigolium server for analysis. |
## Scanning Paradigms
### Native Scan
The native scan pipeline is fully deterministic, pure Go, no AI involvement. Requests flow through a fixed sequence of phases, each handling a distinct stage of reconnaissance or testing.
**Phases (in order):**
```
Heuristics -> External Harvesting -> Spidering -> Discovery -> KnownIssueScan -> DynamicAssessment
```
| Phase | Purpose |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Heuristics | Lightweight fingerprinting and technology detection |
| External Harvesting | Wayback Machine and other passive source enumeration |
| Spidering | Active crawling, JS analysis, link and form extraction (alias: `spitolas`) |
| Discovery | Endpoint and content discovery via wordlists (aliases: `deparos`, `discover`) |
| KnownIssueScan | Nuclei templates and Kingfisher secret detection against discovered paths |
| DynamicAssessment | Core vulnerability testing, injection, XSS, SSRF, etc.; user-supplied JS/YAML extensions also dispatch here (CLI aliases: `audit`, `dast`, `assessment`) |
**Strategies** control which phases run and how aggressively:
| Strategy | Behavior |
| -------- | ---------------------------------------------------------------------------------- |
| Lite | Fast surface-level scan; skips heavy crawling and discovery |
| Balanced | Default. Runs all phases with sensible limits |
| Deep | Exhaustive scanning with higher limits, broader wordlists, and external harvesting |
### Agentic Scan
Agentic scanning uses AI agents to drive or augment the scanning process. Invoked via `vigolium agent `. All AI dispatch runs through the in-process **olium** engine (`pkg/olium/`); eleven providers are supported: `openai-codex-oauth`, `anthropic-api-key`, `anthropic-oauth`, `openai-api-key`, `openai-responses`, `anthropic-cli`, `anthropic-claude-sdk-bridge`, `anthropic-compatible`, `anthropic-vertex`, `google-vertex`, and `openai-compatible` (Ollama / OpenRouter / LM Studio / vLLM / …).
| Mode | Command | Description |
| ------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query** | `vigolium agent query` | Single-shot prompt execution. Good for code review, endpoint discovery, secret detection. No network scanning. |
| **Autopilot** | `vigolium agent autopilot` | One long-running LLM session with full bash/file/web tools plus `report_finding` and `halt_scan`. The agent decides what to scan, runs scans, inspects results, and iterates until it halts. |
| **Swarm** | `vigolium agent swarm` | Multi-phase pipeline where native Go handles heavy lifting and AI intervenes at checkpoints, planning attacks, triaging results, and generating custom JS scanner extensions. |
| **Audit** | `vigolium agent audit` | Unified driver dispatcher. `--driver auto\|both\|audit\|piolium` drives the embedded vigolium-audit harness, the standalone piolium harness, or both side-by-side under one parent scan. |
| **Piolium** | `vigolium agent audit --driver=piolium` | Direct access to the standalone piolium audit harness (requires a separate `~/.piolium` install). |
| **Olium** | `vigolium agent olium` (or `vigolium ol`) | Direct interactive TUI access to the olium engine. Use `-p` for a non-interactive one-shot prompt. |
All agent modes support `--source` for source-aware analysis and store session artifacts (plans, extensions, output) in a configurable sessions directory.
## Architecture at a Glance
```
+-----------------------+
| Input Sources |
| curl / OpenAPI / Burp |
| HAR / Postman / URL |
+-----------------------+
|
+-----------------+-----------------+
| |
vigolium scan vigolium server
| |
v v
+--------------+ +------------------+
| Scope Filter | | REST API (Fiber) |
+--------------+ +------------------+
| |
+-----------------+-----------------+
|
+-----------------+-----------------+
| |
Native Scan Agentic Scan
| |
+--------------------+ +------------------+
| Executor (Workers) | | Agent Engine |
| Rate Limiter | | Prompt Templates |
+--------------------+ +------------------+
| |
+---------------------+ +--------------------+
| Module Registry | | Olium Providers |
| 198 Active Modules | | openai-codex-oauth |
| 115 Passive Modules | | anthropic-api-key |
+---------------------+ | anthropic-oauth |
| | openai-api-key |
| | openai-responses |
| | anthropic-cli |
| | anthropic-compat. |
| | claude-sdk-bridge |
| +--------------------+
| |
+-----------------+-----------------+
|
v
+------------------------+
| Results Store |
| SQLite / PostgreSQL |
| HTML / JSONL / Console |
+------------------------+
```
## Architecture Documents
Deep-dives into each subsystem live alongside this page:
| Subsystem | Document | Covers |
| -------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| Native scan pipeline | [Native Scan](/architecture/native-scan) | CLI entry → input parsing → executor → modules → results → DB, all 12 stages |
| Agentic scan engine | [Agentic Scan](/architecture/agentic-scan) | Subcommands, orchestrators, the engine seam, olium runtime, providers |
| Data & persistence | [Data & Storage](/architecture/data-and-storage) | `project_uuid` multi-tenancy, repository pattern, data models, cloud storage |
| Server & API | [Server & API](/architecture/server-and-api) | Fiber server, traffic ingestion, REST surface, agent run API |
## Where to Go Next
| I want to... | Go to |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Get up and running quickly | [Quickstart](/getting-started/quickstart) |
| Choose a scanning strategy | [Strategies](/native-scan/strategies) |
| Learn about individual scan phases | [Phases](/native-scan/phases/discovery) (discovery, spidering, audit, extension, known-issue-scan) |
| Explore agentic scanning | [Agent Mode](/agentic-scan/agent-mode) |
| Use Autopilot / Swarm mode | [Autopilot](/agentic-scan/autopilot) · [Swarm](/agentic-scan/swarm) |
| Use the olium engine directly (TUI / headless) | [Olium](/agentic-scan/olium) |
| Run Vigolium as a server | [Server Mode](/server-mode/running-the-server) |
| Configure scans and settings | [Configuration](/getting-started/configuration) |
| Format and export results | [Output & Reporting](/getting-started/output-and-reporting) |
| Write custom JS extensions | [Writing Extensions](/customization/writing-extensions) |
| Browse the REST API | [API Overview](/api-overview) |
| Manage projects (multi-tenancy) | [Projects API](/api-references/projects) |
| Use cloud storage (gs\:// URLs, bundles, uploads) | [Storage API](/api-references/storage) |
| Debug issues | [FAQ](/others/faq) |