⚙️ Configuration

Configuration Hierarchy

Guardy uses a layered configuration system with clear precedence (highest to lowest):

┌─────────────────────────────────────┐
│      1. CLI Flags (Highest)         │  guardy scan --max-file-size 5
├─────────────────────────────────────┤
│    2. Environment Variables         │  GUARDY_SCAN_MAX_THREADS=8
├─────────────────────────────────────┤
│    3. Config Files (Deep Merged)    │
│       ┌─────────────────────────┐   │
│       │ Project: ./.guardy.yml  │   │  (highest priority)
│       ├─────────────────────────┤   │
│       │ Git ancestry: ../*.yml  │   │  (walk up to git root)
│       ├─────────────────────────┤   │
│       │ User: ~/.config/*.yml   │   │
│       ├─────────────────────────┤   │
│       │ System: /etc/.yml       │   │  (lowest priority)
│       └─────────────────────────┘   │
├─────────────────────────────────────┤
│    4. Built-in Defaults (Lowest)    │
└─────────────────────────────────────┘

How it works:

Settings at higher levels override lower levels
Config files are deep merged (nested objects combine, primitives override)
First matching file at each level is used

File Discovery

File Naming Priority

Guardy searches for config files following these priorities:

Format Priority:  JSON  >  YAML  >  TOML
Name Priority:    .guardy.*  >  guardy.*

Files checked (first match wins):
  1. .guardy.json     ← Highest priority
  2. guardy.json
  3. .guardy.yaml
  4. .guardy.yml
  5. guardy.yaml
  6. guardy.yml
  7. .guardy.toml
  8. guardy.toml      ← Lowest priority

Search Locations

Guardy walks up the directory tree searching for config files:

📁 Current Project
│
├─ 1️⃣  ./.guardy.yml              (Project config - highest priority)
│
├─ 2️⃣  ../../.guardy.yml          (Git ancestry - walk up to root)
│
├─ 3️⃣  ~/.config/.guardy.yml      (User config)
│
└─ 4️⃣  /etc/.guardy.yml           (System config - lowest priority)

How it works: Guardy finds the first matching file at each location, then deep merges them with project configs overriding user/system configs.

Config Merging

Config files are deep merged, not replaced. Nested objects merge recursively, primitive values override:

# /etc/.guardy.yml (system)
scanner:
  max_file_size_mb: 10
  include_binary: false

# ~/.config/.guardy.yml (user)
scanner:
  max_file_size_mb: 5  # Overrides system
  entropy_threshold: 0.00001  # Adds new setting

# ./.guardy.yml (project)
scanner:
  include_binary: true  # Overrides user/system

# Final merged config:
# scanner:
#   max_file_size_mb: 5 (from user)
#   include_binary: true (from project)
#   entropy_threshold: 0.00001 (from user)

Environment Variables

Every config option can be overridden with environment variables:

# General
export GUARDY_VERBOSE=true
export GUARDY_QUIET=false
export GUARDY_DEBUG=true
export GUARDY_COLOR=auto

# Scanner
export GUARDY_SCAN_MAX_THREADS=8
export GUARDY_SCAN_MAX_SIZE=10
export GUARDY_SCAN_ENTROPY_ENABLED=true

# Hooks
export GUARDY_HOOKS_SKIP_ALL=false
export GUARDY_HOOKS_PARALLEL=true

# Sync
export GUARDY_SYNC_ENABLED=true

Override Config Path

# Use custom config file
guardy --config /path/to/custom.yml scan

# Or via environment
export GUARDY_CONFIG=/path/to/custom.yml
guardy scan

Disable Recursive Discovery

# Only use specified config, no hierarchy
guardy --recursive-config=false scan

# Or via environment
export GUARDY_RECURSIVE_CONFIG=false

Configuration Sections

Scanner

Secret scanning configuration. See Scanner Configuration for details.

scanner:
  max_file_size_mb: 10
  include_binary: false
  entropy_threshold: 0.00001
  max_threads: 0  # auto-detect

Hooks

Git hooks configuration. See Hooks for details.

hooks:
  pre-commit:
    builtin: ["scan_secrets"]
    parallel: true
    commands:
      format:
        run: dprint fmt
        glob: ["*.{ts,js,json,md}"]
        stage_fixed: true

Sync

File synchronization configuration. See Sync Configuration for details.

sync:
  enabled: true
  source: "https://github.com/org/guardy-config"
  files:
    - ".guardy.yml"
    - "hooks/"

General

Global settings:

general:
  verbose: false
  quiet: false
  debug: false
  color: auto  # auto, always, never
  interactive: true

Complete Example

# .guardy.yml

general:
  verbose: false
  color: auto

scanner:
  max_file_size_mb: 10
  include_binary: false
  entropy_threshold: 0.00001
  exclude:
    - "node_modules/**"
    - "target/**"
  allowlist:
    strings:
      - "example_key_for_docs"

hooks:
  pre-commit:
    builtin: ["scan_secrets"]
    parallel: true
    commands:
      format:
        run: dprint fmt
        glob: ["*.{ts,js,json,md}"]
        stage_fixed: true

      lint:
        run: cargo clippy
        glob: ["*.rs"]

  commit-msg:
    builtin: ["conventional_commits"]

  pre-push:
    commands:
      test:
        run: cargo test
        fail_on_error: true

sync:
  enabled: true
  source: "https://github.com/org/guardy-config"
  files:
    - ".guardy.yml"
    - "hooks/"

Validation

Check your configuration:

# Show merged configuration
guardy config show

# Show configuration with sources
guardy config show --show-source

# Validate configuration
guardy config validate

⚙️ Configuration

On this page