security-mcp 1.1.4 → 1.3.3

package/README.md

@@ -1,381 +1,288 @@
-# security-mcp - AI Security Engineer for Claude Code, Cursor, Copilot & Codex
+# 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)
 
-**Stop shipping vulnerable code.**
+An autonomous application-security engineering layer for AI-assisted development.
 
-**security-mcp** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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.
+security-mcp is a [Model Context Protocol](https://modelcontextprotocol.io) 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.
 
-Works with **Claude Code, GitHub Copilot, Cursor, Codex, Replit**, and any MCP-compatible editor.
+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.
 
-> **One command to install. Zero security background required.**
-
----
-
-## 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)
-- [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)
-- [Architecture](#architecture)
-- [MCP Tools Reference](#mcp-tools-reference)
-- [Security Frameworks Applied](#security-frameworks-applied)
-- [Configuration](#configuration)
-- [Environment Variables](#environment-variables)
-- [The 10 Rules That Are Never Broken](#the-10-rules-that-are-never-broken)
-- [Troubleshooting](#troubleshooting)
-- [FAQ](#faq)
-
----
-
-## 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:
+Works with Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf, Codex, Replit, and any MCP-compatible editor.
 
 ```bash
-npx -y security-mcp@latest doctor
+npx -y security-mcp@latest install
 ```
 
-Checks Node.js version, editor configs, and skill files — prints PASS/FAIL per check with actionable fix commands.
-
 ---
 
-## What Problem Does This Solve?
+## Table of Contents
 
-When you use an AI coding assistant to build features fast, security is easy to skip - not because you don't care, but because:
+- [Why this exists](#why-this-exists)
+- [What's new in 1.3.2](#whats-new-in-132)
+- [System overview](#system-overview)
+- [The two entry points](#the-two-entry-points)
+  - [/senior-security-engineer](#senior-security-engineer)
+  - [/ciso-orchestrator](#ciso-orchestrator)
+- [The gate engine](#the-gate-engine)
+- [Cloud security controls engine](#cloud-security-controls-engine)
+- [Install](#install)
+- [CI/CD gate](#cicd-gate)
+- [Built for teams](#built-for-teams)
+- [Self-protection and supply-chain posture](#self-protection-and-supply-chain-posture)
+- [MCP tools](#mcp-tools)
+- [Frameworks](#frameworks)
+- [Policy and exceptions](#policy-and-exceptions)
+- [Environment variables](#environment-variables)
+- [The 10 non-negotiable rules](#the-10-non-negotiable-rules)
+- [CLI reference](#cli-reference)
+- [Documentation and disclosure](#documentation-and-disclosure)
+- [License](#license)
 
-- 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.
+## Why this exists
 
-**The result:** You ship faster AND more securely. No security background required.
+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.
 
-## Who Is This For?
+You get three things from one install:
 
-- **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?"**
+- 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.
 
 ---
 
-## 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.
+## What's new in 1.3.2
 
-**Use this on every PR. Use it before you push. Use it when something feels off.**
+**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`. See [the dedicated section](#cloud-security-controls-engine).
 
-### `/ciso-orchestrator` - A Full Security Program in One Command
+**Two new CLI commands.** `security-mcp ci:pr-gate` runs the gate directly from `npx` and exits non-zero on HIGH/CRITICAL. `security-mcp sign-policy` HMAC-signs the active policy so tampering is detected at gate startup.
 
-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.
+**The tool hardened itself.** An unsigned policy can no longer relax the gate to PASS (severity_block is floored to HIGH/CRITICAL). An unsigned exceptions file can no longer suppress HIGH/CRITICAL by default. Attestation refuses to sign anything that is not a clean PASS. There is a fully offline mode, a checksum-verified installer with no `curl | sh` path, and data at rest is written with `0o600` permissions. Details in [self-protection and supply-chain posture](#self-protection-and-supply-chain-posture).
 
-**Use this before major releases, compliance audits, or security reviews. -> [See the full 39-agent architecture](#ciso-orchestrator-flow-39-agents)**
+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.
 
 ---
 
-| | `/senior-security-engineer` | `/ciso-orchestrator` |
-| --- | --- | --- |
-| **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 | 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) |
-
-**Rule of thumb:** Use `/senior-security-engineer` on every PR. Use `/ciso-orchestrator` before major releases or compliance deadlines.
+## System overview
 
----
+```mermaid
+graph TD
+  subgraph Editor["Your editor (Claude Code, Cursor, VS Code, ...)"]
+    A["/senior-security-engineer"]
+    B["/ciso-orchestrator"]
+  end
 
-## Quick Start - Install in 60 Seconds
+  A -->|MCP stdio| S["MCP server"]
+  B -->|MCP stdio| S
 
-```bash
-npx -y security-mcp@latest install
-```
+  S --> G["Gate engine (35 checks)"]
+  S --> O["Orchestration (39+ agents)"]
+  S --> C["Cloud controls (998 rules)"]
+  S --> P["Platform subsystems"]
 
-Restart your editor. Then in Claude Code:
+  G --> AT["SHA-256 attestation"]
+  O --> AT
+  P --> R["Model router / learning / hash chain / auth"]
 
-```text
-/senior-security-engineer
+  CI["CI: security-mcp ci:pr-gate"] --> G
 ```
 
-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:
-
-```text
-/ciso-orchestrator
-```
+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.
 
 ---
 
-## Step-by-Step Installation Guide
+## The two entry points
 
-### Step-by-Step: Claude Code
+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.
 
-**Prerequisite:** Node.js 20+ installed. Check with `node --version`.
+| | `/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 |
 
-**Step 1 - Run the installer:**
+Rule of thumb: run `/senior-security-engineer` on every PR, and `/ciso-orchestrator` before a release or an audit.
 
-```bash
-npx -y security-mcp@latest install --claude-code
-```
+### /senior-security-engineer
 
-This writes the MCP server config to `~/.claude/settings.json`.
+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.
 
-**Step 2 - Verify the config was written:**
+This is the daily driver. Use it on every PR.
 
-```bash
-cat ~/.claude/settings.json
+```mermaid
+graph TD
+  U["Invoke /senior-security-engineer"] --> SC{"Pick scope"}
+  SC -->|A| D["Recent changes / git diff"]
+  SC -->|B| F["Full codebase"]
+  SC -->|C| P["Specific files / folders"]
+  D --> ST["Build strategy"]
+  F --> ST
+  P --> ST
+  ST --> GT["Run gate"]
+  GT --> FX["Write inline fixes"]
+  FX --> RV["Re-run check, confirm clean"]
+  RV -->|remaining| FX
+  RV -->|clean| AT["SHA-256 attested report"]
 ```
 
-You should see:
+### /ciso-orchestrator
 
-```json
-{
-  "mcpServers": {
-    "security-mcp": {
-      "command": "npx",
-      "args": ["-y", "security-mcp@latest", "serve"]
-    }
-  }
-}
-```
+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.
 
-**Step 3 - Restart Claude Code** to pick up the new MCP server.
+It runs in three phases:
 
-**Step 4 - Verify the tools loaded.** In Claude Code, run:
+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.
 
-```text
-/mcp
-```
+```mermaid
+graph TD
+  ORCH["CISO orchestrator"] --> P1
+  ORCH --> P2
+  ORCH --> P3
 
-You should see `security-mcp` listed as a connected server with `security.*`, `orchestration.*`, and `repo.*` tools available.
+  subgraph P1["Phase 1: discovery (parallel)"]
+    TM["threat-modeler"] --> TM1["stride-pasta-analyst"] & TM2["attack-navigator"] & TM3["business-logic-attacker"] & TM4["privacy-flow-analyst"]
+    AC["appsec-code-auditor"] --> AC1["injection-specialist"] & AC2["auth-session-hacker"] & AC3["logic-race-fuzzer"] & AC4["serialization-memory-attacker"]
+    CI["cloud-infra-specialist"] --> CI1["aws/gcp/azure-pentester"] & CI2["k8s-container-escaper"]
+    SD["supply-chain-devsecops"] --> SD1["dependency-confusion-attacker"] & SD2["cicd-pipeline-hijacker"] & SD3["artifact-integrity-analyst"]
+    AI["ai-llm-redteam"] --> AI1["prompt-injection-specialist"] & AI2["model-extraction-attacker"] & AI3["rag-poisoning-specialist"] & AI4["agentic-loop-exploiter"]
+    MB["mobile-security-specialist"] --> MB1["ios-security-auditor"] & MB2["android-penetration-tester"] & MB3["mobile-api-network-attacker"]
+    CR["crypto-pki-specialist"] --> CR1["tls-certificate-auditor"] & CR2["algorithm-implementation-reviewer"] & CR3["key-management-lifecycle-analyst"]
+  end
 
-**Step 5 - Run your first security review:**
+  subgraph P2["Phase 2: adversarial + compliance (parallel)"]
+    PT["pentest-team"] --> PT1["pentest-web-api"] & PT2["pentest-infra"] & PT3["pentest-social"]
+    GRC["compliance-grc"] --> GRC1["evidence-collector"] & GRC2["compliance-gap-analyst"]
+  end
 
-```text
-/senior-security-engineer
+  subgraph P3["Phase 3: synthesis"]
+    M["Verify attestations + merge + dedupe"] --> V["Verify §0-§24 coverage"] --> A["Signed attestation"]
+  end
 ```
 
-The agent will ask:
-
-- **A) Recent changes** - scans only what changed since your last commit (fastest, use daily)
-- **B) Full codebase** - scans everything (use for new projects or after major changes)
-- **C) Specific files or folders** - scans exactly what you specify
-
-Pick one and let it run.
+Cloud, AI/LLM, and mobile sub-agents are conditional: they activate only when the relevant stack is detected, and report N/A otherwise.
 
 ---
 
-### Step-by-Step: Cursor
+## The gate engine
 
-**Step 1 - Run the installer:**
+The gate is the deterministic core. On every run it executes 35 security checks in parallel (33 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.
 
-```bash
-npx -y security-mcp@latest install --cursor
+```mermaid
+graph TD
+  PL["Load policy (HMAC-verified)"] --> SC["Resolve scope"]
+  SC --> CT["Classify change type"]
+  CT -->|docs-only| SS["Secrets scan only"]
+  CT -->|code| DS["Detect surfaces"]
+  DS --> CAT["Load catalog + scanner readiness + evidence coverage"]
+  CAT --> RUN["Run 35 checks in parallel"]
+  RUN --> SLA["Assign risk SLAs"]
+  SLA --> CM["Build coverage manifest"]
+  CM --> EX["Apply exceptions"]
+  EX --> CONF["Confidence score (70% coverage + 30% scanner)"]
+  CONF --> BL["Diff against baseline"]
+  BL --> VR{"Verdict by severity_block"}
+  VR --> PB["Persist new baseline"]
+  SS --> VR
 ```
 
-This writes to `~/.cursor/mcp.json`.
+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.
 
-**Step 2 - Verify:**
+### Deep-analysis modules
 
-```bash
-cat ~/.cursor/mcp.json
-```
-
-Expected output:
-
-```json
-{
-  "mcpServers": {
-    "security-mcp": {
-      "command": "npx",
-      "args": ["-y", "security-mcp@latest", "serve"]
-    }
-  }
-}
-```
+| Module | Patterns | What it targets |
+| --- | --- | --- |
+| Deep injection | 42 | SQL/NoSQL, SSTI, SpEL/OGNL, deserialization, CRLF, SSRF, and more |
+| Deep authentication | 43 | JWT confusion, session and OAuth flaws, weak hashing, token entropy |
+| Deep supply chain | 32 | Obfuscated payloads, malicious scripts, exfiltration channels |
+| Business logic | 31 | IDOR, race conditions, payment and e-commerce abuse |
+| Data platform | 47 | Databricks and Snowflake misconfiguration |
+| Deep Docker | 49 | Container build and runtime hardening |
+| GitOps | 41 | ArgoCD and Flux pipeline integrity |
+| Agentic-instruction integrity | 11 | Poisoned AI agent instruction files |
+| AI governance | 3 | Shadow-AI and data-to-LLM exfiltration |
 
-**Step 3 - Restart Cursor.**
+Alongside these, the gate runs Kubernetes (70 checks), IaC (56), 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.
 
-**Step 4 - Open Cursor's MCP panel** (Settings -> MCP) and confirm `security-mcp` shows as connected.
+### Scanner orchestration and threat intel
 
-**Step 5 - In the Cursor AI chat, type:**
+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.
 
-```text
-Use /senior-security-engineer to review my recent changes
-```
+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.
 
 ---
 
-### Step-by-Step: VS Code / GitHub Copilot
-
-**Step 1 - Run the installer:**
-
-```bash
-npx -y security-mcp@latest install --vscode
-```
-
-This writes to your VS Code user `settings.json`.
+## Cloud security controls engine
 
-**Step 2 - Verify in VS Code:**
+A registry-driven engine scans infrastructure-as-code against 998 rules mapped to AWS Foundational Security Best Practices (FSBP), CIS Benchmarks for AWS, GCP, and Azure, and the Microsoft Cloud Security Benchmark.
 
-Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) -> `Preferences: Open User Settings (JSON)`.
-
-You should see:
-
-```json
-{
-  "mcp.servers": {
-    "security-mcp": {
-      "command": "npx",
-      "args": ["-y", "security-mcp@latest", "serve"]
-    }
-  }
-}
-```
-
-**Step 3 - Restart VS Code.**
-
-**Step 4 - In GitHub Copilot Chat, type:**
-
-```text
-@security-mcp run /senior-security-engineer on recent changes
-```
+| Coverage | Rules |
+| --- | --- |
+| AWS | 483 |
+| Azure | 320 |
+| GCP | 195 |
+| Terraform / HCL | 774 |
+| CloudFormation | 128 |
+| Bicep | 96 |
+
+```mermaid
+graph TD
+  IAC["IaC files (TF / CFN / Bicep)"] --> DET["Detect against 998-rule registry"]
+  DET --> V["Violations"]
+  V --> AF{"Safe to auto-fix?"}
+  AF -->|yes, Terraform| FIX["Apply fix"]
+  FIX --> RD["Re-detect"]
+  RD -->|cleared| KEEP["Keep change"]
+  RD -->|not cleared| REV["Revert, report manual"]
+  AF -->|no| MAN["Manual action + snippet"]
+```
+
+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.
 
 ---
 
-### Step-by-Step: Windsurf
+## Install
 
-**Step 1 - Run the installer:**
+Prerequisite: Node.js 20 or higher (`node --version`).
 
 ```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:
+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:
 
-```json
-{
-  "mcpServers": {
-    "security-mcp": {
-      "command": "npx",
-      "args": ["-y", "security-mcp@latest", "serve"]
-    }
-  }
-}
+```text
+/senior-security-engineer
 ```
 
-**Step 3 - Restart Windsurf.**
-
-**Step 4 - In the Windsurf AI chat, type:**
+For a full audit:
 
 ```text
-Use /senior-security-engineer to review my recent changes
+/ciso-orchestrator
 ```
 
----
-
-### Manual Configuration (Any MCP Editor)
-
-If the installer doesn't detect your editor, or you prefer to configure manually:
-
-**Step 1 - Print the config snippet:**
+Confirm the install is healthy at any time:
 
 ```bash
-npx -y security-mcp@latest config
+npx -y security-mcp@latest doctor
 ```
 
-**Step 2 - Copy the output** and paste it into your editor's MCP configuration file.
-
-**Claude Code** (`~/.claude/settings.json`):
+### Manual config
 
-```json
-{
-  "mcpServers": {
-    "security-mcp": {
-      "command": "npx",
-      "args": ["-y", "security-mcp@latest", "serve"]
-    }
-  }
-}
-```
+Add the server to your editor's MCP config and restart.
 
-**Cursor** (`~/.cursor/mcp.json`):
+Claude Code (`~/.claude/settings.json`), Cursor (`~/.cursor/mcp.json`), Windsurf (`~/.windsurf/mcp.json`):
 
 ```json
 {
@@ -388,7 +295,7 @@ npx -y security-mcp@latest config
 }
 ```
 
-**VS Code / GitHub Copilot** (`settings.json`):
+VS Code / GitHub Copilot (user `settings.json`):
 
 ```json
 {
@@ -401,153 +308,19 @@ npx -y security-mcp@latest config
 }
 ```
 
-**Windsurf / Codex / Replit** - use the same `command`/`args` format your editor supports for MCP servers.
-
-**Step 3 - Restart your editor** after saving the config.
-
 ---
 
-### Global Install (Optional)
+## CI/CD gate
 
-If you want the `security-mcp` binary available system-wide without `npx`:
+The gate runs as plain Node.js with no AI session involved, so it belongs in your pipeline as a required check.
 
 ```bash
-npm install -g security-mcp@latest
-security-mcp install-global
+npx -y security-mcp@latest ci:pr-gate
 ```
 
-Then you can use:
-
-```bash
-security-mcp install-global --claude-code
-security-mcp install-global --cursor
-security-mcp install-global --vscode
-```
-
----
-
-### Preview Without Writing Anything
-
-To see what the installer would do without making any changes:
-
-```bash
-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`
-
-**Step 1 - Open your project in your editor.**
-
-**Step 2 - Invoke the skill:**
-
-```text
-/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.
+It exits non-zero on HIGH or CRITICAL findings.
 
-**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:**
-
-```text
-/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:
-
-```text
-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:
-
-```bash
-npx -y security-mcp ci:pr-gate
-```
-
-### Add to GitHub Actions
+### GitHub Actions
 
 Create `.github/workflows/security-gate.yml`:
 
@@ -556,7 +329,7 @@ name: Security Gate
 
 on:
   pull_request:
-    branches: [main, master]
+    branches: [main]
 
 jobs:
   security-gate:
@@ -564,529 +337,121 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0        # required for git diff to work
+          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 ci:pr-gate
+        run: npx -y security-mcp@latest ci:pr-gate
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-### What the CI Gate Checks
-
-The gate runs **20 checks in parallel** against your diff:
-
-| Category | What It Catches |
-| --- | --- |
-| **Secrets** | Hardcoded API keys, tokens, passwords, private keys (via Gitleaks patterns) |
-| **Dependencies** | CRITICAL/HIGH CVEs in npm/pip/go/maven packages; CISA KEV cross-check and EPSS >50% auto-escalation via live threat-intel (24h cached) |
-| **Cryptography** | MD5, SHA-1, DES, RC4, ECB mode, `Math.random()` for tokens, short JWT secrets |
-| **Authentication** | Missing rate limiting, no account lockout, JWT `alg:none`, weak session config |
-| **Injection** | SQL, NoSQL, command injection, path traversal, SSRF, prototype pollution |
-| **Web headers** | Missing CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy |
-| **IaC** | `0.0.0.0/0` firewall rules, public storage buckets, wildcard IAM permissions |
-| **AI/LLM** | `eval()` on model output, unvalidated model responses, prompt injection patterns |
-| **Database** | TLS disabled on connections, raw query concatenation, missing connection encryption |
-| **Mobile** | `android:debuggable=true`, cleartext traffic, insecure ATS config |
-| **GraphQL** | Introspection in production, no depth/complexity limits, batching abuse |
-| **Kubernetes** | Privileged containers, missing security context, hostPath mounts |
-| **DLP** | PII in logs, stack traces in API responses, sensitive data in error messages |
-| **Supply chain** | Missing lockfiles, floating version ranges (`^`, `~`), abandoned packages |
-| **SBOM** | Generates CycloneDX SBOM for the scanned surface |
-| **Runtime** | HTTP security headers and TLS config on live staging URL (if configured) |
-| **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
-
-Copy the default policy into your project and edit:
-
-```bash
-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:
-
-```text
-Ask your AI: "Run security.generate_policy with surfaces=[web, api, ai] and cloud=aws"
-```
-
-### Add Exceptions for Known Accepted Risks
+### Optional HMAC integrity
 
-Copy and edit the exceptions file:
+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:
 
 ```bash
-mkdir -p .mcp/exceptions
-cp node_modules/security-mcp/defaults/security-exceptions.json .mcp/exceptions/security-exceptions.json
+security-mcp sign-policy
 ```
 
-Format:
-
-```json
-{
-  "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.
+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.
 
 ---
 
-## 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
-
-| Insecure | Fixed to |
-| --- | --- |
-| `const KEY = "sk-abc123"` | `const KEY = process.env["API_KEY"]` + vault reference |
-| `password: "hardcoded"` in config | Environment variable + secret manager setup |
-| JWT signed with `"secret"` | RS256 with generated key pair, proper validation |
-| Bcrypt with cost factor 4 | Argon2id with `memory: 65536, iterations: 3, parallelism: 4` |
-
-### Authentication and Authorization
+## Built for teams
 
-- 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
+Four platform subsystems let a security team operate security-mcp at scale, not just run it ad hoc.
 
-### Injection and Input Validation
+**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.
 
-- 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
+**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.
 
-### Web Security Headers
+**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.
 
-Before:
-
-```javascript
-app.get("/", (req, res) => res.send(html));
-```
-
-After:
-
-```javascript
-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
+**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.
 
 ---
 
-## Architecture
-
-### System Overview
-
-```text
-┌───────────────────────────────────────────────────────────────┐
-│                   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)       │
-│                                                              │
-│  20 checks run in parallel:                                  │
-│  checkSecrets    checkDependencies   checkApi    checkInfra  │
-│  checkCrypto     checkMobileIos      checkMobileAndroid      │
-│  checkAi         checkGraphQL        checkKubernetes         │
-│  checkDatabase   checkDlp            checkWebNextjs          │
-│  runSbomChecks   runAiRedteamChecks  runRuntimeChecks        │
-│  checkInjectionDeep (11 patterns)  checkAuthDeep (12 patterns)│
-│                                                              │
-│  Surface detection -> Control catalog -> Exception handling ->  │
-│  Coverage manifest -> Taint map -> Confidence scoring -> PASS / FAIL │
-└──────────────────────────────────────────────────────────────┘
-```
+## Self-protection and supply-chain posture
 
-### `/senior-security-engineer` Flow
+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.
 
-```text
-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?
-    ├── 20 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)
-
-```text
-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:
-
-```text
-~/.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
-
-```text
-.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
-```
+- **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 Reference
+## MCP tools
 
-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.
+Your AI calls these automatically; you rarely invoke them by hand. There are around 40, grouped into three namespaces plus two MCP prompts.
 
-### Core Security Tools
+### Most useful tools
 
-| Tool | What It Does |
+| Tool | Purpose |
 | --- | --- |
-| `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 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 |
-| `security.get_system_prompt` | Returns the full security engineering directive, optionally scoped to your stack and cloud provider |
-| `security.generate_policy` | Generates a `security-policy.json` tailored to your active surfaces and cloud provider |
-| `security.terraform_hardening_blueprint` | Terraform hardening baseline with module layout, guardrails, and control mappings |
-| `security.generate_opa_rego` | OPA/Rego policy code for Terraform plans, CI pipelines, and Kubernetes admission |
-| `security.generate_compliance_report` | Maps gate findings to SOC 2, PCI-DSS, ISO 27001, NIST 800-53, HIPAA, or GDPR controls |
-| `security.generate_remediations` | Maps each finding ID to a concrete code-level fix template |
-| `security.notify_webhooks` | Sends findings to Slack, Jira, PagerDuty, or any webhook URL |
-| `security.self_heal_loop` | Proposes adaptive policy improvements based on recurring findings (requires explicit human approval) |
-| `security.attest_review` | Writes a SHA-256 integrity-hashed attestation file at `.mcp/reports/{runId}.attestation.json` |
-| `repo.read_file` | Reads a project file for analysis (path-traversal guarded) |
-| `repo.search` | Searches the codebase for patterns or regex (ReDoS guarded, max 500 matches) |
-
-### Orchestration Tools (`/ciso-orchestrator` only)
-
-| Tool | What It Does |
-| --- | --- |
-| `orchestration.create_agent_run` | Initialises the 39-agent manifest and `.mcp/agent-runs/{id}/` directory |
-| `orchestration.update_agent_status` | Agents report start/completion; automatically advances phase when all phase agents finish |
-| `orchestration.merge_agent_findings` | Deduplicates findings from all agents, sorts by severity, writes `merged-findings.json` |
-| `orchestration.ensure_skill` | Downloads a skill from the GitHub registry if not cached locally (`~/.claude/skills/`) |
-| `orchestration.read_agent_memory` | Loads an agent's prior patterns, false-positives, remediations, and cached intel |
-| `orchestration.write_agent_memory` | Persists newly learned patterns and remediations after a run |
-| `orchestration.check_updates` | Checks npm and the skills manifest for newer versions of security-mcp or installed skills |
-| `orchestration.apply_updates` | Returns update commands (manual) or instructions for the agent to run them (auto) |
-| `orchestration.verify_skill_coverage` | Reports which SKILL.md sections §1-§24 had zero coverage findings in this run |
+| `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.
 
 ---
 
-## Security Frameworks Applied
+## Frameworks
 
-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:
+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.
 
-| Framework | What It Covers |
+| Domain | Standards |
 | --- | --- |
-| **OWASP Top 10** (Web + API) | The 10 most critical web and API vulnerability classes |
-| **OWASP ASVS Level 2/3** | Application security verification standard - L3 for auth, payments, PII |
-| **OWASP MASVS** | Mobile application security verification standard |
-| **OWASP Top 10 for LLMs** | AI-specific vulnerabilities: prompt injection, training data poisoning, etc. |
-| **OWASP Testing Guide** | Methodology used by pentest sub-agents for endpoint-level testing |
-| **MITRE ATT&CK Enterprise + Cloud + Mobile** | Real attacker playbooks - every finding maps to a technique ID |
-| **MITRE D3FEND** | Defensive countermeasure mapped to every ATT&CK technique in scope |
-| **MITRE ATLAS** | Adversarial ML/AI attack techniques |
-| **MITRE CAPEC** | Attack patterns used at design-time threat modeling |
-| **NIST 800-53 Rev 5** | Full US government security control catalog |
-| **NIST CSF 2.0** | Govern / Identify / Protect / Detect / Respond / Recover |
-| **NIST 800-207** | Zero Trust Architecture - every request authenticated and authorized |
-| **NIST 800-218 (SSDF)** | Secure Software Development Framework |
-| **NIST AI RMF** | AI risk management: Map, Measure, Manage, Govern |
-| **PCI DSS 4.0** | Payment card industry data security standard |
-| **SOC 2 Type II** | Trust Services Criteria (Security, Availability, Confidentiality, PI) |
-| **ISO 27001:2022 + 27002** | International information security management system |
-| **ISO 42001:2023** | AI management system - applied to all LLM/AI components |
-| **GDPR / CCPA / HIPAA** | Data privacy: consent, retention, breach notification, minimum necessary |
-| **SLSA Level 3** | Software supply chain security - hermetic builds, signed provenance |
-| **CIS Benchmarks Level 2** | Hardened cloud, OS, and container configurations |
-| **CVSS v4.0 + EPSS** | Vulnerability scoring and exploit probability - EPSS > 0.5 fixed within 48h |
+| 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 |
 
 ---
 
-## Configuration
-
-### Customize the Security Policy
+## Policy and exceptions
 
-The policy file controls what the gate blocks, what evidence it requires, and how exceptions are handled. Copy the default and edit:
+The policy lives at `.mcp/policies/security-policy.json`. Copy the default to start:
 
 ```bash
 mkdir -p .mcp/policies
 cp node_modules/security-mcp/defaults/security-policy.json .mcp/policies/security-policy.json
 ```
 
-Key sections:
-
-```json
-{
-  "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):
-
-```bash
-mkdir -p .mcp/exceptions
-cp node_modules/security-mcp/defaults/security-exceptions.json .mcp/exceptions/security-exceptions.json
-```
-
-Edit `.mcp/exceptions/security-exceptions.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):
 
 ```json
 {
@@ -1095,179 +460,137 @@ Edit `.mcp/exceptions/security-exceptions.json`:
     {
       "id": "EX-001",
       "finding_ids": ["DEP_CVE_CVE-2024-12345"],
-      "justification": "Library being replaced in sprint 42; no public exploit yet",
+      "justification": "Library being replaced next sprint; no public exploit",
       "ticket": "JIRA-9999",
-      "owner": "your-email@company.com",
-      "approver": "security-lead@company.com",
+      "owner": "alice@example.com",
+      "approver": "bob@example.com",
       "approval_role": "SecurityLead",
-      "expires_on": "2025-06-30"
+      "expires_on": "2026-12-31"
     }
   ]
 }
 ```
 
-**Expired exceptions automatically become `SECURITY_EXCEPTION_EXPIRED` CRITICAL findings** that block the gate until renewed or resolved.
+Expired exceptions automatically become blocking findings until they are renewed or resolved.
 
 ---
 
-## Environment Variables
+## Environment variables
 
-### CI / Gate
+### Gate and scope
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `GITHUB_TOKEN` | set by Actions | Authenticates git operations in CI |
+| `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_POLICY` | `.mcp/policies/security-policy.json` | Path to policy file |
-| `SECURITY_GATE_SCANNERS` | built-in | Path to custom scanner config (must be within project directory) |
-| `SECURITY_GATE_EXCEPTIONS` | `.mcp/exceptions/security-exceptions.json` | Path to exceptions file (must be within project directory) |
-| `SECURITY_GATE_MODE` | `full` | Set to `file_by_file` for scoped per-file scanning |
-| `SECURITY_GATE_TARGETS` | (all changed files) | Comma-separated file paths to restrict the scan surface |
+| `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 |
 
-### Integrations (all optional)
+### Integrity and signing
 
 | Variable | Purpose |
 | --- | --- |
-| `SECURITY_SLACK_WEBHOOK` | Sends gate results to a Slack channel |
-| `SECURITY_JIRA_URL` | Creates Jira tickets for gate failures |
-| `SECURITY_JIRA_TOKEN` | Jira API token (never logged) |
-| `SECURITY_JIRA_PROJECT` | Jira project key (default: `SECURITY`) |
-| `SECURITY_PAGERDUTY_KEY` | Pages on-call when CRITICAL findings are found |
-| `SECURITY_WEBHOOK_URL` | POST gate results as JSON to any URL |
-
-### Live Scanning (optional)
-
-| Variable | Purpose |
-| --- | --- |
-| `SECURITY_STAGING_URL` | Enables live HTTP header and TLS checks against your staging environment |
-| `SECURITY_AI_ENDPOINT` | Enables live jailbreak, injection, PII, and rate-limit probes against your AI endpoint |
-| `SECURITY_AUTO_SBOM` | Set `true` to auto-generate a CycloneDX SBOM on each gate run |
-
----
-
-## The 10 Rules That Are Never Broken
+| `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 |
 
-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:
-
-```bash
-npx -y security-mcp@latest install
-```
+### Observability
 
-Then verify the skill exists:
-
-```bash
-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 [Manual Configuration](#manual-configuration-any-mcp-editor))
-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.
+| 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 |
 
-**Fix:** Use `npx -y security-mcp@latest ci:pr-gate` which always pulls the latest published version, rather than referencing a local path.
+### Privacy and air-gap
 
-### A finding is a false positive
+| Variable | Purpose |
+| --- | --- |
+| `SECURITY_OFFLINE` | Disable all third-party network egress |
 
-**Fix:** Add it to `.mcp/exceptions/security-exceptions.json` with a justification, ticket, owner, and expiry date. See [Add a Security Exception](#add-a-security-exception).
+### MCP channel
 
-### The gate is too strict for my current project stage
+| 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 |
 
-**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`:
+### Remediation
 
-```json
-"environments": {
-  "dev": {
-    "severity_block": ["CRITICAL"],
-    "required_checks": ["secrets_scan"]
-  }
-}
-```
+| Variable | Purpose |
+| --- | --- |
+| `SECURITY_AGENTIC_QUARANTINE` | Handling for poisoned agent files: `strip`, `sanitize`, `quarantine`, or `off` |
 
-### I want to update to the latest version
+### Integrations
 
-```bash
-npx -y security-mcp@latest install
-```
+| 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 |
 
-This always pulls the latest published version. If you have it globally installed:
+### Live scanning
 
-```bash
-npm install -g security-mcp@latest
-```
+| 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 |
 
 ---
 
-## FAQ
-
-**Q: Does this send my code to any external service?**
+## The 10 non-negotiable rules
 
-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.
+No matter what the AI is asked to build, these hold:
 
-**Q: Do I need to know security to use this?**
+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.
 
-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?**
+## CLI reference
 
-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.
+The `security-mcp` binary exposes:
 
-**Q: What AI models does this work with?**
+| 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 |
 
-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?**
+## Documentation and disclosure
 
-See [SECURITY.md](SECURITY.md) for the responsible disclosure policy.
+- **Deep-dive docs:** the [GitHub Wiki](https://github.com/AbrahamOO/security-mcp/wiki).
+- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md).
+- **Reporting a vulnerability in security-mcp itself:** see [SECURITY.md](SECURITY.md), which uses GitHub private security advisories for responsible disclosure.
 
 ---
 
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md).
-
 ## License
 
-[MIT](LICENSE) - security-mcp contributors
+[MIT](LICENSE)