Skip to main content
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 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

ModeBinaryDescription
CLI Scannervigolium scanRun scans directly from the command line against targets, input files (OpenAPI, Postman, Burp, cURL, HAR), or source code paths.
Server Modevigolium serverLaunch a REST API server with Swagger UI. Ingest traffic, trigger scans, query findings, and run agent sessions over HTTP.
Ingestor Clientvigolium ingestLightweight 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
PhasePurpose
HeuristicsLightweight fingerprinting and technology detection
External HarvestingWayback Machine and other passive source enumeration
SpideringActive crawling, JS analysis, link and form extraction (alias: spitolas)
DiscoveryEndpoint and content discovery via wordlists (aliases: deparos, discover)
KnownIssueScanNuclei templates and Kingfisher secret detection against discovered paths
DynamicAssessmentCore 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:
StrategyBehavior
LiteFast surface-level scan; skips heavy crawling and discovery
BalancedDefault. Runs all phases with sensible limits
DeepExhaustive 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 / …).
ModeCommandDescription
Queryvigolium agent querySingle-shot prompt execution. Good for code review, endpoint discovery, secret detection. No network scanning.
Autopilotvigolium agent autopilotOne 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.
Swarmvigolium agent swarmMulti-phase pipeline where native Go handles heavy lifting and AI intervenes at checkpoints, planning attacks, triaging results, and generating custom JS scanner extensions.
Auditvigolium agent auditUnified 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.
Pioliumvigolium agent audit --driver=pioliumDirect access to the standalone piolium audit harness (requires a separate ~/.piolium install).
Oliumvigolium 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:
SubsystemDocumentCovers
Native scan pipelineNative ScanCLI entry → input parsing → executor → modules → results → DB, all 12 stages
Agentic scan engineAgentic ScanSubcommands, orchestrators, the engine seam, olium runtime, providers
Data & persistenceData & Storageproject_uuid multi-tenancy, repository pattern, data models, cloud storage
Server & APIServer & APIFiber server, traffic ingestion, REST surface, agent run API

​
Where to Go Next

I want to…Go to
Get up and running quicklyQuickstart
Choose a scanning strategyStrategies
Learn about individual scan phasesPhases (discovery, spidering, audit, extension, known-issue-scan)
Explore agentic scanningAgent Mode
Use Autopilot / Swarm modeAutopilot · Swarm
Use the olium engine directly (TUI / headless)Olium
Run Vigolium as a serverServer Mode
Configure scans and settingsConfiguration
Format and export resultsOutput & Reporting
Write custom JS extensionsWriting Extensions
Browse the REST APIAPI Overview
Manage projects (multi-tenancy)Projects API
Use cloud storage (gs:// URLs, bundles, uploads)Storage API
Debug issuesFAQ