Documentation

Install it, configure it, and run it.

01 Quick start

Install

Pick a method. foxguard has no runtime dependencies.

Run your first scan

terminal

# 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.

02 Configuration reference

Drop a .foxguard.yml in your project root to customize behavior. Every field is optional, and foxguard runs with zero config.

.foxguard.yml

# Minimum severity to report (low | medium | high | critical)
severity: medium

# Paths to exclude from scanning (glob patterns)
exclude:
  - "vendor/**"
  - "node_modules/**"
  - "**/*.test.ts"
  - "migrations/**"

# Rules to disable by ID
disable:
  - py-hardcoded-secret    # Handled by vault integration
  - go-md5-usage           # Legacy checksums, not security-critical

# Output format (terminal | json | sarif)
format: terminal

# Enable post-quantum crypto audit
pqc: false

# Enable secrets scanning
secrets: true

# Baseline branch for diff-only mode
# baseline: main

# Maximum file size to scan (bytes)
max-file-size: 1048576

# Number of threads (0 = auto-detect)
threads: 0

CLI flags override config

Every config option has a matching CLI flag, and flags win over .foxguard.yml. Run foxguard --help for the full list.

03 GitHub App setup

foxguard scans every PR automatically, with no CI wiring. Install the app and findings land as PR comments in seconds.

Install the app

Go to github.com/apps/foxguard-app and select the repos you want scanned.

Open a PR

foxguard scans the PR head ref. Most repos finish in under a second. Results post as a PR comment.

Fix and merge

Push fixes and the scan re-runs automatically. A clean scan posts a clean comment. There is nothing to configure.

Self-hosting

For air-gapped or regulated environments, self-host the webhook receiver. Register your own GitHub App, point its webhook URL at your instance, and deploy with Docker:

docker run --rm -p 8080:8080 \
  -e FOXGUARD_WEBHOOK_SECRET=$(openssl rand -hex 32) \
  ghcr.io/0sec-labs/foxguard-github-app:latest

See the GitHub App page for more details.

04 VS Code extension

See findings inline as you code. Install from the Visual Studio Marketplace or the command line:

terminal

code --install-extension 0sec-labs.foxguard

Real-time diagnostics

Findings appear as squiggly underlines with severity-colored markers. Hover for details, CWE links, and fix suggestions.

Quick-fix actions

Suppress a finding with an inline comment directly from the lightbulb menu. Supports per-line and per-file suppression.

05 CI/CD integration

foxguard exits 1 on findings, so gating merges is trivial. Use SARIF output for GitHub Code Scanning, GitLab SAST, and other platforms.

GitHub Actions

.github/workflows/foxguard.yml

name: foxguard
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install foxguard
        run: curl -fsSL https://foxguard.dev/install.sh | sh

      - name: Run scan
        run: foxguard . --format sarif -o results.sarif

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Alternatively, use the GitHub App, which does this automatically with no workflow file needed.

GitLab CI

.gitlab-ci.yml

foxguard:
  stage: test
  image: rust:latest
  before_script:
    - curl -fsSL https://foxguard.dev/install.sh | sh
  script:
    - foxguard . --format json -o gl-sast-report.json
  artifacts:
    reports:
      sast: gl-sast-report.json
    when: always

Any CI system

terminal

# Install
curl -fsSL https://foxguard.dev/install.sh | sh

# Scan and fail the build if findings exist
foxguard . --severity high
# exit code 1 = findings found, exit code 0 = clean

06 Suppression guide

Suppress false positives and pick the scope that fits.

Inline comments

Add a foxguard-ignore comment on the line above a finding to suppress it. Optionally specify the rule ID.

example.py

# foxguard-ignore: py-hardcoded-secret — rotated via vault
API_KEY = "sk-test-placeholder"

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

Config-based disable

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

.foxguard.yml

disable:
  - py-hardcoded-secret
  - go-md5-usage

Path exclusion

Exclude entire directories or file patterns from scanning.

.foxguard.yml

exclude:
  - "vendor/**"
  - "testdata/**"
  - "**/*_test.go"
  - "legacy/**"

Baseline / diff-only mode

Report only findings introduced since a baseline branch. Adopt foxguard on an existing codebase without drowning in pre-existing issues.

terminal

# Only show findings not present on main
foxguard diff main

TUI triage

Review findings one by one in the terminal UI, suppress with a keybinding, or export what remains.

terminal

foxguard tui .

07 Output formats

Terminal (default)

Human-readable output with colors, file paths, line numbers, and fix suggestions.

foxguard .

JSON

Machine-readable findings for scripts, dashboards, or custom integrations.

foxguard . --format json

SARIF

Standard format for GitHub Code Scanning, GitLab SAST, and other security platforms.

foxguard . --format sarif

08 Post-quantum crypto audit

Audit your codebase for crypto primitives that quantum computers will break, mapped to NSA CNSA 2.0 timelines. The transition deadlines are close.

What gets flagged

→RSA: key exchange, signing, encryption (all key sizes)
→ECDSA / ECDH: elliptic curve operations (P-256, P-384, etc.)
→DH: classic Diffie-Hellman key exchange
→DSA: Digital Signature Algorithm

PQC audit

foxguard pqc .

CBOM generation

foxguard pqc . --format cbom --output cbom.json

The CBOM (Cryptographic Bill of Materials) inventories every crypto primitive in your codebase for compliance reporting and for tracking your migration to post-quantum algorithms.

Questions?

Open an issue or check the README for more details.

GitHub repo Compare with Semgrep