Stateless Scanning

Overview

Vigolium offers several ways to scan a target and get results in a single command without managing a persistent database. This is ideal for CI/CD pipelines, scripting, and quick ad-hoc checks.

Quick Scan with `scan-url`

The fastest way to scan a single URL: no phases, just direct module execution.

vigolium scan-url https://example.com/api/users?id=1

“Stateless” is a statement about the database’s lifetime, not about its absence. Every result Vigolium produces is written through a database. Without -S the run persists into the project database like any other; with -S it runs into a throwaway file that is exported and then deleted. Dropping -S is therefore not a way to make a run cheaper - and under -S a failed export is a failed run (exit 1, error.code: export_failed), because the artifact is the only copy that survives.

JSON output for scripting:

vigolium scan-url -j https://example.com/api/users?id=1

With authentication and a POST body:

vigolium scan-url \
  --method POST \
  --body '{"user":"admin","pass":"secret"}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer tok123' \
  https://example.com/api/login

Run only specific modules:

vigolium scan-url -m sqli -m xss https://example.com/search?q=test

Skip passive analysis for faster results:

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

Scanning Raw HTTP Requests with `scan-request`

Feed a raw HTTP request from a file or stdin:

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

# From stdin (raw HTTP)
printf 'GET /api/users?id=1 HTTP/1.1\r\nHost: example.com\r\n\r\n' | vigolium scan-request

# From a curl command (auto-detected)
echo "curl -X POST -d 'user=admin' https://example.com/login" | vigolium scan-request

Override the target host when the request file lacks a full URL:

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

Piping Input from stdin

Both scan-url and scan-request auto-detect the input format from stdin: Plain URL:

echo 'https://example.com/search?q=test' | vigolium scan-url

Curl command:

echo "curl -X POST -H 'Content-Type: application/json' -d '{\"id\":1}' https://example.com/api" | vigolium scan-url

Raw HTTP request:

printf 'POST /api/login HTTP/1.1\r\nHost: example.com\r\nContent-Type: application/x-www-form-urlencoded\r\n\r\nuser=admin&pass=secret' | vigolium scan-request

Full Pipeline with `--stateless`

For a complete multi-phase scan without a persistent database, use the --stateless flag on vigolium scan. This creates a temporary database, runs all phases, exports results, and cleans up:

vigolium scan --stateless \
  -t https://example.com \
  --format jsonl \
  -o results

This produces results.jsonl with all findings. Combine multiple output formats:

vigolium scan --stateless \
  -t https://example.com \
  --format jsonl,html \
  -o results

This produces both results.jsonl and results.html.

Reach for `-S` for isolation, not just for CI

The other half of what -S buys you is an empty database. A scan against the persisted database resolves its work set from every origin already in the project that passes the scope matcher (see Host scope), so repeated scans into the default store silently grow what each run touches - and records from earlier scans sort ahead of the target you just named. -S removes that variable entirely, which makes it the right default for a measurement run, a coverage comparison, or any scan whose result set you intend to read as “what this target looks like”. -o is optional, not required: without it the run warns that results will be discarded with the temp database and continues. The warning is suppressed under --silent, --split-by-host, -j and --ci-output - the last two stream every record to stdout as it is written, so nothing is actually lost.

A requested artifact that was never written fails the run (v0.5.0). An export failure used to exit 0, report scan.finished status=completed and leave no file. It now exits 1 with error.code: "export_failed", which outranks the --fail-on gate - a 4 whose artifact is missing would send a CI job to read a file that is not there. Each --format is attempted independently, so with --format jsonl,sqlite one of them may still be on disk; the Exports summary on stderr lists what landed.

Output Formats

Console (default)

Human-readable colored output to the terminal:

vigolium scan-url https://example.com/search?q=test

JSONL

Machine-readable, one JSON object per line. Use -j or --format jsonl:

vigolium scan-url -j https://example.com/search?q=test
vigolium scan-url --format jsonl https://example.com/search?q=test

HTML

Interactive report with ag-grid table. Requires -o to specify the output path:

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

SARIF

A SARIF 2.1.0 log of the run’s findings, for GitHub code scanning, DefectDojo, and SARIF viewers. Requires -o:

vigolium scan --stateless -t https://example.com --format sarif -o results.sarif

Pairs naturally with a stateless CI run — nothing is persisted, and the artifact is the upload. See Output and Reporting for the finding→schema mapping.

SQLite

Dump the per-run database to a single standalone .sqlite file (via VACUUM INTO). Only available in stateless mode and requires -o. Aliases: sqlite3, db:

vigolium scan --stateless -t https://example.com --format sqlite -o scan

You can reopen the file later without a persistent project DB (see Reading Results Back).

Filesystem (fs)

Write a flat, browsable tree instead of a single file — handy for piping a scan straight to a coding agent that prefers ls/grep/jq over a database:

vigolium scan --stateless -t https://example.com --format fs -o run

This produces run-traffic/ and run-findings/ with per-host raw .req/.resp.* files, cross-linked finding .md files, and a jq-friendly index.json in each. --split-by-host is a no-op (fs already splits by host), and --omit-response drops the response files. See Output and Reporting for the full layout.

Multiple Formats

Comma-separate formats to produce several outputs at once:

vigolium scan --stateless -t https://example.com --format console,jsonl,html -o scan-output

Reading Results Back

A stateless run leaves no project database behind, but you can still browse a .jsonl or .sqlite export after the fact. Point finding/traffic at the file with -S/--stateless + --db — project scoping is turned off and nothing is written to your project DB:

# Browse a JSONL export with the usual filters/sorting
vigolium finding -S --db ./scan-output.jsonl --min-severity high
vigolium traffic -S --db ./scan-output.jsonl --status 500 -n 20

# Or a standalone .sqlite produced by --format sqlite
vigolium finding -S --db ./scan.sqlite --json --with-records

# Render one finding as Markdown (add --compact to window long responses)
vigolium finding -S --db ./scan.sqlite --id 42 --markdown --compact

CI/CD Integration

Use --ci-output-format for clean, parseable output with no banners or color codes:

vigolium scan --stateless \
  -t https://example.com \
  --ci-output-format \
  -o findings

This forces JSONL output and suppresses all decorative output.

Scanning from Various Input Sources

From an OpenAPI Spec

vigolium scan --stateless \
  --input api-spec.yaml -I openapi \
  -t https://api.example.com \
  --format jsonl -o results

From a Burp Suite Export

vigolium scan --stateless \
  --input export.xml -I burpxml \
  --format jsonl -o results

From a HAR File

vigolium scan --stateless \
  --input traffic.har -I har \
  --format jsonl -o results

From a Postman Collection

vigolium scan --stateless \
  --input collection.json -I postman \
  -t https://api.example.com \
  --format jsonl -o results

Tuning the Scan

Control concurrency and rate limits:

vigolium scan --stateless \
  -t https://example.com \
  -c 100 \
  --rate-limit 200 \
  --format jsonl -o results

Use a scanning strategy preset:

# Lightweight: fewer modules, faster
vigolium scan --stateless -t https://example.com --strategy lite -o results --format jsonl

# Deep: more modules, thorough
vigolium scan --stateless -t https://example.com --strategy deep -o results --format jsonl

Include the full HTTP response in findings for debugging:

vigolium scan-url --include-response -j https://example.com/api/users?id=1

Examples

Quick check on a single endpoint:

vigolium scan-url https://example.com/api/users?id=1

Full scan with JSON output in one shot:

vigolium scan --stateless -t https://example.com --discover --format jsonl -o findings

Scan a curl command from clipboard:

pbpaste | vigolium scan-url -j

Scan an API spec and export HTML report:

vigolium scan --stateless --input openapi.yaml -I openapi -t https://api.example.com --format html -o report

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Overview

Quick Scan with `scan-url`

Scanning Raw HTTP Requests with `scan-request`

Piping Input from stdin

Full Pipeline with `--stateless`

Reach for `-S` for isolation, not just for CI

Output Formats

Console (default)

JSONL

HTML

SARIF

SQLite

Filesystem (fs)

Multiple Formats

Reading Results Back

CI/CD Integration

Scanning from Various Input Sources

From an OpenAPI Spec

From a Burp Suite Export

From a HAR File

From a Postman Collection

Tuning the Scan

Examples

​Overview

​Quick Scan with scan-url

​Scanning Raw HTTP Requests with scan-request

​Piping Input from stdin

​Full Pipeline with --stateless

​Reach for -S for isolation, not just for CI

​Output Formats

​Console (default)

​JSONL

​HTML

​SARIF

​SQLite

​Filesystem (fs)

​Multiple Formats

​Reading Results Back

​CI/CD Integration

​Scanning from Various Input Sources

​From an OpenAPI Spec

​From a Burp Suite Export

​From a HAR File

​From a Postman Collection

​Tuning the Scan

​Examples

Overview

Quick Scan with `scan-url`

Scanning Raw HTTP Requests with `scan-request`

Piping Input from stdin

Full Pipeline with `--stateless`

Reach for `-S` for isolation, not just for CI

Output Formats

Console (default)

JSONL

HTML

SARIF

SQLite

Filesystem (fs)

Multiple Formats

Reading Results Back

CI/CD Integration

Scanning from Various Input Sources

From an OpenAPI Spec

From a Burp Suite Export

From a HAR File

From a Postman Collection

Tuning the Scan

Examples