security-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 security-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# security-mcp
+
+[![npm version](https://img.shields.io/npm/v/security-mcp.svg)](https://www.npmjs.com/package/security-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+[![CI](https://github.com/AbrahamOO/security-mcp/actions/workflows/security-gate.yml/badge.svg)](https://github.com/AbrahamOO/security-mcp/actions)
+
+**AI security MCP server and automated gate for Claude Code, GitHub Copilot, Cursor, Codex, Replit, and any MCP-compatible editor** -- enforcing OWASP, MITRE ATT&CK, NIST 800-53, Zero Trust, PCI DSS 4.0, and 20+ security frameworks on every code change before it ships.
+
+---
+
+## Quick Start
+
+Install the MCP security server into all detected editors with one command:
+
+```bash
+npx security-mcp install
+```
+
+Target a specific editor:
+
+```bash
+npx security-mcp install --claude-code
+npx security-mcp install --cursor
+npx security-mcp install --vscode
+```
+
+Preview what would be installed without writing anything:
+
+```bash
+npx security-mcp install --dry-run
+```
+
+After installation, restart your editor. The `security-mcp` MCP server starts automatically.
+
+In **Claude Code**, invoke the skill directly:
+
+```text
+/security-review
+```
+
+---
+
+## What It Does
+
+`security-mcp` gives your AI coding assistant the knowledge and tools of a **Principal Security Engineer** who has internalized every major security framework. It operates at four levels:
+
+### 1. MCP Server (Real-Time Tools)
+
+The MCP server exposes tools that your AI can call during any coding session:
+
+| Tool | What It Does |
+| --- | --- |
+| `security.get_system_prompt` | Returns the full elite security prompt (optionally filtered by stack, cloud provider, or payment processor) |
+| `security.threat_model` | Generates a complete STRIDE + PASTA + ATT&CK + D3FEND threat model template for any described feature |
+| `security.checklist` | Returns the pre-release security checklist, filterable by surface (web, api, mobile, ai, infra, payments) |
+| `security.generate_policy` | Generates a `security-policy.json` tailored to your project surfaces and cloud provider |
+| `security.run_pr_gate` | Runs the security policy gate against the current Git diff and reports findings |
+| `repo.read_file` | Reads a file from the workspace |
+| `repo.search` | Searches the codebase for patterns |
+
+### 2. MCP Prompts
+
+Two reusable prompts are registered in the MCP server:
+
+- **`security-engineer`** - Loads the full security system prompt, turning your AI into a Principal Security Engineer persona for the session.
+- **`threat-model-template`** - Accepts a `feature` argument and returns a ready-to-fill threat model template.
+
+### 3. Claude Code Skill
+
+The `/security-review` skill is a 24-section, 900-line security directive that embeds the complete security framework directly into Claude Code's context. It covers:
+
+- STRIDE + PASTA + LINDDUN + DREAD threat modeling
+- MITRE ATT&CK (Enterprise, Cloud, Mobile) coverage table
+- MITRE D3FEND countermeasure mapping
+- MITRE ATLAS adversarial ML threat coverage
+- Zero Trust architecture enforcement (NIST 800-207)
+- Cloud security rules (GCP, AWS, Azure) with absolute prohibitions
+- Container and Kubernetes hardening (CIS Benchmark Level 2)
+- Supply chain security (SLSA L3, SBOM, Sigstore)
+- DevSecOps pipeline gates (SAST, SCA, IaC, DAST)
+- Input validation - three-layer defense for every field type
+- AI/LLM security (prompt injection defense, RAG access control, output validation)
+- PCI DSS 4.0 payment flow controls
+- GDPR/CCPA/HIPAA data flow compliance
+- Vulnerability SLAs (CRITICAL: 24h, HIGH: 7d, MEDIUM: 30d)
+- Pre-release security checklist (Section 22E)
+
+### 4. Security Gate (CI/CD)
+
+The policy gate runs in CI and blocks PRs that violate security policy:
+
+```bash
+npx security-mcp ci:pr-gate
+```
+
+Gate checks cover hardcoded secrets, dependency vulnerabilities, IaC misconfigurations,
+auth and authorization gaps, SSRF and CSRF exposure, and AI/LLM output bounding.
+
+---
+
+## Supported Editors
+
+| Editor | Installation Method | Config Location |
+| --- | --- | --- |
+| Claude Code | `npx security-mcp install --claude-code` | `~/.claude/settings.json` |
+| Cursor (global) | `npx security-mcp install --cursor` | `~/.cursor/mcp.json` |
+| Cursor (workspace) | `npx security-mcp install --cursor` | `.cursor/mcp.json` |
+| VS Code | `npx security-mcp install --vscode` | User `settings.json` |
+| GitHub Copilot | Manual config (see below) | `.vscode/settings.json` |
+| Codex | Manual config (see below) | Editor config |
+| Replit | Manual config (see below) | `.replit` config |
+| Any MCP-compatible | `npx security-mcp config` for snippet | Paste into editor config |
+
+---
+
+## Security Frameworks Covered
+
+- OWASP Top 10 (Web + API)
+- OWASP ASVS Level 2/3
+- OWASP MASVS (Mobile)
+- OWASP SAMM
+- OWASP Top 10 for LLMs
+- MITRE ATT&CK Enterprise v14+
+- MITRE ATT&CK Cloud
+- MITRE ATT&CK Mobile
+- MITRE CAPEC
+- MITRE D3FEND
+- MITRE ATLAS (adversarial ML)
+- NIST 800-53 Rev 5
+- NIST CSF 2.0
+- NIST 800-207 (Zero Trust Architecture)
+- NIST 800-218 (SSDF)
+- NIST AI RMF
+- NIST 800-190 (Container Security)
+- PCI DSS 4.0
+- SOC 2 Type II
+- ISO/IEC 27001:2022
+- ISO/IEC 42001:2023 (AI Management)
+- GDPR / CCPA / HIPAA
+- CIS Benchmarks Level 2
+- CSA CCM v4
+- SLSA Level 3
+- FedRAMP Moderate
+- CVSS v4.0 + EPSS
+- CWE/SANS Top 25
+
+---
+
+## Manual Configuration
+
+### Claude Code (`~/.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "security-mcp": {
+      "command": "npx",
+      "args": ["-y", "security-mcp", "serve"]
+    }
+  }
+}
+```
+
+### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "security-mcp": {
+      "command": "npx",
+      "args": ["-y", "security-mcp", "serve"]
+    }
+  }
+}
+```
+
+### VS Code / GitHub Copilot (`settings.json`)
+
+```json
+{
+  "mcp.servers": {
+    "security-mcp": {
+      "command": "npx",
+      "args": ["-y", "security-mcp", "serve"]
+    }
+  }
+}
+```
+
+Print the recommended config snippet for any editor:
+
+```bash
+npx security-mcp config
+```
+
+---
+
+## Security Policy
+
+Copy the default security policy to your project and customize it:
+
+```bash
+cp node_modules/security-mcp/defaults/security-policy.json .mcp/policies/security-policy.json
+cp node_modules/security-mcp/defaults/evidence-map.json .mcp/mappings/evidence-map.json
+```
+
+Or generate a policy tailored to your project via the MCP tool:
+
+```text
+Ask your AI: "Run security.generate_policy with surfaces=[web, api, ai] and cloud=aws"
+```
+
+---
+
+## CI/CD Integration
+
+Add the security gate to your GitHub Actions workflow:
+
+```yaml
+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
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run security gate
+        run: npx -y security-mcp ci:pr-gate
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The gate exits non-zero on CRITICAL or HIGH findings, blocking the PR merge.
+
+---
+
+## Threat Modeling
+
+Ask your AI to generate a threat model for any feature:
+
+```text
+Run security.threat_model with feature="user authentication with OAuth 2.0" and surfaces=["web", "api"]
+```
+
+The tool returns a complete STRIDE + PASTA + ATT&CK + D3FEND template covering:
+
+- Asset inventory and trust boundaries
+- STRIDE analysis per component and trust boundary
+- ATT&CK technique mapping with D3FEND countermeasures
+- NIST 800-53 Rev 5 control IDs
+- Residual risk register with owner and review date
+- Pre-release security checklist
+
+---
+
+## Non-Negotiable Rules (Always Enforced)
+
+The security persona enforces these rules without exception:
+
+- No `0.0.0.0/0` ingress or egress rules anywhere
+- All internal services communicate via private VPC paths only (VPC endpoints, PrivateLink)
+- Secrets stored only in a dedicated secret manager - never in code, env files, or logs
+- TLS 1.3 for all in-transit data; TLS 1.0/1.1 strictly prohibited
+- Argon2id (or bcrypt cost 14+) for password hashing - no MD5, SHA-1, or unsalted hashes
+- Server-side schema validation (Zod, Yup, Valibot) on every API input
+- No inline JavaScript; CSP nonce-based only
+- FIDO2/WebAuthn passkey for admin and privileged operations
+- Threat model required before implementing auth, payment, or AI features
+- Zero Trust: never trust, always verify - every request, every token, every service call
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Security Disclosure
+
+See [SECURITY.md](SECURITY.md) for responsible disclosure policy.
+
+## License
+
+[MIT](LICENSE) - security-mcp contributors

package/defaults/evidence-map.json

@@ -0,0 +1,126 @@
+{
+  "_description": "Maps security gate evidence IDs to file glob patterns. Copy to .mcp/mappings/evidence-map.json and customize for your project layout.",
+  "deny_by_default_authz": [
+    "src/**/auth*.ts",
+    "src/**/auth*.js",
+    "src/**/middleware*.ts",
+    "src/**/middleware*.js",
+    "middleware.ts",
+    "middleware.js",
+    "app/api/**",
+    "src/api/**",
+    "server/middleware/**"
+  ],
+  "service_to_service_auth": [
+    "src/**/service*.ts",
+    "src/**/client*.ts",
+    "infra/**",
+    "k8s/**",
+    "helm/**"
+  ],
+  "no_hardcoded_secrets": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.py",
+    "**/*.go",
+    "**/*.java",
+    "**/*.env*",
+    "**/*.yaml",
+    "**/*.yml",
+    "**/*.json",
+    "**/*.toml",
+    "**/*.ini",
+    "**/*.conf"
+  ],
+  "secret_manager_refs": [
+    "infra/**",
+    "terraform/**",
+    "k8s/**",
+    "helm/**",
+    "src/**",
+    "app/**"
+  ],
+  "tls_config_verified": [
+    "infra/**",
+    "terraform/**",
+    "k8s/**",
+    "helm/**",
+    "src/**/tls*.ts",
+    "src/**/ssl*.ts",
+    "nginx/**",
+    "caddy/**"
+  ],
+  "security_headers_present": [
+    "middleware.ts",
+    "middleware.js",
+    "src/**/middleware*.ts",
+    "src/**/security*.ts",
+    "src/**/headers*.ts",
+    "next.config.*",
+    "nginx/**",
+    "caddy/**",
+    "infra/**"
+  ],
+  "csrf_protection_present": [
+    "app/api/**",
+    "src/api/**",
+    "server/routes/**",
+    "src/**/csrf*.ts",
+    "src/**/csrf*.js"
+  ],
+  "csrf_tests_present": [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/*.test.js",
+    "**/*.spec.js",
+    "tests/**",
+    "test/**",
+    "__tests__/**"
+  ],
+  "ssrf_guard_present": [
+    "src/**/ssrf*.ts",
+    "src/**/ssrf*.js",
+    "src/**/http-client*.ts",
+    "src/**/fetch*.ts",
+    "src/**/url-validator*.ts",
+    "src/**/request*.ts",
+    "lib/**/http*.ts",
+    "lib/**/fetch*.ts"
+  ],
+  "ssrf_tests_present": [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "tests/**",
+    "test/**"
+  ],
+  "ios_ats_strict": [
+    "**/Info.plist",
+    "ios/**"
+  ],
+  "android_nsc_strict": [
+    "**/network_security_config.xml",
+    "**/AndroidManifest.xml",
+    "android/**"
+  ],
+  "release_not_debuggable": [
+    "**/AndroidManifest.xml",
+    "**/build.gradle",
+    "**/build.gradle.kts",
+    "android/**"
+  ],
+  "json_schema_validation": [
+    "ai/**",
+    "ml/**",
+    "src/**/ai*.ts",
+    "src/**/llm*.ts",
+    "src/**/agent*.ts",
+    "src/**/schema*.ts"
+  ],
+  "tool_allowlist_router": [
+    "ai/**",
+    "ml/**",
+    "src/**/tool-router*.ts",
+    "src/**/tool*.ts",
+    "src/**/agent*.ts"
+  ]
+}

package/defaults/security-policy.json

@@ -0,0 +1,93 @@
+{
+  "name": "security-policy",
+  "version": "1.0.0",
+  "description": "Default security gate policy for security-mcp. Copy to .mcp/policies/security-policy.json and customize for your project.",
+  "required_checks": {
+    "secrets_scan": { "severity_block": ["HIGH", "CRITICAL"] },
+    "dependency_scan": { "severity_block": ["CRITICAL"] },
+    "sast": { "severity_block": ["CRITICAL"] },
+    "iac_scan": { "severity_block": ["HIGH", "CRITICAL"] }
+  },
+  "requirements": [
+    {
+      "id": "ZERO_TRUST",
+      "type": "gate",
+      "description": "All services enforce authentication + authorization. No implicit trust for any request.",
+      "evidence": ["deny_by_default_authz", "service_to_service_auth"]
+    },
+    {
+      "id": "SECRET_MANAGER_ONLY",
+      "type": "gate",
+      "description": "Secrets stored only in a dedicated secret manager. Never in code, env files, logs, or images.",
+      "evidence": ["no_hardcoded_secrets", "secret_manager_refs"]
+    },
+    {
+      "id": "TLS_13",
+      "type": "gate",
+      "description": "TLS 1.3 mandatory for all in-transit data. TLS 1.0/1.1 strictly prohibited.",
+      "evidence": ["tls_config_verified"]
+    },
+    {
+      "id": "CSP_NO_INLINE",
+      "type": "gate",
+      "description": "Content Security Policy enforced. No unsafe-inline, no unsafe-eval. Nonce-based CSP only.",
+      "evidence": ["security_headers_present"]
+    },
+    {
+      "id": "CSRF",
+      "type": "gate",
+      "description": "CSRF protection on all state-mutating endpoints.",
+      "evidence": ["csrf_protection_present", "csrf_tests_present"]
+    },
+    {
+      "id": "SSRF",
+      "type": "gate",
+      "description": "SSRF guards on all server-side HTTP calls. Private IP ranges and metadata endpoints blocked.",
+      "evidence": ["ssrf_guard_present", "ssrf_tests_present"]
+    },
+    {
+      "id": "MOBILE_MASVS",
+      "type": "gate",
+      "description": "Mobile apps meet OWASP MASVS L2. iOS ATS strict, Android NSC strict, release builds not debuggable.",
+      "evidence": ["ios_ats_strict", "android_nsc_strict", "release_not_debuggable"]
+    },
+    {
+      "id": "AI_BOUNDED_OUTPUTS",
+      "type": "gate",
+      "description": "AI/LLM outputs validated against JSON schema. Tool calls routed through an allowlist.",
+      "evidence": ["json_schema_validation", "tool_allowlist_router"]
+    }
+  ],
+  "artifacts_required": [
+    {
+      "pattern": "security/threat-models/*.md",
+      "description": "A threat model document is required for any change touching these paths.",
+      "on_changes": [
+        "src/**",
+        "app/**",
+        "api/**",
+        "server/**",
+        "infra/**",
+        "terraform/**",
+        "k8s/**",
+        "helm/**",
+        "mobile/**",
+        "ios/**",
+        "android/**",
+        "ai/**",
+        "ml/**"
+      ]
+    }
+  ],
+  "vulnerability_slas": {
+    "CRITICAL": "24h",
+    "HIGH": "7d",
+    "MEDIUM": "30d",
+    "LOW": "90d",
+    "CISA_KEV": "24h"
+  },
+  "exceptions": {
+    "require_ticket": true,
+    "approval_roles": ["SecurityLead", "GRC", "CTO"]
+  }
+}

package/dist/ci/pr-gate.js

@@ -0,0 +1,17 @@
+import { runPrGate } from "../gate/policy.js";
+async function main() {
+    const baseRef = process.env.SECURITY_GATE_BASE_REF || "origin/main";
+    const headRef = process.env.SECURITY_GATE_HEAD_REF || "HEAD";
+    const policyPath = process.env.SECURITY_GATE_POLICY || ".mcp/policies/security-policy.json";
+    const result = await runPrGate({ baseRef, headRef, policyPath });
+    // Print result for Actions logs
+    console.log(JSON.stringify(result, null, 2));
+    if (result.status !== "PASS") {
+        process.exit(2);
+    }
+}
+// eslint-disable-next-line unicorn/prefer-top-level-await
+main().catch((err) => {
+    console.error("security gate crashed:", err);
+    process.exit(3);
+});

package/dist/cli/index.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * security-mcp CLI
+ *
+ * Subcommands:
+ *   serve    Start the MCP server over stdio (used by editors)
+ *   install  Auto-detect editors and write MCP + skill configs
+ *   config   Print MCP config JSON for manual editor setup
+ *   --version
+ *   --help
+ */
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+import { runInstall } from "./install.js";
+import { main as runServer } from "../mcp/server.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+function getVersion() {
+    try {
+        const pkg = require(resolve(__dirname, "../../package.json"));
+        return pkg.version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+const VERSION = getVersion();
+const HELP = `
+security-mcp v${VERSION}
+
+  AI security MCP server and gate for Claude Code, Cursor, Copilot, Codex, Replit, and any MCP-compatible editor.
+
+USAGE
+  npx security-mcp <command> [options]
+
+COMMANDS
+  serve            Start the MCP server over stdio (default for editors)
+  install          Auto-detect installed editors and write MCP configs
+  config           Print MCP config JSON for manual editor setup
+
+OPTIONS (install)
+  --claude-code    Write config for Claude Code only
+  --cursor         Write config for Cursor only
+  --vscode         Write config for VS Code only
+  --global         Write to global editor config (default)
+  --dry-run        Print what would change without writing
+
+OPTIONS (general)
+  --version        Print version
+  --help           Print this help
+
+EXAMPLES
+  # Start MCP server (called automatically by editors):
+  npx -y security-mcp serve
+
+  # Install into all detected editors:
+  npx security-mcp install
+
+  # Install into Claude Code only:
+  npx security-mcp install --claude-code
+
+  # Preview install without writing:
+  npx security-mcp install --dry-run
+
+  # Print JSON config snippet:
+  npx security-mcp config
+
+EDITOR CONFIG (add manually if install fails):
+  {
+    "mcpServers": {
+      "security-mcp": {
+        "command": "npx",
+        "args": ["-y", "security-mcp", "serve"]
+      }
+    }
+  }
+
+  Claude Code:  ~/.claude/settings.json
+  Cursor:       ~/.cursor/mcp.json  or  .cursor/mcp.json
+  VS Code:      .vscode/mcp.json   (workspace)
+
+MORE INFO
+  https://github.com/AbrahamOO/security-mcp
+`;
+const CONFIG_SNIPPET = {
+    mcpServers: {
+        "security-mcp": {
+            command: "npx",
+            args: ["-y", "security-mcp", "serve"]
+        }
+    }
+};
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`security-mcp v${VERSION}\n`);
+        process.exit(0);
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(HELP);
+        process.exit(0);
+    }
+    const command = args[0] ?? "serve";
+    switch (command) {
+        case "serve": {
+            // MCP stdio server - never write to stdout except via MCP protocol
+            await runServer();
+            break;
+        }
+        case "install": {
+            const options = {
+                claudeCode: args.includes("--claude-code"),
+                cursor: args.includes("--cursor"),
+                vscode: args.includes("--vscode"),
+                dryRun: args.includes("--dry-run"),
+                // If no editor flag specified, install to all detected
+                all: !args.includes("--claude-code") && !args.includes("--cursor") && !args.includes("--vscode")
+            };
+            await runInstall(options);
+            break;
+        }
+        case "config": {
+            process.stdout.write(JSON.stringify(CONFIG_SNIPPET, null, 2) + "\n");
+            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");
+            break;
+        }
+        default: {
+            process.stderr.write(`Unknown command: ${command}\nRun with --help for usage.\n`);
+            process.exit(1);
+        }
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});