# foxguard for Claude Code
Live security scanning inside [Claude Code](https://code.claude.com). Every file Claude writes or edits is auto-scanned by [foxguard](https://foxguard.dev) — findings are fed straight back so Claude self-corrects before bad patterns land.
## What you get
- **PostToolUse auto-scan** — every `Write` / `Edit` / `MultiEdit` triggers `foxguard --format json` on the changed file. Medium+ findings are surfaced to Claude on stderr; clean files are silent.
- **SessionStart preamble** — Claude starts each session with foxguard's secure-coding defaults already in context.
- **Slash commands** for on-demand scans:
- `/foxguard:setup` — verify install, set severity threshold
- `/foxguard:scan [path]` — full scan, grouped and triaged by severity
- `/foxguard:diff-scan [base]` — only what this branch introduces vs `main`
- `/foxguard:pq-audit [path]` — post-quantum readiness with CNSA 2.0 deadlines
- `/foxguard:secrets [path]` — hardcoded secrets, tokens, private keys
- `/foxguard:triage [args]` — instructions for the interactive TUI
- **`secure-coding` skill** — model-invoked remediation guidance for command exec, SQL, path traversal, SSRF, secrets, randomness, crypto, and deserialization.
## Install
### 1. Install foxguard
Pick whichever fits:
```sh
# Prebuilt binary — fastest
# Homebrew
brew install pwnkit-labs/foxguard/foxguard
# npm (global or zero-install)
npm i -g foxguard # or just: npx foxguard
# cargo
cargo install foxguard
```
Verify with `foxguard --version`.
### 2. Install the plugin
Until the plugin is published to a marketplace, load it directly from this repo:
```sh
claude --plugin-dir /path/to/foxguard/plugins/claude-code
```
Or add to your settings to load it permanently. Once installed, run `/foxguard:setup` to confirm it's wired up.
Marketplace submission copy, versioning notes, and local validation commands are
tracked in [MARKETPLACE.md](MARKETPLACE.md).
## Configuration
Environment variables:
| `FOXGUARD_HOOK_SEVERITY` | `medium` | Minimum severity for the auto-scan. One of `low|medium|high|critical`. |
Set in your shell profile or in Claude Code's environment to tune noise.
## How the auto-scan looks
After Claude edits a file, if foxguard finds an issue, Claude sees something like:
```
foxguard found 1 issue(s) in src/auth.py (severity >= medium):
[CRITICAL] py/no-command-injection at line 42
os.system() called with dynamic argument — risk of command injection
CWE-78
> os.system("ls " + user_input)
Fix these before continuing. Run `/foxguard:scan` for the full repo or `/foxguard:triage` for the interactive TUI.
```
Claude is expected to fix the finding (or explain why it's a false positive) before moving on.
## Layout
```
plugins/claude-code/
├── .claude-plugin/plugin.json # manifest
├── hooks/hooks.json # PostToolUse + SessionStart
├── scripts/
│ ├── scan-edited-file.sh # the PostToolUse scanner
│ └── secure-defaults.txt # SessionStart preamble
├── skills/
│ ├── setup/SKILL.md # /foxguard:setup
│ ├── scan/SKILL.md # /foxguard:scan
│ ├── diff-scan/SKILL.md # /foxguard:diff-scan
│ ├── pq-audit/SKILL.md # /foxguard:pq-audit
│ ├── secrets/SKILL.md # /foxguard:secrets
│ ├── triage/SKILL.md # /foxguard:triage
│ └── secure-coding/SKILL.md # model-invoked remediation guidance
└── README.md
```
## Notes
- The hook intentionally never blocks Claude on its own machinery: missing binary, parse errors, or unreadable inputs all exit `0`. Only real findings exit `2`.
- The hook calls `foxguard` from `PATH` first, then falls back to `npx --yes foxguard`. If neither is available it stays silent — run `/foxguard:setup` to fix that.
- `--severity medium` is the default cutoff. Drop to `low` for stricter coverage; raise to `high` for noisier projects.
- foxguard's exit codes: `0` clean, `1` findings, `2` error. The hook checks for findings via the JSON, not the exit code, so a piped error doesn't trigger a false alarm.
- This package is scoped to Claude Code. Broader agent or editor integration
design should be tracked separately from the Claude Code marketplace release.
## License
MIT — same as foxguard.