Architecture Overview

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.

Native Scan

The deterministic Go scan pipeline, end to end.

Agentic Scan

The AI agent engine, orchestrators, and olium runtime.

Data & Storage

Multi-tenancy, the database model, and cloud storage.

Server & API

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 317 modules (201 active, 116 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 <mode>. 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`	Autonomous operator with Bash/file/web/browser and first-class Vigolium tools. Legacy mode reports directly; durable modes rotate context, persist resumable state, and can verify candidates before promotion.
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    |
           | 201 Active Modules  |             | openai-codex-oauth |
           | 116 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	CLI entry → input parsing → executor → modules → results → DB, all 12 stages
Agentic scan engine	Agentic Scan	Subcommands, orchestrators, the engine seam, olium runtime, providers
Data & persistence	Data & Storage	`project_uuid` multi-tenancy, repository pattern, data models, cloud storage
Server & API	Server & 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
Choose a scanning strategy	Strategies
Learn about individual scan phases	Phases (discovery, spidering, audit, extension, known-issue-scan)
Explore agentic scanning	Agent Mode
Use Autopilot / Swarm mode	Autopilot · Swarm
Use the olium engine directly (TUI / headless)	Olium
Run Vigolium as a server	Server Mode
Configure scans and settings	Configuration
Format and export results	Output & Reporting
Write custom JS extensions	Writing Extensions
Browse the REST API	API Overview
Manage projects (multi-tenancy)	Projects API
Use cloud storage (gs:// URLs, bundles, uploads)	Storage API
Debug issues	FAQ

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Native Scan

Agentic Scan

Data & Storage

Server & API

Operating Modes

Scanning Paradigms

Native Scan

Agentic Scan

Architecture at a Glance

Architecture Documents

Where to Go Next

Native Scan

Agentic Scan

Data & Storage

Server & API

​Operating Modes

​Scanning Paradigms

​Native Scan

​Agentic Scan

​Architecture at a Glance

​Architecture Documents

​Where to Go Next

Operating Modes

Scanning Paradigms

Native Scan

Agentic Scan

Architecture at a Glance

Architecture Documents

Where to Go Next