CI/CD Integration

VaultGuard is designed for CI pipelines. It uses exit codes for pass/fail gating, supports machine-readable output formats, and can be configured entirely through environment variables.

No config files needed in CI

VaultGuard reads all settings from VAULTGUARD_* environment variables. You can configure scans entirely through your CI environment without committing config files.

Exit Codes

Code	Meaning
0	No findings detected (clean scan)
1	Findings detected
2	Scan error (invalid config, path not found, runtime failure)

A scan that finds issues exits with code 1, which fails most CI steps by default. This is the intended behavior -- findings should block the pipeline.

GitHub Actions

Full workflow that installs VaultGuard, runs a scan, and uploads SARIF results to GitHub Code Scanning:

name: Security Scan
on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main]

jobs:
  vaultguard:
    runs-on: ubuntu-latest
    permissions:
      security-events: write  # required for SARIF upload
    steps:
      - uses: actions/checkout@v4

      - name: Install VaultGuard
        run: curl -sSf https://releases.vaultguard.sh/install.sh | sh

      - name: Run scan (SARIF)
        run: vaultguard scan --sarif --output results.sarif
        continue-on-error: true  # don't fail before uploading SARIF

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

      - name: Run scan (fail on findings)
        run: vaultguard scan

Why scan twice?

The first scan generates SARIF for GitHub Code Scanning and uses continue-on-error so the upload step always runs. The second scan enforces the pass/fail gate. This ensures findings appear in the Code Scanning UI even when the pipeline fails.

Fail Only on High+ Severity

Use --min-severity to ignore low and medium findings:

      - name: Run scan
        run: vaultguard scan --min-severity high

With Baseline

Commit a baseline to your repo and scan against it so only new findings cause failures:

      - name: Run scan with baseline
        run: vaultguard scan --baseline .vaultguard-baseline.json

Baselines for gradual adoption

If you are adding VaultGuard to an existing project, generate a baseline first (vaultguard baseline generate) and commit it. CI will only flag new findings, letting your team fix existing issues at their own pace. See Baselines.

JSON Output for Custom Parsing

Use --json for scripting and custom CI integrations:

      - name: Run scan
        run: |
          vaultguard scan --json > results.json || true
          CRITICAL=$(jq '[.findings[] | select(.severity == "Critical")] | length' results.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "::error::$CRITICAL critical findings detected"
            exit 1
          fi

Environment Variables

All scan flags have environment variable equivalents. This is useful when you want to configure VaultGuard at the job or workflow level without modifying scan commands.

    env:
      VAULTGUARD_FORMAT: json
      VAULTGUARD_MIN_SEVERITY: medium
      VAULTGUARD_ENTROPY_THRESHOLD: "6.0"
      VAULTGUARD_BASELINE: .vaultguard-baseline.json
      NO_COLOR: "1"

Full list of variables:

Variable	Effect
VAULTGUARD_FORMAT	Output format: human, json, sarif
VAULTGUARD_NO_SECRETS	Disable secret detection
VAULTGUARD_NO_CVE	Disable CVE detection
VAULTGUARD_NO_MISCONFIG	Disable misconfiguration detection
VAULTGUARD_QUALITY	Enable code quality checks
VAULTGUARD_INTEGRITY	Enable lockfile integrity verification
VAULTGUARD_TYPOSQUAT	Enable typosquatting detection
VAULTGUARD_ENTROPY_THRESHOLD	Shannon entropy threshold (float)
VAULTGUARD_MIN_SEVERITY	Minimum severity: critical, high, medium, low, info
VAULTGUARD_MIN_CONFIDENCE	Minimum confidence threshold (0.0-1.0)
VAULTGUARD_DISABLE_PROVIDER	Comma-separated providers to skip
VAULTGUARD_BASELINE	Path to baseline file
VAULTGUARD_VERBOSE	Verbosity level (0-3)

Reducing Noise in CI

Minimum Severity

Only fail on high and critical findings:

vaultguard scan --min-severity high

Findings below the threshold are dropped entirely. They do not appear in output or affect the exit code.

Disable Noisy Providers

Entropy and generic pattern matchers can produce false positives. Disable them when you need a clean signal:

vaultguard scan --disable-provider entropy,generic

Start strict, loosen as needed

Begin with all providers enabled and --min-severity high. If specific providers cause too many false positives in your codebase, disable them selectively with --disable-provider.

Available providers: aws, github, gitlab, openai, stripe, supabase, firebase, database, discord, slack, atlassian, vault, jwt, pem, generic, entropy.

Confidence Filtering

Drop low-confidence findings:

vaultguard scan --min-confidence 0.8

GitLab CI

vaultguard-scan:
  image: ubuntu:latest
  script:
    - curl -sSf https://releases.vaultguard.sh/install.sh | sh
    - vaultguard scan --json --output results.json
  artifacts:
    paths:
      - results.json
    when: always

Generic CI

For any CI system, the pattern is the same:

# Install
curl -sSf https://releases.vaultguard.sh/install.sh | sh

# Scan (exit code 1 on findings, 0 on clean)
vaultguard scan

# Or with SARIF for tool integration
vaultguard scan --sarif --output results.sarif

Check the exit code to gate deployments:

vaultguard scan --min-severity high
if [ $? -eq 1 ]; then
  echo "Security findings detected, blocking deployment"
  exit 1
fi