From ca4a049a1908782292925902e1791e1cc456f510 Mon Sep 17 00:00:00 2001 From: Peak Twilight Date: Sat, 2 May 2026 22:02:10 +0200 Subject: [PATCH] docs: surface Claude Code plugin --- README.md | 13 +++- docs/claude-code-integration.md | 127 +++++++++++++++----------------- 2 files changed, 72 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 9827b4e..5ef7122 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,16 @@ curl -fsSL https://foxguard.dev/install.sh | sh # prebuilt binary (macO cargo install foxguard # crates.io ``` -**Editor:** [VS Code extension](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard) scans on save and shows findings inline. +**Editors and agents:** + +- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard) scans on save and shows findings inline. +- [Claude Code plugin](./plugins/claude-code) auto-scans files after Claude writes or edits them, adds `/foxguard:*` scan/triage/PQ/secrets skills, and injects secure-coding defaults into agent sessions. + +```sh +claude --plugin-dir ./plugins/claude-code +``` + +Run `/foxguard:setup` inside Claude Code to verify the scanner is available. See [Claude Code integration](docs/claude-code-integration.md) for local plugin loading, hook behavior, and marketplace status. ## CI integration @@ -132,7 +141,7 @@ jobs: upload-sarif: "true" ``` -Findings land in **Security → Code Scanning**. On any other CI: `npx foxguard@latest --format sarif . > out.sarif`. For Claude Code and other editor hooks, see [docs/claude-code-integration.md](docs/claude-code-integration.md). +Findings land in **Security → Code Scanning**. On any other CI: `npx foxguard@latest --format sarif . > out.sarif`. For Claude Code and other agent/editor hooks, see [docs/claude-code-integration.md](docs/claude-code-integration.md). **Pre-commit:** diff --git a/docs/claude-code-integration.md b/docs/claude-code-integration.md index 953ecc7..6341409 100644 --- a/docs/claude-code-integration.md +++ b/docs/claude-code-integration.md @@ -1,90 +1,85 @@ # Claude Code Integration -foxguard can run as a [Claude Code hook](https://docs.anthropic.com/en/docs/claude-code/hooks) to scan agent-written code before each commit. When findings are detected, the commit is blocked and Claude sees the output — giving it a chance to fix the issue before retrying. - -## Setup - -Add the following to `.claude/settings.json` in your project root: - -```json -{ - "hooks": { - "PreCommit": [ - { - "command": "npx foxguard --changed --severity high .", - "description": "foxguard security scan" - } - ] - } -} +foxguard ships a Claude Code plugin in [`plugins/claude-code`](../plugins/claude-code). It is the recommended Claude Code integration path because it runs automatically during an agent session instead of waiting until commit time. + +## What The Plugin Does + +- Runs a `PostToolUse` hook after `Write`, `Edit`, `MultiEdit`, and `NotebookEdit` so files Claude changes are scanned immediately. +- Emits medium-and-above findings back to Claude so the agent can fix them before the issue lands in the repo. +- Adds a `SessionStart` secure-coding preamble covering command execution, SQL, SSRF, path traversal, secrets, randomness, crypto, and deserialization. +- Provides namespaced `/foxguard:*` skills for setup, full scans, diff scans, PQ audits, secrets scans, and TUI triage. + +## Local Install + +Install foxguard first: + +```sh +curl -fsSL https://foxguard.dev/install.sh | sh +# or: npm i -g foxguard +# or: cargo install foxguard +``` + +Then load the plugin from this repo: + +```sh +claude --plugin-dir ./plugins/claude-code ``` -That's it. Claude Code will run foxguard before every commit. +Inside Claude Code, run: -## What happens when findings are detected +```text +/foxguard:setup +``` -1. Claude writes code and attempts to commit. -2. foxguard scans the changed files. -3. If any findings at or above the configured severity are found, foxguard exits non-zero. -4. Claude Code blocks the commit and shows foxguard's output to the agent. -5. The agent sees the finding (rule ID, file, line, description) and can fix it. -6. On the next commit attempt, foxguard runs again. +That verifies the `foxguard` binary is available and explains the active hook severity threshold. -## Customizing severity threshold +## Hook Behavior -The `--severity` flag controls the minimum severity that causes a non-zero exit: +The auto-scan hook reads the Claude Code hook JSON from stdin, extracts `tool_input.file_path` or `tool_input.path`, and runs: -```json -{ "command": "npx foxguard --changed --severity critical ." } +```sh +foxguard --format json --severity medium ``` -Valid values: `low`, `medium`, `high`, `critical`. +If findings are present, the hook exits `2` and prints a compact finding summary to stderr. Missing binaries, unreadable files, invalid hook input, and clean scans exit `0` so plugin machinery does not block Claude by itself. -- `critical` — only block on critical findings (SQL injection, command injection, etc.) -- `high` — block on high and critical (recommended default) -- `medium` — block on medium and above -- `low` — block on everything - -## Adding secrets scanning - -To also catch leaked credentials, add a second hook entry: - -```json -{ - "hooks": { - "PreCommit": [ - { - "command": "npx foxguard --changed --severity high .", - "description": "foxguard security scan" - }, - { - "command": "npx foxguard secrets --changed .", - "description": "foxguard secrets scan" - } - ] - } -} +Tune the threshold with: + +```sh +export FOXGUARD_HOOK_SEVERITY=high ``` -## Combining with the VS Code extension +Valid values: `low`, `medium`, `high`, `critical`. + +## Commands And Skills -For a full agentic security loop: +Claude Code plugin skills are namespaced by the plugin name: -1. **VS Code extension** — scans on save, shows findings as inline underlines while the agent is editing. -2. **Claude Code hook** — catches anything missed before commit. +- `/foxguard:setup` verifies installation and configuration. +- `/foxguard:scan [path]` runs a full scan and summarizes findings. +- `/foxguard:diff-scan [base]` reports findings introduced by the current branch. +- `/foxguard:pq-audit [path]` runs post-quantum crypto and CNSA 2.0 checks. +- `/foxguard:secrets [path]` scans for leaked credentials and private keys. +- `/foxguard:triage [args]` opens or explains the interactive TUI triage flow. -Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard), then add the hook config above. The two complement each other: the extension gives real-time feedback, the hook is the final gate. +The plugin also includes a model-invoked `secure-coding` skill so Claude can pull in foxguard-aligned remediation guidance while writing security-sensitive code. -## Pinning a version +## Pre-commit Still Helps -To avoid network fetches on every commit, pin the version: +The plugin is live feedback. A pre-commit hook is still useful as a final gate for human edits, other agents, or terminal changes outside Claude Code: -```json -{ "command": "npx foxguard@0.6.2 --changed --severity high ." } +```sh +foxguard init ``` -Or install foxguard globally (`curl -fsSL https://foxguard.dev/install.sh | sh`) and reference the binary directly: +Or configure your own hook to run: -```json -{ "command": "foxguard --changed --severity high ." } +```sh +npx foxguard --changed --severity high . ``` + +## Publishing Status + +The plugin can be loaded locally today with `--plugin-dir`. Publishing to an official Claude plugin marketplace is an external release step: it requires final marketplace metadata, a release/versioning decision, local plugin smoke testing in Claude Code, and submission through Anthropic's plugin form. + +Track the publishing checklist in the GitHub issue linked from the README/PR queue rather than treating it as part of the scanner binary release.