Quick Start

This guide walks through initializing a project, running your first scan, and acting on the results.

Initialize Configuration

From your project root:

vaultguard init

This creates a .vaultguard.toml configuration file and adds .vaultguard/ to your .gitignore. The default configuration enables secret detection, CVE scanning, and misconfiguration checks.

You can skip this step

VaultGuard works without a config file. Defaults are sensible for most projects. Use init when you want to customize scan behavior.

Run Your First Scan

Scan the current directory:

vaultguard scan

Scan a specific path:

vaultguard scan ./src

Understanding the Output

By default, VaultGuard shows a condensed view: the top 5 findings ranked by severity, followed by a summary.

  vaultguard scan

  Critical  AWS Access Key found in src/config.py:12
  Critical  Database connection string in lib/db.ts:8
  High      Hardcoded API token in utils/auth.js:45
  High      CVE-2024-29041 in express@4.18.2 (Cargo.lock)
  Medium    Debug mode enabled in config/settings.yaml:3

  Scan complete: 14 findings (2 critical, 5 high, 4 medium, 3 low)
  Results saved to .vaultguard/results/latest.json

  Run vaultguard fix for remediation guidance.

The summary line shows the total count across all severity levels, not just the top 5 displayed.

Where are the rest of my findings?

The condensed view only shows the top 5. Use vaultguard scan -v for verbose mode to see every finding with full details, or --json to get the complete machine-readable output.

Verbose Output

For detailed per-finding output with file context, use verbose mode:

vaultguard scan -v

Verbose mode prints every finding with its location, severity, provider, and description as the scan runs.

Machine-Readable Output

For CI pipelines or tooling integration:

vaultguard scan --json     # JSON to stdout
vaultguard scan --sarif    # SARIF to stdout

JSON and SARIF modes skip auto-save and print directly to stdout. Redirect to a file as needed:

vaultguard scan --sarif > results.sarif

SARIF for GitHub Code Scanning

SARIF output integrates directly with GitHub's Code Scanning feature. Upload results with the github/codeql-action/upload-sarif action to see findings inline on pull requests. See CI/CD Integration for a complete workflow.

View Remediation Guidance

After a scan, VaultGuard auto-saves results to .vaultguard/results/latest.json. The fix command reads these results and generates actionable remediation steps:

vaultguard fix

Output is grouped by finding type (secrets, CVEs, misconfigurations) with provider-aware guidance. For example, an AWS key finding includes steps to rotate the key via IAM, while a CVE finding shows the fixed package version.

To read a specific results file:

vaultguard fix --file .vaultguard/results/latest.json

For machine-readable remediation output:

vaultguard fix --json

Exit Codes

VaultGuard uses exit codes for CI integration:

Code	Meaning
0	No findings
1	Findings detected
2	Scan or runtime error
3	Authentication required
4	Invalid configuration

Exit code 1 means findings, not failure

A common gotcha in CI: exit code 1 means "findings detected", not "something broke". If your pipeline fails on a VaultGuard scan, check the output for actual findings before debugging infrastructure.

A typical CI check:

vaultguard scan || exit 1

Next Steps

Configure ignore rules. Suppress false positives or accepted risks with .vaultguard.ignore:

vaultguard ignore init
vaultguard ignore add --reason "test fixture" --path "tests/fixtures/*"

Set up a baseline. Lock in existing findings so future scans only flag new issues. Add inline suppression comments directly in source:

password = "test-only-value"  # vaultguard-ignore:secret

Add to CI. Use --json or --sarif output with exit code checks in your pipeline. VaultGuard reads configuration from environment variables prefixed with VAULTGUARD_*, so no config files are required in CI.

Adjust scan modules. Enable or disable specific detectors per scan:

vaultguard scan --no-secrets          # Skip secret detection
vaultguard scan --no-cve              # Skip CVE scanning
vaultguard scan --quality             # Enable code quality checks
vaultguard scan --integrity           # Enable integrity verification
vaultguard scan --typosquat           # Enable typosquatting detection

See the CLI Reference for the full list of flags and configuration options.