security-mcp 1.3.1 → 1.3.4

package/README.md

@@ -1,260 +1,216 @@
-# 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.**
+Works with Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf, Codex, Replit, and any MCP-compatible editor.
+
+```bash
+npx -y security-mcp@latest install
+```
 
 ---
 
 ## Table of Contents
 
-- [What's New in v1.3.0](#whats-new-in-v130)
-- [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)
-- [Installation](#installation)
-- [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)
+- [Why this exists](#why-this-exists)
+- [What's new in 1.3.3](#whats-new-in-133)
+- [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)
 
 ---
 
-## What's New in v1.3.0
+## Why this exists
 
-v1.3.0 delivers **104 new blindspot detection checks** across 7 threat domains, discovered by running a full 8-agent CISO Orchestrator pass followed by an adversarial pentest verification round. It also closes 5 critical security vulnerabilities in the gate engine itself.
+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.
 
-### 42 Deep Injection Patterns (was 15)
+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.
 
-`checkInjectionDeep` now covers 42 detection patterns:
+You get three things from one install:
 
-| Added in v1.3.0 | ATT&CK | What It Catches |
-| --- | --- | --- |
-| **SSTI (Java/PHP)** | T1059 | FreeMarker, Thymeleaf, Velocity, Twig, Smarty template injection |
-| **SpEL / OGNL injection** | T1059 | Spring Expression Language and OGNL via user-controlled string eval |
-| **Pickle / Java deserialization** | T1059.001 | Unsafe `pickle.loads`, `ObjectInputStream`, `readObject` on untrusted data |
-| **Second-order injection** | T1059 | Data stored to DB then later executed — two-pass file-correlation check |
-| **CSS injection** | T1059 | User content reflected inside `<style>` or `style=` without sanitization |
-| **Elasticsearch injection** | T1059 | Dynamic query construction in Elasticsearch DSL with user input |
-| **WebSocket injection** | T1059 | User-controlled data in `ws.send()` without validation |
-| **SSE-CRLF** | T1059 | CRLF in Server-Sent Events `data:` field hijacking the SSE stream |
-| **PDF / document injection** | T1059 | User input in PDF field generation without escaping |
-| **HTTP response splitting** | T1059 | CRLF in HTTP header values |
-| **Bracket-notation prototype pollution** | T1203 | `obj[key] = value` with user-controlled keys |
+- 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.
 
-Plus all original patterns: XXE, SSTI multiline, LDAP, XPath, JNDI/Log4Shell, MongoDB `$where`, prototype pollution, CRLF, unsafe YAML, deserialization, path traversal, log injection, SSRF, command injection, ReDoS, SQL/ORM (Prisma, Sequelize, Knex, TypeORM), Redis `EVAL`, HTTP header injection.
+---
 
-### 43 Deep Auth Patterns (was 16)
+## What's new in 1.3.3
 
-`checkAuthDeep` now covers 43 detection patterns:
+**Inter-agent payload integrity.** `orchestration.merge_agent_findings` is the single trust sink for a whole agent run, so it now validates every agent's findings against a strict schema and verifies each file's hash against that agent's signed attestation before the findings reach the gate. With an attestation chain present it runs **enforced**: unattested or tampered agent files are rejected, and a hash mismatch or failed chain forces the gate to FAIL even with zero findings. Set `SECURITY_REQUIRE_AGENT_ATTESTATION` to fail closed unless the run is HMAC-signed, enforced, and chain-valid.
 
-| Added in v1.3.0 | CWE | What It Catches |
-| --- | --- | --- |
-| **JWT `kid` injection** | CWE-20 | `kid` header used as file path or SQL expression for key material |
-| **JWKS URI override** | CWE-20 | Attacker-controlled `jku` / `x5u` headers pointing to external key stores |
-| **OAuth client secret in repo** | CWE-798 | `client_secret` literals or env defaults checked into source |
-| **Session token in URL** | CWE-598 | Session IDs in query parameters — logged by every proxy |
-| **Low-entropy token** | CWE-330 | Token / secret generated with `Math.random()` or timestamp-seeded RNG |
-| **Remember-me no rotation** | CWE-613 | Persistent login tokens never rotated on use |
-| **Password reset single-use** | CWE-640 | Reset tokens reusable after initial redemption |
-| **Account enumeration** | CWE-204 | Different error messages for valid vs. invalid usernames |
-| **Bcrypt cost factor** | CWE-916 | `bcrypt.hash(pw, N)` where N < 12 |
-
-Plus all original patterns: JWT alg:none/HS-RS confusion, session fixation, OAuth state/redirect_uri/PKCE, hardcoded JWT secret, rate limit on auth, plaintext password compare, SAML signature bypass, insecure cookie flags, refresh token rotation, API key in URL, reset token expiry, admin route without authz, timing oracle.
-
-### 31 Business Logic Patterns (was 8)
-
-`checkBusinessLogic` now catches 31 patterns including 13 new e-commerce and payment abuse vectors:
-
-- **Currency confusion** — mixed-currency arithmetic without normalization
-- **Discount stacking** — coupon codes combined with promotions without stack limits
-- **Order fulfillment bypass** — status transitions that skip required payment/verification steps
-- **Webhook timestamp** — missing replay-window check on webhook signature verification
-- **Tax / shipping parameter tamper** — client-supplied tax and shipping totals accepted server-side
-- **Client-side total** — final order amount derived from a browser-supplied value
-- **Referral abuse** — self-referral detection absent from referral credit logic
-- **Email normalization** — `user+tag@domain.com` not normalized when enforcing unique accounts
-- **Feature flag bypass** — feature flags controllable via client-supplied headers or query params
-- **API version bypass** — security controls on v2 routes not enforced on legacy v1 endpoints
-- **Double-spend payment** — concurrent payment requests without idempotency key enforcement
-- **Free trial abuse** — trial period enforced only by client-supplied start date
-- **Pagination abuse** — unlimited page size parameter enabling full-table data dump
-
-### 32 Supply Chain Deep Patterns (was 16)
-
-`checkSupplyChainDeep` now covers 32 patterns. New additions detect obfuscated payloads, malicious package scripts, and exfiltration channels that bypass standard SAST tools — including keyloggers, reverse shells, cryptomining signatures, DNS exfiltration, clipboard monitoring, and more.
-
-### Critical Security Fixes
-
-| ID | Severity | Fix |
-| --- | --- | --- |
-| **VULN-001** | CRITICAL | Dead multiline regex in `checkSecondOrderInjection` silently nulled the entire injection-deep module — replaced with two-pass file-correlation |
-| **VULN-002** | HIGH | Symlink traversal in `policy.ts` glob calls — `followSymbolicLinks: false` enforced |
-| **VULN-003** | HIGH | Evidence previews leaked secret values — `redactSecrets()` added to `search.ts` |
-| **AUTH-OBO-01** | HIGH | Lockout off-by-one in `auth.ts` allowed 4 attempts instead of 3 |
-| **META-01/03/04** | MEDIUM | Prompt injection vectors in MCP server — `_notice` framing and `sanitizePromptParam()` added |
+**Per-tool-call audit log.** Every MCP tool invocation emits one structured JSONL record with the eight mandatory fields — timestamp, agent id, tool, input parameters (secrets redacted), output (outcome + size + truncated preview), credentials used (session id, never the secret), user context, and outcome status — to `.mcp/audit/tool-calls.jsonl` (`0o600`). Point `SECURITY_TOOL_AUDIT_LOG` at an append-only sink for tamper-proof retention. Logging never interrupts tool execution.
 
-### Also in v1.2.1
+Both close gaps from an agentic-AI threat model of security-mcp's own multi-agent system and were hardened through a three-agent adversarial review (highest-severity-wins dedupe, secret/PII value scrubbing in the audit preview, honest unsigned-chain reporting). See the [CHANGELOG](CHANGELOG.md) for the full list and accepted residual risk.
 
-- OWASP Top 10 now **10/10 covered** — A09 (Security Logging and Monitoring Failures) fully completed
-- NIST AU-11 / PCI Req 10 log retention detection added to `checkAuthDeep`
-- ISO 42001 §9.1 routing decision audit log added to model router
-- `runScanners` (gitleaks / semgrep / trivy / checkov / osv-scanner) wired into the gate — was implemented but never called since v1.0; now active check 27
+**1.3.2 — cloud security controls engine.** A registry-driven engine that scans infrastructure-as-code against 998 rules mapped to AWS FSBP, CIS Benchmarks (AWS / GCP / Azure), and the Microsoft Cloud Security Benchmark, across Terraform, CloudFormation, and Bicep. Terraform violations can be auto-remediated with `security-mcp autoharden` ([dedicated section](#cloud-security-controls-engine)). It also added the `security-mcp ci:pr-gate` and `sign-policy` CLI commands, and hardened the tool against itself (unsigned policies and exceptions can no longer relax the gate; data at rest is written `0o600`) — see [self-protection and supply-chain posture](#self-protection-and-supply-chain-posture).
 
-### Also in v1.2.0
+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.
 
-- **Secrets** — dotfiles glob, base64/hex decode pre-pass, 10 new token formats (Vercel, PlanetScale, Databricks, Linear, Railway, npmrc, HuggingFace, ARM, Twilio), gitleaks history scan, split-string heuristic
-- **Injection** — SQL/ORM detection (Prisma `$queryRaw`, Sequelize, Knex, TypeORM), JNDI/Log4Shell, LDAP, XPath, Redis `EVAL`, ReDoS static catastrophic-backtracking patterns
-- **Cryptography** — AES-CBC-without-HMAC (+ split-string evasion fix), GCM nonce reuse and timestamp IV, RSA PKCS#1v1.5, SHA-256-as-password-hash, hardcoded PBKDF2 salt, `rejectUnauthorized: false`, weak TLS min version
-- **Checklists** — all 6 surface checklists updated with `automated: true` entries for every new check ID
+---
 
-### MCP Caller Authentication
+## System overview
 
-Protect the MCP server channel against rogue processes that obtain stdio access:
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AbrahamOO/security-mcp/main/assets/diagrams/system-overview.svg" alt="System overview: editor skills and CI both call the same MCP server, which drives the gate engine, orchestration, cloud controls, and platform subsystems into a shared attestation." width="820">
+</p>
 
-```bash
-export SECURITY_MCP_SHARED_SECRET="$(openssl rand -hex 32)"
-```
+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.
 
-When set, every tool call is blocked until the AI agent calls `security.authenticate` with the matching token. Uses constant-time HMAC comparison (CWE-208), 3-strike lockout, and minimum 16-byte secret enforcement. Backwards-compatible — when unset, all tools are immediately available.
+---
 
-### Policy HMAC Integrity Signing
+## The two entry points
 
-Prevent tampered policy files from silently disabling severity blocking:
+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.
 
-```bash
-export SECURITY_POLICY_HMAC_KEY="$(openssl rand -hex 32)"
-npx security-mcp sign-policy
-```
+| | `/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 |
 
-When set, the gate rejects any policy file whose HMAC sidecar (`.hmac`) does not match — making it impossible to quietly change `severity_block: ["HIGH","CRITICAL"]` to `[]` without detection.
+Rule of thumb: run `/senior-security-engineer` on every PR, and `/ciso-orchestrator` before a release or an audit.
 
----
+### /senior-security-engineer
 
-## What Problem Does This Solve?
+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.
 
-When you use an AI coding assistant to build features fast, security is easy to skip - not because you don't care, but because:
+This is the daily driver. Use it on every PR.
 
-- 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
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AbrahamOO/security-mcp/main/assets/diagrams/senior-security-engineer.svg" alt="senior-security-engineer flow: pick scope, build strategy, run gate, write inline fixes, re-run until clean, then emit a SHA-256 attested report." width="720">
+</p>
 
-**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.
+### /ciso-orchestrator
 
-**The result:** You ship faster AND more securely. No security background required.
+A full security program in one command, held to the same 90% fixing, 10% advisory mandate as the single agent: every specialist writes the fix rather than filing a finding. Nine specialist lead agents command 30 sub-agents, for 39 named agents in the static spawn tree. At runtime the orchestrator dynamically spawns additional ghost and coverage agents based on cross-domain findings, so a real run typically fields 40 or more. It draws on a registry of 91 specialist skills (registry version 1.6.0), loaded on demand based on your detected stack, and covers PCI DSS 4.0, SOC 2, ISO 27001, NIST 800-53, HIPAA, and GDPR mapping.
 
----
+It runs in three phases:
+
+1. **Discovery (parallel).** Seven leads run at once: threat modeling, AppSec code audit, cloud and infrastructure, supply chain, AI/LLM red team, mobile, and crypto/PKI.
+2. **Adversarial and compliance (parallel).** A penetration-test team reads Phase 1's threat model as its attack brief, while a compliance/GRC synthesizer maps findings to controls.
+3. **Synthesis.** Each agent's findings file is schema-validated and verified against that agent's signed attestation before it is trusted, then findings are merged and deduplicated, SKILL.md section coverage (§0 through §24) is verified, and a signed attestation is written. A tampered attestation chain or a findings-hash mismatch forces the gate to FAIL.
 
-## Who Is This For?
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AbrahamOO/security-mcp/main/assets/diagrams/ciso-orchestrator.svg" alt="ciso-orchestrator spawn tree: Phase 1 discovery leads and sub-agents in parallel, Phase 2 pentest and compliance teams, Phase 3 attestation verification, merge, coverage check, and signed attestation." width="940">
+</p>
 
-- **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?"**
+Cloud, AI/LLM, and mobile sub-agents are conditional: they activate only when the relevant stack is detected, and report N/A otherwise.
 
 ---
 
-## Two Modes - Pick Your Depth
+## The gate engine
 
-### `/senior-security-engineer` - Your Daily Security Expert
+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.
 
-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.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AbrahamOO/security-mcp/main/assets/diagrams/gate-engine.svg" alt="Gate engine pipeline: load HMAC-verified policy, resolve scope, classify change, detect surfaces, run 35 checks in parallel, assign SLAs, build coverage manifest, apply exceptions, score confidence, diff against baseline, and produce a verdict." width="760">
+</p>
+
+A crashed check module never disappears quietly. It becomes a HIGH coverage-gap finding, so the absence of a result is itself a result. A control that regresses from satisfied to missing against the saved baseline also becomes a HIGH finding.
+
+### Deep-analysis modules
+
+| Module | Patterns | What it targets |
+| --- | --- | --- |
+| Deep injection | 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 |
 
-**Use this on every PR. Use it before you push. Use it when something feels off.**
+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.
 
-### `/ciso-orchestrator` - A Full Security Program in One Command
+### Scanner orchestration and threat intel
 
-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.
+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.
 
-**Use this before major releases, compliance audits, or security reviews. -> [See the full 39-agent architecture](#ciso-orchestrator-flow-39-agents)**
+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.
 
 ---
 
-| | `/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) |
+## Cloud security controls engine
 
-**Rule of thumb:** Use `/senior-security-engineer` on every PR. Use `/ciso-orchestrator` before major releases or compliance deadlines.
+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.
+
+| Coverage | Rules |
+| --- | --- |
+| AWS | 483 |
+| Azure | 320 |
+| GCP | 195 |
+| Terraform / HCL | 774 |
+| CloudFormation | 128 |
+| Bicep | 96 |
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/AbrahamOO/security-mcp/main/assets/diagrams/cloud-controls.svg" alt="Cloud controls flow: detect IaC against the 998-rule registry, surface violations, auto-fix safe Terraform cases then re-detect to confirm, revert if not cleared, and report anything unsafe as a manual action with a snippet." width="720">
+</p>
+
+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.
 
 ---
 
-## Quick Start - Install in 60 Seconds
+## Install
+
+Prerequisite: Node.js 20 or higher (`node --version`).
 
 ```bash
 npx -y security-mcp@latest install
 ```
 
-Restart your editor. Then in Claude Code:
+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:
 
 ```text
 /senior-security-engineer
 ```
 
-That's it. The engineer will ask how you want to scope the review, then find and fix security issues in your code.
-
-For a full 39-agent deep audit:
+For a full audit:
 
 ```text
 /ciso-orchestrator
 ```
 
----
-
-## Installation
-
-> **Prerequisite:** Node.js 20+. Check with `node --version`.
-
-### One Command — Auto-detects Your Editor
+Confirm the install is healthy at any time:
 
 ```bash
-npx -y security-mcp@latest install
-```
-
-The installer detects Claude Code, Cursor, VS Code, and Windsurf automatically and writes the config to the correct location. Restart your editor when it finishes, then type `/senior-security-engineer`.
-
-### Install for a Specific Editor
-
-```bash
-npx -y security-mcp@latest install --claude-code   # ~/.claude/settings.json
-npx -y security-mcp@latest install --cursor        # ~/.cursor/mcp.json
-npx -y security-mcp@latest install --vscode        # VS Code user settings.json
-npx -y security-mcp@latest install --windsurf      # ~/.windsurf/mcp.json
+npx -y security-mcp@latest doctor
 ```
 
-### Manual Config (Any MCP-Compatible Editor)
+### Manual config
 
-Add this to your editor's MCP server config and restart:
+Add the server to your editor's MCP config and restart.
 
-**Claude Code** (`~/.claude/settings.json`) · **Cursor** (`~/.cursor/mcp.json`) · **Windsurf** (`~/.windsurf/mcp.json`):
+Claude Code (`~/.claude/settings.json`), Cursor (`~/.cursor/mcp.json`), Windsurf (`~/.windsurf/mcp.json`):
 
 ```json
 {
@@ -267,7 +223,7 @@ Add this to your editor's MCP server config and restart:
 }
 ```
 
-**VS Code / GitHub Copilot** (user `settings.json`):
+VS Code / GitHub Copilot (user `settings.json`):
 
 ```json
 {
@@ -282,118 +238,17 @@ Add this to your editor's MCP server config and restart:
 
 ---
 
-## Verify Your Installation
+## CI/CD gate
 
-After installing, confirm everything is wired up correctly:
+The gate runs as plain Node.js with no AI session involved, so it belongs in your pipeline as a required check.
 
 ```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.
-
-**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
+npx -y security-mcp@latest ci:pr-gate
 ```
 
-**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
-```
+It exits non-zero on HIGH or CRITICAL findings.
 
-### Add to GitHub Actions
+### GitHub Actions
 
 Create `.github/workflows/security-gate.yml`:
 
@@ -402,7 +257,7 @@ name: Security Gate
 
 on:
   pull_request:
-    branches: [main, master]
+    branches: [main]
 
 jobs:
   security-gate:
@@ -410,533 +265,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 **24 check modules 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** | 42 patterns — XXE, SSTI (Java/PHP), SpEL/OGNL, prototype pollution, second-order injection, NoSQL/MongoDB/Redis/LDAP/XPath injection, JNDI/Log4Shell, CRLF, WebSocket injection, CSS injection, SSE-CRLF, PDF injection, HTTP response splitting, unsafe YAML, deserialization (pickle/Java), path traversal, log injection, SSRF, command injection, ReDoS, SQL/ORM (Prisma/Sequelize/Knex/TypeORM), and more |
-| **Deep auth** | 43 patterns — JWT alg confusion/kid injection/JWKS override, session fixation, OAuth state/redirect_uri/PKCE/client secret, hardcoded JWT secret, rate limit, plaintext compare, SAML signature, cookie flags, token rotation, HS/RS confusion, API key in URL, reset expiry/single-use, admin route without authz, timing oracle, account enumeration, session token in URL, low-entropy token, bcrypt cost factor, and more |
-| **Supply chain deep** | 32 patterns — keyloggers, reverse shells, destructive commands, credential exfiltration, env variable theft, malicious postinstall scripts, dynamic require(), base64-obfuscated exec, cryptomining, sensitive file reads, unpinned dependencies, hidden file writes, DNS exfiltration, clipboard monitoring, obfuscated DOM injection, and more |
-| **Business logic** | 31 patterns — IDOR without ownership check, mass assignment, race conditions, integer overflow, currency confusion, discount stacking, order fulfillment bypass, webhook replay, tax/shipping tamper, client-side total, referral abuse, email normalization, feature flag bypass, API version bypass, double-spend, free trial abuse, pagination abuse, and more |
-
-### 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
-
-- Rate limiting middleware added to all auth endpoints (configurable thresholds)
-- Account lockout after N failed attempts with progressive delays
-- Session absolute timeout (8h) and idle timeout (30 min)
-- FIDO2/WebAuthn requirement flagged for admin interfaces
-- IDOR protection: tenant/user IDs read from JWT claims, never from request params
-
-### Injection and Input Validation
-
-- Zod/Yup schema validation added to every API route handler
-- SQL: string concatenation -> parameterized queries or tagged template literals
-- Command execution: `exec(userInput)` -> `spawnSync` with arg array, no shell
-- Path traversal: user-controlled paths validated against project boundary
-- SSRF: server-side HTTP clients get RFC-1918 CIDR block lists + DNS validation
-
-### Web Security Headers
-
-Before:
-
-```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
+## Built for teams
 
-- `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
+Four platform subsystems let a security team operate security-mcp at scale, not just run it ad hoc.
 
-### Cryptography
+**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.
 
-- `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
+**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.
 
-### AI / LLM Security
+**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.
 
-- 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)       │
-│                                                              │
-│  28 checks run in parallel:                                  │
-│  checkSecrets    checkDependencies   checkApi    checkInfra  │
-│  checkCrypto     checkMobileIos      checkMobileAndroid      │
-│  checkAi         checkGraphQL        checkKubernetes         │
-│  checkDatabase   checkDlp            checkWebNextjs          │
-│  runSbomChecks   runAiRedteamChecks  runRuntimeChecks        │
-│  runCiPipelineChecks  runDockerChecks  runScanners           │
-│  checkInjectionDeep (42 patterns)  checkAuthDeep (43 patterns)│
-│  checkSupplyChainDeep (32)  checkBusinessLogic (31)         │
-│                                                              │
-│  Surface detection -> Control catalog -> Exception handling ->  │
-│  Coverage manifest -> Taint map -> Confidence scoring -> PASS / FAIL │
-└──────────────────────────────────────────────────────────────┘
-```
-
-### `/senior-security-engineer` Flow
-
-```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?
-    ├── 28 checks in parallel (incl. deep injection + deep auth)
-    ├── apply exceptions from .mcp/exceptions/
-    ├── compute confidence score
-    └── returns PASS/FAIL + findings[]
-        │
-        ▼
-  Claude writes inline fixes for every finding
-  (production-ready secure code, not suggestions)
-  Every HIGH/CRITICAL: FIXED with verified-clean re-run,
-  OR formally blocked with risk-acceptance record
-        │
-        ▼
-  security.attest_review(runId)
-    └── .mcp/reports/{runId}.attestation.json
-    └── SHA-256 integrity hash
-```
-
-### `/ciso-orchestrator` Flow (39 Agents)
-
-```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:
+## Self-protection and supply-chain posture
 
-```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)
-```
+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.
 
-### 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 |
-| --- | --- |
-| `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 |
+| Tool | Purpose |
 | --- | --- |
-| `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
+## Policy and exceptions
 
-### Customize the Security Policy
-
-The policy file controls what the gate blocks, what evidence it requires, and how exceptions are handled. Copy the default and edit:
+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
 {
@@ -945,181 +388,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_MCP_SHARED_SECRET` | (none) | Authenticates MCP tool callers via constant-time HMAC; enables 3-strike lockout. Generate with `openssl rand -hex 32` |
-| `SECURITY_POLICY_HMAC_KEY` | (none) | Signs the policy file so any tampering is detected at gate startup. Generate with `openssl rand -hex 32` |
+| `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 |
+| `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 |
 
-### 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 |
+### Observability
 
----
-
-## The 10 Rules That Are Never Broken
-
-No matter what your AI is asked to build, these are enforced without exception:
-
-1. **No `0.0.0.0/0` firewall rules** - ingress and egress must be source-restricted
-2. **All internal services over private VPC only** - no public IPs for databases, queues, or internal APIs
-3. **Secrets in a secret manager only** - never in code, `.env` files, CI logs, or container images
-4. **TLS 1.3 for everything in transit** - TLS 1.0 and 1.1 are explicitly blocked
-5. **Passwords hashed with Argon2id or bcrypt (cost ≥ 14)** - MD5 and SHA-1 are forbidden
-6. **Every API input validated server-side with a schema** - no passing raw request data to business logic
-7. **No inline JavaScript** - Content Security Policy is nonce-based only; no `unsafe-inline` or `unsafe-eval`
-8. **Admin interfaces require FIDO2/WebAuthn passkey** - TOTP is not acceptable for admin access
-9. **Threat model before any auth, payment, or AI feature** - no design-free implementation
-10. **Zero Trust: every request authenticated and authorized regardless of origin** - no implicit network trust
-
----
-
-## Troubleshooting
-
-### The `/senior-security-engineer` command isn't available in my editor
-
-**Cause:** The skill was not installed to `~/.claude/skills/`.
-
-**Fix:** Re-run the installer:
-
-```bash
-npx -y security-mcp@latest install
-```
-
-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 [Installation](#installation))
-2. Fully restart the editor (quit and reopen, not just reload window)
-3. Check Node.js version: `node --version` - must be 20 or higher
-
-### The CI gate fails with "cannot find module"
-
-**Cause:** The dist files weren't included in the npm package, or you're referencing a path that doesn't exist.
+| 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?**
-
-No. The MCP server runs locally as a Node.js process. Your code never leaves your machine. The only external calls made are to the npm registry (to check for updates) and optionally to GitHub (to download skill files) - both only if explicitly permitted. Live CVE/CISA KEV fetches during `/ciso-orchestrator` require your explicit internet permission at runtime.
-
-**Q: Do I need to know security to use this?**
-
-No. The tool is designed so that you don't need to understand what OWASP or ATT&CK mean. You describe what you're building, and the security engineer handles the rest.
-
-**Q: Will it slow down my development?**
+## The 10 non-negotiable rules
 
-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.
+No matter what the AI is asked to build, these hold:
 
-**Q: What if it fixes something I don't want changed?**
+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.
 
-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)