Configuration Reference

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_UUID
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_UUID`	Default project UUID for CLI operations (equivalent to `--project-uuid`)
`VIGOLIUM_PROJECT_NAME`	Default project name for CLI operations (equivalent to `--project-name`)
`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_DB_PATH`	Default for the global `--db` flag — pins a shell to one session database

`VIGOLIUM_DB_PATH`

Set it once and every command in that shell reads and writes the same database file, without repeating --db:

export VIGOLIUM_DB_PATH=~/engagements/acme/session.sqlite

vigolium scan -t https://acme.test        # writes here
vigolium finding --min-severity high      # reads from here
vigolium fuzz -u <record-uuid>            # resolves the record from here

Each run prints a one-line notice naming the resolved database (suppressed under --silent, -j, and --ci-output-format). The variable carries one deliberate asymmetry. Reads additionally treat the file as a standalone source — project scoping is turned off, so every row in the file is listed regardless of the project_uuid it carries, exactly as -S --db <file> behaves. Writes do not: a scan into the pinned database still records its own project. This means you can point the variable at a colleague’s export and query all of it, while your own scans stay properly attributed.

An explicit --db always wins. The variable is skipped until the file exists, so the first read of a not-yet-written session doesn’t fail. And it never sets --stateless for you: on scan / scan-url / scan-request / run that flag means “scan into a throwaway temp database” and is mutually exclusive with --db — passing -S explicitly on one of those commands makes the variable a no-op.

A pinned path that exists but is unusable is now a hard error (v0.4.5), not a silent fall-through to the shared default database. Previously a bad VIGOLIUM_DB_PATH quietly redirected every command to ~/.vigolium/database-vgnm.sqlite, so a scan you believed was isolated to one engagement landed in the file every other engagement shares. If you need to confirm which store you actually got, read db_path off any -j/--json envelope or off the scan.started event.

vigolium log reads through this same path, so a pinned shell reaches that session’s log with project scoping off, exactly like finding and traffic. Any environment variable can also be interpolated inside 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

These commands modify the main config file directly. For one-off overrides during a scan, use CLI flags instead.

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

  # Alternate-port sweep on the target hosts (runs at deep intensity or with
  # --follow-subdomains; CLI override: --port-sweep-ports)
  port_sweep:
    ports: [3000, 5000, 8000, 8008, 8080, 8081, 8082, 8083, 8088, 8888, 9000, 8443, 9443]
    concurrency: 50
    dial_timeout_ms: 1500
    http_timeout_ms: 4000
    honeypot_ratio: 0.7          # drop a host when this share of swept ports answer (a port-spoofing honeypot)

  scan_logs:
    persist_logs: false          # write a per-scan session log (browse with `vigolium log`)
    sessions_dir: ~/.vigolium/native-sessions/

Available strategies and their default phases:

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 audit --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: 25          # 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
  dedup_cluster_cap: 10        # keep at most N near-identical responses per cluster (omit = 10, 0 = disabled)
  auto_fuzz_low_yield: true    # auto-enable FUZZ on the original target when spidering came up empty or hit an SSO wall (omit = on)
  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_secret_scan: false     # turn off in-process secret scanning during discovery

    prefix_breaker:                # circuit-breaker that stops recursing into trap directories
      enabled: true                # omit = on (CLI: --no-prefix-breaker)
      min_samples: 0               # 0 = engine default for each of these
      trip_ratio: 0
      prefix_segments: 0
      length_bucket: 0

  # Post-discovery cleanup of stored records: status retention + reflected-URL-robust dedup
  deparos_dedup:
    enabled: true                  # omit = on
    drop_client_errors: true       # a fuzzed path the server 4xx-rejects is not a discovered resource
    keep_one_per_host: [401, 403, 429]   # collapsed to one representative per host, not dropped
    keep_per_path: [405, 415, 422]       # every distinct path kept — each is a real endpoint, wrong method/payload
    per_path_cap: 100              # cap on distinct keep_per_path paths per (host, status); negative = unbounded
    normalize_reflected: true      # collapse records differing only by an echoed URL or per-request token

  # Targeted re-spider of rich/SPA routes discovery turned up, after dedup
  respider:
    enabled: true                  # omit = on
    max_seeds_per_host: 3
    max_seeds_total: 10
    per_seed_max_duration: 45s
    per_seed_max_states: 25
    max_depth: 3
    step_max_duration: 5m          # wall-clock cap for the whole step

  # Embedded JavaScript intelligence engine (jstangle)
  jstangle:
    enabled: true
    replay_mode: exact             # how harvested requests are reconstructed
    replay_safety: read-only       # read-only = never replay state-changing methods
    source_maps: true
    asset_graph: true              # follow imported chunks to find more endpoints
    protocol_handshake: false
    worker_count: 0                # 0 = scale to CPU count
    memory_budget_mb: 768
    cache_mb: 128
    job_timeout: 60s
    max_requests_per_file: 500
    max_asset_depth: 4
    max_assets_per_parent: 64
    max_assets_per_host: 512
    max_assets_total: 2048
    normal_input_mb: 1             # inputs above this skip the expensive passes
    max_ast_input_mb: 4
    hard_input_mb: 10              # inputs above this are skipped entirely
    max_ast_nodes: 500000
    worker_max_jobs: 100
    worker_max_rss_mb: 1024

discovery.engine.disable_kingfisher is gone — secret scanning is in-process Go now (no external kingfisher binary). The replacement key is disable_secret_scan.

`spidering`

Browser-based crawling.

spidering:
  max_depth: 6               # 0 = unlimited
  max_states: 1500           # 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
  self_register: false       # complete a public signup form and crawl as that account
  graph_output_dir: ""       # write the crawl graph here (one file per host); empty disables

  # 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

max_depth and max_states default to 6 and 1500 — they were unlimited before v0.3.8. Both bound how the crawl spends its max_duration: without a depth bound a link-dense site can sink the whole budget into one deep branch and never revisit the breadth near the seed, and without a state bound a template that mints a state per row (a paginated table, a calendar) spends it on near-identical pages. Set either to 0 to restore unlimited.

self_register lets the crawl complete a public signup form and continue as the account it creates — on an app with open registration, that is the difference between crawling the marketing shell and crawling the product. It runs at most once per host, only submits to an in-scope host, and reuses the identity it creates at any later login form. It stays off by default because registering is a write; --intensity deep turns it on, and setting this key to true forces it on at any intensity. graph_output_dir writes the finished crawl graph into a directory (one file per host). Captured traffic records what was requested; the graph records how the crawler got there — which action on which state, with which form values, and the selector to find that element again — which is what makes a run reproducible and lets a later pass re-reach a specific state. It is a directory rather than a path because one browser session reuses a single config across all of a host’s seeds.

`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"]

  # hygiene_modules: true           # unset = follow intensity (see below)

  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

Hardening advisories (`hygiene_modules`)

Fourteen modules report a missing best-practice control rather than an exploitable condition - absent security headers, weak TLS protocol and cipher policy, cookie and session-cookie attributes, and the CSP / HSTS / SRI / Permissions-Policy / COOP audits. They are cheap to run and fire on nearly every response, so on a crawl of any size they contribute one near-identical Info/Low row per URL and bury the findings worth triaging. Below --intensity deep they do not run (v0.5.0). The gated set is every module tagged hygiene; see the full list.

vigolium scan -t https://example.com --intensity deep          # per scan
vigolium scan -t https://example.com --module-tag hygiene      # just this family
vigolium scan -t https://example.com --module-id security-headers-missing
vigolium config set dynamic-assessment.hygiene_modules true    # every scan

hygiene_modules sets the default for a broad (["all"]) selection: true runs them at every intensity, false suppresses them even at deep. Naming them explicitly with --module-tag or --module-id always wins, the same way an explicit selection already bypasses the intensity tier ceiling. The Info-tier fingerprints, the endpoint/param observers and surface-scoring are not in this set - their output feeds tech tags, scoring and active-module targeting, so they run at every intensity. Neither is clickjacking-detect, which stays on at Medium.

`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: balanced      # balanced (default) | all | relaxed | 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: []

cli_origin_mode defaulted to relaxed before v0.4.9. relaxed matches the target’s keyword against the candidate’s registrable label, so a scan of app.example.net admitted example.com, example.io and anything else whose label contained “example” - in practice an organization’s SSO/IdP and marketing estate. The default is now balanced (hosts sharing the target’s eTLD+1). This setting also decides which stored records a scan picks up, not just which new traffic is allowed; see Host scope.

`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
  mirror_fs_path: ""               # mirror ingested traffic + findings to this dir as a live filesystem tree (see --mirror-fs)
  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
  disable_swagger: false           # drop the Swagger UI + spec endpoint (CLI: --no-swagger)
  users_file: ~/.vigolium/users.json   # file-based logins for POST /api/auth/login
  license: open-source             # license tag surfaced in /server-info
  enable_burp_bridge: false        # opt in to merging live proxy history into /api/http-records
  burp_bridge_url: ""              # loopback bridge address used when enable_burp_bridge is true

The narrowing flags — --view-only, --no-agent, --demo-only, --alternative-ingest-key, --disable-warm-session — are CLI-only; see Narrowing the Exposed Surface. burp_bridge_url has a sensible default address, so the boolean is what decides whether the bridge is contacted — otherwise every config would silently enable it. Precedence is -B/--burp-bridge-url → $VIGOLIUM_BURP_BRIDGE_URL → config (only when enable_burp_bridge: true); passing the flag works regardless of the boolean. --caido-bridge-url is an alias of the same flag (the Caido plugin exposes the same loopback bridge) — both spellings set the same value and read the same env var and config key.

`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: openai-compatible    # 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 | openai-compatible (default: openai-compatible)
    model: gemma4:latest           # empty = provider default; matches custom_provider.model_id default (openai-compatible / anthropic-compatible)
    oauth_cred_path: ~/.codex/auth.json    # openai-codex-oauth provider
    bridge_binary: ""              # anthropic-claude-sdk-bridge: path to the vigolium-audit binary hosting the SDK bridge (empty = embedded blob, then PATH)
    oauth_token: ""                # anthropic-oauth bearer token (from `claude setup-token`); supports ${ENV_VAR}
    llm_api_key: ""                # for anthropic-api-key / openai-api-key / openai-responses; 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              # 0/unset = default 4; negative = unbounded
    call_timeout_sec: 600          # per-call deadline; -1 = no enforced timeout
    autopilot_mode: legacy         # legacy | shadow | enforced

    # Skills always loaded for autopilot/swarm regardless of planner selection.
    # Empty = built-in default [triage-finding, write-jsext]. The CLI flags
    # --skill / --skill-tag / --no-skill-filter override selection per-run.
    always_on_skills: []

    # Custom backend: used when provider == openai-compatible (OpenAI Chat
    # Completions — Ollama, OpenRouter, LM Studio, vLLM, Together, Groq, …) or
    # provider == anthropic-compatible (Anthropic Messages /v1/messages gateway).
    custom_provider:
      base_url: http://localhost:11434/v1   # e.g. http://localhost:11434/v1 (Ollama)
      model_id: gemma4:latest               # backend-specific model id
      api_key: ""                           # optional; leave empty to skip Authorization header; supports ${ENV_VAR}
      extra_headers: []                     # list of curl-style "Key: Value" strings, applied after standard headers

      # OpenRouter provider routing — typed knob for the request "provider" object.
      # Only fields you set are sent; unset fields are dropped from the wire body.
      provider_routing:
        order: []                  # upstream provider slugs in preference order
        only: []                   # restrict to these provider slugs
        ignore: []                 # exclude these provider slugs
        allow_fallbacks: true      # false = strict (only the chosen providers)
        sort: ""                   # price | throughput | latency
        quantizations: []          # e.g. [fp8, int8]
        data_collection: ""        # allow | deny
        require_parameters: false  # only providers that honour every request parameter
        zdr: false                 # Zero Data Retention providers only

      # Generic JSON-body passthrough merged into every openai-compatible request
      # (OpenRouter extensions, vLLM/Together body options, etc.). Reserved keys
      # (model, messages, tools, stream, stream_options) are rejected. Don't set a
      # `provider` key here if you also use provider_routing — use one or the other.
      extra_body: {}

    # Vertex AI (anthropic-vertex / google-vertex) — GCP project / region.
    # Credentials come from `oauth_cred_path` (service-account JSON) or
    # $GOOGLE_APPLICATION_CREDENTIALS. $GOOGLE_CLOUD_PROJECT and
    # $GOOGLE_CLOUD_LOCATION override these YAML values.
    google_cloud_project: ""       # GCP project id
    google_cloud_location: ""      # GCP region; default us-central1

  # 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

  # Vigolium-audit integration (embedded harness)
  audit:
    enable: false                  # auto-enabled by --audit flag on autopilot/swarm
    mode: lite                     # lite | balanced | deep | mock
    sync_interval: 30              # seconds between state syncs
    # The audit driver runs the `claude` or `codex` CLI. There is no
    # platform knob here — the agent is resolved from agent.olium.provider
    # (anthropic-* → claude, openai-* → codex), overridable per-run with
    # --provider or --agent {claude|codex} on `vigolium agent audit`.

autopilot_mode is opt-in: legacy keeps one growing conversation and writes findings directly, shadow adds bounded context rotation while mirroring candidates, and enforced promotes only fresh-context verifier-confirmed candidates. Only shadow and enforced support agent autopilot --resume <agentic-scan-uuid>. Provider quick reference:

Provider	Default model	Credential source
`openai-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`
`anthropic-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`
`openai-responses`	`gpt-5.5`	`llm_api_key` or `$OPENAI_API_KEY` (public OpenAI Responses API, `/v1/responses`)
`anthropic-cli` (alias `anthropic-claude-cli`)	`claude-opus-4-7`	local `claude` binary on `$PATH`
`anthropic-claude-sdk-bridge`	Claude Code default	logged-in Claude Code subscription via the `vigolium-audit bridge` sidecar (no key); `bridge_binary` / `--bridge-bin` override
`anthropic-compatible`	via `custom_provider.model_id`	`agent.olium.custom_provider` (Anthropic Messages `/v1/messages` gateway or proxy)
`anthropic-vertex`	`claude-opus-4-6`	GCP service-account JSON (or ADC) via `google_cloud_project` / `google_cloud_location`
`google-vertex`	`gemini-2.5-pro`	GCP service-account JSON (or ADC) via `google_cloud_project` / `google_cloud_location`
`openai-compatible` (default)	`gemma4:latest` (via `custom_provider.model_id`)	`agent.olium.custom_provider` (Ollama, OpenRouter, LM Studio, vLLM, …)

CLI flags --provider, --model, --oauth-cred, --oauth-token, --llm-api-key, --base-url, --bridge-bin override these per-invocation. The REST API does not mirror these overrides, server-side workloads use the YAML config exclusively. See Setting Up the Agent for a step-by-step walkthrough or 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
    max_open_conns: 8              # WAL reader pool: concurrent readers + 1 writer

  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

  # Remap the severity a finding is recorded with, keyed by nuclei template ID.
  # Default tones down generic config.json exposure (often only public base
  # URLs / feature flags). Add your own template-ID → severity entries.
  severity_overrides:
    config-json-exposure-fuzz: medium   # critical | high | medium | low | info

  # Collapse many findings of the same module into one finding per distinct
  # *value* (e.g. one row per leaked secret, listing every URL it appears on)
  # instead of one row per URL.
  group_by_value:
    enabled: true
    per_host: true              # group within a host rather than project-wide
    max_urls: 50                # URLs listed on the surviving finding
    by_module: [...]            # modules grouped by their finding identity (long built-in list)
    by_rule: [secret-detect, host-header-injection, ldap-injection, ...]  # grouped by the matched rule
    bundle_suspect: [secret-detect]  # also bundle the module's Suspect-tier results
    tags: []                    # extra module tags to include

Run vigolium config ls known_issue_scan.group_by_value to print the full built-in module lists for your build.

`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, arquivo]   # keyless — the default set
  # Additional sources: urlscan, virustotal (join the set only once their key is set)

  api_keys:
    urlscan: ""
    virustotal: ""

wayback and commoncrawl also mine archived response bodies (and Wayback’s robots.txt history) for URLs no index holds. Mined URLs are scope-checked and junk-extension filtered before they enter the scan, while index rows are passed through verbatim. Budgets are fixed constants rather than flags, since the phase runs unattended.

`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, audit, query). Static analysis tooling (ast-grep, semgrep, etc.) has been removed, for AI-driven code audit, use vigolium agent audit 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

When enabled, agent runs invoked with --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

This loads ~/.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

See projects for full project management documentation.

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Config File Location

Config Precedence

Environment Variables

`VIGOLIUM_DB_PATH`

CLI Config Overrides

Config Sections

`scanning_strategy`

`scanning_pace`

`discovery`

`spidering`

`dynamic-assessment`

Hardening advisories (`hygiene_modules`)

`scope`

`server`

`agent`

`database`

`known_issue_scan`

`mutation_strategy`

`external_harvester`

`oast`

`source_aware`

`storage`

`notify`

Scanning Profiles

Project-Level Config

​Config File Location

​Config Precedence

​Environment Variables

​VIGOLIUM_DB_PATH

​CLI Config Overrides

​Config Sections

​scanning_strategy

​scanning_pace

​discovery

​spidering

​dynamic-assessment

​Hardening advisories (hygiene_modules)

​scope

​server

​agent

​database

​known_issue_scan

​mutation_strategy

​external_harvester

​oast

​source_aware

​storage

​notify

​Scanning Profiles

​Project-Level Config

Config File Location

Config Precedence

Environment Variables

`VIGOLIUM_DB_PATH`

CLI Config Overrides

Config Sections

`scanning_strategy`

`scanning_pace`

`discovery`

`spidering`

`dynamic-assessment`

Hardening advisories (`hygiene_modules`)

`scope`

`server`

`agent`

`database`

`known_issue_scan`

`mutation_strategy`

`external_harvester`

`oast`

`source_aware`

`storage`

`notify`

Scanning Profiles

Project-Level Config