Claude Code Security Guidance Plugin: Catch Vulnerabilities While AI Writes Code

Core question this article answers: When using AI programming assistants, how can you make the AI automatically discover and fix security vulnerabilities it introduces, without waiting until code review or production?

Every developer who uses AI-assisted coding has experienced this scenario: the AI quickly generates seemingly perfect code, but hidden inside are eval() calls executing user input, innerHTML injections, or missing permission checks. These vulnerabilities might slip through code review and only cause incidents after reaching production.

Anthropic’s Security Guidance Plugin for Claude Code solves exactly this problem. It makes Claude review its own code for common security issues while writing, and fix what it finds—before the code ever reaches a pull request. This isn’t a command you need to remember; it runs automatically in the background as your security companion.

This article dives deep into the plugin’s installation, its three-layer defense mechanism, customization options, cost considerations, and how it fits into your existing security toolchain. Whether you’re an indie developer or an engineering lead at a large organization, you’ll find practical ways to make AI coding more secure.

Installation & Activation: Integrate Security Reviews in Three Steps

Core question: How do I quickly install this plugin and have it automatically work every time I use Claude Code?

Prerequisites

Before installing, ensure your environment meets these requirements (these come directly from the plugin’s own dependencies):

Requirement	Details
Claude Code CLI	Version 2.1.144 or higher
Python	3.8 or later, available on your `PATH` (the plugin tries `python3`, `python`, and `py -3` in order)
Git repository	Your working directory must be in a Git repo (otherwise some review layers silently skip)
Network access	First run downloads `claude-agent-sdk` and creates a virtual environment

Reflection: Many developers overlook the Python and Git dependencies, leading to a plugin that “seems installed but doesn’t work.” In my experience, run /reload-plugins in a fresh test repository first and watch for environment initialization logs – that’s the fastest way to confirm the plugin is loading correctly.

Installation Steps

In a Claude Code session, install from the official marketplace:

/plugin install security-guidance@claude-plugins-official

During installation, you’ll be prompted for a scope:

User scope: Writes the plugin to your user settings – it will load in every new local session you start on this machine.
Project scope: Only applies to the current project.

If the system reports that the marketplace isn’t found, add it first:

/plugin marketplace add anthropics/claude-plugins-official

After installation, activate the plugin in your current session:

/reload-plugins

Enable in Cloud Sessions and Shared Repositories

Core question: If I work in Claude Code on the Web (cloud), or want my entire team to have this plugin enabled by default, how do I do that?

User-scoped plugin settings do not carry over to cloud sessions (because those run on Anthropic’s infrastructure). To enable the plugin for cloud sessions or for everyone who clones a repository, commit the configuration to your project’s .claude/settings.json file:

{
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true
  }
}

Once this file is committed to your Git repository, anyone who clones the repo and uses Claude Code will have the plugin automatically enabled. Enterprise administrators can also enable it organization-wide via managed settings.

Three-Layer Defense: From Pattern Matching to Deep Code Review

Core question: What exactly does this plugin check, and when and how does it find security issues?

The plugin doesn’t run a single “big scan” at one moment. Instead, it checks at three critical points in Claude’s coding lifecycle, each with different depth. This layered design ensures both performance (shallow checks have no AI cost) and depth (deep checks read surrounding context).

Layer 1: Pattern Matching After Every File Edit (Zero Cost, No AI)

When Claude uses Edit, Write, or NotebookEdit tools to modify a file, the plugin immediately scans the new content for known risky patterns. This layer makes no AI model calls, so it adds zero usage cost and negligible latency.

Typical matched patterns include:

Dynamic code execution: eval(, new Function, os.system, child_process.exec
Unsafe deserialization: pickle
DOM injection: dangerouslySetInnerHTML, .innerHTML =, document.write
CI/CD workflow files: any changes under .github/workflows/ (since these can grant repository-level permissions)

Scenario example: Suppose Claude is helping you write a Node.js script and generates const result = eval(userInput). Immediately after the file saves, the plugin detects the eval( substring and appends a warning to Claude’s context. In the next step, Claude sees: “Dangerous pattern detected: eval call. Use a safer alternative.” It might then proactively change the code to use JSON.parse or a function map.

Each warning fires only once per pattern per file per session, so repeated matches in the same file don’t flood the conversation.

Layer 2: End-of-Turn Diff Review (Background Model Call)

Core question: If pattern matching can’t find logic flaws like permission bypasses, what else does the plugin do?

A “turn” is one round of Claude responding: you send a message, Claude works and replies. After each turn, the plugin computes a git diff of everything that changed in the working tree during that turn (including changes from Claude’s edit tools, Bash commands, and subagents), and sends it to a separate, security-focused Claude model for review.

This review runs in the background and does not delay Claude’s immediate reply. If the review finds issues, Claude is re‑prompted with the findings and addresses them as a follow‑up – you’ll see “Security review found X issues, fixing…” directly in your conversation.

This layer catches what pattern matching cannot:

Authorization bypass
Insecure direct object references (IDOR)
SQL / NoSQL / command injection (complex variants)
Server-side request forgery (SSRF)
Weak cryptography (e.g., using MD5 or ECB mode)

Technical limits:

Covers up to 30 changed files per review
Fires at most 3 times in a row before yielding back to you

Scenario example: Claude generates a REST API endpoint: /admin/users/:id. It correctly calls requireRole('admin') at the top, but later in a database query it accidentally writes db.users.find({ id: req.params.id }) without an orgId filter. Pattern matching can’t catch this logic flaw. But the independent model review reads the source of req.params.id, considers the route’s semantics, judges whether there’s a privilege escalation risk, and asks Claude to add an organization ID filter.

Layer 3: Commit/Push Deep Agentic Review (Reads Surrounding Context)

Core question: If code has already been committed locally, can the plugin still do anything useful?

When Claude runs git commit or git push through its Bash tool, the plugin triggers a deeper agentic review. This review doesn’t just look at the diff – it actively reads surrounding code: callers, sanitizers, related files – to decide whether a seemingly dangerous pattern is actually safe in your specific codebase.

Why is this needed?

Some code snippets look dangerous in isolation but are safe in your project. For example, an eval call that only processes hardcoded math expressions, or an innerHTML assignment that passes through a strict DOMPurify sanitizer. The deep agentic review dramatically reduces false positives by reading more context.

Important limits:

Only reviews commits/pushes that Claude makes via the Bash tool. Commits you run from your own terminal (or via the ! shell escape inside a session) are not reviewed.
Capped at 20 reviews per rolling hour.
If the commit review finds issues already reported by the end-of-turn review, Claude is not re-prompted – so a clean commit produces no visible output from this layer.

Reflection: This layered design embodies an important security principle – don’t trust a single judgment source. Layer 1 is deterministic rules, Layer 2 is context‑free model review, Layer 3 is context‑aware model review. Each layer tries to make up for the shortcomings of the previous one while controlling costs. In practice, most common vulnerabilities are caught in Layer 2; Layer 3 is more for complex, codebase‑specific logic issues.

Customizing Your Own Rules: Adapt to Your Project’s Specific Needs

Core question: The built-in checks don’t cover my project’s unique requirements – can I add my own rules, and how?

The plugin provides two extension points: a Markdown guidance file for model‑backed reviews, and a YAML/JSON patterns file for the per‑edit pattern matching layer. Both are additive – you cannot remove built‑in rules, but you can add your own.

Add Guidance for Model‑Backed Reviews (`.claude/claude-security-guidance.md`)

Create a Markdown file that describes your project’s unique threat model and review checklist in plain language. This file is loaded into the context of Layer 2 (end‑of‑turn) and Layer 3 (commit) reviews.

Example (for a multi‑tenant web service):

# Security guidance for this repo

- Do not log `customer_id` or `account_number` at INFO level or above.
- All routes under `/admin` must call `require_role("admin")` before any database read.
- Use `crypto.timingSafeEqual` for token comparison instead of `===`.

Lookup locations (all existing locations are loaded and concatenated, with a combined cap of 8 KB):

Scope	Path	Description
User	`~/.claude/claude-security-guidance.md`	Applies to every project on your machine
Project	`.claude/claude-security-guidance.md`	Committed to the repository, shared with the team
Project local	`.claude/claude-security-guidance.local.md`	Gitignored, for personal overrides

Note: These guidelines are suggestions, not hard blocks. The plugin surfaces violations as findings for Claude to fix, but it does not block writes. For hard enforcement, pair it with a hook that blocks edits or a CI check.

Add Custom Per‑Edit Patterns (`security-patterns.yaml`)

Create a YAML or JSON file to add regex or substring rules to the pattern matching layer (Layer 1). These run as deterministic string matches alongside built‑in patterns.

Example:

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "Hardcoded API key prefix. Load credentials from the secret manager."
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["**/src/tenants/**"]
    reminder: "Multi-tenant code must filter by org_id."

Field descriptions:

Field	Type	Description
`rule_name`	string	Identifier shown in the warning
`reminder`	string	Warning text appended to Claude’s context (capped at 1 KB)
`regex`	string	Python regex matched against the edited content
`substrings`	list	Literal substrings; provide this or `regex`
`paths`	list	Optional glob patterns; the rule applies only to matching files (prefix project-relative patterns with `**/`)
`exclude_paths`	list	Optional glob patterns to skip

The plugin loads up to 50 custom rules and skips regexes that look prone to catastrophic backtracking.

File formats: .claude/security-patterns.yaml, .claude/security-patterns.yml, or .claude/security-patterns.json are all supported. JSON works on any Python install without extra dependencies; YAML requires PyYAML (which the plugin does not install for you – use JSON to avoid dependency issues).

Scenario example: Your project’s security policy forbids hardcoding any string starting with AKIA (AWS access keys). Built‑in rules may not cover this custom prefix. By adding the rule above, whenever Claude writes a string containing AKIA (even in test code), the plugin reminds “Load credentials from the secret manager.” Claude may then suggest using environment variables or AWS Secrets Manager instead.

Cost, Performance & Integration: Security Without Sacrificing Efficiency

Core question: How much extra Claude API usage does this plugin consume? Will it hurt my development experience?

Cost Breakdown

Check Layer	Model Calls?	Cost Impact
Per‑file edit pattern matching	No	Zero
End‑of‑turn diff review	Yes	Each review counts as a normal model call
Commit/push deep agentic review	Yes (agentic, may be multi‑turn)	Each review counts as multiple model calls

Default model: Both model‑backed reviews use Claude Opus 4.7. You can change this via environment variables:

SECURITY_REVIEW_MODEL: controls the end‑of‑turn review model
SG_AGENTIC_MODEL: controls the commit review model

Usage estimation: Roughly, each turn where files change triggers one end‑of‑turn review, and each commit triggers one deep review – subject to the caps (20 commit reviews per hour). For normal development cadence, the added cost is modest, especially considering it might prevent a single production incident.

Disable Specific Layers (Without Uninstalling the Plugin)

If you need to temporarily turn off a layer, set the corresponding environment variable:

Variable	Effect
`ENABLE_PATTERN_RULES=0`	Disable Layer 1 (per‑edit pattern matching)
`ENABLE_STOP_REVIEW=0`	Disable Layer 2 (end‑of‑turn review)
`ENABLE_COMMIT_REVIEW=0`	Disable Layer 3 (commit/push review)
`ENABLE_CODE_SECURITY_REVIEW=0`	Disable all model‑backed reviews at once (keep pattern matching)
`SECURITY_GUIDANCE_DISABLE=1`	Disable the plugin entirely without uninstalling

How This Fits with Other Security Tools

Core question: Can this plugin completely replace my existing SAST, DAST, or human code review?

No. It’s the earliest line of defense, not the only one. The official documentation suggests a typical defense‑in‑depth stack:

Stage	Tool	Coverage
In session	Security guidance plugin	Common vulnerabilities in code Claude writes, fixed in the same session
On demand	`/security-review` command	One‑time security pass on the current branch
On pull request	Code Review (Team/Enterprise)	Multi‑agent correctness and security review with full codebase context
In CI	Your existing SAST, dependency scanners	Language‑specific rules, supply‑chain checks, policy enforcement

Reflection: I’ve seen teams try to use only this plugin and abandon all other security measures, only to still have business logic vulnerabilities reach production. Remember: The plugin’s value is reducing the volume of low‑hanging fruit that reaches later stages, not eliminating all vulnerabilities. A mature engineering team should treat it as the goalie’s first reaction, not the entire defensive line.

Troubleshooting: What If the Plugin Doesn’t Work?

Core question: I followed the installation steps, but I don’t see any review output – how do I debug this?

The plugin writes runtime diagnostics to ~/.claude/security/log.txt. This is your first stop for troubleshooting.

Common Silent Skip Reasons (No Message in Conversation)

Reason	Explanation
Directory is not a Git repository	End‑of‑turn and commit reviews require Git state and skip outside a repo
Session lacks Anthropic authentication	Model‑backed reviews skip; only pattern matching runs
`security-patterns.yaml` exists but PyYAML is not importable	The file is ignored. Switch to `security-patterns.json`
Custom regex causes catastrophic backtracking	The plugin skips that regex; check the log

How to Confirm the Plugin Is Loaded?

In a Claude Code session, run:

/plugin list

You should see security-guidance@claude-plugins-official in the list of enabled plugins.

Uninstall or Temporarily Disable

Temporarily disable (user scope) : /plugin disable security-guidance@claude-plugins-official
Completely uninstall: /plugin uninstall security-guidance@claude-plugins-official
Personal disable when project‑enabled: The plugin writes your disable preference to .claude/settings.local.json, leaving teammates unaffected

If the plugin was enabled via organization‑wide managed settings, only an administrator can disable it.

One‑Page Summary & Action Checklist

Quick Deployment Checklist

[ ] Verify Claude Code CLI ≥ 2.1.144 and Python 3.8+ is on your PATH
[ ] In your project root, run /plugin install security-guidance@claude-plugins-official
[ ] Run /reload-plugins to activate in the current session
[ ] (Optional) Add .claude/claude-security-guidance.md with team‑specific review rules
[ ] (Optional) Add .claude/security-patterns.json to extend pattern matching
[ ] (Team sharing) Commit .claude/settings.json with enabledPlugins to your repo
[ ] Use Claude Code normally and watch for “Security review found…” fix messages
[ ] When in doubt, check ~/.claude/security/log.txt

Key Metrics at a Glance

Feature	Value
Per‑edit check cost	Zero
End‑of‑turn review default model	Claude Opus 4.7
Max files per end‑of‑turn review	30
Max consecutive end‑of‑turn reviews	3
Commit review hourly cap	20
Custom rules limit	50
Guidance file size cap	8 KB
Reminder text size cap	1 KB

Frequently Asked Questions (FAQ)

Q1: Does this plugin review code I write manually?

The plugin reviews changes made by Claude via its file editing tools, Bash commands, and subagents. If you manually edit a file without Claude writing it during that turn, it won’t trigger a review. However, you can always ask Claude to manually run /security-review to check all uncommitted changes.

Q2: Will Claude automatically fix issues the plugin finds?

Yes. For end‑of‑turn and commit reviews, Claude receives a re‑prompt with the findings and attempts to fix them in the same session. The fixes are visible – you’ll see Claude say “Security review found X issues, fixing…” and then perform edits. It’s not 100% guaranteed that every issue can be auto‑fixed; some may require your input.

Q3: Does the plugin work on Windows?

Yes, with differences: On Windows, the virtual environment step is skipped, so the agentic commit review only runs if claude-agent-sdk is already importable; otherwise it falls back to a single‑shot review. Pattern matching and end‑of‑turn review are unaffected.

Q4: Will the plugin read my uncommitted local changes as context?

For Layer 3 (commit review), it actively reads surrounding code files, including uncommitted changes. Those reads happen within Claude Code’s security boundary and are only sent to the Anthropic API for model inference (as part of normal usage). The context is not retained after the review.

Q5: Can I make the plugin ignore certain files or directories?

You can use the exclude_paths field in custom pattern rules to skip specific paths. To completely exclude a directory from all review layers, the simplest approach is to add it to .gitignore or ensure it’s outside the Git working tree (since reviews are based on Git diffs).

Q6: What if I accidentally have multiple versions of the plugin installed?

The plugin system typically loads only the most recently enabled instance. Run /plugin list to see what’s currently loaded. It’s best to uninstall the old version before installing a new one.

Q7: Does the plugin support languages other than JavaScript/Python?

The pattern matching layer is language‑agnostic – it just scans text for substrings or regexes. The model‑backed review layer can understand any language that Claude models support (including Java, Go, Rust, C#, etc.), because it reads code semantics, not just lexemes.

Q8: Are security findings logged or persisted?

The review process itself is logged to ~/.claude/security/log.txt for troubleshooting. Specific vulnerability details are not automatically committed to any external system. If your team needs audit trails, consider saving Claude Code session transcripts.

Conclusion

Making AI‑written code secure cannot rely on “luck” or post‑hoc human review. The Claude Code Security Guidance Plugin, by embedding three layers of checks directly into the development session, dramatically reduces the volume of common vulnerabilities that reach your codebase – without disrupting the coding flow.

Its value isn’t in being perfect; it’s in being early and automatic. A vulnerability fixed when the AI first writes it costs zero. The same vulnerability found during PR review costs 10x. Exploited in production? 1000x.

For any team seriously using AI programming assistants, installing and configuring this plugin should be a default step when starting new projects.

Claude Code Security Guidance Plugin: Catch AI Vulnerabilities Before They Reach Production