CI/CD Integration

Integrate Vigolium into CI/CD pipelines to automatically scan applications for vulnerabilities on every deployment.

Overview

Vigolium can be integrated into CI/CD pipelines to automatically scan applications for vulnerabilities on every deployment or pull request. This guide covers common patterns for running scans in automated environments.

Basic CI Scan

A minimal CI scan using the lite strategy for speed and JSONL output for machine parsing:

vigolium scan -t $TARGET_URL --strategy lite --format jsonl -o results.jsonl

The lite strategy skips browser spidering and heavy discovery, making it suitable for time-constrained CI environments. JSONL output produces one JSON object per line, which is straightforward to parse in scripts.

Exit-Code Gating with --fail-on

Use --fail-on <severity> to make a scan exit non-zero when it finds anything at or above a severity threshold — the cleanest way to gate a pipeline without post-processing JSONL. It accepts info, low, medium, high, or critical:

# Fail the build if any high or critical finding is present
vigolium scan -t $TARGET_URL --strategy lite --fail-on high --format jsonl -o results.jsonl

• Output is always written before the gate is evaluated, so your report and exit status stay consistent.
• The gate is scoped to the scan it runs in. Under -P/--parallel, it is evaluated per child process, and the parent batch fails only when every target fails.
• It works on scan, scan-url, scan-request, and run.

The exit-code table

Since v0.4.5 the exit status distinguishes outcomes a pipeline has to react to differently:

Code	Meaning	What CI should do
0	Success	Continue
1	Error — the command failed to do its job	Investigate: this is breakage, not a result
2	Usage error — bad flag, bad value, rejected combination	Fix the invocation
3	fuzz --fail-on-match matched	A fuzz gate fired
4	A --fail-on <severity> gate tripped	Fail the build on findings

Upgrading from v0.4.4 or earlier: check your if statements. --fail-on used to exit 1, the same code the scanner returns when it crashes. A pipeline written as vigolium scan … || exit 1 treated an unreachable target, a bad flag, and a critical finding identically. Now a findings gate is 4, so you can report the finding and escalate a genuine outage separately:

vigolium scan -t "$TARGET_URL" --fail-on high --format sarif -o results.sarif
case $? in
  0) echo "clean" ;;
  4) echo "findings at or above high — failing the build"; exit 1 ;;
  2) echo "bad invocation"; exit 1 ;;
  *) echo "scanner error — this is an outage, not a finding"; exit 1 ;;
esac

To keep a wrapping script or CI step from being interrupted while still surfacing the error on stderr, add --soft-fail, which forces exit code 0 even when --fail-on (or any other error) would otherwise fail the command:

# Record findings and never break the pipeline, even on critical findings
vigolium scan -t $TARGET_URL --fail-on critical --soft-fail --format jsonl -o results.jsonl

If you need finer control than a single severity threshold, fall back to parsing JSONL with jq (see below).

Watching a scan from the pipeline (--events ndjson)

A CI scan is opaque until it finishes. --events ndjson streams one JSON object per line to stdout while the scan runs, leaving the human console on stderr — so a log collector or a progress reporter can read structured events with 2>/dev/null and get zero non-JSON lines:

vigolium scan -t "$TARGET_URL" --events ndjson 2>/dev/null | tee events.ndjson | jq -c 'select(.type=="finding.new")'

The types you’ll care about in CI:

Type	Use it for
scan.started	The canonical phases[] the aliases resolved to, the db_path to query afterwards, and the pace that actually applied
phase.progress	Liveness — requests_sent every 5s distinguishes a working crawl from a wedged one, so a job can time out on real evidence
waf.block	The edge started filtering. Results for that host are incomplete — don’t publish a thin surface as a clean bill of health
finding.new	Metadata as findings land, for streaming to a dashboard
scan.finished	Terminal: status, findings_by_severity, records_written

Three contracts worth building on: every line carries scan_uuid (a sweep is several invocations), v is the event-schema version, and scan.finished is always last — including status:"interrupted" on SIGINT/SIGTERM. Its absence means the process was killed outright (SIGKILL can’t be caught), which is exactly what a CI timeout looks like; treat a stream that stops without a terminal event as a hard kill, not a completed scan.

--events is refused under -P/--parallel. Each child’s stdout is captured to its own per-target console log, so the parent’s stdout — the one you’re reading — would receive nothing. Refusing beats silently producing an empty stream.

JSONL Output for Parsing

Use jq to filter findings by severity:

# Fail the build only on high/critical findings
HIGH_COUNT=$(jq -s '[.[] | select(.severity == "high" or .severity == "critical")] | length' results.jsonl)

if [ "$HIGH_COUNT" -gt 0 ]; then
  echo "Found $HIGH_COUNT high/critical severity findings"
  jq 'select(.severity == "high" or .severity == "critical")' results.jsonl
  exit 1
fi

Extract a summary of findings:

jq '{name: .name, severity: .severity, url: .url}' results.jsonl

GitHub code scanning (SARIF)

--format sarif writes a SARIF 2.1.0 log, so findings land in the repository’s Security → Code scanning tab instead of only in build output. Code findings anchor to a file and line, which is what lets GitHub annotate them onto the pull-request diff; HTTP findings anchor to their URL and carry the proof exchange in the standard webRequest/webResponse fields.

- name: Vigolium scan
  run: vigolium scan -S -t "$TARGET_URL" --format sarif -o results.sarif --soft-fail

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Combine it with the other formats in one run — the scan is executed once and each format is materialized from the same result set:

vigolium scan -S -t "$TARGET_URL" --format sarif,html,jsonl -o results
# → results.sarif  results.html  results.jsonl

Use --soft-fail (or run the upload with if: always()) when you also pass --fail-on, so a failing gate still publishes the SARIF before the job exits non-zero. Findings carry a stable partialFingerprints hash, so GitHub tracks one alert across re-scans rather than reopening it every run.

The same format is available on stored data — vigolium export --format sarif -o project.sarif — and on vigolium import --format sarif, which is the path for publishing an agentic source audit into code scanning.

With Source Code (Agent Mode)

Source-aware analysis lives in agent mode now. When the source code is available in the CI workspace, run an AI-driven swarm with --source for route extraction and AI-generated extensions:

vigolium agent swarm -t $TARGET_URL --source . --intensity quick \
  --format jsonl -o results.jsonl

This is particularly effective in CI because the source code is always present in the checkout directory.

Agent Mode in CI

Code Review (Query)

Run an AI-powered security code review on the current source tree, single LLM call, predictable runtime:

vigolium agent query --prompt-template security-code-review --source . --json

This produces structured JSON output with findings that can be parsed and posted as PR comments.

Diff-Focused Review (Autopilot)

Focus on changed code only, perfect for PR gates:

# GitHub PR diff (auto-fetches changed files via REST API)
vigolium agent autopilot -t $TARGET_URL --source . \
  --diff "https://github.com/$GITHUB_REPOSITORY/pull/$PR_NUMBER" \
  --intensity quick

# Last N commits
vigolium agent autopilot -t $TARGET_URL --source . --last-commits 5 --intensity quick

Full-Scope Swarm with Discovery

For a more thorough AI-driven scan with automatic endpoint discovery:

vigolium agent swarm -t $TARGET_URL --discover --intensity balanced --max-duration 20m

The --max-duration flag ensures the scan does not run indefinitely in CI. Swarm coordinates planning, native scanning, and optional triage with --triage.

Docker

Run a scan in a container:

docker run --rm vigolium scan -t $TARGET_URL --strategy lite --format jsonl

For scans that require source code access, mount the workspace:

docker run --rm -v $(pwd):/workspace vigolium scan -t $TARGET_URL --source /workspace --format jsonl

Tips

• Keep scans fast: Use --strategy lite and --skip spidering in CI to avoid long-running browser-based crawling. Save deep scans for staging or nightly runs.
• Set timeouts: Always use --timeout in CI to prevent scans from blocking the pipeline indefinitely.
• Cache the binary: Download and cache the Vigolium binary in your CI cache (e.g., GitHub Actions cache, GitLab CI cache) to avoid re-downloading on every run.
• Use projects: Create a dedicated project for CI scans with vigolium project create ci-scans to keep findings organized and track trends across builds.
• Incremental scanning: When scanning the same target repeatedly, previous scan data in the project can help Vigolium avoid redundant checks.
• Secrets management: Pass API keys and authentication tokens via environment variables rather than hardcoding them in CI config files. Use --header "Authorization: Bearer $API_TOKEN" at runtime.