security-mcp - AI Security Engineer for Claude Code, Cursor, Copilot & Codex

Stop shipping vulnerable code.

security-mcp is a Model Context Protocol (MCP) server that gives your AI coding assistant the knowledge and tooling of a senior security engineer. Instead of just warning you about vulnerabilities, it writes the secure code - inline, immediately, every time.

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

One command to install. Zero security background required.

Table of Contents

• What's New in v1.3.0
• What Problem Does This Solve?
• Who Is This For?
• Two Modes - Pick Your Depth
• Quick Start - Install in 60 Seconds
• Installation
• Verify Your Installation
• How to Run Your First Security Review
• CI/CD Security Gate
• What Gets Fixed Automatically
• Architecture
• MCP Tools Reference
• Security Frameworks Applied
• Configuration
• Environment Variables
• The 10 Rules That Are Never Broken
• Troubleshooting
• FAQ

What's New in v1.3.0

v1.3.0 delivers 104 new blindspot detection checks across 7 threat domains, discovered by running a full 8-agent CISO Orchestrator pass followed by an adversarial pentest verification round. It also closes 5 critical security vulnerabilities in the gate engine itself.

42 Deep Injection Patterns (was 15)

checkInjectionDeep now covers 42 detection patterns:

Plus all original patterns: XXE, SSTI multiline, LDAP, XPath, JNDI/Log4Shell, MongoDB $where, prototype pollution, CRLF, unsafe YAML, deserialization, path traversal, log injection, SSRF, command injection, ReDoS, SQL/ORM (Prisma, Sequelize, Knex, TypeORM), Redis EVAL, HTTP header injection.

43 Deep Auth Patterns (was 16)

checkAuthDeep now covers 43 detection patterns:

Plus all original patterns: JWT alg:none/HS-RS confusion, session fixation, OAuth state/redirect_uri/PKCE, hardcoded JWT secret, rate limit on auth, plaintext password compare, SAML signature bypass, insecure cookie flags, refresh token rotation, API key in URL, reset token expiry, admin route without authz, timing oracle.

31 Business Logic Patterns (was 8)

checkBusinessLogic now catches 31 patterns including 13 new e-commerce and payment abuse vectors:

• Currency confusion — mixed-currency arithmetic without normalization
• Discount stacking — coupon codes combined with promotions without stack limits
• Order fulfillment bypass — status transitions that skip required payment/verification steps
• Webhook timestamp — missing replay-window check on webhook signature verification
• Tax / shipping parameter tamper — client-supplied tax and shipping totals accepted server-side
• Client-side total — final order amount derived from a browser-supplied value
• Referral abuse — self-referral detection absent from referral credit logic
• Email normalization — user+tag@domain.com not normalized when enforcing unique accounts
• Feature flag bypass — feature flags controllable via client-supplied headers or query params
• API version bypass — security controls on v2 routes not enforced on legacy v1 endpoints
• Double-spend payment — concurrent payment requests without idempotency key enforcement
• Free trial abuse — trial period enforced only by client-supplied start date
• Pagination abuse — unlimited page size parameter enabling full-table data dump

32 Supply Chain Deep Patterns (was 16)

checkSupplyChainDeep now covers 32 patterns. New additions detect obfuscated payloads, malicious package scripts, and exfiltration channels that bypass standard SAST tools — including keyloggers, reverse shells, cryptomining signatures, DNS exfiltration, clipboard monitoring, and more.

Critical Security Fixes

Also in v1.2.1

• OWASP Top 10 now 10/10 covered — A09 (Security Logging and Monitoring Failures) fully completed
• NIST AU-11 / PCI Req 10 log retention detection added to checkAuthDeep
• ISO 42001 §9.1 routing decision audit log added to model router
• runScanners (gitleaks / semgrep / trivy / checkov / osv-scanner) wired into the gate — was implemented but never called since v1.0; now active check 27

Also in v1.2.0

• Secrets — dotfiles glob, base64/hex decode pre-pass, 10 new token formats (Vercel, PlanetScale, Databricks, Linear, Railway, npmrc, HuggingFace, ARM, Twilio), gitleaks history scan, split-string heuristic
• Injection — SQL/ORM detection (Prisma $queryRaw, Sequelize, Knex, TypeORM), JNDI/Log4Shell, LDAP, XPath, Redis EVAL, ReDoS static catastrophic-backtracking patterns
• Cryptography — AES-CBC-without-HMAC (+ split-string evasion fix), GCM nonce reuse and timestamp IV, RSA PKCS#1v1.5, SHA-256-as-password-hash, hardcoded PBKDF2 salt, rejectUnauthorized: false, weak TLS min version
• Checklists — all 6 surface checklists updated with automated: true entries for every new check ID

MCP Caller Authentication

Protect the MCP server channel against rogue processes that obtain stdio access:

export SECURITY_MCP_SHARED_SECRET="$(openssl rand -hex 32)"

When set, every tool call is blocked until the AI agent calls security.authenticate with the matching token. Uses constant-time HMAC comparison (CWE-208), 3-strike lockout, and minimum 16-byte secret enforcement. Backwards-compatible — when unset, all tools are immediately available.

Policy HMAC Integrity Signing

Prevent tampered policy files from silently disabling severity blocking:

export SECURITY_POLICY_HMAC_KEY="$(openssl rand -hex 32)"
npx security-mcp sign-policy

When set, the gate rejects any policy file whose HMAC sidecar (.hmac) does not match — making it impossible to quietly change severity_block: ["HIGH","CRITICAL"] to [] without detection.

What Problem Does This Solve?

When you use an AI coding assistant to build features fast, security is easy to skip - not because you don't care, but because:

• Security is deep expertise that takes years to develop
• Most AI assistants write working code but don't enforce secure code
• Static analysis tools flag problems but don't fix them
• Hiring a security team or running a pentest is expensive and slow

security-mcp closes that gap. It integrates a security enforcement layer directly into your AI assistant. Every code change, every PR, every new feature gets reviewed against OWASP, MITRE ATT&CK, NIST, PCI DSS, and 16 other frameworks - and the AI writes the fix immediately.

The result: You ship faster AND more securely. No security background required.

Who Is This For?

• Vibe coders and solo founders building fast who need security to just work without slowing them down
• Full-stack developers who know their code works but aren't sure if it's safe
• Startups and small teams shipping web apps, mobile apps, APIs, and SaaS products
• AI-assisted developers using Claude Code, Copilot, Cursor, or Codex to write most of their code
• Teams preparing for SOC 2, PCI DSS, or ISO 27001 audits who need evidence and gap analysis
• Security-conscious engineers who want systematic coverage, not ad-hoc reviews
• Anyone who's shipped code and thought "wait, is this actually secure?"

Two Modes - Pick Your Depth

/senior-security-engineer - Your Daily Security Expert

A single elite security engineer agent that reviews your code, finds vulnerabilities, and writes the fix immediately. You choose the scope: just your recent changes, your whole codebase, or specific files and folders. It covers secrets, dependencies, cryptography, injection, authentication, web headers, cloud config, AI/LLM safety, mobile, and more - all in parallel. Every finding gets an inline code fix, not a suggestion. Finishes with a SHA-256 attested report you can keep as an audit trail.

Use this on every PR. Use it before you push. Use it when something feels off.

/ciso-orchestrator - A Full Security Program in One Command

39 specialist agents across 3 phases. Phase 1: 7 lead agents run in parallel, each commanding its own team of sub-agents — threat modeling, deep code analysis, cloud infrastructure, supply chain, AI/LLM red team, mobile, and cryptography. Phase 2: adversarial penetration testing and compliance synthesis run in parallel after Phase 1 completes. Phase 3: findings are merged, deduplicated, and attested. Every domain has a dedicated specialist — an injection attacker, a JWT/OAuth hacker, a cloud privilege escalation analyst, a prompt injection specialist, a TLS auditor, a pentest team that reads the threat model as its attack brief, and a compliance analyst mapping every finding to PCI DSS 4.0, SOC 2, ISO 27001, NIST 800-53, HIPAA, and GDPR. Agents learn from each run and improve over time. 86 specialist skills registered in the registry — loaded on demand based on detected stack. Optionally fetches live CVE, CISA KEV, and ATT&CK data. Produces a merged findings report with full compliance mapping and a signed attestation.

Use this before major releases, compliance audits, or security reviews. -> See the full 39-agent architecture

Rule of thumb: Use /senior-security-engineer on every PR. Use /ciso-orchestrator before major releases or compliance deadlines.

Quick Start - Install in 60 Seconds

npx -y security-mcp@latest install

Restart your editor. Then in Claude Code:

/senior-security-engineer

That's it. The engineer will ask how you want to scope the review, then find and fix security issues in your code.

For a full 39-agent deep audit:

/ciso-orchestrator

Installation

Prerequisite: Node.js 20+. Check with node --version.

One Command — Auto-detects Your Editor

npx -y security-mcp@latest install

The installer detects Claude Code, Cursor, VS Code, and Windsurf automatically and writes the config to the correct location. Restart your editor when it finishes, then type /senior-security-engineer.

Install for a Specific Editor

npx -y security-mcp@latest install --claude-code   # ~/.claude/settings.json
npx -y security-mcp@latest install --cursor        # ~/.cursor/mcp.json
npx -y security-mcp@latest install --vscode        # VS Code user settings.json
npx -y security-mcp@latest install --windsurf      # ~/.windsurf/mcp.json

Manual Config (Any MCP-Compatible Editor)

Add this to your editor's MCP server 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"]
    }
  }
}

Verify Your Installation

After installing, confirm everything is wired up correctly:

npx -y security-mcp@latest doctor

This checks your Node.js version, editor config files, and installed skills — and prints [PASS] or [FAIL] per check with a fix command if anything is missing.

Example output:

  [PASS] Node.js 22.x
  [PASS] Claude Code config (~/.claude/settings.json)
  [PASS] senior-security-engineer skill (~/.claude/skills/senior-security-engineer/SKILL.md)

All checks passed. Restart your editor, then type /senior-security-engineer.

How to Run Your First Security Review

Daily Workflow: /senior-security-engineer

Step 1 - Open your project in your editor.

Step 2 - Invoke the skill:

/senior-security-engineer

Step 3 - Choose your scan scope when prompted:

• Recent changes - scans only files modified since your last commit. Use this on every PR.
• Full codebase - scans all source files. Use when onboarding a new project.
• Specific folders - you name the folders. Use when you know the blast radius.

Step 4 - Watch it work. The agent will:

1. Call security.start_review to create a tracked run
2. Build a scan plan covering all relevant OWASP/NIST/ATT&CK controls
3. Run 20 security checks in parallel across secrets, dependencies, crypto, auth, injection, cloud config, AI/LLM, mobile, and more
4. Write fixes directly into your code for every finding it can remediate
5. Generate a SHA-256 attested report at .mcp/reports/{runId}.attestation.json

Step 5 - Review the output. Each finding shows:

• What the vulnerability is and why it matters
• Which attack it enables (mapped to MITRE ATT&CK and CWE)
• The exact fix that was applied to your code

Step 6 - Commit with confidence. The attestation file is your audit trail.

Deep Audit: /ciso-orchestrator

Use this before a major release, compliance deadline, or security review.

Step 1 - Invoke:

/ciso-orchestrator

Step 2 - Answer the internet permission prompt.

The orchestrator will ask:

"I can fetch live CVE data, CISA KEV, and MITRE ATT&CK updates to improve this analysis. Allow internet access for this run? (yes/no)"

• Yes - agents enrich findings with live threat intelligence. More accurate, more current.
• No - agents use cached intel. Still comprehensive, no external calls made.

Step 3 - Wait for Phase 1 (7 lead agents running in parallel, each commanding their domain-specific sub-agents — 25 sub-agents total across Phase 1).

Each agent writes findings to .mcp/agent-runs/{agentRunId}/.

Step 4 - Wait for Phase 2 (pentest team + compliance synthesizer).

The pentest team reads Phase 1's threat model as its attack brief. The compliance agent maps every finding to PCI DSS 4.0, SOC 2, ISO 27001, NIST 800-53, HIPAA, and GDPR controls.

Step 5 - Review the merged report.

The orchestrator presents:

Agents: 9 leads completed (+ sub-agents)
Findings: X CRITICAL / X HIGH / X MEDIUM / X LOW
Remediated inline: X
Open (need your decision): X
SKILL.md coverage: XX% (§1-§24)
Release blocked: yes / no
Attestation: .mcp/reports/{runId}.attestation.json

Step 6 - For any open findings, follow the required actions in the report. The agent will help you implement each fix.

CI/CD Security Gate

Block insecure code from merging on every pull request - no Claude session required, pure Node.js execution:

npx -y security-mcp ci:pr-gate

Add to GitHub Actions

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

name: Security Gate

on:
  pull_request:
    branches: [main, master]

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

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

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

What the CI Gate Checks

The gate runs 24 check modules in parallel against your diff:

Customize the Gate Policy

Copy the default policy into your project and edit:

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

Or generate one tailored to your stack:

Ask your AI: "Run security.generate_policy with surfaces=[web, api, ai] and cloud=aws"

Add Exceptions for Known Accepted Risks

Copy and edit the exceptions file:

mkdir -p .mcp/exceptions
cp node_modules/security-mcp/defaults/security-exceptions.json .mcp/exceptions/security-exceptions.json

Format:

{
  "version": "1.0.0",
  "exceptions": [
    {
      "id": "EX-001",
      "finding_ids": ["CRYPTO_WEAK_HASH"],
      "justification": "Legacy hash used only for non-security cache keys",
      "ticket": "JIRA-1234",
      "owner": "alice@example.com",
      "approver": "bob@example.com",
      "approval_role": "SecurityLead",
      "expires_on": "2025-12-31"
    }
  ]
}

Expired exceptions automatically become CRITICAL findings that block the gate.

What Gets Fixed Automatically

When your AI has security-mcp active, it writes the production-ready fix - not a suggestion, not a warning comment:

Secrets and Credentials

Authentication and Authorization

• Rate limiting middleware added to all auth endpoints (configurable thresholds)
• Account lockout after N failed attempts with progressive delays
• Session absolute timeout (8h) and idle timeout (30 min)
• FIDO2/WebAuthn requirement flagged for admin interfaces
• IDOR protection: tenant/user IDs read from JWT claims, never from request params

Injection and Input Validation

• Zod/Yup schema validation added to every API route handler
• SQL: string concatenation -> parameterized queries or tagged template literals
• Command execution: exec(userInput) -> spawnSync with arg array, no shell
• Path traversal: user-controlled paths validated against project boundary
• SSRF: server-side HTTP clients get RFC-1918 CIDR block lists + DNS validation

Web Security Headers

Before:

app.get("/", (req, res) => res.send(html));

After:

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", (req, res) => `'nonce-${res.locals.nonce}'`],
    }
  },
  hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
  frameguard: { action: "deny" },
  noSniff: true,
  referrerPolicy: { policy: "strict-origin-when-cross-origin" }
}));

Cloud Infrastructure

• cidr_blocks = ["0.0.0.0/0"] -> source-restricted CIDR with comment explaining rationale
• acl = "public-read" S3 -> Block Public Access enabled at bucket and account level
• Wildcard IAM "Action": "*" -> least-privilege policy with specific actions
• Long-lived static credentials -> IAM roles / Workload Identity / OIDC federation

Cryptography

• crypto.createHash('md5') -> crypto.createHash('sha256')
• Math.random() for tokens -> crypto.randomBytes(32).toString('hex')
• AES-CBC -> AES-256-GCM with per-message nonce
• RSA PKCS#1 v1.5 -> RSA-OAEP or ECDH P-256

AI / LLM Security

• String-concatenated system prompts -> structured messages array with role separation
• eval(modelOutput) -> JSON.parse() + Zod schema validation
• RAG retrieval without auth check -> authorization check before and after retrieval
• Unvalidated tool calls -> allowlist router that blocks unlisted tool names

Architecture

System Overview

┌───────────────────────────────────────────────────────────────┐
│                   Your Editor (Claude Code)                   │
│                                                               │
│  /senior-security-engineer      /ciso-orchestrator           │
│  (single expert agent)          (39-agent security program)  │
│          │                                │                   │
└──────────┼────────────────────────────────┼───────────────────┘
           │                                │
           └──────────────┬─────────────────┘
                          │  MCP protocol (stdio)
                          ▼
┌──────────────────────────────────────────────────────────────┐
│                  MCP Server  (src/mcp/server.ts)             │
│                                                              │
│  security.*  tools         orchestration.*  tools           │
│  ─────────────────         ──────────────────────           │
│  start_review              create_agent_run                 │
│  run_pr_gate               update_agent_status              │
│  threat_model              merge_agent_findings             │
│  checklist                 ensure_skill                     │
│  attest_review             read/write_agent_memory          │
│  get_system_prompt         check_updates / apply_updates    │
│  scan_strategy             verify_skill_coverage            │
│  generate_policy                                            │
│  terraform_blueprint       repo.*  tools                    │
│  generate_opa_rego         ─────────────                    │
│  generate_compliance_report  read_file / search             │
│  notify_webhooks                                            │
│  generate_remediations                                      │
└──────────────────────────────────────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────────────────────────────┐
│               Policy Gate Engine  (src/gate/policy.ts)       │
│                                                              │
│  28 checks run in parallel:                                  │
│  checkSecrets    checkDependencies   checkApi    checkInfra  │
│  checkCrypto     checkMobileIos      checkMobileAndroid      │
│  checkAi         checkGraphQL        checkKubernetes         │
│  checkDatabase   checkDlp            checkWebNextjs          │
│  runSbomChecks   runAiRedteamChecks  runRuntimeChecks        │
│  runCiPipelineChecks  runDockerChecks  runScanners           │
│  checkInjectionDeep (42 patterns)  checkAuthDeep (43 patterns)│
│  checkSupplyChainDeep (32)  checkBusinessLogic (31)         │
│                                                              │
│  Surface detection -> Control catalog -> Exception handling ->  │
│  Coverage manifest -> Taint map -> Confidence scoring -> PASS / FAIL │
└──────────────────────────────────────────────────────────────┘

/senior-security-engineer Flow

User: /senior-security-engineer
        │
        ▼
  Claude reads SKILL.md + asks scope choice:
    A) Recent changes (git diff)
    B) Full codebase
    C) Specific files/folders
        │
        ▼  user picks scope
  security.start_review(mode)
    └── creates .mcp/reviews/{runId}.json
        │
        ▼
  security.threat_model(runId, feature)
    └── STRIDE + PASTA + ATT&CK template for changed surface
        │
        ▼
  §0 Coverage Completeness Protocol (runs first)
    ├── enumerate ALL source files → coverage-manifest.json
    ├── taint-trace every user-controlled input → taint-map.json
    ├── negative assertion per attack class: "FILES: N/N | RESULT: CLEAN"
    └── fix verification loop: re-run check after every fix, confirm CLEAN
        │
        ▼
  security.run_pr_gate(runId, mode, targets)
    ├── git diff / glob targets -> changed files list
    ├── detectSurfaces()  ->  web? api? infra? mobile? ai?
    ├── 28 checks in parallel (incl. deep injection + deep auth)
    ├── apply exceptions from .mcp/exceptions/
    ├── compute confidence score
    └── returns PASS/FAIL + findings[]
        │
        ▼
  Claude writes inline fixes for every finding
  (production-ready secure code, not suggestions)
  Every HIGH/CRITICAL: FIXED with verified-clean re-run,
  OR formally blocked with risk-acceptance record
        │
        ▼
  security.attest_review(runId)
    └── .mcp/reports/{runId}.attestation.json
    └── SHA-256 integrity hash

/ciso-orchestrator Flow (39 Agents)

User: /ciso-orchestrator
        │
        ▼
  CISO Orchestrator
  ├── orchestration.check_updates()   -> prompt if new version available
  ├── ask internet permission          -> stored for all child agents
  ├── scan project for stack context
  │   (package.json, go.mod, terraform/, .github/workflows/, Dockerfile)
  │   -> stackContext: { languages, frameworks, cloudProvider, hasAI, hasMobile, ... }
  ├── security.start_review()          -> runId
  ├── orchestration.create_agent_run() -> agentRunId + manifest.json
  └── orchestration.ensure_skill(×N)  -> download stack-relevant skills from 86-skill registry
        │
        ▼
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PHASE 1 - 7 leads + sub-agents  (all parallel)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Agent 1: threat-modeler
  ├── stride-pasta-analyst        -> STRIDE matrix, PASTA 7 stages, LINDDUN, DREAD
  ├── attack-navigator            -> ATT&CK Navigator layer + D3FEND countermeasures
  ├── business-logic-attacker     -> attack trees per route/flow found in codebase
  └── privacy-flow-analyst        -> GDPR/HIPAA data flows, DPIA trigger check
  Output: .mcp/agent-runs/{id}/threat-model.json

Agent 2: appsec-code-auditor
  ├── injection-specialist        -> SQL/NoSQL/SSTI/OS cmd/CRLF/log injection
  ├── auth-session-hacker         -> JWT algo confusion, SAML wrap, OAuth confusion
  ├── logic-race-fuzzer           -> race conditions, integer overflow, mass assignment
  └── serialization-memory-attacker -> prototype pollution, ReDoS, zip slip, sandbox escape
  Output: .mcp/agent-runs/{id}/appsec-findings.json

Agent 3: cloud-infra-specialist
  ├── aws-penetration-tester      -> IAM escalation, S3, Lambda, EKS    (if AWS)
  ├── gcp-penetration-tester      -> SA abuse, GCS, Cloud Run, GKE       (if GCP)
  ├── azure-penetration-tester    -> Managed Identity, AKS, Key Vault    (if Azure)
  └── k8s-container-escaper       -> privileged pods, RBAC escape, hostPath (if K8s)
  Output: .mcp/agent-runs/{id}/infra-findings.json

Agent 4: supply-chain-devsecops
  ├── dependency-confusion-attacker -> CVEs, CISA KEV, typosquatting, SBOM
  ├── cicd-pipeline-hijacker       -> pull_request_target, mutable Actions, injection
  └── artifact-integrity-analyst   -> SLSA L3, Cosign signatures, provenance
  Output: .mcp/agent-runs/{id}/supply-chain-findings.json

Agent 5: ai-llm-redteam            (skipped if no AI stack detected)
  ├── prompt-injection-specialist  -> direct + indirect injection, PoC payloads
  ├── model-extraction-attacker    -> API abuse, cost amplification, rate limiting
  ├── rag-poisoning-specialist     -> vector store isolation, metadata filter injection
  └── agentic-loop-exploiter       -> tool blast radius, loop hijacking, allowlist gaps
  Output: .mcp/agent-runs/{id}/ai-findings.json

Agent 6: mobile-security-specialist (skipped if no mobile detected)
  ├── ios-security-auditor         -> Keychain, ATS, Secure Enclave, Universal Links
  ├── android-penetration-tester   -> manifest hardening, NSC, exported components
  └── mobile-api-network-attacker  -> cert pinning, API key extraction, token storage
  Output: .mcp/agent-runs/{id}/mobile-findings.json

Agent 7: crypto-pki-specialist
  ├── tls-certificate-auditor      -> TLS 1.3, AEAD ciphers, HSTS preload, OCSP, mTLS
  ├── algorithm-implementation-reviewer -> banned algos, Argon2id params, nonce reuse
  └── key-management-lifecycle-analyst  -> hardcoded keys, rotation, CMEK, post-quantum
  Output: .mcp/agent-runs/{id}/crypto-findings.json

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     Wait for all Phase 1 agents to complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PHASE 2 - adversarial + compliance  (both parallel)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Agent 8: pentest-team  (reads threat-model.json as attack brief)
  ├── pentest-web-api   -> OWASP Testing Guide on every route found in codebase
  ├── pentest-infra     -> privilege escalation graph, Terraform state, cloud posture
  └── pentest-social    -> OSINT on org, spear-phishing scenarios, insider threat model
  Output: .mcp/agent-runs/{id}/pentest-report.json

Agent 9: compliance-grc  (reads all Phase 1 findings)
  ├── evidence-collector    -> logging schema verification, SIEM rules, audit trail
  └── compliance-gap-analyst -> PCI DSS 4.0, SOC 2, ISO 27001, NIST 800-53, HIPAA, GDPR
  Output: .mcp/agent-runs/{id}/compliance-report.json

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     Wait for Phase 2 agents to complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PHASE 3 - synthesis  (sequential)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  orchestration.merge_agent_findings()  -> deduplicate + sort CRITICAL->LOW
  orchestration.verify_skill_coverage() -> check §1-§24 SKILL.md section coverage
  security.attest_review()              -> SHA-256 attestation written

  Final report:
  ├── X CRITICAL / X HIGH / X MEDIUM / X LOW
  ├── Remediated inline: X    Open: X
  ├── SKILL.md section coverage: XX%
  ├── Release blocked: yes / no
  └── .mcp/reports/{runId}.attestation.json

Agent Memory System

Every agent persists what it learns so each subsequent run is smarter:

~/.security-mcp/agent-memory/{agentName}/
  ├── patterns.json         ← confirmed attack patterns for this tech stack
  ├── false-positives.json  ← findings to deprioritize on next run
  ├── remediations.json     ← what fixes worked for this project
  ├── intel.json            ← cached threat intel (refreshed every 24h)
  └── errors.json           ← tool failure log (used for self-healing)

Data Written to Your Project

.mcp/
├── reviews/{runId}.json                ← review run state + step tracking
├── reports/{runId}.attestation.json    ← SHA-256 auditable attestation
├── agent-runs/{agentRunId}/
│   ├── manifest.json                   ← all agent statuses + current phase
│   ├── threat-model.json
│   ├── appsec-findings.json
│   ├── infra-findings.json
│   ├── supply-chain-findings.json
│   ├── ai-findings.json
│   ├── mobile-findings.json
│   ├── crypto-findings.json
│   ├── pentest-report.json
│   ├── compliance-report.json
│   ├── sbom.cyclonedx.json
│   └── merged-findings.json            ← Phase 3 deduplicated, sorted output
├── policies/security-policy.json
└── exceptions/security-exceptions.json

MCP Tools Reference

Your AI uses these automatically. You don't call them directly, but understanding what they do helps you know what's happening during a review.

Core Security Tools

Orchestration Tools (/ciso-orchestrator only)

Security Frameworks Applied

All of the following frameworks are applied automatically. You don't need to know them - they're the standards used by the world's top security teams, and security-mcp maps every finding and fix to them:

Configuration

Customize the Security Policy

The policy file controls what the gate blocks, what evidence it requires, and how exceptions are handled. Copy the default and edit:

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

Key sections:

{
  "required_checks": {
    "secrets_scan": { "severity_block": ["HIGH", "CRITICAL"] },
    "dependency_scan": { "severity_block": ["CRITICAL"] },
    "sast": { "severity_block": ["CRITICAL"] },
    "iac_scan": { "severity_block": ["HIGH", "CRITICAL"] }
  },
  "vulnerability_slas": {
    "CRITICAL": "24h",
    "HIGH": "7d",
    "MEDIUM": "30d",
    "CISA_KEV": "24h"
  },
  "exceptions": {
    "require_ticket": true,
    "approval_roles": ["SecurityLead", "GRC", "CTO"]
  }
}

Add a Security Exception

When you have a finding you've consciously accepted (e.g., a CVE in a library you're actively replacing):

mkdir -p .mcp/exceptions
cp node_modules/security-mcp/defaults/security-exceptions.json .mcp/exceptions/security-exceptions.json

Edit .mcp/exceptions/security-exceptions.json:

{
  "version": "1.0.0",
  "exceptions": [
    {
      "id": "EX-001",
      "finding_ids": ["DEP_CVE_CVE-2024-12345"],
      "justification": "Library being replaced in sprint 42; no public exploit yet",
      "ticket": "JIRA-9999",
      "owner": "your-email@company.com",
      "approver": "security-lead@company.com",
      "approval_role": "SecurityLead",
      "expires_on": "2025-06-30"
    }
  ]
}

Expired exceptions automatically become SECURITY_EXCEPTION_EXPIRED CRITICAL findings that block the gate until renewed or resolved.

Environment Variables

CI / Gate

Integrations (all optional)

Live Scanning (optional)

The 10 Rules That Are Never Broken

No matter what your AI is asked to build, these are enforced without exception:

1. No 0.0.0.0/0 firewall rules - ingress and egress must be source-restricted
2. All internal services over private VPC only - no public IPs for databases, queues, or internal APIs
3. Secrets in a secret manager only - never in code, .env files, CI logs, or container images
4. TLS 1.3 for everything in transit - TLS 1.0 and 1.1 are explicitly blocked
5. Passwords hashed with Argon2id or bcrypt (cost ≥ 14) - MD5 and SHA-1 are forbidden
6. Every API input validated server-side with a schema - no passing raw request data to business logic
7. No inline JavaScript - Content Security Policy is nonce-based only; no unsafe-inline or unsafe-eval
8. Admin interfaces require FIDO2/WebAuthn passkey - TOTP is not acceptable for admin access
9. Threat model before any auth, payment, or AI feature - no design-free implementation
10. Zero Trust: every request authenticated and authorized regardless of origin - no implicit network trust

Troubleshooting

The /senior-security-engineer command isn't available in my editor

Cause: The skill was not installed to ~/.claude/skills/.

Fix: Re-run the installer:

npx -y security-mcp@latest install

Then verify the skill exists:

ls ~/.claude/skills/senior-security-engineer/SKILL.md

The MCP server doesn't appear as connected

Cause: Config file was not written, or the editor wasn't restarted after config was written.

Fix:

1. Check the config file was written (see editor-specific paths in Installation)
2. Fully restart the editor (quit and reopen, not just reload window)
3. Check Node.js version: node --version - must be 20 or higher

The CI gate fails with "cannot find module"

Cause: The dist files weren't included in the npm package, or you're referencing a path that doesn't exist.

Fix: Use npx -y security-mcp@latest ci:pr-gate which always pulls the latest published version, rather than referencing a local path.

A finding is a false positive

Fix: Add it to .mcp/exceptions/security-exceptions.json with a justification, ticket, owner, and expiry date. See Add a Security Exception.

The gate is too strict for my current project stage

Fix: Edit .mcp/policies/security-policy.json to lower severity thresholds for your current environment. For example, set dev environment to only block on CRITICAL:

"environments": {
  "dev": {
    "severity_block": ["CRITICAL"],
    "required_checks": ["secrets_scan"]
  }
}

I want to update to the latest version

npx -y security-mcp@latest install

This always pulls the latest published version. If you have it globally installed:

npm install -g security-mcp@latest

FAQ

Q: Does this send my code to any external service?

No. The MCP server runs locally as a Node.js process. Your code never leaves your machine. The only external calls made are to the npm registry (to check for updates) and optionally to GitHub (to download skill files) - both only if explicitly permitted. Live CVE/CISA KEV fetches during /ciso-orchestrator require your explicit internet permission at runtime.

Q: Do I need to know security to use this?

No. The tool is designed so that you don't need to understand what OWASP or ATT&CK mean. You describe what you're building, and the security engineer handles the rest.

Q: Will it slow down my development?

For daily use with /senior-security-engineer on recent changes, a typical review takes seconds to a few minutes. The fix is inline - you don't need to context-switch to a separate tool.

Q: What if it fixes something I don't want changed?

Everything is in your git working tree. Review the diff with git diff, revert anything you disagree with (git checkout -- <file>), and add a security exception if the finding is a false positive or accepted risk.

Q: Can I use this on an existing codebase with lots of issues?

Yes. Use security.generate_policy to set appropriate thresholds for your current state, add exceptions for known-accepted technical debt, and use the gate's MEDIUM/LOW findings as a backlog rather than blockers.

Q: Is this a replacement for a real pentest?

No - but it covers the same ground and more, continuously, on every change. Use /ciso-orchestrator before major releases to get the depth of a structured security review. For compliance purposes (SOC 2, PCI DSS), the attestation files and compliance reports generated are audit-trail artifacts.

Q: What AI models does this work with?

security-mcp is model-agnostic - it's an MCP server, not a model. It works with any AI assistant that supports the MCP protocol: Claude (all models), GitHub Copilot, Cursor, Codex, and others.

Q: How do I report a vulnerability in security-mcp itself?

See SECURITY.md for the responsible disclosure policy.

Contributing

See CONTRIBUTING.md.

License

MIT - security-mcp contributors