security-mcp

Last updated: 2026-07-07

An autonomous application-security engineering layer for AI-assisted development.

security-mcp is a Model Context Protocol server that turns your AI coding assistant into a security engineer that does the work, not a linter that files tickets. It reads code the way an attacker does, writes the secure fix inline, and enforces a gate in CI so insecure code cannot merge. The operating mandate across the product is the same one a strong security hire would hold: roughly 90% fixing, 10% advisory.

Platform and security teams can standardize their entire AppSec program on it. A solo founder can install it in a minute and ship safer code on day one. No security background is required to benefit, but nothing is dumbed down for the people who have one.

Works with Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf, Codex, Replit, and any MCP-compatible editor.

npx -y security-mcp@latest install

Table of Contents

• Why this exists
• Is security-mcp safe to use?
• What's new in 1.3.5
• What's new in 1.6.1
• What's new in 1.6.0
• What's new in 1.5.0
• What's new in 1.4.0
• What's new in 1.3.3
• System overview
• The two entry points
  • /senior-security-engineer
  • /ciso-orchestrator
• The gate engine
• Cloud security controls engine
• Install
• CI/CD gate
• Built for teams
• Self-protection and supply-chain posture
• MCP tools
• Frameworks
• Policy and exceptions
• Environment variables
• The 10 non-negotiable rules
• CLI reference
• Documentation and disclosure
• License

Why this exists

Most security tooling stops at detection. It produces a list, hands it to a human, and waits. That model breaks down when AI assistants are writing the majority of the code, because the volume of change outpaces anyone's ability to triage a backlog by hand.

security-mcp inverts the default. When it finds a vulnerability it writes the production-ready fix into your working tree, re-runs the check to confirm the issue cleared, and only then moves on. The same engine runs as a deterministic gate in CI, so the contract is simple: HIGH and CRITICAL findings do not merge.

You get three things from one install:

• An interactive security engineer that fixes code inside your editor.
• A multi-agent security program that runs a full audit on demand.
• A standalone CI gate that needs no AI session to enforce the line.

Is security-mcp safe to use? (the MCP's own security & governance)

A security tool that reads your repository and calls out to an AI model is itself part of your trust boundary. Short answer: security-mcp runs locally, sends your code to a third party only for steps you explicitly opt into, and is built so it cannot be silently disabled or made to lie about what it did.

Does it send my code anywhere?

No, not by default. security-mcp runs as a local MCP server over stdio (src/mcp/server.ts connects via StdioServerTransport, never an HTTP listener) or as a plain CLI, and there is no telemetry call anywhere in the server or CLI code. The network calls that do exist are ones you opt into: live threat intel (CISA KEV, EPSS, OpenSSF Scorecard, npm registry), scanner-binary and skill downloads, and any Slack/Jira/PagerDuty/webhook integration you configure. Set SECURITY_OFFLINE=1 for a fully air-gapped run.

How does security-mcp protect my code and secrets?

Findings never echo the thing they detect. Secret-scan matches are replaced with [REDACTED] (src/gate/checks/secrets.ts), a hardcoded session secret is shown truncated as prefix…suffix (src/gate/checks/web-hardening.ts), and an invisible-Unicode prompt-injection finding reports only the codepoint and location, never the raw bytes (src/gate/checks/emerging-supply-ai.ts). Regex scanning is hardened against hostile input too: isCatastrophicRegex rejects catastrophic-backtracking patterns and user-supplied patterns are length-capped, so a crafted string in a malicious repo can't hang the scanner (src/repo/search.ts).

Can the gate be silently disabled?

Not without leaving evidence. Policy, exceptions, and baseline files are HMAC-signed (SECURITY_POLICY_HMAC_KEY, security-mcp sign-policy). If the signature is missing or invalid, the gate does not just warn — it forces HIGH and CRITICAL back into the blocking severity set regardless of what the policy file says (src/gate/policy.ts), so editing an unsigned policy to clear severity_block still can't let HIGH/CRITICAL findings merge. A check module that throws never disappears quietly either: it becomes a HIGH GATE_CHECK_CRASHED finding, with the error text sanitized to strip local filesystem paths before it's shown (sanitizeErrorMessage, src/gate/result.ts).

Can a multi-agent run fake a clean result?

Every /ciso-orchestrator run writes a hash-linked, optionally HMAC-signed attestation chain (initChain, attestAgent, verifyChain, getChain in src/mcp/audit-chain.ts), and the merge step verifies each agent's findings hash against its signed attestation before trusting it (src/mcp/orchestration.ts) — a tampered chain or a hash mismatch forces the gate to FAIL. Spawned agents are also held to a capability floor: enforceCapabilityFloor (src/mcp/capability-enforcer.ts) checks that each agent ran at the model tier its task required (per src/mcp/model-router.ts's task-capability map) and produced real evidence, raising a HIGH finding for a degraded agent and a run-level CRITICAL that fails the gate if any agent falls short.

Does it execute anything unsafely?

Child processes (git, npm audit, binary downloads) are invoked with execFile/spawnSync and fixed argument arrays, never a shell string built from repo or user input (src/cli/onboarding.ts, src/gate/baseline.ts), so the tool itself can't be turned into a command-injection vector. The network fetches it does make are restricted to explicit host allowlists — scanner binaries to ALLOWED_BINARY_HOSTS (src/cli/onboarding.ts), skills to a raw.githubusercontent.com-only prefix check (src/mcp/orchestration.ts) — and downloaded binaries are verified by SHA-256 before use.

Does security-mcp trust itself?

It scans its own source on every change: .github/workflows/security-gate.yml runs the same gate against security-mcp's own code in CI, with a narrowly-scoped exceptions file (.github/security-exceptions-ci.json) for the handful of intentional test fixtures and non-applicable controls. Its own supply chain stays small and pinned: five runtime dependencies (package.json), a committed lockfile, and CI actions pinned to full commit SHAs rather than floating tags.

| Mechanism | What it protects | Where in code | | --- | --- | --- | | Local stdio process, no listener, no telemetry | Your code never leaves your machine to a third party by default | src/mcp/server.ts | | HMAC-signed policy / exceptions / baseline | An unsigned edit can't silently weaken the gate; HIGH/CRITICAL stay blocked | src/gate/policy.ts, src/gate/exceptions.ts, src/gate/baseline.ts | | Hash-linked, optionally signed audit chain + attestations | A verified record of what actually ran, not a self-reported one | src/mcp/audit-chain.ts, src/mcp/orchestration.ts | | Fail-safe crash containment | A crashing check becomes a HIGH finding, not a silent blind spot | src/gate/policy.ts, src/gate/result.ts | | ReDoS-hardened pattern matching | A hostile repo or string can't hang the scanner | src/repo/search.ts | | Secret/PII redaction in findings | Findings never echo a full secret or raw invisible bytes | src/gate/checks/secrets.ts, src/gate/checks/web-hardening.ts, src/gate/checks/emerging-supply-ai.ts | | Host-allowlisted downloads + SHA-256 verified binaries | Skill/scanner fetches can't be redirected to an attacker host | src/cli/onboarding.ts, src/mcp/orchestration.ts | | No-shell child processes | Can't be turned into a command-injection vector | src/cli/onboarding.ts, src/gate/baseline.ts | | Capability-floor enforcement for spawned agents | Agents can't silently run under-powered or unsupervised | src/mcp/capability-enforcer.ts, src/mcp/model-router.ts | | Self-scan in CI | The gate is held to its own bar on every change | .github/workflows/security-gate.yml | | Minimal, pinned dependencies | Small, auditable attack surface | package.json, .github/workflows/ |

security-mcp is honest about where its trust model stops: this is a single-tenant, local, stdio MCP whose trust root is the installed package, and an unsigned attestation chain is tamper-evident rather than cryptographically tamper-proof unless you set SECURITY_AUDIT_HMAC_KEY. See the CHANGELOG for the full residual-risk disclosure, and self-protection and supply-chain posture below for more detail on the CI/gate hardening.

What's new in 1.3.5

1.3.5 is the first version published to npm since 1.3.4. The "What's new" sections below it (1.4.0 through 1.6.1) describe internal milestones that never reached the registry; everything they describe ships publicly in this release.

Pre-release checklist synced with the detection engine. security.checklist now carries a section for every detection domain the gate's check modules actually cover, growing from roughly 180 to 246 items across 8 new sections: Containers / Docker, Database, Data Platform (Databricks / Snowflake), GitOps (ArgoCD / Flux / Helm), Cryptography / PKI, AI-Assisted Development (Vibe Coding), Data Leakage Prevention, and Emerging Threats. Each item is derived from the real finding IDs in src/gate/checks/, so the human attestation checklist and the automated gate now agree on what "covered" means. See the CHANGELOG for the full breakdown.

What's new in 1.6.1

1.6.1 (internal milestone, published as part of 1.3.5) completes the 90%-fix mandate and closes web-hardening detection blindspots: a sixth always-on check module, and a remediation map that now covers every detection ID the engine ships.

Does security-mcp detect open redirect, clickjacking, and hardcoded session secrets?

Yes. A new always-on module, src/gate/checks/web-hardening.ts (checkWebHardening), is wired into runAllChecks and CHECK_NAMES as web-hardening and runs unconditionally on every scan, the same way vibe-coding and emerging-supply-ai do, because these flaws are dangerous regardless of what surface the changed files suggest. Six new rules, each verified firing on a planted vulnerability:

• WEB_MISSING_SECURITY_HEADERS (MEDIUM, CWE-1021/693): a web-server surface exists but there is no response-header hardening anywhere in the repo, no helmet, no X-Frame-Options, no HSTS, no Content-Security-Policy, leaving the app open to clickjacking and protocol downgrade with no CSP as a backstop. This rule is conservative by design: it fires once at repo level and skips static or library repos that have no server surface to harden.
• WEB_OPEN_REDIRECT (HIGH, CWE-601): a redirect target taken directly from user input, for example res.redirect(req.query.url) or an unvalidated NextResponse.redirect.
• WEB_HARDCODED_SESSION_SECRET (HIGH, CWE-798/330): a session, cookie, or JWT signing secret hardcoded as a literal or a well-known weak default (the classic "keyboard cat" case). The rule excludes process.env reads and .env.example files, and truncates the secret value in evidence so the finding never echoes the whole thing.
• WEB_EMAIL_HEADER_INJECTION (HIGH, CWE-93/88): user input flowing unsanitized into email envelope fields (nodemailer/SendGrid to, subject, or custom headers), which opens the door to CRLF header injection and mail-relay abuse.
• WEB_SERVER_ACTION_NO_AUTHZ (HIGH, CWE-306/862): a Next.js Server Action ('use server') that performs a database mutation or read with no server-side auth verifier. A Server Action is a publicly-invocable POST endpoint under the hood, so hiding the triggering button in the UI does not protect it.
• WEB_SENSITIVE_FIELD_IN_RESPONSE (MEDIUM, CWE-213/200): a database row or object serialized straight into a response even though it carries a secret field (passwordHash, salt, mfaSecret, apiKey, refreshToken, ssn), or a SELECT * shape returned as-is.

These six rules lift first-party static rule coverage from roughly 883 to roughly 887 finding IDs. Detection stays regex/heuristic, the same convention as the rest of the gate: no AST, no data-flow graph.

How does security-mcp fix vulnerabilities automatically?

By shipping a concrete remediation template, keyed by finding ID, for essentially every rule the engine can fire, so the AI-assisted-development gate can write the fix instead of just filing a finding. Before 1.6.1, that was true for only 71 of roughly 882 finding IDs (about 8%). 1.6.1 adds six domain remediation partials under src/gate/remediation-parts/ — cloud.ts (256 templates: Kubernetes, IaC, Docker, ArgoCD, Flux, Helm, GitOps, infrastructure, runtime), ai.ts (69: AI and agentic findings), data.ts (172: crypto, JWT, SAML, OAuth, passwords, database, Snowflake, Databricks, supply-chain hygiene), web.ts (203: web, API, business logic, GraphQL, Android, iOS, DLP, CI), misc.ts (112: injection, deserialization, SSRF, TLS, tokens, mobile storage, XSS), and web-hardening-remediations.ts (6, one per new rule above) — all merged into REMEDIATION_MAP.

The result: 888 fix templates covering 100% (887 of 887) of detection IDs, up from roughly 8% before this release. Every template ships a realistic vulnerable pattern, a concrete secure fix in the correct language, a plain-language explanation, and standards references (CWE plus OWASP Top 10, API Security Top 10, LLM Top 10, or MASVS, and NIST/CIS/PCI DSS/FIPS or the relevant provider's docs). This is what turns the product's "90% fixing, 10% advisory" mandate from a description of how the agent tends to behave into a deterministic, verifiable property of the detection engine itself.

What version is security-mcp on, and does that matter for upgrades?

1.6.1, up from 1.6.0. This is a detection-and-remediation-coverage release under the project's odometer versioning rule (every version segment stays below 10), so it is a drop-in upgrade with no breaking changes.

See docs/ARCHITECTURE.md for where web-hardening plugs into runAllChecks, and docs/WIKI.md for the full rule list, severities, and remediation-coverage detail.

What's new in 1.6.0

A new always-on module targeting how attackers exploit vibe-coded apps. src/gate/checks/vibe-coding.ts (checkVibeCoding) runs on every scan regardless of surface, the same way emerging-supply-ai does, because the class of bug it targets, a leaked admin key or an open database rule, is dangerous whether or not the repo happens to look like "web" or "api" from its changed files. It is grounded in a run of 2025-2026 breaches in apps generated by Cursor, Lovable, Bolt, v0, and Replit: the Moltbook Supabase service_role key leak, Lovable's "VibeScamming" Row-Level-Security gap (CVE-2025-48757), the Tea app's world-writable Firebase rules, and Base44's frontend-only auth check with no server-side enforcement. Sixteen new VIBE_-prefixed rule IDs cover the recurring failure modes: client-shipped Supabase service_role/sb_secret_ keys and provider API keys, a NEXT_PUBLIC_/VITE_/REACT_APP_/EXPO_PUBLIC_ variable holding a real secret, Supabase tables without Row-Level Security or with a USING (true) policy, public Firebase/Firestore rules, API routes with no server-side authorization check, client-side-only auth guards, wildcard CORS paired with credentials, client-controlled payment prices, tokens in localStorage, unrestricted file uploads, committed .env/key files, production source maps, debug mode left on, a slopsquatting heuristic for dependencies missing from the lockfile, and unsafe prompt-injection chains (user input into a system prompt, or model output into eval/exec/a shell/dangerouslySetInnerHTML). Detection is the same regex/heuristic approach as the rest of the gate: the client-vs-server split is a path/extension heuristic, not a bundler analysis, and the slopsquatting rule is an offline heuristic where a dependency missing from the lockfile is a candidate for review, not proof of a hallucinated package. First-party static rule coverage grows from roughly 867 to roughly 883 finding IDs.

Remediation map grows to 70-plus templates. Every one of the 16 new VIBE_ finding IDs ships a concrete fix template in src/gate/remediation-map.ts (rotate-and-move-server-side for leaked keys, an ENABLE ROW LEVEL SECURITY + ownership-policy snippet, a server-side session check for API routes, an httpOnly-cookie pattern for token storage, and so on), keeping the same roughly 90%-fixing, 10%-advisory posture as the rest of the product.

See docs/ARCHITECTURE.md for where the module plugs into runAllChecks, and docs/WIKI.md for the full rule list, severities, and the breach each rule maps to.

What's new in 1.5.0

Twenty new detection rules for 2025-2026 threats. Three new check modules cover ground the pattern libraries did not reach before: emerging-web (Next.js middleware auth bypass CVE-2025-29927, the "React2Shell" RSC flight deserialization RCE CVE-2025-55182, Django ORM connector SQL injection CVE-2025-64459, Kestrel chunked-transfer smuggling CVE-2025-55315, JWT jku/x5u SSRF, path-to-regexp ReDoS, and an unstripped proxy-middleware header gap), emerging-cloud (the "IngressNightmare" ingress-nginx snippet injection CVE-2025-1974, an AWS PassRole privilege-escalation chain that now also covers the Bedrock AgentCore code-interpreter vector, unpinned git-ref Terraform modules, a GCP token-creator-on-project IAM binding pattern, and the runc container-escape delivery surface behind CVE-2025-31133/52565/52881), and emerging-supply-ai (the Shai-Hulud npm worm IOCs, off-registry-resolved lockfile entries, the mcp-remote command-injection CVE-2025-6514, invisible-Unicode prompt injection, MCP config "rug pull" CVE-2025-54136/54135, dangerous pickle opcodes in model files, and A2A credential forwarding). emerging-web runs on web/API surfaces, emerging-cloud runs on infrastructure surfaces, and emerging-supply-ai always runs. Detection is the same regex- and manifest-based heuristic approach as the rest of the gate, not AST or data-flow analysis: version-gated rules read the vulnerable package's manifest or lockfile and fall back to a MEDIUM advisory rather than an assertion when the exact version cannot be resolved, and the pickle-opcode scan is a best-effort binary heuristic that can both miss obfuscated payloads and flag benign files. First-party static rule coverage grows from roughly 847 to roughly 867 finding IDs.

Capability-floor enforcement for spawned agents. A new enforceCapabilityFloor check, wired into orchestration.merge_agent_findings as an additional thoroughness gate, asserts that every agent in a /ciso-orchestrator run actually operated at the capability its task required: the model tier the task demands under model-router's task-capability map, the SKILL.md allowed-tools floor, non-empty evidence for high-risk leads, and section coverage. An agent that falls short raises a HIGH CAPABILITY_DEGRADED finding, and any degraded agent in the run raises one run-level CRITICAL CAPABILITY_FLOOR_NOT_MET finding that forces the gate to FAIL. Two of the four floors are honest about a real gap: orchestration does not yet record which model, task type, and tools a spawned agent actually used, so the model-tier and tool-floor checks currently surface as MEDIUM CAPABILITY_UNVERIFIED advisories until that metadata is captured (tracked as a follow-up; the schema for it already exists).

Remediation coverage more than tripled. The remediation map grew from 15 templates to 55, adding a concrete fix for every new 1.5.0 finding ID and for the largest previously-uncovered gaps from earlier releases. The orphaned DEP_FLOATING_VERSION template, which had no matching finding ID, was removed in favor of DEP_UNPINNED_VERSION. This keeps the product's 90%-fixing, 10%-advisory posture intact as detection coverage grows.

See docs/ARCHITECTURE.md for how the new modules fit into the gate pipeline, and docs/WIKI.md for the full rule list and severities.

What's new in 1.4.0

Full-power model routing by default. The model router now runs security agents at maximum capability instead of cheapest-first. Security-critical reasoning tasks — code review, remediation, threat modeling, compliance analysis, exploit chains, AI red-teaming, pentesting, crypto analysis, auth analysis, incident response, risk scoring — default to the advanced capability tier, and within that tier the most capable model (Claude Opus 4.8) is selected first, with cost only a tiebreak. Light mechanical tasks (secret scanning, DLP, pattern matching, manifest/lockfile parsing, config reads, dependency scans) stay on the cheap tier, and report generation stays standard. A budget safety valve still exists: once spend utilization crosses downgrade_threshold_pct (default 80%), non-protected advanced tasks drop to standard — but exploit-chain, pentest, AI red-team, crypto, auth, threat-model, and remediation tasks never downgrade, no matter the spend. New model_budget policy fields: downgrade_threshold_pct and an opt-out force_standard_tier_for list. Model IDs are refreshed to Claude Sonnet 5, Claude Opus 4.8, and Claude Haiku 4.5.

Orchestration thoroughness enforcement. A green gate now requires proof that agents actually did the work, not just that they reported success. orchestration.merge_agent_findings verifies SKILL.md section coverage and fails the gate if it drops below 90% (SECURITY_MIN_SKILL_COVERAGE_PCT), detects ghost or missing required Phase-1 leads, and flags findings marked remediated with no remediation summary. Failed agents are retried up to twice before being escalated, which also forces the gate to FAIL. stackContext values are now sanitized before they reach spawned-agent prompts.

155 new detection rules. The check engine grew across injection, auth, crypto, business logic, cloud, CI/CD, mobile, AI/LLM, and MCP-specific threats — among them HTTP request smuggling, template/code injection (XSLT, Groovy, Perl), MongoDB operator injection, JWT kid injection, SAML XXE, static-IV and AEAD-bypass crypto flaws, hardcoded webhook and registry secrets, payment idempotency and wallet-balance race conditions, IAM privilege escalation via PassRole, Kubernetes default-SA token automount, unsafe model deserialization (pickle/joblib/torch), MCP tool-description poisoning, and WebView/keychain issues on Android and iOS. Four new AWS cloud-control rules were added to the controls engine, bringing total coverage to 1,002 rules.

Earlier releases (1.3.3) closed inter-agent payload integrity and per-tool-call audit gaps; 1.3.2 added the cloud security controls engine. See the CHANGELOG for the full list.

What's new in 1.3.3

Inter-agent payload integrity. orchestration.merge_agent_findings is the single trust sink for a whole agent run, so it now validates every agent's findings against a strict schema and verifies each file's hash against that agent's signed attestation before the findings reach the gate. With an attestation chain present it runs enforced: unattested or tampered agent files are rejected, and a hash mismatch or failed chain forces the gate to FAIL even with zero findings. Set SECURITY_REQUIRE_AGENT_ATTESTATION to fail closed unless the run is HMAC-signed, enforced, and chain-valid.

Per-tool-call audit log. Every MCP tool invocation emits one structured JSONL record with the eight mandatory fields — timestamp, agent id, tool, input parameters (secrets redacted), output (outcome + size + truncated preview), credentials used (session id, never the secret), user context, and outcome status — to .mcp/audit/tool-calls.jsonl (0o600). Point SECURITY_TOOL_AUDIT_LOG at an append-only sink for tamper-proof retention. Logging never interrupts tool execution.

Both close gaps identified in a threat model of security-mcp's own multi-agent system and were hardened accordingly. See the CHANGELOG for details and the tool's residual-risk disclosure.

1.3.2 — cloud security controls engine. A registry-driven engine that scans infrastructure-as-code against 998 rules mapped to AWS FSBP, CIS Benchmarks (AWS / GCP / Azure), and the Microsoft Cloud Security Benchmark, across Terraform, CloudFormation, and Bicep. Terraform violations can be auto-remediated with security-mcp autoharden (dedicated section). It also added the security-mcp ci:pr-gate and sign-policy CLI commands, and hardened the tool against itself (unsigned policies and exceptions can no longer relax the gate; data at rest is written 0o600) — see self-protection and supply-chain posture.

Earlier releases expanded the deep-analysis pattern libraries (injection, authentication, supply chain, business logic), brought OWASP Top 10 to full coverage, and wired the industry scanners into the gate.

System overview

The MCP server is the trust root. Both entry-point skills, the standalone CI gate, and every supporting subsystem call into the same engine, so an interactive fix and a CI verdict are produced by identical logic.

The two entry points

You drive security-mcp through two skills. One is your daily security engineer. The other is a full security program you run when the stakes are high.

| | /senior-security-engineer | /ciso-orchestrator | | --- | --- | --- | | Shape | One elite engineer agent | 39 named agents, 40+ at runtime | | Best for | Every PR, targeted hardening | Pre-release audits, compliance prep | | Scope | You pick: diff, full codebase, or specific paths | Full: every surface, every framework | | Speed | Seconds to minutes | Minutes to hours | | Output | Inline fixes + SHA-256 attested report | Merged findings, compliance mapping, signed attestation | | Network | Not required | Optional live threat intel |

Rule of thumb: run /senior-security-engineer on every PR, and /ciso-orchestrator before a release or an audit.

/senior-security-engineer

A single elite security-engineer agent. It operates 90% fixing, 10% advisory: it writes the secure code rather than handing you a report to act on. You pick the scope at the start (recent changes via git diff, the full codebase, or specific files and folders), and it runs a strategy pass, then the gate, then inline fixes, and finishes with a SHA-256 attested report you can keep as an audit artifact.

This is the daily driver. Use it on every PR.

/ciso-orchestrator

A full security program in one command, held to the same 90% fixing, 10% advisory mandate as the single agent: every specialist writes the fix rather than filing a finding. Nine specialist lead agents command 30 sub-agents, for 39 named agents in the static spawn tree. At runtime the orchestrator dynamically spawns additional ghost and coverage agents based on cross-domain findings, so a real run typically fields 40 or more. It draws on a registry of 91 specialist skills (registry version 1.6.0), loaded on demand based on your detected stack, and covers PCI DSS 4.0, SOC 2, ISO 27001, NIST 800-53, HIPAA, and GDPR mapping.

It runs in three phases:

1. Discovery (parallel). Seven leads run at once: threat modeling, AppSec code audit, cloud and infrastructure, supply chain, AI/LLM red team, mobile, and crypto/PKI.
2. Adversarial and compliance (parallel). A penetration-test team reads Phase 1's threat model as its attack brief, while a compliance/GRC synthesizer maps findings to controls.
3. Synthesis. Each agent's findings file is schema-validated and verified against that agent's signed attestation before it is trusted, then findings are merged and deduplicated, SKILL.md section coverage (§0 through §24) is verified, and a signed attestation is written. A tampered attestation chain or a findings-hash mismatch forces the gate to FAIL.

Cloud, AI/LLM, and mobile sub-agents are conditional: they activate only when the relevant stack is detected, and report N/A otherwise.

The gate engine

The gate is the deterministic core. On every run it executes 38 security checks in parallel (36 distinct check modules plus 2 precomputed coverage feeds). It is surface-aware: it first detects which surfaces a change touches (web, API, infrastructure, iOS, Android, AI/LLM, agentic) and runs the relevant checks against them.

A crashed check module never disappears quietly. It becomes a HIGH coverage-gap finding, so the absence of a result is itself a result. A control that regresses from satisfied to missing against the saved baseline also becomes a HIGH finding.

Deep-analysis modules

| Module | Patterns | What it targets | | --- | --- | --- | | Deep injection | 56 | SQL/NoSQL, SSTI, SpEL/OGNL, deserialization, CRLF, SSRF, HTTP request smuggling, and more | | Deep authentication | 55 | JWT confusion (including kid injection), session and OAuth flaws, SAML XXE, weak hashing, token entropy | | Deep supply chain | 33 | Obfuscated payloads, malicious scripts, exfiltration channels | | Business logic | 41 | IDOR, race conditions, payment and e-commerce abuse | | Data platform | 52 | Databricks and Snowflake misconfiguration | | Deep Docker | 52 | Container build and runtime hardening | | GitOps | 45 | ArgoCD and Flux pipeline integrity | | Agentic-instruction integrity | 16 | Poisoned AI agent instruction files | | AI governance | 3 | Shadow-AI and data-to-LLM exfiltration |

Alongside these, the gate runs Kubernetes (74 checks), IaC (63), and dedicated modules for secrets, dependencies, crypto, web/Next.js, API, mobile (iOS and Android), GraphQL, database, DLP, SBOM, an incident-response playbook, runtime/DAST, CI pipeline hardening, and a Nuclei DAST integration.

Three additional modules, added in 1.5.0, target current CVEs and agentic-AI threats rather than a broad pattern class: emerging-web (Next.js middleware auth bypass, React2Shell RSC deserialization, Django ORM SQLi, Kestrel smuggling, JWT jku/x5u SSRF, path-to-regexp ReDoS; runs on web/API surfaces), emerging-cloud (IngressNightmare, AWS PassRole privilege escalation, unpinned Terraform module refs, GCP token-creator bindings, runc escape delivery surfaces; runs on infrastructure surfaces), and emerging-supply-ai (Shai-Hulud worm IOCs, off-registry lockfile resolution, mcp-remote command injection, invisible-Unicode injection, MCP config rug-pulls, dangerous pickle opcodes, A2A credential forwarding; always runs). See docs/WIKI.md for the full rule list.

Scanner orchestration and threat intel

When they are present on the host, the gate orchestrates industry scanners: gitleaks, semgrep, trivy, osv-scanner, checkov, conftest, and zaproxy. Their results fold into the same findings model.

Live threat intelligence (cached for 24 hours) enriches the verdict: CISA KEV, EPSS (a score above 0.5 escalates severity), OpenSSF Scorecard, and the npm registry. Set SECURITY_OFFLINE=1 to disable all third-party egress. Private and internal scoped package names are never sent to public endpoints, online or off.

Cloud security controls engine

A registry-driven engine scans infrastructure-as-code against 1,002 rules mapped to AWS Foundational Security Best Practices (FSBP), CIS Benchmarks for AWS, GCP, and Azure, and the Microsoft Cloud Security Benchmark.

| Coverage | Rules | | --- | --- | | AWS | 487 | | Azure | 320 | | GCP | 195 | | Terraform / HCL | 778 | | CloudFormation | 128 | | Bicep | 96 |

Terraform supports auto-remediation through security-mcp autoharden (use --dry-run to preview). The engine applies a fix, re-detects to confirm the violation actually cleared, and only then keeps the change. Anything it cannot safely auto-fix is reported as a manual action with a code snippet.

Install

Prerequisite: Node.js 20 or higher (node --version).

npx -y security-mcp@latest install

The installer auto-detects Claude Code, Cursor, VS Code, and Windsurf, and writes the config to the right place. Restart your editor, then run a review:

/senior-security-engineer

For a full audit:

/ciso-orchestrator

Confirm the install is healthy at any time:

npx -y security-mcp@latest doctor

Manual config

Add the server to your editor's MCP config and restart.

Claude Code (~/.claude/settings.json), Cursor (~/.cursor/mcp.json), Windsurf (~/.windsurf/mcp.json):

{
  "mcpServers": {
    "security-mcp": {
      "command": "npx",
      "args": ["-y", "security-mcp@latest", "serve"]
    }
  }
}

VS Code / GitHub Copilot (user settings.json):

{
  "mcp.servers": {
    "security-mcp": {
      "command": "npx",
      "args": ["-y", "security-mcp@latest", "serve"]
    }
  }
}

CI/CD gate

The gate runs as plain Node.js with no AI session involved, so it belongs in your pipeline as a required check.

npx -y security-mcp@latest ci:pr-gate

It exits non-zero on HIGH or CRITICAL findings.

GitHub Actions

Create .github/workflows/security-gate.yml:

name: Security Gate

on:
  pull_request:
    branches: [main]

jobs:
  security-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # required for git diff

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Block insecure code from merging
        run: npx -y security-mcp@latest ci:pr-gate
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Optional HMAC integrity

To make the policy tamper-evident, add a repository secret named SECURITY_POLICY_HMAC_KEY that is at least 32 bytes, then sign and commit:

security-mcp sign-policy

Commit the policy file together with its generated .hmac sidecar. Once a key is set, the gate requires a valid signature on the policy, and a missing sidecar is rejected by design, so the key and the signature must land in the same change.

Built for teams

Four platform subsystems let a security team operate security-mcp at scale, not just run it ad hoc.

Multi-provider model router. Cost-aware routing across model providers, with circuit breakers and a spend budget so a single provider outage or a runaway run cannot stall or overspend the program.

Learning engine. Remembers confirmed patterns and false positives per project, with rate-limited false-positive suppression so noise drops over time. Routing decisions are written to an ISO 42001 audit log.

Tamper-evident attestation hash chain. Each agent attestation is chained (init_chain, attest_agent, verify_chain, get_chain), so the audit trail cannot be silently rewritten after the fact.

MCP caller authentication. An optional shared-secret gate on the MCP channel uses constant-time HMAC comparison, a 3-strike lockout, and a session TTL (8 hours by default, capped at 24). When unset, the channel stays open for frictionless local use.

Self-protection and supply-chain posture

A security tool is part of your supply chain, so security-mcp is built to resist the same attacks it looks for. This matters most when the threat is a malicious repository or a compromised dependency trying to neutralize the gate.

• Signed policy, exceptions, and baseline. These files are HMAC-signed. When the policy is not signed, the gate floors severity_block to HIGH/CRITICAL, so an unsigned edit cannot relax the gate to PASS.
• Exceptions cannot quietly suppress. By default an unsigned exceptions file may not suppress HIGH/CRITICAL findings. A break-glass env var exists for scanning intentionally-vulnerable fixtures.
• Honest attestation. Attestation refuses to sign unless the latest gate result is PASS with all required steps complete. There are no forged green attestations.
• Verified inter-agent payloads. The merge step that aggregates every agent's findings is the trust sink for a whole run, so it schema-validates each agent's findings file and checks its hash against that agent's signed attestation before trusting it. Findings dedupe keeps the highest severity per id, so a same-id low-severity entry cannot shadow a real CRITICAL. A tampered chain or a findings-hash mismatch forces FAIL. Set SECURITY_REQUIRE_AGENT_ATTESTATION=1 to fail closed unless the run is HMAC-signed, fully attested, and clean — note that an unsigned attestation chain is only tamper-evident, not tamper-proof, against an attacker who can write the run directory, so the HMAC key is the real boundary.
• Per-tool-call audit trail. Every MCP tool call is logged as one structured JSONL record (timestamp, agent id, tool, inputs, output summary, session credential, outcome) to .mcp/audit/tool-calls.jsonl. Secret-bearing keys and secret-shaped values (in inputs and in the output preview) are scrubbed; failed auth attempts are recorded as such, not as successes; the log rotates at 50 MB and writing never interrupts a tool call. Set SECURITY_TOOL_AUDIT_LOG to forward to an append-only sink.
• Locked-down data at rest. Findings, agent memory, and signatures are written with 0o600 file permissions.
• Prompt-injection defense. Tool outputs that originate from the repo are sanitized before they reach an LLM.
• Verified installer. Downloaded scanner binaries are verified by SHA-256, unchecksummed binaries are refused, and there is no curl | sh install path.
• Air-gap mode. SECURITY_OFFLINE=1 produces a fully offline run with no third-party egress.

MCP tools

Your AI calls these automatically; you rarely invoke them by hand. There are around 40, grouped into three namespaces plus two MCP prompts.

Most useful tools

| Tool | Purpose | | --- | --- | | security.start_review | Open a stateful review run and get a runId | | security.run_pr_gate | Run the gate, return PASS/FAIL with findings | | security.attest_review | Write a SHA-256 attestation (PASS-gated) | | security.threat_model | STRIDE + PASTA + ATT&CK model for a surface | | security.scan_strategy | Map every check to OWASP/NIST/ATT&CK controls | | security.generate_policy | Generate a policy tailored to your stack | | security.terraform_hardening_blueprint | Terraform hardening baseline + mappings | | security.generate_opa_rego | OPA/Rego for plans, pipelines, admission | | security.generate_compliance_report | Map findings to SOC 2, PCI, ISO, NIST, HIPAA, GDPR | | security.generate_remediations | Concrete fix template per finding | | repo.read_file / repo.search | Read or search the codebase (guarded) | | orchestration.create_agent_run | Stand up the multi-agent run + manifest | | orchestration.merge_agent_findings | Dedupe and sort findings across agents | | orchestration.verify_skill_coverage | Check §0-§24 SKILL.md coverage |

Operational families

Beyond the tools above, the rest of the surface clusters into four families:

• Model routing and budget. get_routing, get_model_for_task, track_usage, model_budget_status, get_provider_health, record_provider_failure, reset_provider_circuit.
• Learning and pattern memory. record_outcome, pattern_report, self_heal_loop, plus orchestration.read_agent_memory / write_agent_memory.
• Attestation hash chain. init_chain, attest_agent, verify_chain, get_chain.
• Caller auth and lifecycle. authenticate, logout, plus update tools orchestration.check_updates / apply_updates and skill loading orchestration.ensure_skill.

Namespace counts: security.* (29 tools), repo.* (2), orchestration.* (9), and 2 MCP prompts.

Frameworks

Every finding and fix maps to recognized standards. You do not need to know them to benefit; they are there so your evidence stands up to an auditor.

| Domain | Standards | | --- | --- | | OWASP | Top 10 (Web + API), ASVS L2/L3, MASVS, Top 10 for LLMs, Testing Guide | | MITRE | ATT&CK (Enterprise + Cloud + Mobile), D3FEND, ATLAS, CAPEC | | NIST | 800-53 Rev 5, CSF 2.0, 800-207 Zero Trust, 800-218 SSDF, AI RMF, 800-131A | | Compliance | PCI DSS 4.0, SOC 2 Type II, ISO 27001:2022 + 27002, ISO 42001:2023, GDPR / CCPA / HIPAA | | Supply chain and cloud | SLSA Level 3, CIS Benchmarks L2, AWS FSBP, Microsoft Cloud Security Benchmark | | Scoring | CVSS v4.0 + EPSS |

Policy and exceptions

The policy lives at .mcp/policies/security-policy.json. Copy the default to start:

mkdir -p .mcp/policies
cp node_modules/security-mcp/defaults/security-policy.json .mcp/policies/security-policy.json

Exceptions live at .mcp/exceptions/security-exceptions.json. Each entry needs id, finding_ids, justification, ticket, owner, approver (the owner cannot be the approver), approval_role, and expires_on (within 365 days):

{
  "version": "1.0.0",
  "exceptions": [
    {
      "id": "EX-001",
      "finding_ids": ["DEP_CVE_CVE-2024-12345"],
      "justification": "Library being replaced next sprint; no public exploit",
      "ticket": "JIRA-9999",
      "owner": "[email protected]",
      "approver": "[email protected]",
      "approval_role": "SecurityLead",
      "expires_on": "2026-12-31"
    }
  ]
}

Expired exceptions automatically become blocking findings until they are renewed or resolved.

Environment variables

Gate and scope

| Variable | Default | Purpose | | --- | --- | --- | | SECURITY_GATE_POLICY | .mcp/policies/security-policy.json | Policy file path | | SECURITY_GATE_MODE | recent_changes | Scan mode | | SECURITY_GATE_TARGETS | (changed files) | Comma-separated paths to restrict the scan | | SECURITY_GATE_BASE_REF | origin/main | Branch to diff against | | SECURITY_GATE_HEAD_REF | HEAD | Branch being scanned | | SECURITY_GATE_EXCEPTIONS | (default path) | Exceptions file path | | SECURITY_GATE_SCANNERS | built-in | Custom scanner config path | | SECURITY_GATE_EVIDENCE_MAP | (none) | Evidence-coverage map path | | SECURITY_GATE_CONTROL_CATALOG | (none) | Control-catalog path |

Integrity and signing

| Variable | Purpose | | --- | --- | | SECURITY_POLICY_HMAC_KEY | Signs policy / exceptions / baseline (>=32 bytes) | | SECURITY_REQUIRE_SIGNED_EXCEPTIONS | Fail closed on any unsigned exceptions file | | SECURITY_REQUIRE_AGENT_ATTESTATION | Fail closed unless the agent run is signed + enforced + clean (see below) | | SECURITY_ALLOW_UNSIGNED_HIGH_SUPPRESSION | Break-glass: allow unsigned HIGH/CRITICAL suppression | | SECURITY_ATTEST_ALLOW_INCOMPLETE | Break-glass: attest without a complete PASS | | SECURITY_ATTEST_KEY | Signs attestation files | | SECURITY_AUDIT_HMAC_KEY | Signs the routing audit log and the per-agent attestation chain |

Observability

| Variable | Default | Purpose | | --- | --- | --- | | SECURITY_TOOL_AUDIT_LOG | .mcp/audit/tool-calls.jsonl | Path for the per-tool-call structured audit log; point at an append-only / write-once sink for tamper-proof retention |

Privacy and air-gap

| Variable | Purpose | | --- | --- | | SECURITY_OFFLINE | Disable all third-party network egress |

MCP channel

| Variable | Default | Purpose | | --- | --- | --- | | SECURITY_MCP_SHARED_SECRET | (none) | Require caller auth on the MCP channel | | SECURITY_SESSION_TTL_MS | 8h | Session lifetime, capped at 24h |

Remediation

| Variable | Purpose | | --- | --- | | SECURITY_AGENTIC_QUARANTINE | Handling for poisoned agent files: strip, sanitize, quarantine, or off |

Integrations

| Variable | Purpose | | --- | --- | | SECURITY_SLACK_WEBHOOK | Post gate results to Slack | | SECURITY_JIRA_URL | Create Jira tickets for failures | | SECURITY_JIRA_TOKEN | Jira API token (never logged) | | SECURITY_JIRA_PROJECT | Jira project key (default SECURITY) | | SECURITY_PAGERDUTY_KEY | Page on-call for CRITICAL findings | | SECURITY_WEBHOOK_URL | POST gate results as JSON to any URL |

Live scanning

| Variable | Purpose | | --- | --- | | SECURITY_STAGING_URL | Enable runtime + Nuclei DAST against staging | | SECURITY_AI_ENDPOINT | Enable live AI red-team probes | | SECURITY_AUTO_SBOM | Auto-generate a CycloneDX SBOM each run |

The 10 non-negotiable rules

No matter what the AI is asked to build, these hold:

1. No 0.0.0.0/0 firewall rules. Ingress and egress are source-restricted.
2. Internal services live on a private VPC only, never on public IPs.
3. Secrets live in a secret manager only, never in code, .env, CI logs, or images.
4. TLS 1.3 for everything in transit. TLS 1.0 and 1.1 are blocked.
5. Passwords hashed with Argon2id, or bcrypt at cost 14 or higher.
6. Every API input validated server-side with a schema.
7. No inline JavaScript. Content Security Policy is nonce-based only.
8. Admin interfaces require FIDO2/WebAuthn.
9. Threat-model before any auth, payment, or AI feature.
10. Zero Trust: every request authenticated and authorized regardless of origin.

CLI reference

The security-mcp binary exposes:

| Command | Purpose | | --- | --- | | serve | Run the MCP server | | install | Install for auto-detected editors | | install-global | Install globally | | config | Manage configuration | | doctor (alias verify) | Health check | | autoharden | Auto-remediate Terraform (--dry-run to preview) | | ci:pr-gate | Run the gate in CI (non-zero exit on HIGH/CRITICAL) | | sign-policy | HMAC-sign the active policy |

Documentation and disclosure

• Deep-dive docs: the GitHub Wiki.
• Contributing: CONTRIBUTING.md.
• Reporting a vulnerability in security-mcp itself: see SECURITY.md, which uses GitHub private security advisories for responsible disclosure.

License

MIT

Change History

• 2026-07-07 — Added the "What's new in 1.3.5" section: pre-release checklist synced with the detection engine (8 new sections, 246 items) and the note that internal milestones 1.4.0–1.6.1 ship publicly in 1.3.5.
• 2026-07-07 — Tightened the 1.4.0 self-hardening note to an outcome statement (removed internal review-process mechanics), keeping the residual-risk disclosure pointer.
• 2026-07-06 — Added the "MCP security & governance / safe to use" section (self trust model, tamper-evident policy, fail-safe, egress control, no-shell exec, self-scan).
• 2026-07-06 — Added the "What's new in 1.6.1" section: the always-on web-hardening module (six new WEB_ rules) and the remediation map reaching 888 templates / 100% (887/887) detection-ID coverage.