Metadata-Version: 2.4
Name: foxguard
Version: 0.13.1
License-File: LICENSE
License-File: LICENSE-APACHE
Summary: A security scanner as fast as a linter, written in Rust.
Home-Page: https://foxguard.dev
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://foxguard.dev
Project-URL: Issues, https://github.com/0sec-labs/foxguard/issues
Project-URL: Repository, https://github.com/0sec-labs/foxguard

<p align="center">
  <img src="www/public/foxguard-logo.png" width="128" alt="foxguard" />
</p>

<h1 align="center">foxguard</h1>

<p align="center">
  <strong>Fast local security scanning for code, secrets, dependencies, and crypto risk.</strong>
  <br />
  <sub>Integrated into <a href="https://github.com/0sec-labs/0sec">0sec</a>, the open cybersecurity harness.</sub>
</p>

<p align="center">
  <a href="https://github.com/0sec-labs/foxguard/actions/workflows/ci.yml"><img src="https://github.com/0sec-labs/foxguard/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://github.com/0sec-labs/foxguard"><img src="https://img.shields.io/badge/foxguard-clean-3fb950" alt="foxguard: clean" /></a>
  <a href="https://crates.io/crates/foxguard"><img src="https://img.shields.io/crates/v/foxguard?color=d97706&label=crates.io" alt="crates.io" /></a>
  <a href="https://www.npmjs.com/package/foxguard"><img src="https://img.shields.io/npm/v/foxguard?color=d97706&label=npm" alt="npm" /></a>
  <a href="https://github.com/apps/foxguard-app/installations/new"><img src="https://img.shields.io/badge/GitHub_App-Install-2ea44f?logo=github" alt="Install GitHub App" /></a>
</p>

```sh
npx foxguard .
```

<p align="center">
  <img src="assets/demo.gif" alt="foxguard scan demo" width="640" />
</p>

## Why

- <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/checklist.png" alt="">&nbsp; 200+ built-in rules across 12 source languages, plus config and manifest checks
- <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/git-branch.png" alt="">&nbsp; Taint tracking for 14 languages, with cross-file analysis for Python, JavaScript, Go, Java, Ruby, PHP, C#, and Kotlin
- <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/zap.png" alt="">&nbsp; Fast local and CI scans, with diff mode for “what did this branch add?”
- <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/key.png" alt="">&nbsp; Secrets scanning, OSV-backed dependency scanning, and post-quantum crypto audit
- <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/plug.png" alt="">&nbsp; Semgrep/OpenGrep-compatible YAML bridge that loads ~98% of the public registry ([coverage report](docs/parity/registry-coverage.md))
- <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/file-code.png" alt="">&nbsp; Terminal, JSON, SARIF, CycloneDX 1.6 CBOM, and Semgrep-compatible JSON output

## Install

```sh
npx foxguard .                                      # zero install
curl -fsSL https://foxguard.dev/install.sh | sh     # prebuilt binary (macOS/Linux)
cargo install foxguard                              # from source
```

Prebuilt installs verify release binaries against `checksums.txt`. Release binaries also publish GitHub artifact attestations; use `gh attestation verify` for manual verification, or see [release provenance](docs/release-provenance.md).

**GitHub Action:**

```yaml
- uses: 0sec-labs/foxguard/action@v0.13.1
  with:
    path: .
    severity: medium
    fail-on-findings: "true"
    upload-sarif: "true"
```

**pre-commit:**

```yaml
repos:
  - repo: https://github.com/0sec-labs/foxguard
    rev: v0.13.1
    hooks:
      - id: foxguard
```

Integrations: [GitHub App](https://github.com/apps/foxguard-app/installations/new), [VS Code](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard), [Claude Code plugin](docs/claude-code-integration.md), and [MCP server](docs/mcp-server.md).

### Hosted GitHub App operations

`foxguard-github-app` writes newline-delimited JSON logs. Completed and failed
scans use `event=foxguard.scan.completed` and `event=foxguard.scan.failed`, with
delivery, installation, repository, PR, commit, duration, and `usage_scope`
fields for correlation. Keep identifiers as log fields, not metric labels.

Set `FOXGUARD_INTERNAL_ACCOUNTS` to a comma-separated list of your own GitHub
accounts and organizations. Matching is case-insensitive. Other owners are
classified as `external`; an unset list or missing owner produces `unknown`.
External activity is not proof of a paying customer, and scans are not people.

The installation registry is reconciled against all pages of GitHub's App
installation API at startup and hourly. Failed refreshes retain existing state;
concurrent webhooks take precedence. Sparse webhook metadata preserves known
account details and observed repository names. Those names are not a complete
inventory of an installation's accessible repositories.

Persist `FOXGUARD_INSTALLATIONS_PATH` and `FOXGUARD_PULL_REQUEST_JOBS_PATH` on
durable storage. Monitor `foxguard.installations.reconcile_failed` alongside
scan failures; `foxguard.installations.reconciled` reports the total and
internal/external/unknown installation counts after a successful refresh.
Size `FOXGUARD_PR_WORKERS` against measured scanner peak memory and the
container memory limit: child-process OOM kills can occur without restarting
the hosted application.

## Quick Start

```sh
foxguard .                              # scan everything
foxguard diff main .                    # only new findings vs main
foxguard secrets .                      # leaked credentials and keys
foxguard sca .                          # dependency vulnerabilities from OSV
foxguard pqc .                          # post-quantum crypto audit
foxguard --format sarif . > results.sarif
foxguard --format semgrep-json .        # Semgrep CLI-compatible JSON
```

Use `foxguard --fix src/` or `foxguard --fix src/app.py` to apply supported taint
fixes in place. Targets are checked against the canonical scan directory or the
selected file; findings outside that scope are skipped. Python command-injection
fixes add `import subprocess` when needed, preserving module docstrings and future
imports. Review generated changes before committing.

## Language Coverage

| Language | Built-in rules | Taint tracking | Framework-aware rules |
|----------|:-:|:-:|---|
| JavaScript / TypeScript | Yes | Yes | Express, Next.js |
| Python | Yes | Yes | Django, Flask, FastAPI |
| Go | Yes | Yes | Gin |
| Kotlin | Yes | Yes | Spring |
| Java | Yes | Yes | Spring |
| Ruby | Yes | Yes | Rails |
| PHP | Yes | Yes | Laravel |
| Rust | Yes | -- | -- |
| C# | Yes | Yes | .NET |
| Swift | Yes | Yes | iOS |
| Haskell | Yes | -- | Cardano seed rules |

Taint tracking also covers C, Bash, and Solidity. Config, manifest, and external-rule scans cover Dockerfile, Nginx, Apache, HAProxy, HCL/Terraform, YAML/JSON/XML/HTML, C via Semgrep YAML/Coccinelle, and more.

## Security Modes

```sh
foxguard sca .
foxguard pqc .
foxguard --rules ./semgrep-rules .
```

SCA supports `Cargo.lock`, `package-lock.json`, `pnpm-lock.yaml`, `requirements.txt`, `poetry.lock`, and `Pipfile.lock`. The PQC audit is a two-sided scorecard: it flags quantum-vulnerable primitives (RSA, ECDSA/DSA, ECDH/DH) with CNSA 2.0 migration deadlines, and it also detects post-quantum algorithms already in use (ML-KEM, ML-DSA, SLH-DSA, FN-DSA, HQC, and hybrids like X25519MLKEM768) as informational, quantum-resistant inventory — reporting a migration-readiness percentage. Both sides export to a CycloneDX 1.6 CBOM, where post-quantum algorithms appear as quantum-resistant assets rather than vulnerabilities.

## Configuration

foxguard auto-discovers `.foxguard.yml` from the scan path upward.

```yaml
scan:
  baseline: .foxguard/baseline.json
  disable_rules: [py/no-eval]

secrets:
  exclude_paths: [fixtures, testdata]
```

Suppress an accepted finding inline with `// foxguard: ignore[rule-id]`.

## Documentation

Start with the [documentation index](./docs/README.md). Key references: [architecture](./docs/architecture.md), [Semgrep/OpenGrep compatibility](./docs/compatibility.md), and the [release runbook](./docs/releasing.md).

## Benchmarks

| Repo | LoC | foxguard | Semgrep | Speedup |
|------|-----|----------|---------|---------|
| express | 15K JS | 0.28s | 6.09s | **22x** |
| flask | 14K Py | 0.33s | 6.51s | **20x** |
| gin | 18K Go | 0.50s | 4.95s | **10x** |
| sentry | 1.3M Py | 35s | 194s | **5x** |

Reproduce with `./benchmarks/run.sh`; results vary by machine. See [`benchmarks/README.md`](./benchmarks/README.md).

## Contributing

See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for rule authoring, tests, and development setup.

## License

MIT OR Apache-2.0 -- [0sec Labs](https://0sec.ai)

