AI-powered security review of code changes as a Claude Code plugin. Loosely based on anthropics/claude-code-security-review.
Run a single slash command — /stride-security-review:security-review — to get a structured, severity-graded list of security findings on whatever you've changed. Powered by a dedicated security-reviewer agent that uses semantic analysis, not pattern matching, and filters out low-impact noise so the findings you see are the ones worth acting on.
/plugin marketplace add cheezy/stride-marketplace
/plugin install stride-security-review@stride-marketplaceThe plugin auto-discovers the slash command, the agent, and the skill on install. No further configuration needed.
Claude Code ships with a built-in /security-review command (a diff-only review that does NOT understand this plugin's flags — --full, --json, --maestro, --rci, --baseline, --patches, --considerations are silently ignored). To invoke this plugin, use the namespaced form /stride-security-review:security-review. All examples below use that form.
Renamed in v2.0.0. This plugin was previously named
security-review, which created a namespace collision with the Claude Code built-in. The rename tostride-security-reviewresolves the collision: the bare/security-reviewcleanly belongs to the built-in, and this plugin lives at/stride-security-review:security-review. If you have scripted invocations of the old namespaced form, update them to the new one.
In any git repository, run:
# Diff mode (default) — review what's changed against HEAD
/stride-security-review:security-review # all working-tree changes (staged + unstaged) vs HEAD
/stride-security-review:security-review lib/auth.ex # scope to one file
/stride-security-review:security-review lib/ test/ # scope to directories
/stride-security-review:security-review --json # raw JSON output for piping into tools
/stride-security-review:security-review --json lib/foo # path-scoped, raw JSON
# Full mode (--full) — review the codebase end-to-end (new in v1.1.0)
/stride-security-review:security-review --full # every tracked file in the repo
/stride-security-review:security-review --full lib/ # full scan scoped to a path
/stride-security-review:security-review --full --json # full scan, raw JSON output
# MAESTRO 7-layer classification (--maestro) — group findings by agentic-AI threat layer
/stride-security-review:security-review --maestro # classify each finding by MAESTRO layer
/stride-security-review:security-review --maestro --full # full scan + layer classification
/stride-security-review:security-review --maestro --json lib/ # raw JSON with maestro_layer fields
# Recursive Criticism & Improvement (--rci [N]) — run N additional critique passes
/stride-security-review:security-review --rci # one extra critique pass after the first dispatch
/stride-security-review:security-review --rci 2 # two extra critique passes (values above 3 clamp to 3)
/stride-security-review:security-review --rci --full # critique pass over a full scan (expensive)
# Baseline suppression (--baseline) — suppress already-acknowledged findings
/stride-security-review:security-review --baseline # auto-detect .security-review-baseline.json in repo root
/stride-security-review:security-review --baseline ci.json # explicit baseline path
/stride-security-review:security-review --update-baseline # rewrite the baseline from current findings
# Auto-remediation patches (--patches) — emit surgical-fix diffs alongside findings
/stride-security-review:security-review --patches # diff mode + per-finding patch suggestions
/stride-security-review:security-review --patches --json # raw JSON includes the patch field
# Considerations mode (--considerations <source>) — verify a task's security_considerations were mitigated
/stride-security-review:security-review --considerations threat-model.md # one consideration per line in the file
/stride-security-review:security-review --considerations "No secrets in logs" # a single inline consideration
/stride-security-review:security-review --considerations threat-model.md --json # raw JSON includes consideration_verdicts
/stride-security-review:security-review --considerations threat-model.md --rci --fail-on high # verdicts kept through the critique pass; exit 1 on any unmitigated verdict
Diff mode answers "is this change safe to merge?" — invoke it before pushing a PR. Full mode answers "what latent issues are in this codebase right now?" — invoke it when onboarding the plugin onto an existing repo, or on a periodic posture-check cadence. MAESTRO mode answers "which architectural layer needs the most attention?" — invoke it on codebases that wire LLMs / agents / Model Context Protocol clients into the request flow, so findings can be grouped by the seven-layer model from Cloud Security Alliance's MAESTRO framework. The flags compose: --maestro --full --json lib/ is valid. The output JSON schema is identical in diff and full modes; --maestro is the one flag that adds an optional field (maestro_layer) to each finding when set. Considerations mode answers "were the security considerations this change declared actually mitigated by the diff?" — pass --considerations <source> (a file with one consideration per line, or an inline string) and each listed consideration comes back with a mitigated / partial / unmitigated verdict alongside the usual findings. It is diff-based (ignored under --full) and, like --maestro/--patches, adds its output (the top-level consideration_verdicts array) only when the flag is set.
Sample output for a small diff with one finding:
Security review — 1 finding across 2 files
Critical: 0 High: 1 Medium: 0 Low: 0 Info: 0
## High
**[injection]** lib/users.ex:42 — confidence: high — CWE-89, A03:2021
User-supplied `username` parameter is concatenated directly into a SQL string at the call to
Repo.query/2 below. The trust boundary is the HTTP request handler at line 38, and the sink is
the raw query string passed to Postgres — classic SQL injection. Worst-case outcome is
full-table read for any user with credentials to reach this endpoint.
Fix: Use Ecto's parameterized query API. Replace the string-concatenated query with
Repo.query("SELECT * FROM users WHERE username = $1", [username]) so user input is bound as a
parameter rather than interpolated into the SQL text.
The security-reviewer agent (see agents/security-reviewer.md) reviews diffs across these vulnerability classes:
| Class | Examples |
|---|---|
| Injection | SQL, command, LDAP, NoSQL, XXE, template, header |
| Authentication | Missing auth check, timing-vulnerable comparison, weak password requirements |
| Authorization | IDOR, privilege escalation through parameter tampering, trusting client roles |
| Data exposure | Hardcoded secrets, secrets in logs, PII in error responses, sensitive data over plaintext |
| Cryptography | MD5/SHA1 for passwords, ECB mode, static IVs, predictable RNG for tokens |
| Input validation | Path traversal, SSRF, open redirect, zip-bomb decompression, trusting client validation |
| Race conditions | Filesystem TOCTOU, unlocked read-modify-write on security-sensitive state, symlink races |
| XSS / code execution | DOM/reflected/stored XSS, SSTI, deserialization of untrusted data |
| Insecure configuration | CORS * with credentials, disabled CSRF, debug mode in prod, missing security headers, disabled cert verification |
| Supply chain | Floating-tag container base images, curl | sh installers, CI/CD references by branch/tag instead of immutable SHA, manifest/lockfile drift, typosquat or hallucinated package names — multi-platform (Docker, GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, Jenkins) and multi-ecosystem (npm/PyPI/RubyGems/Hex/crates.io/Maven/NuGet/Packagist/Go modules) |
In addition to the universal classes above, seven framework-specific rule packs ship by default — each a file in packs/ that the agent reads only when a reviewed file needs it (see How rule packs load); a pack's rules apply on file extension AND import detection (never extension alone):
| Pack | Activates on | Idiomatic rules |
|---|---|---|
| Android / Kotlin | .kt / .java / .gradle with android.* / androidx.* / kotlinx.* imports, or AndroidManifest.xml content |
Exported <activity> / <service> / <receiver> without signature-level permission, WebView with setJavaScriptEnabled(true) + addJavascriptInterface on a dynamic-URL load, android:usesCleartextTraffic="true" without networkSecurityConfig, SharedPreferences storing tokens/passwords/PINs (should be EncryptedSharedPreferences), SQLiteDatabase.rawQuery / execSQL with string concatenation, trust-all HostnameVerifier / X509TrustManager |
| Django / Python | .py with django.* / rest_framework / django.db imports |
mark_safe on user input, extra / raw() query interpolation, CSRF disabled, DEBUG=True / ALLOWED_HOSTS=['*'] / missing SECURE_* in prod settings, mass-assignment via cleaned_data, open redirect, unsafe deserialization (pickle.loads / yaml.load / signing.loads no max_age), SSRF via requests/urllib/httpx, DRF ModelSerializer fields='__all__' |
| Express / Node.js | .js / .mjs / .cjs / .ts with express / koa / fastify / @hapi/hapi / restify imports |
Reflected XSS via res.send(req.query.x), eval / Function() / vm.runInNewContext with user input, child_process.exec / execSync with shell wrapper, Mongoose Model.find(req.body) NoSQL injection, prototype pollution via lodash.merge / _.set |
| iOS / Swift | .swift / .m / .mm / .h with UIKit / SwiftUI / Foundation / WebKit / Security / CommonCrypto / CryptoKit / Network imports, or Info.plist content |
Sensitive data in UserDefaults (should be Keychain), WKWebView with allowFileAccessFromFileURLs or permissive JS bridge, ATS NSAllowsArbitraryLoads = true without NSExceptionDomains allow-list, URLSession delegate trusting any server certificate, deep-link handler dispatching state-changing actions without auth confirmation |
| Phoenix / Elixir | .ex / .exs / .heex / .eex with Phoenix.LiveView / Phoenix.Controller / Plug.Conn / Ecto.Query / Phoenix.HTML references |
Phoenix.HTML.raw/1 on user-controlled data, missing force_ssl, Plug.CSRFProtection disabled, Ecto.Query.fragment with string interpolation, LiveView event handler trusting phx-value-id without re-scoping, Ecto.Changeset.cast/3 with no explicit allow-list, Plug.Conn.redirect(external:) open redirect, Phoenix.Token.verify without max_age, System.cmd shell wrapper, LiveView allow_upload missing guards |
| Rails / Ruby | .rb / .erb with ActionController / ActiveRecord / ApplicationController references |
html_safe / raw() on user input, find_by_sql / connection.execute with interpolation, protect_from_forgery disabled, params.permit! mass-assignment, eval / send / instance_eval with user input, redirect_to params[:url] open redirect, Marshal.load / YAML.load / YAML.unsafe_load deserialization, missing authenticate_user! on state-changing controllers, unfiltered render json: @user leaking password_digest / *_token / *_secret |
| React / Next.js | .jsx / .tsx / .js / .ts with react / next/* imports, or pages/api/** / app/**/route.{js,ts} path |
dangerouslySetInnerHTML with user HTML, Next.js API route without auth check, redirect() / rewrite() with user-controlled destination, <a href={user_url}> / <img src={user_url}> with javascript: or data: scheme bypass, getServerSideProps / getStaticProps / Route Handler leaking secrets via props |
Each pack's rules map to one of the universal vulnerability classes — there are NO per-framework enum values. Adding an eighth pack (Spring, Gin, Laravel, FastAPI, etc.) is described under How rule packs load.
A dedicated CI/CD pipeline rule pack activates on recognized pipeline files across eight platforms (alphabetical): Azure Pipelines, Bitbucket Pipelines, CircleCI, Drone, GitHub Actions, GitLab CI, Jenkins, Tekton. The same five rules apply to every platform: (1) external action / orb / template not pinned to an immutable SHA, (2) overly-broad permissions or scopes, (3) untrusted-ref or fork-PR build patterns, (4) secrets exposed alongside attacker-controlled input, (5) expression / interpolation injection in shell-step bodies. Activation is by file path (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, bitbucket-pipelines.yml, Jenkinsfile, azure-pipelines.yml, .drone.yml, .tekton/*.yaml), or by pipeline structure when a file arrives under another name — generic YAML never triggers these rules. Adding a ninth platform means listing its file path in packs/ci-cd.md and walking the five existing rules, mapping the platform's syntax into one of the five rows; the rule count stays fixed and only the example column grows.
A Web defense-in-depth pack covers HTTP-response hardening across every framework above: missing Content-Security-Policy on HTML responses, missing Strict-Transport-Security, missing X-Frame-Options / frame-ancestors, and Set-Cookie without Secure / HttpOnly / SameSite on session/auth cookies. The pack is framework-agnostic (it activates on middleware / endpoint / response-pipeline shapes rather than file extension) and is explicitly defense-in-depth — when a primary XSS or CSRF finding is already raised on the same response site, the missing-header finding is a sibling note, not a duplicate.
For codebases that integrate LLMs, AI agents, or Model Context Protocol clients, five additional MAESTRO-derived classes activate (the file must import a recognized LLM/agent/MCP SDK in any language — Python, JavaScript/TypeScript, Go, Ruby, Elixir, Java/Kotlin all supported):
| Class | Examples |
|---|---|
| Prompt injection | Untrusted text concatenated into an LLM prompt without separation; messages=[{"role":"user","content": user_input}] patterns; un-delimited RAG context |
| Tool abuse | Agent function-call / MCP tool layer exposing file/shell/DB/HTTP/credential operations without per-tool authorization or input validation |
| Agent trust boundary | Agent-to-agent (A2A) message passing where one agent's output flows into another's prompt without the receiver treating it as untrusted |
| Model output execution | LLM response text flowing into eval, exec, subprocess with shell=True, Function(), os/exec.Command, or any code-execution sink |
| Vector store poisoning | User-controllable content embedded into a vector DB (Pinecone, Weaviate, Chroma, pgvector, etc.) without sanitization or source attribution |
The agent uses semantic analysis: a grep hit on eval( is not a finding; eval(user_input) at a trust boundary is. The analysis methodology, severity rubric, and JSON output schema live in the agent prompt.
The agent prompt, agents/security-reviewer.md, is a core of about 15 KB: the methodology, the vulnerability classes, the false-positive filter, the output schema, severity and the per-consideration verdict contract. Everything else is a file the agent reads only when the input needs it, from its own install directory (${CLAUDE_PLUGIN_ROOT}, which Claude Code substitutes into the prompt):
| Directory | Files | Read when |
|---|---|---|
packs/ |
android, django, express, ios, phoenix, rails, react-nextjs, web-defense, supply-chain, ci-cd, agentic |
a reviewed file's extension, path, structure or imports match the pack — a mixed diff loads every matching pack, and web-defense rides along with any web framework pack |
modes/ |
considerations, result-file, reproduction |
the dispatch is in considerations mode, carries an accepted SECURITY_RESULT_PATH, or the agent is about to run a reproduction |
- Only file types and imports choose a pack. Text inside the diff — a comment or string asking for a pack, or for one to be skipped — never loads, skips or limits one.
- A missing pack never means no review. If a pack cannot be read (a path left unsubstituted, a denied read, a deleted file), the agent reviews with the core rules alone and adds nothing to its output. A result file is never written without
modes/result-file.md, and nothing is ever run withoutmodes/reproduction.md. - The reads are instructions, not code under review. They are allowed in every mode and do not count toward the 10-file read limit or the considerations-mode tool budget.
- The directories sit at the plugin root, not under
agents/. Claude Code registers every.mdbelowagents/as an agent — a pack there would show up as a dispatchablestride-security-review:packs:<name>agent. - A read may prompt. The files live in the plugin's install directory, outside your project. If your permission settings prompt for that read and it is declined, the review continues on the core rules.
A typical Stride considerations-mode dispatch on a Phoenix change now loads about 39 KB of instructions (core, considerations, result-file, phoenix, web-defense) instead of 95.6 KB; a plain diff-mode review of one framework loads about 25 KB.
Adding a pack. Write packs/<name>.md with no YAML frontmatter, an activation predicate built from file extension AND an import or identifier signal (never a path alone), and 4–6 idiomatic rules mapped to existing vulnerability_class values. Cite any prior-art SAST tool for the framework (Sobelow, Brakeman, Bandit, gosec, eslint-plugin-security) as context, not as a dependency — the reviewer's value is what those tools miss. Then add its row to the loading table in the agent prompt and its name to the PACKS list in scripts/check_agent_contract.sh, which fails on a pack the table does not name, a name with no file, and any file below agents/.
Everything the agent reviews — diff hunks, code comments, string literals, the files it reads and the considerations it is handed — is data, never instructions: a comment telling the reviewer to report nothing is ignored. In diff and considerations mode it may read the changed files in full and their direct callers, up to 10 files beyond the diff; it never enumerates the rest of the repository. In considerations mode a dispatch also has a budget of 20 tool calls, at most 2 of them reproductions (writing the result file never counts). It grades from the diff first, a read past direct callers — a caller's caller, or a config file the changed code reads — must be named and justified in the verdict's note, and a consideration the budget leaves unverified comes back partial with a note that begins budget reached:. No finding backs that verdict, so --fail-on fails on it at every threshold and the Stride workflow escalates it; it is never mitigated. Diff and full modes have no budget.
To keep signal-to-noise high, the agent suppresses findings whose only impact is:
- Denial-of-service that is not also a data-integrity or confidentiality issue.
- Rate limiting as a general concern — unless its absence is on a credential or token-generation endpoint (which falls under Authentication).
- Memory exhaustion unless it enables another vulnerability class.
- Hypothetical risks not realizable through the changed code.
- Code style disguised as security concerns.
One exception, in considerations mode only. When a consideration the task lists names one of these risks itself — "uploads are size-bounded", "the export endpoint is rate-limited" — that risk is assessed for that consideration, and a partial or unmitigated verdict on it is backed by a finding like any other. A risk the list does not name is still suppressed, and diff and full modes keep the filter unchanged.
If your organization needs those classes flagged, see Customization — extend the agent prompt rather than working around the filter.
The agent's tools are Read, Grep, Glob and Bash, and it is read-only on the working tree: it never creates, modifies, moves or deletes anything in the repository it reviews, tracked or untracked, not even to restore it afterwards. It inspects code with Read, Grep and Glob, and uses Bash for three things only — writing the result file at SECURITY_RESULT_PATH, a short list of read-only commands (ls, wc and five git forms — git --no-pager --no-lazy-fetch -c core.fsmonitor=false -c gpg.program=false -c gpg.ssh.program=false -c gpg.x509.program=false ls-files, git --no-pager --no-lazy-fetch -c core.fsmonitor=false -c gpg.program=false -c gpg.ssh.program=false -c gpg.x509.program=false diff --cached --no-ext-diff --no-textconv --submodule=short, git --no-pager --no-lazy-fetch -c core.fsmonitor=false -c gpg.program=false -c gpg.ssh.program=false -c gpg.x509.program=false diff --no-ext-diff --no-textconv --submodule=short <commit> <commit>, git --no-pager --no-lazy-fetch -c core.fsmonitor=false -c gpg.program=false -c gpg.ssh.program=false -c gpg.x509.program=false log --no-ext-diff --no-textconv --submodule=short --no-show-signature and git --no-pager --no-lazy-fetch -c core.fsmonitor=false -c gpg.program=false -c gpg.ssh.program=false -c gpg.x509.program=false show --no-ext-diff --no-textconv --submodule=short --no-show-signature — never a bare git diff against the working tree, which rewrites .git/index), and, when reading cannot settle a question, one reproduction inside a temporary copy, under the rules in modes/reproduction.md, which the agent reads first — without them it runs nothing. In considerations mode a reproduction only confirms a specific claim stated in a verdict's note or a finding's description, and a dispatch runs at most two.
The flags on those git forms stop git running a program named in the reviewed repository's config or attributes — a core.fsmonitor hook, diff.external, a diff.<driver>.command, a textconv driver, the gpg.program (or gpg.ssh.program or gpg.x509.program) that log.showSignature, a %G placeholder in a format.pretty default or a pretty.<name> alias would call, a core.pager when the shell has a terminal, a submodule's own diff programs when diff.submodule=diff, or the core.sshCommand, credential helper or proxy a partial clone's lazy fetch would start — which would run outside any sandbox with the agent's full environment. --no-lazy-fetch also keeps a lazy fetch from writing a pack into .git/objects, and needs git 2.44 or later; an older git rejects it and runs nothing, and the agent then reads with Read. Local config does not travel with a clone, so this takes a planted .git/config, but a reviewer that never runs reviewed code should not run a program the repository names either. The agent never drops a flag, adds --ext-diff, --textconv or --show-signature, or puts a %G signature placeholder in --format or --pretty, which runs gpg.program whatever the flags say; it reads the working tree with Read rather than through git: git ls-files -m and git diff-index without --cached run a configured clean filter. The probe's copy step lists files with git --no-lazy-fetch -c core.fsmonitor=false ls-files for the same reason — in a sparse partial clone --exclude-standard would otherwise lazy-fetch a skip-worktree .gitignore — and the probe refuses to run, grading by reading, on a git older than 2.44.
That copy is a stride-security-probe.XXXXXX directory under $TMPDIR (else /tmp), made by copying the repository's files rather than linking them, used by a single command that runs one test or snippet, and removed when that command exits. The command refuses a copy that holds a symbolic link, and runs the snippet inside a sandbox that denies network access, every write outside the copy and every read under your home directory — on macOS (sandbox-exec) also every Unix socket, launchd job creation, mach service lookups, Launch Services, Apple Events, open/launchctl/osascript, signals, POSIX and System V IPC, process-information and task-port calls to any process outside the box, opening /dev/tty or any other /dev/tty* device, and running or loading as native code any file in the copy, so a script there runs through its interpreter (sh test.sh); on Linux (bwrap) new namespaces, an empty /run, /tmp, /var and home directory, so no Unix socket under them is reachable, and a new session — under env -i, so the credentials in your environment are not inherited and HOME and TMPDIR point into the copy. On Linux the command first searches the rest of the filesystem, for at most ten seconds (twelve if find ignores the first signal), and refuses to probe when it finds a socket, a named pipe or a second path to your home directory such as a bind mount of it — a Nix daemon's socket under /nix/var, for example — when the search fails or does not finish, or when the path to your home directory holds a *, ? or [; the search reads only names and file types, but on a network filesystem those reads reach its server. It cannot see a bind mount, at a path outside your home directory, of a directory inside it, such as ~/site mounted at /srv/site, so on a host with one the snippet can read what that mount exposes, and it looks only once, before the box starts, so a socket, a named pipe or a mount that appears afterwards can be reached from the box. The snippet runs in the background with no input, and its output comes back through a pipe, never a terminal, so it cannot push input into the terminal of the shell running the probe; the probe prints the snippet's exit status as snippet exit: <n>. On exit the command kills the snippet — on macOS its whole process group, which the box starts through /usr/bin/perl as the group's leader so that this holds in zsh without a terminal too (the probe refuses to run on a Mac without /usr/bin/perl), and on Linux every process in the box's own process namespace — then unlocks the copy's directories, inside the box so that a link a surviving process swaps in cannot turn the unlock on a file outside the copy, and so that a directory the snippet locked cannot keep the copy, and removes it. It refuses to run when HOME is unset, relative, /, not a directory or not your account's home directory, when it or the copy has a quote, backslash or newline in its path, or when the copy would sit under it. Before it looks anything up it drops every empty or relative entry, such as ., from PATH, and refuses when none is left, so no such entry can run a file in the repository or the copy outside the box in place of a tool the command runs. An absolute entry is still searched even when it points into the repository, such as a project bin directory that direnv adds, so with one on PATH the agent grades by reading. Its exit trap moves to / and sets PATH to /usr/bin:/bin:/usr/sbin:/sbin before it looks anything up, the command refuses to probe when TMPDIR holds a relative path, which the trap would miss from /, and the pipe that carries the output back, which starts before that clean-up, names /bin/cat by its path. On macOS a snippet can still signal and inspect the processes it starts, but not your editor, agent or any other outside process, though it can still read their command lines (and, on a macOS release that returns them, their environments); a snippet that needs POSIX semaphores or shared memory, such as Python multiprocessing locks, fails in the box. With neither sandbox available the agent runs nothing and grades by reading, and it runs nothing in CI (the command checks CI first) or when the caller says the change comes from an untrusted contributor, because the sandbox hides your home directory but not the rest of the filesystem. A probe installs nothing and never runs a command written in the code under review. On macOS a process that leaves the snippet's process group, such as one that calls setsid() or setpgid(), can outlive the command, because the command signals only the group it started and never a process by name; it stays in the box, with no network access, no read under your home directory, no signal to an outside process and no write outside the copy's directory, and while it holds the command's output open the command does not return. On either system a command killed with SIGKILL, which no trap can catch, kills nothing and removes nothing, so the snippet and what it started can keep running inside the box until they end on their own. A dispatch killed mid-command, or a process the snippet started that outlives the command, can leave a copy behind; it holds only copied files, and an operator can clear stale ones with:
find "${TMPDIR:-/tmp}" -maxdepth 1 -name 'stride-security-probe.*' -mmin +60 -exec rm -rf {} +scripts/check_probe_cleanup.sh runs the probe block itself on macOS, with a harmless snippet of its own, under bash, sh and zsh with no terminal: a snippet's background process must be gone when the command exits, and a snippet's child that calls setsid() must still be refused, after the command exits, a write outside the copy, a read under your home directory, a connection to the loopback address and a signal to an outside process; and with ., an empty entry and relative entries on PATH, no tool planted in the repository or the copy under the name of one the command runs may run; an rm planted in an absolute PATH entry must not run in the exit trap; and a relative TMPDIR must refuse to probe and leave no copy in the repository. CI does not run it — eval.yml runs on Linux, where sandbox-exec is absent and the script only reports skipped — so run bash scripts/check_probe_cleanup.sh on a Mac after changing the block. The Linux bwrap box has never been run.
The guarantee is the agent's written contract, not the tools: line: Claude Code does not narrow Bash to particular commands through an agent's frontmatter, so Bash is listed whole and the prompt says what it is for. scripts/check_agent_contract.sh pins that contract and checks the tools: line against it.
The agent returns a single fenced ```json document conforming to the schema below — or, when the caller supplies an absolute SECURITY_RESULT_PATH (`.stride/.security--r.json`; the Stride workflow does, `/security-review` does not), writes that same document to the file and returns at most 10 plain-text lines (`result:`, verdict counts, severity counts, `files_reviewed`, no fence). If the write fails it returns `result: NOT WRITTEN — ` and then the document inline. It never writes the document to any other file a prompt names.
{
"findings": [
{
"severity": "critical | high | medium | low | info",
"file": "path/relative/to/repo/root.ext",
"line": 42,
"vulnerability_class": "injection | authentication | authorization | data_exposure | crypto | input_validation | race_condition | xss_or_code_exec | insecure_config | supply_chain | prompt_injection | tool_abuse | agent_trust_boundary | model_output_execution | vector_store_poisoning",
"cwe": ["CWE-89"],
"owasp": ["A03:2021"],
"description": "What and why",
"remediation": "Specific fix",
"confidence": "high | medium | low",
"maestro_layer": "data-operations",
"patch": "--- a/lib/users.ex\n+++ b/lib/users.ex\n@@ ..."
}
],
"summary": {
"files_reviewed": 7,
"findings_by_severity": {"critical": 0, "high": 1, "medium": 2, "low": 0, "info": 0},
"files_skipped": [{"path": "priv/static/app.js", "reason": "oversize"}],
"suppressed_count": 0,
"rci_passes": 0
}
}Required per-finding fields (always present): severity, file, line, vulnerability_class, cwe, owasp, description, remediation, confidence. Every finding carries cwe (array of CWE-IDs like ["CWE-89"]) and owasp (array of OWASP Top 10 2021 category strings like ["A03:2021"]) so triage tools can group findings by canonical class without parsing prose. Both arrays default to [] only when a finding doesn't map to any standard category (rare).
Optional per-finding fields (emitted only when the corresponding flag is set):
| Field | Emitted when | Notes |
|---|---|---|
maestro_layer |
--maestro is set (the command sends its MAESTRO block) |
One of seven canonical layer IDs from CSA MAESTRO: foundation-models, data-operations, agent-frameworks, deployment-infrastructure, evaluation-observability, security-compliance, agent-ecosystem. Omitted entirely when --maestro is not set. |
patch |
--patches is set (the command sends its Patches block) AND the agent can produce a surgical fix |
A unified-diff string the user can pipe to git apply. The agent emits a patch only when the fix is surgical (1–20 lines, single file, no new deps, no API breaks), unambiguous, and verifiable from the supplied input alone. Most findings won't have one even with --patches set. |
Optional summary fields:
| Field | Emitted when | Notes |
|---|---|---|
files_skipped |
--full is set |
Array of {path, reason} records for files the binary/size filters dropped. reason is one of binary, oversize, unreadable. Always emitted in full mode (even as [] to prove the filter ran); omitted in diff mode. |
suppressed_count |
--baseline is set |
Integer count of findings filtered out by the baseline. A finding that backs a partial or unmitigated consideration verdict is never filtered out, so it is never counted here. Omitted entirely when no baseline is in play. |
rci_passes |
--rci [N] is set |
Integer recording how many Recursive Criticism & Improvement passes ran on top of the initial dispatch. Every pass re-sends the considerations, MAESTRO and patches directives of the first dispatch, so consideration_verdicts, maestro_layer and patch survive it. Omitted when --rci is not set. |
consideration_verdicts |
--considerations <source> is set |
Top-level array with one {consideration, status, evidence, note} entry per listed consideration, in order, where status is exactly one of mitigated / partial / unmitigated (there is no fourth value; a consideration the change has no surface for is mitigated). A partial/unmitigated verdict is backed by a matching findings[] entry, which its evidence names by file:line (or a file:start-end range). A gap that predates the change is graded against the changed code and named in note plus one info finding. A consideration that embeds a credential, or names where one lives, is echoed as [REDACTED — row text embedded a credential] in its position rather than verbatim. Omitted entirely when --considerations is not set. |
Cross-batch dedup (full mode). Full-mode batches are merged with an order-stable dedup pass keyed by (file, line, vulnerability_class) — duplicates that surface across batches or RCI passes collapse to the first occurrence. Diff mode is a single dispatch and dedup is a no-op there; the merged document is byte-identical to the agent's output.
Opt-in rules travel with their flag. The agent prompt carries only a one-line gate for maestro_layer, patch and rci_passes; the MAESTRO layer table and its mapping, the patch rules and the RCI critique directive live in the slash command, which sends each one only when its flag is set. A caller that dispatches the agent directly gets these fields only by sending the same blocks (see "Opt-in directive blocks" in commands/security-review.md).
Flag composition. All flags compose. --maestro --rci 2 --patches --baseline --full --json lib/ is a valid invocation. The --json flag prints the document verbatim so other tools (CI gates, Stride hooks, dashboards) can consume it. With --considerations, --rci re-grades the verdicts on every pass, --baseline never suppresses a finding that backs a partial or unmitigated verdict, and --fail-on fails on any unmitigated verdict whatever the threshold.
The default /stride-security-review:security-review invocation reviews the working-tree diff against HEAD. That answers "is this PR safe to merge?" — but not "what latent issues are in this codebase right now?" The --full flag (added in v1.1.0) answers the second question by reviewing whole files rather than hunks.
Typical reasons to reach for --full: onboarding the plugin onto an existing repo (establish a baseline before you start gating PRs); a periodic posture check (quarterly, or on a cron); vendoring or forking an upstream codebase (review the imported code end-to-end before integrating); or a class-wide audit where the changed code is not the unit of interest. For PR-time gating, stay in diff mode — it is faster and the right shape for that question.
/stride-security-review:security-review --full # review every tracked file
/stride-security-review:security-review --full lib/ apps/web/ # scope to listed paths
/stride-security-review:security-review --full --json # raw JSON for piping
--full is additive — it composes with path arguments and with --json. Diff mode remains the default and its behavior is unchanged. The output JSON schema is identical in both modes, so any tool already consuming the diff-mode JSON continues to work against a --full run.
This is the surface contract every downstream piece of the plugin (slash command, agent prompt, skill, fixtures) follows. Implementation details for each bullet live in the file that owns that piece.
| Concern | Decision |
|---|---|
| Flag | --full. Parsed in the slash command's argument step and stripped from the path list before it reaches enumeration. |
| Enumeration source | git ls-files (optionally narrowed to user-supplied paths). This honors .gitignore, untracked-exclusions, and sparse-checkout — none of which find or a filesystem walk would honor for free. Untracked files are intentionally out of scope; if you want them reviewed, git add -N them first. |
| Binary filter | A single-shot grep -Il . <file1> <file2> ... call lists every non-empty text file in the enumeration. Any candidate path NOT in grep's stdout is treated as binary and skipped. This preserves the original null-byte-in-prefix heuristic (grep -I) and avoids dispatching the agent on PNGs, compiled artifacts, or minified bundles whose null bytes break tokenization. The call is batched into chunks of ~50 paths to stay under ARG_MAX; each chunk is a single Bash invocation matching the slash command's Bash(grep:*) permission entry, so the filter runs unattended in CI (no per-file pipe to gate). |
| Size cap | Skip any file larger than 262,144 bytes (256 KiB). Above this threshold the file is almost always generated, vendored, or minified, and the agent's signal-to-noise on it collapses. A single-shot wc -c <file1> <file2> ... call (batched into chunks of ~50) yields one <bytes> <path> line per file; any path over the threshold lands in files_skipped with reason: "oversize". Each wc chunk is a single Bash invocation matching Bash(wc:*). |
| Batch size | Dispatch the security-reviewer agent on 10 files per batch. Below this we burn dispatch overhead; above it we crowd the context window and lose per-file fidelity. Batches MAY be dispatched in parallel via multiple Agent tool calls in a single response. |
| Findings merge rule | The output of each batch is a JSON document conforming to the schema in the previous section. Merge in batch order, then run an order-stable dedup pass keyed by (file, line, vulnerability_class) — first occurrence wins. Dedup catches the rare case where shared setup code drives different batches to converge on the same finding, and where RCI passes replay the same batch. summary.findings_by_severity is recomputed from the post-dedup findings list, not summed from per-batch counters (those drift after dedup). summary.files_reviewed is summed across batches. The dedup pass is a no-op in diff mode (one dispatch, no RCI) so diff-mode JSON output is byte-identical to the agent's response. |
| Skipped-files reporting | The Step 2b enumeration loop records every filtered file as {path, reason} where reason ∈ {binary, oversize, unreadable}. The merged document carries these as summary.files_skipped (always emitted in full mode, even as []) so users can audit coverage. The human-readable report renders a ## Skipped block capped at 50 entries with an ... and N more overflow line. |
| Empty-input short-circuit | If enumeration yields zero files after filtering (e.g., empty repo, all files binary or over-cap), print the same short-circuit message diff mode uses for an empty diff and stop without dispatching the agent. |
| Output schema | The JSON document downstream tools consume is identical in diff and full modes for the required fields; full mode additionally emits summary.files_skipped. Optional fields gated by flags (maestro_layer, patch, summary.rci_passes, summary.suppressed_count) compose the same way in both modes. |
- It does not change vulnerability classes, severity rubric, or the false-positive filter. Those live in the agent prompt and apply to both modes.
- It does not become the default. Diff mode is the PR-gating workflow most users invoke; full mode is an explicit posture-check action.
- It does not enumerate untracked files.
git ls-filesis the source of truth; if a file isn't tracked, it isn't reviewed. - It does not deduplicate findings against an earlier run. Each invocation is independent; trend tracking is the consumer's job.
Two customization knobs:
- Scope by path. Pass paths as arguments to limit the review to a subset of changed files (diff mode) or tracked files (full mode). Useful in monorepos. Composable with both modes.
- Extend the agent prompt. Fork or patch
agents/security-reviewer.mdto add organization-specific vulnerability classes or to tighten/loosen the false-positive filter, or add or edit a rule pack inpacks/(see How rule packs load). Keep the output schema stable so downstream tooling continues to parse correctly.
The skill at skills/security-review-essentials/SKILL.md documents the surface; the agent prompt documents the behavior. Customize the agent prompt for behavior changes; customize the skill description for trigger-phrase tuning. Both descriptions are loaded into every session, so scripts/check_agent_contract.sh bounds each at 150–400 bytes and pins its trigger phrases; a deliberate trigger change updates its pin there too.
The --json flag makes /stride-security-review:security-review pipeable. Examples:
- A Stride completion hook can run
/stride-security-review:security-review --jsonand refuse to mark a taskdoneif a critical finding is present. - A CI gate can run
/stride-security-review:security-review --full --jsonon a schedule to track the codebase-wide finding count over time without coupling to any one PR. - A CI gate can call the agent directly (without the slash command) by importing the agent prompt and feeding it a diff from
git diff origin/main. Importpacks/andmodes/with it: the prompt reads them from${CLAUDE_PLUGIN_ROOT}, and a caller that has only the core file gets the core rules only. - Any direct caller opens the prompt with the agent's one mode tag,
/security-review invocation, mode: <mode>(diff,considerationsorfull_file), on its own line; no other spelling is a tag. With no tag the agent reviews indiffmode, except that a considerations list an older caller sends with no tag, under any header, is still reviewed inconsiderationsmode. - A dashboard can ingest the JSON across many runs and chart the per-class trend.
The agent does not call any external service, so composition is safe in repos with sensitive content.
The plugin ships a reference workflow at .github/workflows/security-review.yml. Drop it into your own repo's .github/workflows/, set an ANTHROPIC_API_KEY secret, and the slash command will run on every pull request — blocking the merge when a finding meets the configured severity threshold.
When the slash command is invoked with --fail-on <severity>, it exits non-zero if any finding at or above the threshold is present. Severities order as critical > high > medium > low > info.
With --considerations, the gate also fails closed on the verdicts, whatever the threshold: an unmitigated verdict trips it even with no finding, as does a partial verdict that no finding backs and a missing or malformed consideration_verdicts array — including one whose entries do not answer the considerations in order. A partial verdict with a backing finding is gated by that finding's severity.
| Exit | Meaning |
|---|---|
0 |
No findings at/above <severity> and, with --considerations, no unmitigated verdict, no unbacked partial verdict and well-formed verdicts (or --fail-on not set) |
1 |
At least one finding at/above <severity>, or (with --considerations) an unmitigated verdict, a partial verdict no finding backs, or missing or malformed verdicts |
2 |
Setup or usage error (invalid --fail-on value, missing ANTHROPIC_API_KEY, agent dispatch failure) |
Default behavior (no --fail-on flag) preserves exit 0 always — byte-identical exit behavior for callers that do not opt in.
claude -p exit-code propagation has varied across Claude Code CLI versions. The shipped workflow uses a belt-and-suspenders pattern: it runs the slash command with --json --fail-on <severity> AND post-checks the JSON output with jq. The gate fails if EITHER the slash command exited non-zero OR jq counts at least one finding at/above the threshold. Either signal is sufficient to block the merge.
# Snippet from .github/workflows/security-review.yml (full file in this repo).
# The gate lines below are excerpted verbatim from that workflow — it is the
# source of truth; edit the workflow first and re-excerpt here.
- name: Run security review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
set +e
claude -p "/stride-security-review:security-review --json --fail-on critical" > review.json
claude_exit=$?
set -e
gate_count=$(jq -r '[.findings[]? | select(.severity == "critical")] | length' review.json)
# Fail the job if EITHER the JSON shows gated findings OR `claude -p` itself
# exited non-zero (which covers both gate trips [exit 1] and slash-command
# usage / dispatch errors [exit 2]). The "$claude_exit -ne 0" form catches all
# non-zero exits without conflating them with the no-output guard above.
if [ "$gate_count" -gt 0 ] || [ "$claude_exit" -ne 0 ]; then
echo "::error::Security review gate tripped (${gate_count} findings at/above ${FAIL_ON}; claude_exit=${claude_exit})."
exit 1
fiThe shipped workflow does not pass --considerations, so its jq post-check counts findings only. If your workflow adds --considerations, extend the jq gate so it also counts unmitigated verdicts, for example ([.findings[]? | select(.severity == "critical")] | length) + ([.consideration_verdicts[]? | select(.status == "unmitigated")] | length). The command's own exit code also covers a partial verdict that no finding backs and a missing or malformed verdict array, which a one-line jq filter does not.
Stricter posture: --fail-on high blocks on any critical or high finding. --fail-on medium blocks on critical, high, OR medium. info-only findings never trip a threshold. Pair with --baseline to accept a known set of findings and gate only on new ones; a baseline never suppresses a finding that backs a partial or unmitigated consideration verdict.
--sarif emits a SARIF v2.1.0 document on stdout — the de facto interchange format for security findings. Mutually exclusive with --json; both flags together produces exit 2.
# Upload findings to GitHub Code Scanning. The sarifs endpoint takes the
# SARIF payload gzipped then base64-encoded; gh api -f cannot read that
# directly from stdin, so capture into a variable first.
ENCODED=$(claude -p "/stride-security-review:security-review --sarif --full" \
| gzip \
| base64 -w0) # macOS base64 has no -w0; drop the flag there
gh api -X POST "repos/${GITHUB_REPOSITORY}/code-scanning/sarifs" \
-f commit_sha="${GITHUB_SHA}" \
-f ref="refs/heads/${GITHUB_REF_NAME}" \
-f sarif="${ENCODED}"Findings appear in the repository's Security → Code Scanning tab with severity badges, file:line links, and CWE/OWASP tags. Stable cross-run dedup uses the same fingerprint algorithm as --baseline (SHA-256 of vulnerability_class|file|line|first-80-chars-of-description, emitted under the stride/v1 key in partialFingerprints).
The full SARIF field mapping lives in schema/README.md; the schema itself is referenced from https://json.schemastore.org/sarif-2.1.0.json.
By default, diff mode scans git diff HEAD — i.e., the working tree against the last commit on the current branch. That's the right scope for a local pre-commit check, but the wrong scope for a CI gate, which should review every change the branch introduces relative to its merge target.
The --base <ref> flag widens the diff to <ref>...HEAD (three-dot range). Three-dot scopes strictly to the changes the current branch introduced over the merge-base; two-dot would also include base-side commits since divergence, producing a noisier diff. On GitHub Actions, pass --base origin/${{ github.base_ref }}. On GitLab, pass the merge-request target. The shipped workflow does this automatically when github.base_ref is non-empty. The flag is a no-op under --full (full mode reads tracked files via git ls-files, which is ref-independent). Invalid refs produce exit 2 with a clear error; the command never silently falls back to HEAD.
The scripts/run_eval.sh runner dispatches this checkout's security-reviewer agent against every fixture in test/fixtures/ and asserts the results documented in test/fixtures/EXPECTED.md. It is the same suite CI runs (.github/workflows/eval.yml).
What "this checkout's agent" means, concretely — each fixture runs as:
claude -p --plugin-dir <repo root> --agent stride-security-review:security-reviewer \
--tools '' --disallowedTools '<file and shell tools>' --strict-mcp-config \
--no-session-persistence --output-format text # prompt on stdin--plugin-dirloads the plugin from the working tree and overrides an installed copy of the same name, so an edit toagents/security-reviewer.mdis what gets scored — not the released version, and not base Claude.--agentmakessecurity-reviewerthe session agent; the fixture prompt (the whole file, or the diff plus its considerations list) is its input.- The call runs from an empty scratch directory with, by default, every tool off and no MCP servers. The prompt already carries everything the agent needs, and this keeps it from reading the expected answers in
EXPECTED.mdor editing the repo. It also means the eval never exercises the agent's read scope — and, since the rule packs are files the agent reads, a default run scores the core prompt with no pack loaded, the agent's missing-pack fallback. To score the agent as it runs in Claude Code, with its packs, give it aReadscoped to a plugin copy withouttest/:EVAL_PLUGIN_DIR=<copy> EVAL_TOOLS=Read EVAL_ALLOWED_TOOLS="Read(/<absolute copy path>/**)" EVAL_DISALLOWED_TOOLS='Grep Glob Bash Edit Write NotebookEdit WebFetch WebSearch'. The eval checks verdicts and whether a finding exists — not redaction,notetext, or a finding's severity — so those are checked by hand inlogs/where a row says so.
Every run prints the exact command as # invocation: … and the auth mode as # auth: … right after the TAP plan line; --dry-run prints them without calling Claude, and scripts/check_eval_invocation.sh pins them (key-free, in CI).
jqon$PATH- The Claude Code CLI (
claude) on$PATH— setCLAUDE_CLIif your binary lives elsewhere - Auth (unless using
--dry-run):ANTHROPIC_API_KEYexported, or a CLI logged in to claude.ai (claude auth statusreportsloggedIn). With neither, the runner exits2. It never prints the key or the auth-status output.
bash scripts/run_eval.sh # every expectation in EXPECTED.md — check_fixtures.sh prints the current count
bash scripts/run_eval.sh --fixture test/fixtures/sql_injection.py
bash scripts/run_eval.sh --only considerations/ # only fixtures whose path starts with the prefix
bash scripts/run_eval.sh --dry-run # parser/comparator only; no API calls
bash scripts/run_eval.sh --verbose # echo prompts and raw agent JSON to stderr| Variable | Default | Purpose |
|---|---|---|
EVAL_PLUGIN_DIR |
the repo root | Plugin directory to load — point it at a modified copy to check that a prompt change moves the score |
EVAL_AGENT |
stride-security-review:security-reviewer |
Agent to run |
EVAL_TOOLS |
empty (no tools) | Value passed to claude --tools |
EVAL_ALLOWED_TOOLS |
empty | Tools that may run without a permission prompt. When set, the run passes --allowedTools with it and --setting-sources '', so your own settings, allow-list and hooks stay out of the run. With Bash in the list every shell command the agent issues runs unprompted and your own deny rules and sandbox settings are not loaded — use it only on these first-party fixtures, with EVAL_PLUGIN_DIR pointing at a copy of the plugin without test/ |
EVAL_DISALLOWED_TOOLS |
Read Grep Glob Bash Edit Write NotebookEdit WebFetch WebSearch |
Value passed to claude --disallowedTools |
LOG_DIR |
logs |
Where per-fixture logs land |
Output is TAP 13: one ok N / not ok N line per fixture, followed by a trailing pass/fail summary. Exit code 0 means every expectation held: for a findings fixture, the expected vulnerability_class + severity was produced at least once on the expected file (the Bitbucket multi-finding fixture requires both expected findings); for a → NONE control, no finding at all; for a considerations-mode fixture, the ordered consideration_verdicts[].status list matches the row, plus the row's backing-finding expectation when it states one.
Per fixture, three files land in logs/ (gitignored):
logs/<sanitized-path>.json— the parsed JSON document the agent emitted, with any wrapping prose stripped.logs/<sanitized-path>.raw.txt— the full unmodified stdout fromclaude -p, useful when the parser can't fence-extract or when you want to see what surrounded the JSON.logs/<sanitized-path>.err.txt— the CLI's stderr; an unknown agent name or an auth failure shows up here.
EXPECTED.md ends with a Recorded runs table: the date, CLI version, auth mode and TAP result of each real run, so a ticked row always traces back to a run rather than to a hand edit.
.github/workflows/eval.yml runs the key-free checks first (fixture parity, transform tests, the agent contract pins, the invocation check), then the eval — with Read scoped to a copy of the plugin without test/, .git or logs/, so the agent loads its rule packs as it does in Claude Code and still cannot read EXPECTED.md. A tool-less run would score the core prompt alone. On a push to main or a manual dispatch, a missing ANTHROPIC_API_KEY secret fails the job — a green run on main means the agent eval actually ran. On a pull request the key is often unavailable by design (GitHub gives fork and Dependabot PRs no secrets), so there the eval is skipped with a notice and the key-free checks still gate the PR. scripts/check_eval_invocation.sh runs the workflow's key-gate script for each event, so this behaviour is tested rather than only described.
The runner asserts (file, vulnerability_class, severity, count). CWE and OWASP mismatches surface as # warn: TAP comments but do not fail the run — they are advisory metadata, not the contract. EXPECTED.md is the spec; do not modify it to match the agent.
Issues and PRs welcome at https://github.com/cheezy/stride-security-review. For prompt or filter changes, please include a smoke-test diff and the expected finding in your PR description so reviewers can verify the change does what you say.
MIT — see LICENSE.