surshar / claude-code
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
Built by Anthropic · github.com/anthropics
| 1 | # security-guidance |
| 2 | |
| 3 | Security review for Claude-generated code. Three layers: |
| 4 | |
| 5 | 1. **Pattern warnings** — instant regex-based reminders on `Edit`/`Write` for ~25 known-dangerous patterns (`yaml.load`, `torch.load(weights_only=False)`, `pickle.load` on untrusted data, raw `innerHTML`, hardcoded secrets, etc.). |
| 6 | 2. **LLM diff review** — when Claude finishes a turn, the plugin sends the diff to a fast LLM call (Opus 4.7 by default) and feeds high-severity findings back to Claude so it can fix them before you see the response. |
| 7 | 3. **Agentic commit review** — on `git commit`, an SDK-driven reviewer reads related files (`Read`/`Grep`/`Glob`) to trace data flow across the codebase, catching multi-file vulnerabilities pattern matching misses (IDOR, auth bypass, cross-file SSRF). |
| 8 | |
| 9 | Findings cover common web-vulnerability classes — injection, XSS, SSRF, hardcoded secrets, IDOR, auth bypass, unsafe deserialization, and path traversal among others. |
| 10 | |
| 11 | ## Install |
| 12 | |
| 13 | ``` |
| 14 | /plugin install security-guidance@claude-plugins-official |
| 15 | ``` |
| 16 | |
| 17 | Marketplace ships enabled by default in Claude Code — no setup beyond having the CLI itself. |
| 18 | |
| 19 | ## Prerequisites |
| 20 | |
| 21 | - Claude Code CLI ≥ v2.1.144 |
| 22 | - Python 3.8+ on `PATH` (`python3`, `python`, or `py -3` — the plugin picks the first that works) |
| 23 | - A working API path (subscription, API key, or 3P provider config) |
| 24 | |
| 25 | ## Configuration |
| 26 | |
| 27 | All configuration is via environment variables. None are required for default behavior. |
| 28 | |
| 29 | ### Selecting a model |
| 30 | |
| 31 | ```bash |
| 32 | # 1P / gateway: a canonical model id |
| 33 | SECURITY_REVIEW_MODEL=claude-opus-4-7 # default |
| 34 | |
| 35 | # Bedrock: use the inference-profile id |
| 36 | SECURITY_REVIEW_MODEL=us.anthropic.claude-opus-4-7 |
| 37 | |
| 38 | # Vertex: use the Vertex date-tag form |
| 39 | SECURITY_REVIEW_MODEL=claude-opus-4-7@20260218 |
| 40 | ``` |
| 41 | |
| 42 | `SECURITY_REVIEW_MODEL` controls the LLM diff review. `SG_AGENTIC_MODEL` (same syntax) controls the agentic commit reviewer; defaults to the same model. |
| 43 | |
| 44 | ### Enabling/disabling layers |
| 45 | |
| 46 | | Variable | Default | What it does | |
| 47 | |---|---|---| |
| 48 | | `SECURITY_GUIDANCE_DISABLE=1` | unset | Kill switch — disables the entire plugin | |
| 49 | | `ENABLE_PATTERN_RULES=0` | on | Disable layer 1 (regex pattern warnings) | |
| 50 | | `ENABLE_CODE_SECURITY_REVIEW=0` | on | Disable all LLM reviews (Stop hook + commit/push) | |
| 51 | | `ENABLE_STOP_REVIEW=0` | on | Disable only the Stop-hook diff review, keeping commit/push reviews. Useful for multi-agent / shared-worktree setups where another agent can move HEAD between a worker's turns | |
| 52 | | `ENABLE_COMMIT_REVIEW=0` | on | Disable layer 3 (agentic commit review) | |
| 53 | | `SG_SKIP_SECRET_FILES=0` | on | Stop skipping well-known secret files (`.env*`, private keys, `secrets.yaml`, `credentials.json`, `.netrc`, …) so they are reviewed like any other file. Files your `Read` deny rules cover stay excluded either way — see [Privacy and data handling](#privacy-and-data-handling) | |
| 54 | |
| 55 | ### Higher-recall mode |
| 56 | |
| 57 | ```bash |
| 58 | SG_DUAL_OR=on # default off |
| 59 | ``` |
| 60 | |
| 61 | Runs two parallel review calls and unions the findings. Catches a few percentage points more vulnerabilities in our testing, at roughly 2× the API cost per review. Most users don't need it. |
| 62 | |
| 63 | ## Org-specific policies |
| 64 | |
| 65 | Drop a `claude-security-guidance.md` in any of: |
| 66 | |
| 67 | - `~/.claude/claude-security-guidance.md` — user-wide rules |
| 68 | - `<project>/.claude/claude-security-guidance.md` — project rules, intended to be committed |
| 69 | - `<project>/.claude/claude-security-guidance.local.md` — local overrides, intended to be `.gitignore`'d |
| 70 | |
| 71 | All three are loaded and concatenated into the LLM diff review's prompt in the order user → project → project-local. If the combined size exceeds the 8 KB prompt budget, the tail is truncated, so user-wide rules are kept and project-local rules are dropped first. The agentic commit reviewer (layer 3) does not currently read this file. Example: |
| 72 | |
| 73 | ```markdown |
| 74 | # Acme security rules |
| 75 | |
| 76 | - All SELECTs against the `customers` or `orders` tables MUST go through `db.replica`, |
| 77 | never `db.primary`. Primary is for writes only. |
| 78 | - Background jobs must not use the user-context auth token; they get |
| 79 | service-account creds from `jobs.get_service_account()`. |
| 80 | - Calls to `requests.get(url)` with a user-controlled `url` need |
| 81 | the SSRF-allowlist wrapper at `acme.net.safe_request`. |
| 82 | ``` |
| 83 | |
| 84 | Built-in rules cover common web-vulnerability classes without it — `claude-security-guidance.md` is for things specific to your codebase that the model can't infer. |
| 85 | |
| 86 | ## Privacy and data handling |
| 87 | |
| 88 | The plugin sends data to a model endpoint to perform its reviews. Specifically, each Stop-hook diff review transmits the changed file paths, the diff hunks, and the relevant file contents in the diff; each agentic commit review additionally transmits any files the reviewer pulls in via `Read`/`Grep`/`Glob` while tracing data flow. Your `claude-security-guidance.md` contents (user, project, and local) are appended to the prompt on every review, so don't put secrets in it. |
| 89 | |
| 90 | Two kinds of file are kept out of every review, both from the diff the plugin sends and from what the agentic reviewer's sub-agent may `Read`/`Grep`/`Glob` (the sub-agent gets no shell tool, so `cat` or `git show` are not a way around this): |
| 91 | |
| 92 | - **Files your session's `Read` permission rules deny or ask about.** The plugin reads `permissions.deny` and `permissions.ask` from the same settings files Claude Code loads — managed (`managed-settings.json` and `managed-settings.d/`), user (`~/.claude/settings.json`), project (`.claude/settings.json`) and local (`.claude/settings.local.json`) — and applies the `Read(...)` rules with Claude Code's path conventions (`//abs`, `~/home`, `/project-relative`, gitignore-style globs). The sub-agent receives the same rules as `--disallowedTools`. Rules that exist only in MDM/registry policy, server-managed settings, or `--settings` / `--disallowedTools` command-line flags are not visible to a hook; put them in one of the settings files above if the reviewer must honor them. |
| 93 | - **Well-known secret files**, on by default: `.env` / `.env.*` / `*.env`, private keys and keystores (`*.pem`, `*.key`, `*.p12`, `*.jks`, `id_rsa*`, …), credential stores (`.netrc`, `.npmrc`, `.pypirc`, `.git-credentials`, `credentials`, `kubeconfig`) and `secret(s)` / `credential(s)` data files (`.json`, `.yaml`, `.toml`, …). Source files such as `secrets.py` are still reviewed. In the sub-agent these names follow permission-rule (gitignore) semantics, so a directory that shares one — `credentials/`, `.env/` — is off-limits to it as well. Set `SG_SKIP_SECRET_FILES=0` to review these too. |
| 94 | |
| 95 | The flip side: the reviewer cannot flag a problem inside a file it never sees, and a project's own `.claude/settings.json` decides what is hidden — the same trust Claude Code itself places in project settings. Each withheld path is named in the debug log (`secretpaths: withheld from review …`). |
| 96 | |
| 97 | Anything else that changed in the working tree during the turn is reviewed, including files your own `PreToolUse` hooks would have stopped the main session from reading: the content reaches the reviewer as a diff, not through a tool call, so those hooks never run. What comes back into the main conversation is the finding, not the file, and before a finding is emitted or kept in session state the plugin masks the credential values it can recognize in the quoted code — the value after a `password` / `secret` / `token` / `api_key`-style key (code, JSON, YAML, `.env`, XML, Dockerfile `ENV`), passwords in connection URLs, `Authorization` and `curl -u` credentials, well-known API-key formats, private-key blocks, and, in a finding classed as a hardcoded secret, any other quoted literal or long opaque token — to `****` plus the last two characters, so the main session learns where the secret is without receiving it. This is pattern matching, not a guarantee: add a `Read(...)` deny rule for any file whose content must not reach the review endpoint at all. |
| 98 | |
| 99 | Where that data goes depends on your Claude Code configuration: |
| 100 | - **Default (Anthropic API / subscription):** sent to `api.anthropic.com` and handled under Anthropic's [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy). |
| 101 | - **LLM gateway** (`ANTHROPIC_BASE_URL` set): sent to your gateway URL instead. The gateway operator's terms apply. |
| 102 | - **3rd-party providers** (Bedrock / Vertex / Foundry / Mantle): sent to your configured provider endpoint. The provider's data-handling terms apply (e.g., AWS / GCP / Azure). |
| 103 | |
| 104 | The plugin writes its own debug log to `~/.claude/security/log.txt` (override with `SECURITY_GUIDANCE_DEBUG_LOG`). The log contains diffstate metadata and finding categories — no full file contents or model prompts — and rotates at 1 MB. Nothing is uploaded. |
| 105 | |
| 106 | ## Limitations |
| 107 | |
| 108 | This is a best-effort assistive tool, not a guarantee. Treat findings as suggestions, not as a substitute for human code review, SAST/DAST, dependency scanning, or pen-testing. The reviewer can miss vulnerabilities, produce false positives, and may behave differently across codebases, languages, and model versions. **No warranty is provided** — use is subject to Anthropic's [Commercial Terms](https://www.anthropic.com/legal/commercial-terms). |
| 109 | |
| 110 | ## Troubleshooting |
| 111 | |
| 112 | **Plugin doesn't seem to fire** — check that `~/.claude/claude-security-guidance.md` (or hook activity) shows in debug logs. Run Claude Code with `--debug-file /tmp/claude/debug.txt` and grep for `security_reminder_hook`. The plugin also writes its own log to `~/.claude/security/log.txt`. |
| 113 | |
| 114 | **Review never finds anything** — verify your API path works. On 3P providers, check `SECURITY_REVIEW_MODEL` is set to a provider-specific id (not a bare `claude-opus-4-7`). On LLM gateways, check the gateway's logs for `POST /v1/messages` traffic from the plugin. |
| 115 | |
| 116 | **Too many false positives** — drop `SECURITY_REVIEW_MODEL` to a cheaper model (`claude-sonnet-4-6`) and re-evaluate; if precision is the priority, stay on Opus 4.7. |
| 117 | |
| 118 | **Want to silence a specific finding** — add a comment to the line explaining why it's safe; the LLM reviewer treats inline justifications as exclusions. For systemic exclusions, document them in your `claude-security-guidance.md`. |
| 119 | |
| 120 | ## Reporting issues |
| 121 | |
| 122 | Open an issue on the [security-guidance plugin repo](https://github.com/anthropics/claude-code/issues) with: |
| 123 | - The Claude Code CLI version (`claude --version`) |
| 124 | - Provider setup (1P / Bedrock / Vertex / LLM gateway / etc.) |
| 125 | - A minimal repro diff |
| 126 | - The relevant section of `~/.claude/security/log.txt` |