Blackbox Scanning

Blackbox scanning tests a web application from the outside without access to source code. Vigolium sends crafted HTTP requests and analyzes responses to find vulnerabilities.

Quick Start

# Scan a single URL
vigolium scan -t https://example.com

# Scan multiple targets
vigolium scan -t https://api.example.com -t https://admin.example.com

# Scan targets from a file
vigolium scan -T targets.txt

Strategies

Use --strategy to control how much reconnaissance Vigolium performs before dynamic testing.

Lite, Fast, Minimal Discovery

Runs only the dynamic-assessment phase against the provided targets. No crawling, no content discovery.

vigolium scan -t https://example.com --strategy lite

Best for: quick checks, CI pipelines, known endpoints.

Since v0.4.5, lite also carries a pace ceiling — concurrency 10, rate limit 20 req/s, max-per-host 10 — on top of selecting fewer phases. Before that, lite and balanced opened a crawl identically: a name every operator reads as “gentler on the target” was gentler in module count alone.The ceiling only ever narrows. An explicitly typed --concurrency / --rate-limit / --max-per-host overrules it (an operator overruling the preset is the point of having both), and a scanning_pace config already gentler than lite is not dragged up to it. balanced is the baseline and deep is explicitly the one that opens wide, so neither ships a ceiling.

Balanced, Default

Runs content discovery, browser spidering, known-issue-scan analysis, and audit.

vigolium scan -t https://example.com
# Equivalent to:
vigolium scan -t https://example.com --strategy balanced

Best for: general-purpose scanning with good coverage.

Deep, Maximum Recon

Adds external intelligence harvesting (Wayback Machine, CommonCrawl, etc.) on top of balanced.

vigolium scan -t https://example.com --strategy deep

Best for: thorough assessments where you want to discover forgotten endpoints and historical paths.

Phase-by-Phase Walkthrough

Input Formats

Vigolium accepts targets in multiple formats via -I / --input-mode:

Format	Flag	Example
URL list (default)	`-I urls`	`vigolium scan -T urls.txt`
OpenAPI / Swagger	`-I openapi`	`vigolium scan -i api-spec.yaml -I openapi`
WSDL / SOAP	`-I wsdl`	`vigolium scan -i service.wsdl -I wsdl -t https://soap.example.com`
Postman Collection	`-I postman`	`vigolium scan -i collection.json -I postman`
Burp XML export	`-I burpxml`	`vigolium scan -i burp-export.xml -I burpxml`
Raw HTTP request	`-I burpraw`	`vigolium scan -i request.txt -I burpraw`
cURL commands	`-I curl`	`vigolium scan -i curls.sh -I curl`
HAR file	`-I har`	`vigolium scan -i traffic.har -I har`
Nuclei output	`-I nuclei`	`vigolium scan -i nuclei.json -I nuclei`
Deparos discovery output	`-I deparos`	`vigolium scan -i deparos.jsonl -I deparos`
Burp scope export	`-I burpscope`	`vigolium scan -T scope.json` (content-sniffed)

-T/--target-file reads its file as one target URL per line, so a spec or an export must go through -i/--input — pointing -T at a YAML spec makes every line of that file a target. The exceptions are the two formats that genuinely are target lists: urls and burpscope.

# Scan an OpenAPI spec (auto-uses server URLs from the spec)
vigolium scan -i openapi.yaml -I openapi

# Scan an OpenAPI spec against a specific target
vigolium scan -i openapi.yaml -I openapi -t https://staging.example.com

# Scan a Burp Suite export
vigolium scan -i burp-session.xml -I burpxml

# Pipe curl commands
cat curls.sh | vigolium scan -I curl

# OpenAPI with custom headers and parameter values
vigolium scan -i api.yaml -I openapi \
  --spec-header "Authorization: Bearer token123" \
  --spec-var "user_id=42"

External Harvesting

Queries external data sources for historical URLs and endpoints. Enabled by --strategy deep or --external-harvest.

# Enable explicitly
vigolium scan -t https://example.com --external-harvest

# Or via deep strategy
vigolium scan -t https://example.com --strategy deep

Sources: Wayback Machine, CommonCrawl, AlienVault OTX, Arquivo.pt are keyless and enabled by default; URLScan and VirusTotal join the set only once their API key is configured in vigolium-configs.yaml under external_harvester.api_keys. Configure the active set with external_harvester.sources. Wayback and CommonCrawl also mine archived response bodies, not just the index:

Wayback replays each capture through /web/<ts>id_/ (the raw, un-rewritten copy) and walks every main host’s robots.txt history — the old Disallow: lines name paths no crawler was ever allowed to record.
CommonCrawl range-fetches the WARC record each index row already locates, which is one small gzip member rather than the whole archive file.

Index rows are emitted verbatim — an index row is what the archive recorded, including the malformed URLs a scanner once requested. Mined URLs are the ones that get filtered: scope-checked on a label boundary, junk-extension filtered, and stripped of archive hostnames, so mining a page can’t fan the scan out across every CDN and analytics host it references. Mining is gated on the index carrying timestamps (a replay is addressed by timestamp) and capped by fixed per-domain budgets, since the phase runs unattended.

Content Discovery

Brute-force directory and file discovery using the deparos engine. Enabled by --strategy balanced/deep or --discover.

# Run discovery with a time limit
vigolium scan -t https://example.com --discover --discover-max-time 30m

# Run only discovery phase
vigolium scan -t https://example.com --only discovery

The discovery engine uses recursive brute-forcing (default depth 5), observed filename variants, JS analysis, and case-sensitivity auto-detection.

Browser Spidering

Chromium-based crawling that handles SPAs, JavaScript rendering, and form interactions. Enabled by --strategy balanced/deep or --spider.

# Spider with time limit
vigolium scan -t https://example.com --spider --spider-max-time 15m

# Multiple browser instances for faster crawling
vigolium scan -t https://example.com --spider -b 3

# Non-headless (visible browser)
vigolium scan -t https://example.com --spider --headless=false

# Disable form filling
vigolium scan -t https://example.com --spider --no-forms

Spider flags:

-b / --browsers, number of browser instances (default: 1)
-E / --browser-engine, chromium, ungoogled, or fingerprint (default: chromium)
--headless: headless mode (default: true)
--no-cdp: disable CDP event listener detection
--no-forms: disable automatic form filling
--spider-max-time: max duration (default: 30m)

Known Issue Scan

Runs Nuclei templates and Kingfisher secret scanning against discovered hosts and response bodies. Enabled by --strategy balanced/deep or by the strategy. By default, known-issue-scan enriches its target list with path prefixes discovered in previous phases (discovery, spidering). This increases coverage, Nuclei templates run against individual path prefixes (e.g., https://example.com/api/v1/) rather than just the host root. Disable this for faster but less granular scans:

# vigolium-configs.yaml
known_issue_scan:
  enrich_targets: true    # default: true (use discovered paths as targets)
                          # false: use host-level URLs only (faster)

# Filter Nuclei templates by tag
vigolium scan -t https://example.com --known-issue-scan-tags cve,misconfig

# Filter by severity
vigolium scan -t https://example.com --known-issue-scan-severities critical,high

# Custom templates directory (short alias: --templates-dir)
vigolium scan -t https://example.com --known-issue-scan-templates-dir ~/nuclei-templates/
vigolium scan -t https://example.com --templates-dir ~/nuclei-templates/

Pinning it skips the one-time nuclei-templates clone into ~/nuclei-templates. Since v0.4.5 that first-run clone announces itself rather than looking like a hung scan.

Dynamic Assessment

The core scanning phase (canonical name dynamic-assessment; aliases audit, dast, assessment). Runs active and passive modules against all discovered HTTP records. Enabled in all strategies. Uses a feedback loop (up to 3 rounds): after each round, checks for newly discovered records and rescans if found. OAST (Out-of-band Application Security Testing) injects blind callback payloads when configured:

# With a fixed OAST URL
vigolium scan -t https://example.com --oast-url https://your-oast.example.com/callback

Performance Tuning

CLI Speed Flags

Flag	Default	Description
`-c` / `--concurrency`	50	Number of concurrent scan workers
`--max-per-host`	30	Max concurrent requests per host
`-r` / `--rate-limit`	100	Max request submissions per second
`--max-host-error`	30	Skip host after N consecutive errors
`--max-findings-per-module`	10	Suppress findings after this many per module (0 = unlimited)
`--timeout`	15s	Per-request HTTP timeout
`--retries`	1	Retry count for failed requests
`--scanning-max-duration`	unset	Override global max scan duration
`--discover-max-time`	1h	Max duration for content discovery
`--spider-max-time`	30m	Max duration for spidering

# Fast scan with high concurrency
vigolium scan -t https://example.com -c 100 -r 200 --max-per-host 5

# Gentle scan with low rate
vigolium scan -t https://example.com -c 10 -r 20 --max-per-host 1

# Time-boxed deep scan
vigolium scan -t https://example.com --strategy deep \
  --scanning-max-duration 1h \
  --discover-max-time 20m \
  --spider-max-time 10m

Scanning Pace (Config File)

The scanning_pace section in vigolium-configs.yaml provides centralized speed control. Common values serve as a baseline inherited by all phases; per-phase subsections override specific values.

scanning_pace:
  # Common defaults (inherited by all phases)
  concurrency: 50
  rate_limit: 100
  max_per_host: 10

  # Per-phase overrides (0 = inherit from common)
  discovery:
    concurrency: 30
    max_duration: 1h

  known_issue_scan:
    concurrency: 50
    rate_limit: 100
    max_duration: 30m

  external_harvester:
    max_duration: 5m

  dynamic-assessment:
    concurrency: 50

Precedence (highest to lowest): CLI flags > scanning profile > per-phase overrides > common values > built-in defaults.

Proactive WAF/CDN Pacing

An aggressive active phase can burst a WAF/CDN edge into a rate-based block — and once the edge starts filtering, the findings that would have surfaced are hidden behind challenge pages. To stay ahead of that, the per-host rate limiter pre-throttles a host the first time earlier-phase traffic fingerprints it behind a recognized edge, before the heavy phase ever fires:

Detection reads ordinary responses — headers on plain 200s are enough to fingerprint CloudFront, Cloudflare, Akamai, Imperva/Incapsula, Sucuri, and Azure Front Door. No block or challenge is required to arm the pacing.
On the first match, per-host concurrency drops to a quarter of its ceiling (MaxPerHost/4), then ramps back up on healthy responses so a well-behaved edge isn’t paced forever.
The drop prints once per host as a [waf-pacing-armed] notice (for example 40→10), so you can see exactly when and how far a host was throttled.

# Disable the proactive pre-throttle (reactive back-off after a confirmed block still applies)
vigolium scan -t https://example.com --no-waf-pacing

This is the proactive half of Vigolium’s WAF handling: it slows down before an edge blocks. It complements the reactive WAF-block warning (the one-time-per-host [waf-block-detected] notice covered on the discovery phase page), which fires after a confirmed block. Passing --no-waf-pacing disables only the proactive pacing; the reactive back-off after a confirmed block is unaffected.

Output Formats

Format	Flag	Description
Console	`--format console` (default)	Colored human-readable table output
JSONL	`--format jsonl` or `--json` / `-j`	One JSON object per finding per line
HTML	`--format html -o report.html`	Interactive ag-grid HTML report
Document report	`--format report -o report.docx`	Document-style report (Word)
PDF	`--format pdf -o report.pdf`	PDF report (uses headless Chrome)
SQLite	`--format sqlite -o scan` (needs `-S`)	Standalone DB dump (`VACUUM INTO`); aliases `sqlite3`, `db`

Multiple formats can be combined with a comma, e.g. --format jsonl,html.

# JSON output
vigolium scan -t https://example.com --json

# HTML report
vigolium scan -t https://example.com --format html -o scan-report.html

# JSON to file
vigolium scan -t https://example.com -j -o findings.jsonl

Lightweight Scan Commands

For quick, targeted scans of individual URLs or raw requests.

`scan-url`: Single URL

# Basic GET scan
vigolium scan-url https://example.com/api/users

# POST with body and headers
vigolium scan-url https://example.com/api/login \
  --method POST \
  --body '{"username":"admin","password":"test"}' \
  -H "Content-Type: application/json"

# Skip passive modules
vigolium scan-url https://example.com/api/data --no-passive

# JSON output
vigolium scan-url https://example.com/api/users --json

# With content discovery
vigolium scan-url https://example.com --discover

`scan-request`: Raw HTTP Request

# From stdin
echo -e "GET /api/users HTTP/1.1\r\nHost: example.com\r\n" | vigolium scan-request

# From file
vigolium scan-request -i request.txt

# With target override
vigolium scan-request -i request.txt --target https://staging.example.com

When phase flags (--discover, --spider, --external-harvest, --known-issue-scan) are used with these commands, they delegate to the full Runner pipeline (database required).

Module Selection

# List all available modules
vigolium scan -t https://example.com --list-modules
# Or:
vigolium module ls

# Run specific modules only
vigolium scan -t https://example.com -m xss-light-url-params,sqli-error-based

# Run a single module
vigolium scan-url https://example.com/search?q=test -m xss-light-url-params

Hand-picking modules auto-skips known-issue-scan. Narrowing a scan to specific modules (--module-id, or -m/--modules) signals a targeted, low-noise run, so Vigolium auto-appends --skip known-issue-scan — otherwise the broad Nuclei/Kingfisher known-issue pass would flood the results. A one-line console note explains the auto-skip; pass --only known-issue-scan to force the pass back on. It’s a no-op when --only is set or when no module narrowing is active, and is silent under --silent.

Filtering by Tag

Modules are tagged with classification labels (e.g., spring, rails, django, xss, injection, light). Use --module-tag to run only modules matching specific tags:

# Run all Spring-related modules
vigolium scan -t https://example.com --module-tag spring

# Run all Rails and Django modules
vigolium scan -t https://example.com --module-tag rails --module-tag django

# Combine with -m (results are merged as a union)
vigolium scan -t https://example.com -m xss-light-url-params --module-tag spring

Tags are matched with OR logic, a module runs if it matches any of the specified tags. When both -m and --module-tag are provided, the results are merged (union).

Custom Extensions

Load JavaScript or YAML extension modules alongside or instead of built-in modules. See Extension Scanning for full details.

# Add extensions on top of built-in modules
vigolium scan -t https://example.com --ext ./my-scanner.js

# Load extensions from a directory
vigolium scan -t https://example.com --ext-dir ~/my-extensions/

# Run ONLY extension modules (skip built-in modules)
vigolium run extension -t https://example.com --ext ./my-scanner.js

# List loaded extensions
vigolium ext ls

Heuristics

Pre-flight checks detect WAFs, redirects, and technology before scanning. Controlled via --heuristics-check:

# Skip heuristics for faster start
vigolium scan -t https://example.com --skip-heuristics

# Advanced heuristics
vigolium scan -t https://example.com --heuristics-check advanced

Heuristics are automatically disabled when --only is used.

OAST (Out-of-Band Testing)

OAST detects blind vulnerabilities where the application triggers an out-of-band callback (DNS/HTTP) instead of reflecting payloads in the response. Vigolium uses an interactsh server for callback tracking. OAST is enabled by default. The OAST probe module injects callback URLs into insertion points and monitors for interactions during and after the scan.

# Use a fixed OAST callback URL (bypasses interactsh auto-generation)
vigolium scan -t https://example.com --oast-url https://your-oast.example.com/callback

Configuration in vigolium-configs.yaml:

oast:
  enabled: true                     # Enable/disable OAST (default: true)
  server_url: "oast.pro"            # Interactsh server URL
  token: ""                         # Auth token for private interactsh servers
  poll_interval: 5                  # Seconds between interaction polls
  grace_period: 10                  # Seconds to wait after scan for late callbacks

  oast_url: ""                      # Fixed callback URL (bypasses interactsh)

  enabled_blind_xss: false          # Enable blind XSS payload injection
  blind_xss_src: ""                 # JavaScript src URL for blind XSS payloads

Mutation Strategy

The mutation strategy controls how Vigolium generates payloads for parameter fuzzing. Value-aware mutation analyzes the original parameter value, classifies it by semantic type, and generates type-appropriate mutations.

mutation_strategy:
  default_modes:
    - append                        # How payloads are applied: "append", "replace", "insert"

  value_aware:
    enabled: true                   # Enable value-aware mutation (default: true)
    max_per_intent: 5               # Max mutations per intent per parameter
    default_intents:
      - neighbor                    # Similar values (e.g., id=5 → id=4, id=6)
      - boundary                    # Edge cases (e.g., 0, -1, MAX_INT, empty)
      - escalation                  # Privilege escalation (e.g., role=user → role=admin)

    enum_mappings:                  # Custom enum escalation mappings
      role: ["admin", "superadmin", "root"]
      status: ["active", "approved", "verified"]

    param_synonyms:                 # Custom parameter name synonyms
      user_id: ["uid", "userId", "account_id"]

Recognized value types include: integer, UUID, email, JWT, boolean, path, sequential ID, and 15+ others. Each type has specialized neighbor, boundary, and escalation mutations.

Project Scoping

Use --project-uuid (with a UUID) or --project-name (with a name) to scope all scan data to a specific project for multi-tenant isolation. Both are global flags, so they work on every command, not just scan:

# Scan within a project
vigolium scan -t https://example.com --project-uuid a1b2c3d4-...

# Or set the environment variable for your session
eval $(vigolium project use a1b2c3d4-...)
vigolium scan -t https://example.com

See Projects for the full multi-tenancy reference.

Common Scenarios

# API scan from OpenAPI spec
vigolium scan -i api-spec.yaml -I openapi \
  --spec-header "Authorization: Bearer $TOKEN"

# Full deep scan with HTML report
vigolium scan -t https://example.com --strategy deep \
  --format html -o report.html

# Quick CI check with JSON output
vigolium scan -t https://staging.example.com --strategy lite -j

# Rescan existing database records
vigolium scan

# Scan with proxy (Burp, ZAP)
vigolium scan -t https://example.com --proxy http://127.0.0.1:8080

# Pin the scan UUID (sync results across nodes, or group several runs)
vigolium scan -t https://example.com --scan-uuid 6f1c2b90-8b1e-4a6c-9d2f-5c7a1e3b9d40

# Verbose output with traffic dump
vigolium scan -t https://example.com -v --dump-traffic

# Scan only Spring-related modules within a project
vigolium scan -t https://example.com --module-tag spring --project-uuid a1b2c3d4-...

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Quick Start

Strategies

Lite, Fast, Minimal Discovery

Balanced, Default

Deep, Maximum Recon

Phase-by-Phase Walkthrough

Input Formats

External Harvesting

Content Discovery

Browser Spidering

Known Issue Scan

Dynamic Assessment

Performance Tuning

CLI Speed Flags

Scanning Pace (Config File)

Proactive WAF/CDN Pacing

Output Formats

Lightweight Scan Commands

`scan-url`: Single URL

`scan-request`: Raw HTTP Request

Module Selection

Filtering by Tag

Custom Extensions

Heuristics

OAST (Out-of-Band Testing)

Mutation Strategy

Project Scoping

Common Scenarios

​Quick Start

​Strategies

​Lite, Fast, Minimal Discovery

​Balanced, Default

​Deep, Maximum Recon

​Phase-by-Phase Walkthrough

​Input Formats

​External Harvesting

​Content Discovery

​Browser Spidering

​Known Issue Scan

​Dynamic Assessment

​Performance Tuning

​CLI Speed Flags

​Scanning Pace (Config File)

​Proactive WAF/CDN Pacing

​Output Formats

​Lightweight Scan Commands

​scan-url: Single URL

​scan-request: Raw HTTP Request

​Module Selection

​Filtering by Tag

​Custom Extensions

​Heuristics

​OAST (Out-of-Band Testing)

​Mutation Strategy

​Project Scoping

​Common Scenarios

Quick Start

Strategies

Lite, Fast, Minimal Discovery

Balanced, Default

Deep, Maximum Recon

Phase-by-Phase Walkthrough

Input Formats

External Harvesting

Content Discovery

Browser Spidering

Known Issue Scan

Dynamic Assessment

Performance Tuning

CLI Speed Flags

Scanning Pace (Config File)

Proactive WAF/CDN Pacing

Output Formats

Lightweight Scan Commands

`scan-url`: Single URL

`scan-request`: Raw HTTP Request

Module Selection

Filtering by Tag

Custom Extensions

Heuristics

OAST (Out-of-Band Testing)

Mutation Strategy

Project Scoping

Common Scenarios