security-mcp 1.1.2 → 1.1.4

package/README.md

@@ -17,15 +17,18 @@ Works with **Claude Code, GitHub Copilot, Cursor, Codex, Replit**, and any MCP-c
 
 ## Table of Contents
 
+- [What's New in 1.1.4](#whats-new-in-114)
 - [What Problem Does This Solve?](#what-problem-does-this-solve)
 - [Who Is This For?](#who-is-this-for)
-- [Two Modes - Pick Your Depth](#two-modes--pick-your-depth)
-- [Quick Start - Install in 60 Seconds](#quick-start--install-in-60-seconds)
+- [Two Modes - Pick Your Depth](#two-modes---pick-your-depth)
+- [Quick Start - Install in 60 Seconds](#quick-start---install-in-60-seconds)
 - [Step-by-Step Installation Guide](#step-by-step-installation-guide)
   - [Claude Code](#step-by-step-claude-code)
   - [Cursor](#step-by-step-cursor)
   - [VS Code / GitHub Copilot](#step-by-step-vs-code--github-copilot)
+  - [Windsurf](#step-by-step-windsurf)
   - [Manual Configuration](#manual-configuration-any-mcp-editor)
+- [Verify Your Installation](#verify-your-installation)
 - [How to Run Your First Security Review](#how-to-run-your-first-security-review)
 - [CI/CD Security Gate](#cicd-security-gate)
 - [What Gets Fixed Automatically](#what-gets-fixed-automatically)
@@ -40,6 +43,57 @@ Works with **Claude Code, GitHub Copilot, Cursor, Codex, Replit**, and any MCP-c
 
 ---
 
+## What's New in 1.1.4
+
+### 20 Checks (up from 18) - Deep Injection + Deep Auth Modules
+
+Two new deep-check modules run automatically for web and API surfaces:
+
+**`checkInjectionDeep`** — 11 new patterns: XXE (CWE-611), SSTI (CWE-94), prototype pollution (CWE-1321), open redirect (CWE-601), NoSQL operator injection (CWE-943), CRLF injection (CWE-113), unsafe YAML load (CWE-502), unsafe deserialization, path traversal (CWE-22), log injection (CWE-117), SSRF (CWE-918).
+
+**`checkAuthDeep`** — 12 new patterns: JWT algorithm confusion / `alg:none` (CWE-327), session fixation (CWE-384), OAuth missing state parameter (CWE-352), OAuth `redirect_uri` open redirect (CWE-601), PKCE not enforced (RFC 7636), hardcoded JWT secret (CWE-798), missing rate limit on auth endpoints (CWE-307), plaintext password comparison (CWE-256), SAML signature validation disabled (CWE-347), insecure cookie flags (CWE-1004/614), refresh token not rotated (CWE-613), JWT HS/RS confusion (CVE-2015-9235 pattern).
+
+### Coverage Completeness Protocol (§0)
+
+Every security review now runs a mandatory 5-step protocol before reporting any result:
+
+1. **Complete file inventory** — enumerate all source files into `coverage-manifest.json`; no attack class can be called CLEAN without checking every file.
+2. **Taint tracking** — trace every user-controlled input (`req.body`, `req.query`, WebSocket, env, file uploads, external API responses) to all downstream sinks, classifying each SAFE / UNSAFE / UNRESOLVED.
+3. **Negative assertions** — after each attack class: `ATTACK CLASS: {name} | FILES: N/N | PATTERNS: {list} | RESULT: CLEAN`.
+4. **Fix verification loop** — after every fix, re-run the triggering check and confirm it no longer fires before advancing.
+5. **All-or-nothing mandate** — every HIGH/CRITICAL finding is either FIXED (verified clean) or BLOCKED (risk-accepted, gate failing, remediation plan written to `deferred-fixes.json`).
+
+### Enhanced Threat Model Template
+
+The `security.threat_model` tool now generates a more complete template including LINDDUN privacy threat analysis (Linking, Identifying, Non-repudiation, Detecting, Data Disclosure, Unawareness, Non-compliance), TRIKE risk matrix (actor-action-asset-risk), DREAD scoring, attack trees for the top 3 critical paths, adversary profiles mapped to ATT&CK techniques, and supply chain threat enumeration.
+
+### Expanded Release Checklists
+
+All domain-specific release checklists now include:
+
+- **OAuth/OIDC** — PKCE with S256, state/nonce verification, exact-match `redirect_uri`, code reuse prevention, audience validation
+- **Business Logic** — idempotency keys on payment mutations, negative input validation, race condition testing for balance/quota/inventory
+- **Serialization/Injection** — XXE, SSTI, unsafe YAML, deserialization, prototype pollution, open redirect, CRLF in every checklist
+- **AI/LLM** — system prompt extraction resistance, multi-turn attack chains, multimodal injection, agentic tool allowlist, AML.T0054/T0057 mitigations
+- **Payments (PCI DSS 4.0)** — PAN masking, DOM mutation monitoring, EMV 3DS 2.2+, Magecart prevention (SRI on checkout pages)
+- **Observability Gate** (new) — anomaly detection baselines, SLO definitions for security events, alert fatigue review, runbook coverage
+
+### Windsurf Support
+
+The installer now detects and configures Windsurf (`~/.windsurf/mcp.json`) automatically alongside Claude Code, Cursor, and VS Code.
+
+### `doctor` Command
+
+Verify your installation health at any time:
+
+```bash
+npx -y security-mcp@latest doctor
+```
+
+Checks Node.js version, editor configs, and skill files — prints PASS/FAIL per check with actionable fix commands.
+
+---
+
 ## 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:
@@ -77,19 +131,19 @@ A single elite security engineer agent that reviews your code, finds vulnerabili
 
 ### `/ciso-orchestrator` - A Full Security Program in One Command
 
-40 specialist agents running in parallel across 3 phases: threat modeling, deep code and infrastructure attack simulation, then compliance synthesis. Every domain gets its own specialist - a dedicated 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 that maps 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. Optionally fetches live CVE, CISA KEV, and ATT&CK data. Produces a merged findings report with full compliance mapping and a signed attestation.
+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 40-agent architecture](#ciso-orchestrator-flow-40-agents)**
+**Use this before major releases, compliance audits, or security reviews. -> [See the full 39-agent architecture](#ciso-orchestrator-flow-39-agents)**
 
 ---
 
 | | `/senior-security-engineer` | `/ciso-orchestrator` |
 | --- | --- | --- |
-| **What it is** | Single expert agent | 40-agent parallel security program |
+| **What it is** | Single expert agent | 39-agent multi-phase security program |
 | **Best for** | Daily development, PR reviews, targeted hardening | Pre-launch audits, compliance prep, incident response |
 | **Speed** | Seconds to minutes | Minutes to hours |
 | **Scope** | You choose: recent changes, full codebase, or specific files | Always full - every surface, every framework |
-| **Agents** | 1 | 40 (9 leads + 30 specialists) |
+| **Agents** | 1 | 39 (9 leads + 30 sub-agents) |
 | **Output** | Inline code fixes + SHA-256 attestation | Full domain reports + merged findings + attestation |
 | **API cost** | Low | High |
 | **Internet** | Not required | Optional (enriches findings with live CVEs, CISA KEV, MITRE ATT&CK) |
@@ -112,7 +166,7 @@ Restart your editor. Then in Claude Code:
 
 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 40-agent deep audit:
+For a full 39-agent deep audit:
 
 ```text
 /ciso-orchestrator
@@ -257,6 +311,45 @@ You should see:
 
 ---
 
+### Step-by-Step: Windsurf
+
+**Step 1 - Run the installer:**
+
+```bash
+npx -y security-mcp@latest install
+```
+
+This auto-detects Windsurf and writes to `~/.windsurf/mcp.json`.
+
+**Step 2 - Verify:**
+
+```bash
+cat ~/.windsurf/mcp.json
+```
+
+Expected output:
+
+```json
+{
+  "mcpServers": {
+    "security-mcp": {
+      "command": "npx",
+      "args": ["-y", "security-mcp@latest", "serve"]
+    }
+  }
+}
+```
+
+**Step 3 - Restart Windsurf.**
+
+**Step 4 - In the Windsurf AI chat, type:**
+
+```text
+Use /senior-security-engineer to review my recent changes
+```
+
+---
+
 ### Manual Configuration (Any MCP Editor)
 
 If the installer doesn't detect your editor, or you prefer to configure manually:
@@ -343,6 +436,28 @@ npx -y security-mcp@latest install --dry-run
 
 ---
 
+## Verify Your Installation
+
+After installing, confirm everything is wired up correctly:
+
+```bash
+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:
+
+```text
+  [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`
@@ -365,7 +480,7 @@ npx -y security-mcp@latest install --dry-run
 
 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 18 security checks in parallel across secrets, dependencies, crypto, auth, injection, cloud config, AI/LLM, mobile, and more
+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`
 
@@ -398,7 +513,7 @@ The orchestrator will ask:
 - **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 + 30 sub-agents, all parallel).**
+**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}/`.
 
@@ -463,7 +578,7 @@ jobs:
 
 ### What the CI Gate Checks
 
-The gate runs **18 checks in parallel** against your diff:
+The gate runs **20 checks in parallel** against your diff:
 
 | Category | What It Catches |
 | --- | --- |
@@ -486,6 +601,8 @@ The gate runs **18 checks in parallel** against your diff:
 | **AI red-team** | Static + optional dynamic probes against AI endpoints |
 | **Exceptions** | Validates any active security exceptions are non-expired and properly approved |
 | **Baseline regression** | Detects when previously-satisfied controls go missing (BASELINE_REGRESSION HIGH finding injected on regression) |
+| **Deep injection** | XXE, SSTI, prototype pollution, open redirect, NoSQL operator injection, CRLF, unsafe YAML load, deserialization, path traversal, log injection, SSRF (11 new patterns) |
+| **Deep auth** | JWT algorithm confusion, session fixation, OAuth missing state, OAuth open redirect_uri, PKCE not enforced, hardcoded JWT secret, missing rate limit on auth endpoints, plaintext password compare, SAML signature disabled, insecure cookie flags, refresh token not rotated, JWT HS/RS confusion (12 new patterns) |
 
 ### Customize the Gate Policy
 
@@ -621,7 +738,7 @@ app.use(helmet({
 │                   Your Editor (Claude Code)                   │
 │                                                               │
 │  /senior-security-engineer      /ciso-orchestrator           │
-│  (single expert agent)          (40-agent security program)  │
+│  (single expert agent)          (39-agent security program)  │
 │          │                                │                   │
 └──────────┼────────────────────────────────┼───────────────────┘
            │                                │
@@ -652,15 +769,16 @@ app.use(helmet({
 ┌──────────────────────────────────────────────────────────────┐
 │               Policy Gate Engine  (src/gate/policy.ts)       │
 │                                                              │
-│  18 checks run in parallel:                                  │
+│  20 checks run in parallel:                                  │
 │  checkSecrets    checkDependencies   checkApi    checkInfra  │
 │  checkCrypto     checkMobileIos      checkMobileAndroid      │
 │  checkAi         checkGraphQL        checkKubernetes         │
 │  checkDatabase   checkDlp            checkWebNextjs          │
-│  runSbomChecks   runAiRedteamChecks  runRuntimeChecks  ...  │
+│  runSbomChecks   runAiRedteamChecks  runRuntimeChecks        │
+│  checkInjectionDeep (11 patterns)  checkAuthDeep (12 patterns)│
 │                                                              │
 │  Surface detection -> Control catalog -> Exception handling ->  │
-│  Confidence scoring -> PASS / FAIL                           │
+│  Coverage manifest -> Taint map -> Confidence scoring -> PASS / FAIL │
 └──────────────────────────────────────────────────────────────┘
 ```
 
@@ -684,10 +802,17 @@ User: /senior-security-engineer
     └── 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?
-    ├── 18 checks in parallel
+    ├── 20 checks in parallel (incl. deep injection + deep auth)
     ├── apply exceptions from .mcp/exceptions/
     ├── compute confidence score
     └── returns PASS/FAIL + findings[]
@@ -695,6 +820,8 @@ User: /senior-security-engineer
         ▼
   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)
@@ -702,7 +829,7 @@ User: /senior-security-engineer
     └── SHA-256 integrity hash
 ```
 
-### `/ciso-orchestrator` Flow (40 Agents)
+### `/ciso-orchestrator` Flow (39 Agents)
 
 ```text
 User: /ciso-orchestrator
@@ -716,7 +843,7 @@ User: /ciso-orchestrator
   │   -> stackContext: { languages, frameworks, cloudProvider, hasAI, hasMobile, ... }
   ├── security.start_review()          -> runId
   ├── orchestration.create_agent_run() -> agentRunId + manifest.json
-  └── orchestration.ensure_skill(×39) -> download skills if not cached
+  └── orchestration.ensure_skill(×N)  -> download stack-relevant skills from 86-skill registry
         │
         ▼
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -853,7 +980,7 @@ Your AI uses these automatically. You don't call them directly, but understandin
 | Tool | What It Does |
 | --- | --- |
 | `security.start_review` | Starts a stateful review run; returns `runId` used to track all subsequent steps and produce the final attestation |
-| `security.run_pr_gate` | Runs 18 security checks in parallel; returns PASS/FAIL, findings with severity, and required actions |
+| `security.run_pr_gate` | Runs 20 security checks in parallel; returns PASS/FAIL, findings with severity, and required actions |
 | `security.threat_model` | Generates a STRIDE + PASTA + ATT&CK threat model template for a specific feature or surface |
 | `security.checklist` | Returns the pre-release security checklist, optionally filtered by surface (web / api / mobile / ai / infra / payments) |
 | `security.scan_strategy` | Builds an exhaustive scan plan mapping every check to OWASP, NIST, ATT&CK, and compliance controls |

package/defaults/control-catalog.json

@@ -544,6 +544,206 @@
       "surfaces": ["all"],
       "frameworks": ["GDPR", "HIPAA", "PCI DSS 4.0"],
       "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "OAUTH_PKCE_ENFORCED",
+      "description": "All OAuth 2.0 public clients use PKCE with S256 code challenge method.",
+      "automation": "tooling",
+      "surfaces": ["web", "api", "mobile"],
+      "frameworks": ["RFC 7636", "OWASP ASVS 3.5.3"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "JWT_ALG_CONFUSION_PREVENTED",
+      "description": "All jwt.verify() calls pin the algorithm to RS256/ES256 — algorithm confusion attack prevented.",
+      "automation": "tooling",
+      "surfaces": ["web", "api"],
+      "frameworks": ["CWE-327", "OWASP A07"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "SESSION_FIXATION_PREVENTED",
+      "description": "Session is regenerated after authentication to prevent session fixation attacks.",
+      "automation": "tooling",
+      "surfaces": ["web", "api"],
+      "frameworks": ["CWE-384", "OWASP A07"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "BUSINESS_LOGIC_REVIEWED",
+      "description": "Business logic abuse scenarios (state skipping, negative values, race conditions) are tested before release.",
+      "automation": "evidence",
+      "surfaces": ["all"],
+      "frameworks": ["OWASP Testing Guide OTG-BUSLOGIC", "NIST SP 800-53 SA-11"],
+      "evidence": ["pentest-report.json", "threat-model.json"]
+    },
+    {
+      "id": "RACE_CONDITION_MITIGATED",
+      "description": "All limit-once invariants (balance, quota, inventory, coupons) are protected by atomic DB operations.",
+      "automation": "tooling",
+      "surfaces": ["api"],
+      "frameworks": ["CWE-362", "OWASP Testing Guide OTG-BUSLOGIC-009"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "PROTOTYPE_POLLUTION_MITIGATED",
+      "description": "All object merges of user-controlled data are protected by schema validation before merge.",
+      "automation": "tooling",
+      "surfaces": ["web", "api"],
+      "frameworks": ["CWE-1321", "OWASP A03"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "HTTP_SMUGGLING_MITIGATED",
+      "description": "Proxy and origin servers normalize CL/TE headers; H2C upgrade disabled.",
+      "automation": "evidence",
+      "surfaces": ["web", "api"],
+      "frameworks": ["CWE-444", "OWASP Testing Guide OTG-INPVAL-016"],
+      "evidence": ["pentest-report.json"]
+    },
+    {
+      "id": "XXE_PREVENTED",
+      "description": "XML parsers disable external entity processing (processEntities:false).",
+      "automation": "tooling",
+      "surfaces": ["api"],
+      "frameworks": ["CWE-611", "OWASP A03"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "SSTI_PREVENTED",
+      "description": "Server-side templates are never compiled from user-controlled input.",
+      "automation": "tooling",
+      "surfaces": ["web", "api"],
+      "frameworks": ["CWE-94", "OWASP A03"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "DESERIALIZATION_SAFE",
+      "description": "Untrusted data is never passed to unsafe deserialization functions (node-serialize, eval, new Function).",
+      "automation": "tooling",
+      "surfaces": ["api"],
+      "frameworks": ["CWE-502", "OWASP A08"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "NOSQL_INJECTION_PREVENTED",
+      "description": "MongoDB/DynamoDB queries are built from validated fields, not raw user input.",
+      "automation": "tooling",
+      "surfaces": ["api"],
+      "frameworks": ["CWE-943", "OWASP A03"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "HTTP_VERB_TAMPERING_PREVENTED",
+      "description": "Read-only endpoints return 405 on PUT/DELETE — HTTP verb tampering blocked.",
+      "automation": "tooling",
+      "surfaces": ["api"],
+      "frameworks": ["OWASP Testing Guide OTG-INPVAL-003"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "OPEN_REDIRECT_BLOCKED",
+      "description": "All res.redirect() targets are validated against an allowlist or enforced relative-only.",
+      "automation": "tooling",
+      "surfaces": ["web", "api"],
+      "frameworks": ["CWE-601", "OWASP A01"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "SUBDOMAIN_TAKEOVER_MITIGATED",
+      "description": "DNS audit confirms no dangling CNAME records pointing to unprovisioned services.",
+      "automation": "evidence",
+      "surfaces": ["web"],
+      "frameworks": ["OWASP Testing Guide OTG-CONFIG-010"],
+      "evidence": ["dns-audit.json"]
+    },
+    {
+      "id": "GRAPHQL_FULL_HARDENING",
+      "description": "GraphQL introspection disabled, depth/complexity limits enforced, batching limited, field-level auth present.",
+      "automation": "tooling",
+      "surfaces": ["api"],
+      "frameworks": ["OWASP API Security Top 10", "OWASP Testing Guide"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "AI_MULTIMODAL_INJECTION_PREVENTED",
+      "description": "Multimodal inputs (image, audio, document) are treated as untrusted and cannot inject instructions.",
+      "automation": "evidence",
+      "surfaces": ["ai"],
+      "frameworks": ["OWASP LLM01", "MITRE ATLAS AML.T0054"],
+      "evidence": ["ai-redteam-report.json"]
+    },
+    {
+      "id": "AI_MEMORY_POISONING_PREVENTED",
+      "description": "Agent memory and scratchpad content is validated before use in downstream instructions.",
+      "automation": "evidence",
+      "surfaces": ["ai"],
+      "frameworks": ["OWASP LLM08", "MITRE ATLAS"],
+      "evidence": ["ai-redteam-report.json"]
+    },
+    {
+      "id": "AI_MODEL_INVERSION_MITIGATED",
+      "description": "Model cannot be probed to recite training PII or memorized secrets.",
+      "automation": "evidence",
+      "surfaces": ["ai"],
+      "frameworks": ["OWASP LLM06", "MITRE ATLAS AML.T0057"],
+      "evidence": ["ai-redteam-report.json"]
+    },
+    {
+      "id": "MASVS_ANTI_REVERSING",
+      "description": "Mobile release binary uses code obfuscation and anti-instrumentation controls (MASVS-RESILIENCE).",
+      "automation": "evidence",
+      "surfaces": ["mobile"],
+      "frameworks": ["OWASP MASVS 2.0 RESILIENCE"],
+      "evidence": ["mobile-binary-review.json"]
+    },
+    {
+      "id": "IMDS_V2_ENFORCED",
+      "description": "EC2 instances enforce IMDSv2 (HttpTokens=required) — IMDSv1 disabled.",
+      "automation": "tooling",
+      "surfaces": ["infra"],
+      "frameworks": ["CIS AWS Foundations Benchmark 5.6", "NIST SP 800-53 SC-7"],
+      "required_scanners": ["checkov"]
+    },
+    {
+      "id": "CLOUD_THREAT_DETECTION_ENABLED",
+      "description": "AWS GuardDuty / GCP SCC / Azure Defender for Cloud is enabled across all accounts.",
+      "automation": "tooling",
+      "surfaces": ["infra"],
+      "frameworks": ["CIS Benchmark", "NIST SP 800-53 SI-3"],
+      "required_scanners": ["checkov"]
+    },
+    {
+      "id": "MAGECART_PROTECTION",
+      "description": "Payment pages enforce extra-strict CSP and SRI on all scripts — Magecart e-skimming prevented.",
+      "automation": "tooling",
+      "surfaces": ["payments", "web"],
+      "frameworks": ["PCI DSS 4.0 Req 6.4.3", "OWASP ASVS 14.4"],
+      "required_scanners": ["semgrep"]
+    },
+    {
+      "id": "PCI_3DS_V2_ENFORCED",
+      "description": "EMV 3DS version 2.2+ is used for all card-not-present high-risk transactions.",
+      "automation": "evidence",
+      "surfaces": ["payments"],
+      "frameworks": ["PCI DSS 4.0 Req 8", "EMV 3DS 2.2"],
+      "evidence": ["payment-integration-test-results.json"]
+    },
+    {
+      "id": "HIPAA_PHI_CONTROLS",
+      "description": "Protected Health Information (PHI) is encrypted at rest and in transit; access is limited and audited.",
+      "automation": "evidence",
+      "surfaces": ["all"],
+      "frameworks": ["HIPAA §164.312", "NIST SP 800-53 SC-28"],
+      "evidence": ["hipaa-phi-audit.json"]
+    },
+    {
+      "id": "SUPPLY_CHAIN_CICD_HARDENED",
+      "description": "All CI/CD GitHub Actions are SHA-pinned; GITHUB_TOKEN has minimal permissions; no pwn-request risk.",
+      "automation": "tooling",
+      "surfaces": ["infra"],
+      "frameworks": ["SLSA Level 3", "NIST SP 800-161", "CIS Software Supply Chain Benchmark"],
+      "required_scanners": ["semgrep", "checkov"]
     }
   ]
 }

package/dist/cli/index.js

@@ -9,9 +9,11 @@
  *   --version
  *   --help
  */
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
-import { dirname, resolve } from "path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { homedir, platform } from "node:os";
 import { runInstall } from "./install.js";
 import { main as runServer } from "../mcp/server.js";
 import { notifyIfUpdateAvailable } from "./update.js";
@@ -55,6 +57,7 @@ COMMANDS
   install          Auto-detect installed editors and write MCP configs
   install-global   Install using the globally installed security-mcp binary
   config           Print MCP config JSON for manual editor setup
+  doctor           Verify the installation is working correctly
 
 OPTIONS (install)
   --claude-code        Write config for Claude Code only
@@ -87,6 +90,9 @@ EXAMPLES
   # Preview install without writing:
   npx -y security-mcp@latest install --dry-run
 
+  # Verify installation health:
+  npx -y security-mcp@latest doctor
+
   # Print JSON config snippet:
   npx -y security-mcp@latest config
   security-mcp config --use-global-binary
@@ -103,11 +109,76 @@ EDITOR CONFIG (add manually if install fails):
 
   Claude Code:  ~/.claude/settings.json
   Cursor:       ~/.cursor/mcp.json  or  .cursor/mcp.json
-  VS Code:      .vscode/mcp.json   (workspace)
+  VS Code:      User settings.json  (via Preferences > Open User Settings JSON)
+  Windsurf:     ~/.windsurf/mcp.json
 
 MORE INFO
   https://github.com/AbrahamOO/security-mcp
 `;
+function resolveHome(p) {
+    return p.replace(/^~/, homedir());
+}
+function getVsCodeSettingsPath() {
+    const os = platform();
+    if (os === "win32")
+        return `${process.env["APPDATA"] ?? ""}\\Code\\User\\settings.json`;
+    if (os === "darwin")
+        return `${homedir()}/Library/Application Support/Code/User/settings.json`;
+    return `${homedir()}/.config/Code/User/settings.json`;
+}
+function runDoctor() {
+    const checks = [];
+    // Node.js version
+    const nodeVer = process.versions.node.split(".").map(Number);
+    const nodeOk = (nodeVer[0] ?? 0) >= 20;
+    checks.push({ label: `Node.js ${process.versions.node}`, ok: nodeOk, hint: nodeOk ? undefined : "Node.js 20+ required. Download from https://nodejs.org" });
+    // Claude Code config
+    const claudeConfig = resolveHome("~/.claude/settings.json");
+    const claudeOk = existsSync(claudeConfig);
+    checks.push({ label: `Claude Code config (${claudeConfig})`, ok: claudeOk, hint: claudeOk ? undefined : "Run: npx -y security-mcp@latest install --claude-code" });
+    // Claude Code skill
+    const skillPath = resolveHome("~/.claude/skills/senior-security-engineer/SKILL.md");
+    const skillOk = existsSync(skillPath);
+    checks.push({ label: `senior-security-engineer skill (${skillPath})`, ok: skillOk, hint: skillOk ? undefined : "Run: npx -y security-mcp@latest install --claude-code" });
+    // Cursor global config
+    const cursorConfig = resolveHome("~/.cursor/mcp.json");
+    if (existsSync(resolveHome("~/.cursor"))) {
+        const cursorOk = existsSync(cursorConfig);
+        checks.push({ label: `Cursor config (${cursorConfig})`, ok: cursorOk, hint: cursorOk ? undefined : "Run: npx -y security-mcp@latest install --cursor" });
+    }
+    // VS Code config
+    const vscodePath = getVsCodeSettingsPath();
+    if (existsSync(vscodePath)) {
+        checks.push({ label: `VS Code config (${vscodePath})`, ok: true });
+    }
+    // Windsurf config
+    const windsurfConfig = resolveHome("~/.windsurf/mcp.json");
+    if (existsSync(resolveHome("~/.windsurf"))) {
+        const windsurfOk = existsSync(windsurfConfig);
+        checks.push({ label: `Windsurf config (${windsurfConfig})`, ok: windsurfOk, hint: windsurfOk ? undefined : "Run: npx -y security-mcp@latest install" });
+    }
+    process.stdout.write(`\nsecurity-mcp doctor v${VERSION}\n`);
+    process.stdout.write("=".repeat(40) + "\n\n");
+    let allOk = true;
+    for (const check of checks) {
+        const status = check.ok ? "PASS" : "FAIL";
+        process.stdout.write(`  [${status}] ${check.label}\n`);
+        if (!check.ok) {
+            allOk = false;
+            if (check.hint)
+                process.stdout.write(`         Fix: ${check.hint}\n`);
+        }
+    }
+    process.stdout.write("\n");
+    if (allOk) {
+        process.stdout.write("All checks passed. security-mcp is installed correctly.\n");
+        process.stdout.write("Restart your editor if you haven't already, then type /senior-security-engineer.\n\n");
+    }
+    else {
+        process.stdout.write("Some checks failed. Run the suggested fix commands above, then re-run: npx -y security-mcp@latest doctor\n\n");
+        process.exit(1);
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     const useGlobalBinary = args.includes("--use-global-binary");
@@ -165,7 +236,13 @@ async function main() {
             process.stdout.write("\nAdd the above to your editor's MCP config file.\n");
             process.stdout.write("  Claude Code:  ~/.claude/settings.json\n");
             process.stdout.write("  Cursor:       ~/.cursor/mcp.json\n");
-            process.stdout.write("  VS Code:      .vscode/mcp.json\n");
+            process.stdout.write("  VS Code:      User settings.json (Preferences > Open User Settings JSON)\n");
+            process.stdout.write("  Windsurf:     ~/.windsurf/mcp.json\n");
+            break;
+        }
+        case "doctor":
+        case "verify": {
+            runDoctor();
             break;
         }
         default: {