> ## 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.

# 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:

```bash theme={null}
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`:

```bash theme={null}
# 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**.
* It works on `scan`, `scan-url`, `scan-request`, and `run`.

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:

```bash theme={null}
# 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).

## JSONL Output for Parsing

Use `jq` to filter findings by severity:

```bash theme={null}
# 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:

```bash theme={null}
jq '{name: .name, severity: .severity, url: .url}' results.jsonl
```

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
docker run --rm vigolium scan -t $TARGET_URL --strategy lite --format jsonl
```

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

```bash theme={null}
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.