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.
Config File Location
The main config file is ~/.vigolium/vigolium-configs.yaml. It is created automatically on first run with sensible defaults.
Vigolium searches for configuration in this order:
- Path specified via the
--config flag (error if not found)
~/.vigolium/vigolium-configs.yaml./vigolium-configs.yaml (current working directory)
If no config file is found, built-in defaults are used.
Config Precedence
Settings are resolved from highest to lowest precedence:
- CLI flags -e.g.
--concurrency 100, --rate-limit 50
- Environment variables -e.g.
VIGOLIUM_API_KEY, VIGOLIUM_PROJECT
- Scanning profile -loaded via
--scanning-profile <name> (from ~/.vigolium/profiles/)
- Project-level config -per-project overlay at
~/.vigolium/projects/<uuid>/config.yaml
- Main config file -
~/.vigolium/vigolium-configs.yaml
- Built-in defaults -hardcoded in the Go source
Higher-precedence sources override lower ones. Within the config file, environment variables can be referenced using ${VAR} or $VAR syntax and are expanded at load time.
Environment Variables
| Variable | Purpose |
|---|
VIGOLIUM_API_KEY | API key for the REST server and ingestor client authentication |
VIGOLIUM_PROJECT | Default project UUID for CLI operations (equivalent to --project) |
VIGOLIUM_PROXY | HTTP/SOCKS proxy URL, used when --proxy is not set |
VIGOLIUM_HOME | Base directory for Vigolium data (used by the installer; defaults to ~/.vigolium) |
vigolium-configs.yaml:
database:
postgres:
password: ${VIGOLIUM_DB_PASSWORD}
CLI Config Overrides
Use vigolium config set to update individual config values using dot-notation keys:
vigolium config set scanning_pace.concurrency 100
vigolium config set database.driver postgres
vigolium config set notify.enabled true
vigolium config set notify.severities high,critical
vigolium config set server.service_port 8080
Config Sections
scanning_strategy
Controls which scan phases run for each strategy preset.
scanning_strategy:
default_strategy: balanced # lite | balanced | deep
heuristics_check: basic
scanning_profile: "" # name of a profile to auto-load
profiles_dir: ~/.vigolium/profiles/
session:
session_dir: ~/.vigolium/sessions/
use_in_discovery: true # apply session headers during discovery/spidering
compare_enabled: true # cross-session IDOR/BOLA replay in dynamic-assessment
reauth_interval: "" # e.g. "15m" to refresh tokens periodically
reauth_on_status: [] # e.g. [401, 403]
validate_url: "" # URL to GET after login to verify credentials
# Phase toggles per strategy (canonical names):
balanced:
discovery: true
spidering: true
known_issue_scan: true
dynamic-assessment: true
external_harvesting: false
| Phase | lite | balanced | deep |
|---|
| external_harvesting | - | - | yes |
| discovery | - | yes | yes |
| spidering | - | yes | yes |
| known_issue_scan | - | yes | yes |
| dynamic-assessment | yes | yes | yes |
Phase aliases: dynamic-assessment is the canonical name for active/passive vulnerability scanning. audit, dast, and assessment are accepted aliases on --only / --skip flags. discovery accepts deparos / discover; spidering accepts spitolas; extension accepts ext.
For source-aware whitebox analysis, use vigolium agent swarm --source <path> or vigolium agent archon --source <path> instead of a native scan strategy. See Agent Mode.
scanning_pace
Centralized speed control. Common values serve as baselines; per-phase subsections override them.
scanning_pace:
concurrency: 50 # global worker count
rate_limit: 100 # max requests/sec across all hosts
max_per_host: 10 # max concurrent requests per host
max_duration: 2h # global time cap for a scan phase
# Per-phase overrides (zero = inherit from common):
discovery:
concurrency: 0
rate_limit: 0
concurrency_factor: 0 # multiplier on common concurrency
duration_factor: 0 # multiplier on common max_duration
spidering:
duration_factor: 0.15 # e.g. 2h * 0.15 = 18m
known_issue_scan:
duration_factor: 3.0
external_harvester:
duration_factor: 0.2
audit:
duration_factor: 1.0
parallel_passive: true # run passive modules in parallel
feedback_drain_timeout: 500ms # wait for feedback loop items
discovery
Content discovery (directory/file brute-forcing).
discovery:
mode: files_and_dirs # files_and_dirs | files_only | dirs_only
scope_mode: subdomain # any | subdomain | exact
save_response_body: true
enable_malformed_path_probe: false
enrich_targets: false # feed paths from spidering/harvest into discovery
recursion:
enabled: true
max_depth: 5
wordlists:
short_file_path: "" # custom wordlist paths
long_file_path: ""
short_dir_path: ""
long_dir_path: ""
fuzz_wordlist_path: ""
use_observed_names: true
use_observed_paths: true
use_observed_files: true
enable_numeric_fuzzing: false
extensions:
test_custom: true
custom_list: []
test_observed: true
test_backup_extensions: true
backup_extensions: []
test_no_extension: true
engine:
case_sensitivity: auto_detect # auto_detect | sensitive | insensitive
timeout: 10s # per-request timeout (1s-300s)
custom_headers: {}
enable_cookie_jar: false
max_consecutive_errors: 0
max_consecutive_waf_blocks: 0
observed_max_items: 4000
disable_kingfisher: false
spidering
Browser-based crawling.
spidering:
max_depth: 0 # 0 = unlimited
max_states: 0 # 0 = unlimited
max_duration: 30m
max_consecutive_fails: 100
headless: true
browser_count: 1
strategy: adaptive # normal | random | oldest_first | shallow_first | adaptive
include_response_body: true
browser_engine: chromium # chromium | ungoogled | fingerprint
no_cdp: false # disable CDP event listener detection
no_forms: false # disable automatic form filling
# AI pilot mode (agent-controlled browser):
pilot_mode: false
pilot_auto_register: true
pilot_username: ""
pilot_password: ""
pilot_screenshot: true
pilot_max_retries: 2
pilot_stall_timeout: 7m
dynamic-assessment
Controls which scanner modules run and JavaScript extension settings. (Formerly audit.)
dynamic-assessment:
max_feedback_rounds: 1 # rescan rounds for newly-discovered URLs
max_findings_per_module: 15 # 0 = unlimited
enabled_modules:
active_modules: ["all"] # ["all"] or list of module IDs
passive_modules: ["all"]
extensions:
enabled: false
extension_dir: ~/.vigolium/extensions/
custom_dir: [] # additional script paths
variables: {} # key-value pairs passed to scripts
limits:
timeout: 30s
max_memory_mb: 128
scope
Defines what is in scope for scanning. Exclude rules take priority over include rules.
scope:
applied_on_ingest: false # enforce scope during ingestion (not just scanning)
cli_origin_mode: relaxed # relaxed | all | balanced | strict
ignore_static_file: true # skip images, fonts, video, audio, etc.
max_request_body_size: 1048576 # 1 MB
max_response_body_size: 524288000 # 500 MB
body_size_exceeded_action: truncate # truncate | drop | skip-scan
host:
include: ["*"]
exclude: []
path:
include: ["*"]
exclude: []
status_code:
include: ["*"]
exclude: []
request_content_type:
include: ["*"]
exclude: []
response_content_type:
include: ["*"]
exclude: []
request_string:
include: []
exclude: []
response_string:
include: []
exclude: []
server
REST API server settings.
server:
auth_api_key: "" # auto-generated if empty; also set via VIGOLIUM_API_KEY
service_port: 9002
ingest_proxy_port: 0 # 0 = disabled
cors_allowed_origins: reflect-origin
enable_metrics: true
agent_heavy_max: 5 # max concurrent autopilot/swarm runs via API
agent_light_max: 10 # max concurrent query/chat runs via API
agent_queue_timeout: 30s # wait for an agent slot before returning 429
license: "" # optional license tag surfaced in /server-info
agent
AI agent integration. Every agent invocation is dispatched through the in-process olium runtime — there are no subprocess SDK or ACP backends.
agent:
default_agent: olium
templates_dir: ~/.vigolium/prompts/
sessions_dir: ~/.vigolium/agent-sessions/
stream: true # real-time output streaming
# Olium engine — used by every agent subcommand
olium:
provider: codex-oauth # codex-oauth | anthropic-api-key | claude-oauth | openai-api-key | claude-code-cli
model: gpt-5.5 # empty = provider default
oauth_cred_path: ~/.codex/auth.json # codex-oauth provider
oauth_token: "" # claude-oauth bearer token (from `claude setup-token`); supports ${ENV_VAR}
llm_api_key: "" # for anthropic-api-key / openai-api-key; supports ${ENV_VAR}; falls back to provider env
reasoning_effort: medium # minimal | low | medium | high | xhigh (codex)
system_prompt: "" # override built-in olium system prompt
max_tokens: 1000000
temperature: 0.0
max_turns: 32 # tool-loop iteration cap
cache_size: 1024 # LRU entries; 0 disables
max_concurrent: 4 # global cap on simultaneous in-flight provider calls
call_timeout_sec: 600 # per-call deadline; -1 = no enforced timeout
# LLM config for JavaScript extension agent API (vigolium.agent.* in extensions)
llm:
provider: anthropic # anthropic | openai
model: claude-sonnet-4-20250514
api_key: "" # inline key (prefer api_key_env)
api_key_env: "" # env var name (default: ANTHROPIC_API_KEY or OPENAI_API_KEY)
base_url: "" # custom endpoint for OpenAI-compatible providers
max_tokens: 4096
temperature: 0.0
cache_size: 256 # LRU entries (0 = disabled)
cache_ttl: 300 # seconds
# DB context enrichment limits for swarm/autopilot
context_limits:
max_findings: 50
max_endpoints: 100
max_high_risk: 20
min_risk_score: 50
# Autopilot guardrails (SDK-era; mostly informational under olium)
guardrails:
log_commands: false
max_turns: 0 # 0 = auto (MaxCommands * 3)
disallowed_tools: []
# Optional agent-browser integration (Bash tool can drive a real Chromium for auth-walled flows)
browser:
enable: true
binary_path: agent-browser # default: looked up on $PATH
# Archon-audit integration
archon:
enable: false # auto-enabled by --archon flag
mode: lite # lite | balanced | deep | mock
platform: claude # claude | codex | opencode
plugin_dir: "" # default: ~/.vigolium/archon-audit/
sync_interval: 30 # seconds between state syncs
| Provider | Default model | Credential source |
|---|
codex-oauth | gpt-5.5 | oauth_cred_path (~/.codex/auth.json) |
anthropic-api-key | claude-opus-4-7 | llm_api_key or $ANTHROPIC_API_KEY |
claude-oauth | claude-opus-4-7 | oauth_token (from claude setup-token); falls back to $ANTHROPIC_API_KEY |
openai-api-key | gpt-5.5 | llm_api_key or $OPENAI_API_KEY |
claude-code-cli | claude-opus-4-7 | local claude binary on $PATH |
--provider, --model, --oauth-cred, --oauth-token, --llm-api-key override these per-invocation. The REST API does not mirror these overrides — server-side workloads use the YAML config exclusively. See Olium Agent for full provider details.
database
Storage backend. SQLite is the default; PostgreSQL is supported for multi-user deployments.
database:
enabled: true
driver: sqlite # sqlite | postgres
sqlite:
path: ~/.vigolium/database-vgnm.sqlite
busy_timeout: 15000
journal_mode: WAL # DELETE | TRUNCATE | PERSIST | MEMORY | WAL | OFF
synchronous: NORMAL # OFF | NORMAL | FULL | EXTRA
cache_size: 10000
postgres:
host: localhost
port: 5432
user: vigolium
password: ""
database: vigolium
sslmode: disable
max_open_conns: 25
max_idle_conns: 5
conn_max_lifetime: 5m
known_issue_scan
Known-issue scanning powered by the Nuclei template engine.
known_issue_scan:
tags: [] # nuclei template tags (empty = all)
exclude_tags: [dos]
severities: [] # filter: critical, high, medium, low, info
templates_dir: "" # custom templates path
enrich_targets: true # feed discovered paths into known-issue scan
mutation_strategy
Controls how parameter values are mutated during active scanning.
mutation_strategy:
default_modes: [append]
value_aware:
enabled: true
max_per_intent: 5
default_intents: [neighbor, boundary, escalation]
enum_mappings: {} # custom enum escalation pairs
param_synonyms: {} # custom param name synonyms
field_type_defaults:
email: ["[email protected]", "[email protected]"]
uuid: ["550e8400-e29b-41d4-a716-446655440000"]
integer: ["1", "100", "999"]
# ... (all standard types have built-in defaults)
external_harvester
Pre-scan intelligence gathering from public data sources.
external_harvester:
sources: [wayback, commoncrawl, alienvault]
# Additional sources: urlscan, virustotal (require API keys)
api_keys:
urlscan: ""
virustotal: ""
oast
Out-of-Band Application Security Testing via interactsh callbacks.
oast:
enabled: true
server_url: oast.pro
token: "" # optional auth token
poll_interval: 5 # seconds
grace_period: 10 # seconds after scan for late callbacks
oast_url: "" # fixed callback URL (empty = auto-generate)
blind_xss_src: "" # JS script src for blind XSS payloads
enabled_blind_xss: false
source_aware
Storage location for cloned source repositories. Used when --source receives a git URL (autopilot, swarm, archon, query). Static analysis tooling (ast-grep, semgrep, etc.) has been removed — for AI-driven code audit, use vigolium agent archon or vigolium agent swarm --source --code-audit.
source_aware:
storage_path: ~/.vigolium/source-aware/ # base directory for cloned repos
clone_depth: 1 # `git clone --depth` (1 = shallow)
storage
Cloud storage integration for source code upload/download and scan result archival. Uses an S3-compatible API — supports GCS (via HMAC), AWS S3, and MinIO.
storage:
enabled: false
driver: gcs # gcs | s3 | minio
endpoint: "" # auto for gcs/s3; required for minio
bucket: ${VIGOLIUM_STORAGE_BUCKET_NAME}
region: asia-southeast1
access_key: ${VIGOLIUM_STORAGE_ACCESS_KEY}
secret_key: ${VIGOLIUM_STORAGE_SECRET_KEY}
use_ssl: true
path_style: false # required for some MinIO deployments
--upload-results archive their session bundle to <bucket>/<project-uuid>/agentic-scans/<run-uuid>/results.tar.gz. Native scans use <bucket>/<project-uuid>/native-scans/<scan-uuid>/results.tar.gz. See Storage API for upload/download endpoints.
notify
Real-time finding notifications via Telegram or Discord.
notify:
enabled: false
severities: [high, critical, medium]
telegram:
bot_token: ""
chat_id: ""
discord:
webhook_url: ""
Scanning Profiles
Scanning profiles are YAML files stored in ~/.vigolium/profiles/ that override subsets of the main config. They can tune any combination of: scanning_strategy, scanning_pace, discovery, spidering, known_issue_scan, audit, external_harvester, mutation_strategy, and scope.
Apply a profile with:
vigolium scan --scanning-profile aggressive
~/.vigolium/profiles/aggressive.yaml and overlays it onto the active config. Only non-zero fields in the profile override the base config; unspecified fields are left unchanged.
Built-in profiles are bundled in public/presets/profiles/. See native-scan/scanning-modes-overview for details.
Project-Level Config
Each project can have its own config overlay at ~/.vigolium/projects/<uuid>/config.yaml. This uses the same format as scanning profiles and is automatically applied when the project is active.
Manage project configs with:
vigolium project config set scanning_pace.concurrency 200
vigolium project config show
