only a set of changes, such as a branch’s diff, a pull request’s diff, or a single commit, then turn the findings you choose into patches that you review and apply yourself. The plugin runs locally in your session, and each scan counts against your plan’s usage limits. If you want a managed service that monitors your repositories, see the
Claude Securityproduct, available on the Enterprise plan. The plugin reaches code the managed product can’t reach, such as repositories hosted on GitLab or Bitbucket, or on networks that don’t allow inbound connections. The plugin is also distinct from the review tools already in Claude Code: the
[security guidance plugin](/docs/en/security-guidance)reviews code as Claude writes it,
[runs a single pass over your branch, and](/docs/en/commands#all-commands)
/security-review
[Code Review](/docs/en/code-review)reviews pull requests. For how the layers stack, see
[How the plugin fits with other security tools](#how-the-plugin-fits-with-other-security-tools).
Prerequisites #
To run the plugin, you need:- Claude Code v2.1.154 or later on a paid plan, for the
dynamic workflowsthe scan uses to orchestrate its agents. On Pro, turn them on from the Dynamic workflows row in/config
. - Python 3.9.6 or later available on your
PATH
aspython3
. Check withpython3 --version
. The plugin’s tooling uses only the Python standard library, so nothing is installed. - Linux, macOS, or Windows.
- Git, for change scans and for turning findings into patches; those jobs don’t support other version control systems. A full scan works in any directory, with or without version control.
Install the plugin #
In a Claude Code session, install from the[official Anthropic marketplace](/docs/en/discover-plugins#official-anthropic-marketplace):
If Claude Code reports that the marketplace is not found, run
/plugin marketplace add anthropics/claude-plugins-official
first, then retry the install./reload-plugins
, which applies pending plugin changes without a restart:
Uninstall the plugin
To remove the plugin, uninstall it from the/plugin
menu, or run claude plugin uninstall claude-security
in your terminal.
Scan and fix your codebase #
The plugin adds one command,/claude-security
, which opens a menu of its three jobs: scanning the codebase, scanning a set of changes, and suggesting patches. The happy path runs a full scan, then turns its findings into patches: 1
Open the Claude Security menu
Run
/claude-security
and pick Scan codebase.2
Choose what to scan
The plugin reads your repository first, then offers the whole repository or a focused area, with each option’s file count and relative cost stated. Pick the whole repository, or answer “I don’t know” and the plugin picks a sensible default for your repository’s size.
3
Confirm the run
A scan may take a while, may use a significant number of tokens, and needs Claude Code left open while it completes. Nothing runs until you confirm.
4
Read the report
While the scan runs, it reports each stage as it starts, with the detail available under
. Results land in a timestamped directory in your repository, described in/workflows
Read the scan results.5 Turn findings into patches
Run
/claude-security
again and pick Suggest patches, then choose which findings to address. Reviewed patches land in the report’spatches/
folder; Fix findingscovers how each patch is built and reviewed.6 Apply the patches you accept
Apply each patch from your shell with
git apply
, in its own pull request. Patches are never applied automatically./claude-security scan my branch
, or in plain language, such as “scan commit abc1234”. The plugin works best in auto mode, which lets the scan’s agents proceed without a permission prompt at each step; the plugin reminds you how to enable it when a job starts.
Scan only your changes
When your branch has commits its base doesn’t, the/claude-security
menu offers to scan only that diff, so you can check a branch before merging. You can also scan one of your open pull requests, or a single commit by asking for it, such as “scan commit abc1234”. Only committed changes are scanned: commit or stash in-progress edits first, or run a full scan, which reads the working tree.
Change scans need a git repository; full scans of an unversioned directory still work. Finding your open pull requests is the one step that reaches the network, and it’s offered only when your session already has permission to run the GitHub CLI and gh
is signed in.
Scope large repositories
On a large repository, scan one area at a time instead of the whole tree. Pick one of the focused scopes the plugin offers, such as your API layer or your authentication code, and the run sizes itself to what you pick. The report’s coverage section states what was and wasn’t examined. Run another scan on a different area anytime.### Read the scan results
Every scan writes its results into a timestampedCLAUDE-SECURITY-<timestamp>/
directory in your repository:
: the report, with each finding’s ID, such asCLAUDE-SECURITY-RESULTS.md
F1
, plus its impact, exploit scenario, severity, confidence, and recommendation: the same findings in machine-readable form, one JSON object per lineCLAUDE-SECURITY-RESULTS.jsonl
: the revision stamp, recording which commit was scanned, at what effort, whether uncommitted changes were part of the scanned tree, and how thoroughly the run was verified, so a report is always tied to the code it describes. A scan outside version control stampsCLAUDE-SECURITY-REVISION-<commit>.json
UNVERSIONED
in place of the commit
.gitignore
, so a stray git add
never sweeps a report into a commit. To keep a report in history for an audit trail, delete that one .gitignore
file and commit the directory like any other. Findings only appear in the report after independent verifier agents analyze them, which keeps reports short and worth reading. Scans are nondeterministic: two scans of the same code can surface different findings. Run scans regularly, and use the revision stamps to attribute each report to the exact code and settings it covered.
Fix findings #
Start the fix flow by pickingSuggest patches from the
/claude-security
menu, or ask in plain language, such as “fix finding F3”, then pick which findings from the report to address. Patches are built against committed code, and the report has to still describe the code you have: findings whose code has since changed are skipped with a note, and the plugin offers a fresh scan instead of patching from a stale report. Each patch is drafted in a scratch copy of your repository, so your source files stay untouched until you apply a patch yourself. Before delivery, each patch is reviewed by an agent independent of the one that wrote it, which runs your project’s tests against the change when the code has them and reads the diff on its own terms for anything new it might introduce. A patch is written only when that review can vouch that the change addresses the one finding, introduces no new vulnerability, and leaves behavior otherwise unchanged. When it can’t vouch for all three, you get a short note explaining why instead of a patch.
Patches are never applied automatically
Applying a patch is always your decision. Patches land in the report’spatches/
folder, one F<n>.patch
per finding with a note beside it explaining the change. Apply one from your shell, or ask Claude to apply it and open a pull request:
Scan repositories you don’t trust #
The plugin is built for scanning code you control, where the question is which bugs are in the code rather than whether the code is trying something. A scan runs in your session, under your permissions, and adds no isolation of its own: the repository’s committed.claude/
settings, hooks, and CLAUDE.md
apply exactly as they would in any other session. The scan treats everything the repository says, in code, comments, and findings text, as data under review rather than instructions, but that isn’t a defense against a hostile repository. To scan a repository you don’t fully trust, such as a third-party dependency or an unfamiliar codebase, sandbox the whole session first. sandbox-runtimeenforces filesystem and network restrictions at the operating-system level; its README covers how to run Claude Code inside it.
How the plugin fits with other security tools #
The Claude Security plugin is the on-demand deep-scan layer in a defense-in-depth stack, alongside the[security guidance plugin](/docs/en/security-guidance),
[,](/docs/en/commands#all-commands)
/security-review
[Code Review](/docs/en/code-review), the managed
[Claude Security](https://claude.com/product/claude-security)product, and your existing scanners:
The plugin doesn’t replace your existing source-code security tools. Run it alongside static analysis, dependency scanning, and code review: it reasons about your code the way a human security researcher would, which complements the deterministic checks those tools provide.
Troubleshooting #
The The plugin needs
/claude-security
menu opens with a Python warning.python3
3.9.6 or later on your PATH
. When it can’t find python3
at all, the menu warns that Claude Security won’t work until one is installed; when the first python3
on your PATH
is older, the warning names the version it found. Install Python 3, or put a newer python3
first on your PATH
, then start a new session.
Related resources #
To go deeper on the pieces this page touches:Security guidance plugin: catch issues in code as Claude writes it, in the same sessionCode Review: set up the PR-time multi-agent reviewClaude Security: the managed service that monitors connected repositoriesClaude Code security: how Claude Code approaches trust, permissions, and safeguardsDiscover and install plugins: browse other official plugins