Baselines

Baselines let you accept existing findings in a codebase and only alert on new ones. This is useful when adopting VaultGuard on a project with pre-existing issues that cannot be fixed immediately.

How It Works

A baseline file (.vaultguard-baseline.json) contains SHA256 fingerprints of finding messages. When scanning with a baseline, any finding whose fingerprint matches the baseline is marked as suppressed. Fingerprints are derived from the finding message content, not line numbers, so findings survive code reformatting and minor refactors.

Line-number independent

Unlike ignore rules that match on file path and line number, baseline fingerprints are based on the finding message itself. You can refactor and reformat code without breaking your baseline.

Generate a Baseline

Run a full scan and save the current findings as your baseline:

vaultguard baseline generate

This scans the current directory, generates fingerprints for all findings, and writes them to .vaultguard-baseline.json in the project root.

Specify a different scan path or output location:

vaultguard baseline generate /path/to/project -o baseline.json

Example output:

Scanning /home/user/myproject to generate baseline...
Baseline generated: 23 findings from 847 files
Saved to /home/user/myproject/.vaultguard-baseline.json

Use vaultguard scan --baseline /home/user/myproject/.vaultguard-baseline.json to scan against this baseline.

Scan With a Baseline

Pass the baseline file to scan:

vaultguard scan --baseline .vaultguard-baseline.json

Or set via environment variable:

export VAULTGUARD_BASELINE=.vaultguard-baseline.json
vaultguard scan

Baselined findings are suppressed from output by default. The scan summary still reports suppressed counts:

12 issues found (2 critical, 4 high, 6 medium)
Files scanned: 847 | Skipped: 12 | Duration: 2.3s
23 suppressed

Show Suppressed Findings

To include baseline-suppressed findings in the output:

vaultguard scan --baseline .vaultguard-baseline.json --show-suppressed

Recommended Workflow

1. Generate a baseline on your current codebase:

   vaultguard baseline generate

2. Commit the baseline file:

   git add .vaultguard-baseline.json
   git commit -m "Add VaultGuard scan baseline"

3. Configure CI to scan with the baseline (see CI/CD Integration):

   vaultguard scan --baseline .vaultguard-baseline.json

   New findings trigger a non-zero exit code. Baselined findings do not.

4. As your team fixes existing issues, regenerate the baseline to shrink it:

   vaultguard baseline generate
   git add .vaultguard-baseline.json
   git commit -m "Update baseline after fixing 8 findings"

Keep your baseline fresh

A stale baseline masks fixed findings and inflates the suppressed count. Regenerate after each batch of fixes so the baseline accurately reflects what's still accepted.

Baseline vs. Ignore Rules

Feature	Baseline	Ignore Rules
Scope	All findings from a point-in-time scan	Specific files/lines
Fingerprint	SHA256 of finding message (line-number independent)	File path + optional line number
Typical use	Onboarding VaultGuard onto an existing codebase	Permanent exceptions for known-safe patterns
Maintenance	Regenerate as findings are fixed	Manual rule management

Which one should I use?

Baselines for "adopt now, fix later" workflows where you want to suppress everything existing and only catch new issues. Ignore rules for permanent exceptions like test fixtures or documentation examples that should never trigger findings.