Documentation

Install

Pick a method. foxguard has no runtime dependencies.

Run your first scan

# Scan the current directory
foxguard .

# Scan with JSON output
foxguard . --format json

# Scan with SARIF output (for CI/CD)
foxguard . --format sarif -o results.sarif

# Scan only changed files (diff mode)
foxguard diff main

# Post-quantum crypto audit
foxguard pqc .

# Generate a Cryptographic Bill of Materials
foxguard pqc . --format cbom --output cbom.json

# Interactive triage mode
foxguard tui .

What to expect

foxguard scans source for vulnerabilities, hardcoded secrets, and weak or pre-quantum crypto. Findings print to stdout, grouped by severity. Exit 0 means clean and exit 1 means findings, so you can gate CI on it.

Inline comments

Add a foxguard: ignore[rule/id] comment on the finding line or the line above it. Omit the brackets to suppress all rules on that line. Suppress only after reviewing the finding.

# foxguard: ignore[py/no-hardcoded-secret] — reviewed test fixture
API_KEY = "sk-test-placeholder"

# foxguard: ignore — suppress all rules on the next line
password = get_config("db_password")

Config-based disable

Disable rules globally in .foxguard.yml when they don't apply to your project.

scan:
  disable_rules:
    - py/no-hardcoded-secret
    - go/no-weak-crypto

Path exclusion

Use repeatable --exclude flags for directory prefixes or glob patterns, or your repository's .gitignore.

foxguard --exclude "vendor/**" \
  --exclude "testdata/**" \
  --exclude "**/*_test.go" \
  --exclude "legacy/**" .

Saved baselines and Git diff

A saved baseline is a JSON snapshot; Git diff compares against a branch. CLI baseline scans suppress matching findings. Terminal review keeps them available and separates introduced, recurring, and resolved entries.

# Save the current findings
foxguard baseline --output .foxguard/baseline.json .

# Report findings not in the saved baseline
foxguard --baseline .foxguard/baseline.json .

# Review current findings alongside baseline history
foxguard tui --baseline .foxguard/baseline.json .

# Independently compare against a Git branch
foxguard diff main .

Resolved means not reported under the current scope, rules, and filters—not verified fixed. Compare equivalent scan settings. Baseline identity includes file and source location; moving a finding can appear as introduced plus resolved. Historical entries do not contain current source context.

TUI triage

Choose Scan, Diff, Secrets, or PQC, then review findings without leaving the terminal. Wide screens show a split view; use the detail toggle on smaller screens.

foxguard tui .

• v expands detail; PageUp/PageDown scroll source context, dataflow, and fixes. Esc returns to the list.
• Enter or o opens the selected finding/source/sink using a nonblank VISUAL, then EDITOR, or an installed terminal editor (nvim, vim, nano, vi). Headless terminals do not require xdg-open. For example, set VISUAL="nvim" or EDITOR="code --wait". Missing or invalid editors leave the TUI open with setup guidance.
• / edits search, Enter applies it, and Ctrl+U clears the draft. Esc cancels edits and restores the prior query; outside editing or expanded detail, Esc clears filters.
• 0–4 set minimum severity, c cycles confidence, and Shift+C changes sorting.
• f cycles All, Unreviewed, Todo, Reviewed, and Ignore. The list shows visible/total counts and review progress.
• i opens single-finding triage. Review marks persist in per-user storage, scoped to the canonical project root and scan mode; baseline and configuration actions change repository files.
• Space checks a finding; a toggles visible selections. Hidden selections remain selected. x opens a batch preview with exact targets, hidden counts, destination, and rule/file or project-wide effects. Only y applies it; Esc cancels without writing. Successful configuration writes are not rolled back if another target fails.
• Shift+F manages named search, severity, confidence, review, sort, and baseline filters. In that menu, Enter loads, s saves, and d confirms deletion. Replacement requires confirmation.
• Storage errors leave changes visibly UNSAVED rather than silently clobbering another terminal. Shift+F provides w to retry, r to confirm reloading, and Shift+R to confirm backing up the on-disk review file and resetting this project/mode. Reload/reset discards unsaved changes; unsaved marks are not included in the backup.
• With --baseline, b cycles all current, introduced, recurring, and resolved entries. Resolved means absent under the current scan scope—not verified fixed. Historical rows are read-only, support search and expanded detail, and have no saved source, severity, or confidence. Switch to current findings to triage or export.
• e exports all current scan results—not just filtered rows—to CBOM, JSON, or SARIF in the working directory. Existing reports require y to replace; Esc cancels. Symlinks are rejected.
• ? opens scrollable help. Ctrl+C quits from any view, including search and confirmation dialogs.
• The loading card shows indeterminate activity and actual elapsed time. Ctrl+C also exits during scanning.