Exit Codes

VaultGuard uses exit codes to communicate scan results and error conditions. This is essential for CI/CD integration where pipeline behavior depends on the exit status of each step.

Reference

Code	Meaning	Description
0	No findings	Scan completed successfully. No security issues detected.
1	Findings detected	Scan completed successfully. One or more security issues found.
2	Runtime error	Scan failed due to an I/O error, invalid arguments, or an internal error.
3	Authentication required	The command requires authentication. Run vaultguard login first.
4	Invalid configuration	The .vaultguard.toml file contains syntax errors or invalid values.

Exit code 1 is not an error

Exit code 1 means VaultGuard found security issues, not that something went wrong. This is by design -- it lets CI systems fail the build when findings are present without any additional scripting.

CI/CD Usage

In most CI/CD systems, any non-zero exit code fails the pipeline step. Since VaultGuard returns 1 when findings are detected, a scan with results will fail your build by default. This is usually the desired behavior for security gates.

Fail on findings (default behavior)

# GitHub Actions
- name: Security scan
  run: vaultguard scan --sarif -o results.sarif

If findings exist, the step exits 1 and the workflow fails.

Continue on findings

If you want to collect results without failing the pipeline (e.g., for reporting only), suppress the exit code:

# GitHub Actions
- name: Security scan
  run: vaultguard scan --sarif -o results.sarif || true

Use continue-on-error in GitHub Actions

Instead of || true, you can use continue-on-error: true on the step. This preserves the exit code in the step status while letting the workflow continue.

Fail only on critical/high findings

Use --min-severity to ignore lower-severity findings. The scan returns 0 if no findings remain after filtering:

- name: Security scan (critical + high only)
  run: vaultguard scan --min-severity high

Distinguish errors from findings

Check the specific exit code to handle errors differently from findings:

vaultguard scan
EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "Clean scan" ;;
  1) echo "Findings detected -- review results" ;;
  2) echo "Scan error -- check configuration" ; exit 1 ;;
  4) echo "Invalid config -- fix .vaultguard.toml" ; exit 1 ;;
  *) echo "Unexpected exit code: $EXIT_CODE" ; exit 1 ;;
esac

Jenkins

sh(script: 'vaultguard scan --sarif -o results.sarif', returnStatus: true)
def exitCode = sh(script: 'echo $?', returnStdout: true).trim().toInteger()
if (exitCode == 2) {
    error("VaultGuard scan failed with a runtime error")
}

GitLab CI

security_scan:
  script:
    - vaultguard scan --sarif -o results.sarif
  allow_failure:
    exit_codes:
      - 1  # Findings detected is non-blocking