Configuration

VaultGuard uses a layered configuration system. Settings are resolved in this priority order (highest wins):

1. CLI flags (e.g., --no-secrets, --entropy-threshold 6.0)
2. Environment variables (e.g., VAULTGUARD_NO_SECRETS=true)
3. Project config (.vaultguard.toml in the project root)
4. User config (~/.vaultguard/config.toml)
5. Built-in defaults

Start with the defaults

VaultGuard's defaults are tuned for most projects. You only need a config file when you want to customize behavior. Run vaultguard config show at any time to see what the merged config looks like.

Config Files

Project Config

Create a .vaultguard.toml in your project root:

vaultguard init

This generates a config file with sensible defaults. The file is read by both the CLI and the core scanning engine.

User Config

Place a config.toml at ~/.vaultguard/config.toml for settings that apply to all projects. The project config overrides any overlapping user-level settings.

When to use a user config

User configs are useful for personal preferences like verbose = true or a custom entropy threshold. Team-shared settings should live in the project .vaultguard.toml and be committed to version control.

Config Keys

Key	Type	Default	Description
enable_secrets	bool	true	Detect hardcoded secrets and credentials
enable_cve	bool	true	Detect known vulnerabilities in dependencies
enable_misconfig	bool	true	Detect security misconfigurations
enable_quality	bool	false	Flag code quality issues
enable_integrity	bool	false	Verify lockfile-to-installed-package integrity
enable_typosquat	bool	false	Detect typosquatting in dependency names
entropy_threshold	float	5.5	Shannon entropy threshold for secret detection. Core default is 4.5; the CLI overrides to 5.5 to reduce false positives. Lower values catch more, higher values are stricter.
max_file_size	int	10485760	Maximum file size in bytes to scan (10 MB)
context_filtering	bool	true	Skip findings in test files and example/placeholder variables
exclude_patterns	list	See below	File patterns excluded from scanning
format	string	"human"	Default output format (human, json, sarif)
verbose	bool	false	Enable verbose output by default

Example .vaultguard.toml

A typical config for a Node.js project that also wants quality checks:

# VaultGuard configuration
enable_secrets = true
enable_cve = true
enable_misconfig = true
enable_quality = true
enable_integrity = false
entropy_threshold = 5.5
max_file_size = 10485760
context_filtering = true

exclude_patterns = [
    "package-lock.json",
    "yarn.lock",
    "pnpm-lock.yaml",
    "Cargo.lock",
    "Gemfile.lock",
    "composer.lock",
    "poetry.lock",
    "Pipfile.lock",
    "bun.lockb",
    "*.min.js",
    "*.min.css",
    "dist/",
    "vendor/",
]

Default Exclude Patterns

The CLI automatically excludes lockfiles and minified assets that generate noise without actionable findings:

• package-lock.json
• yarn.lock
• pnpm-lock.yaml
• Cargo.lock
• Gemfile.lock
• composer.lock
• poetry.lock
• Pipfile.lock
• bun.lockb
• *.min.js
• *.min.css

Why are lockfiles excluded?

Lockfiles often contain hash strings and version identifiers that trigger false positives in entropy-based secret detection. CVE scanning reads lockfiles separately through the dependency resolution pipeline, so excluding them from the general scan doesn't affect vulnerability detection.

These patterns are merged with any exclude_patterns you define in your config. If you set exclude_patterns in .vaultguard.toml, the CLI defaults are still appended unless the pattern is already present.

Environment Variables

Every CLI flag has a corresponding environment variable. Useful in CI or when you want per-session overrides without modifying config files.

Variable	Equivalent Flag
VAULTGUARD_FORMAT	--format
VAULTGUARD_VERBOSE	-v
VAULTGUARD_NO_SECRETS	--no-secrets
VAULTGUARD_NO_CVE	--no-cve
VAULTGUARD_NO_MISCONFIG	--no-misconfig
VAULTGUARD_QUALITY	--quality
VAULTGUARD_INTEGRITY	--integrity
VAULTGUARD_TYPOSQUAT	--typosquat
VAULTGUARD_ENTROPY_THRESHOLD	--entropy-threshold
VAULTGUARD_MIN_SEVERITY	--min-severity
VAULTGUARD_MIN_CONFIDENCE	--min-confidence
VAULTGUARD_DISABLE_PROVIDER	--disable-provider
VAULTGUARD_BASELINE	--baseline

Validate and Inspect

Check your config file for syntax errors:

vaultguard config validate

View the fully merged config (user + project + defaults) as it would be applied:

vaultguard config show

Debugging config issues

If a scan isn't behaving as expected, run vaultguard config show to see exactly which values are active. This shows the result of merging all config layers and helps identify where an unexpected override is coming from.

Entropy Threshold

The entropy threshold controls how aggressively VaultGuard flags high-entropy strings as potential secrets. Core defaults to 4.5, but the CLI overrides this to 5.5 to reduce false positives on variable names and generated IDs.

• Lower values (e.g., 4.0): more findings, more false positives
• Higher values (e.g., 6.5): fewer findings, fewer false positives

Tuning entropy requires experimentation

There is no universal "right" threshold. Start with the default (5.5), review your findings, and adjust. If you see too many false positives on UUIDs or hashes, increase the threshold. If real secrets are slipping through, lower it.

Override per-scan:

vaultguard scan --entropy-threshold 4.0

Or set in config:

entropy_threshold = 6.0