@mcp-guardian/server 1.3.3 → 1.3.5

package/README.md

@@ -9,7 +9,7 @@
 [![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
 [![CI](https://github.com/rudraneel93/mcp-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/rudraneel93/mcp-guardian/actions/workflows/ci.yml)
 
-> **Always use the latest version:** `npm install @mcp-guardian/server@latest` — current is **v1.3.1**. See the [Changelog](./CHANGELOG.md) for full version history and [GitHub Releases](https://github.com/rudraneel93/mcp-guardian/releases) for per-version source tags.
+> **Always use the latest version:** `npm install @mcp-guardian/server@latest` — current is **v1.3.3**. See the [Changelog](./CHANGELOG.md) for full version history and [GitHub Releases](https://github.com/rudraneel93/mcp-guardian/releases) for per-version source tags.
 
 MCP Guardian is a **security and governance proxy** for [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) infrastructure. It sits between AI clients and MCP servers, enforcing active security policies, tracking real token costs, and monitoring health — all while providing enterprise-grade observability and audit trails.
 
@@ -77,6 +77,14 @@ MCP Guardian provides:
 - **DPoP (v1.0)** — RFC 9449 sender-constrained token support for replay-proof authentication
 - **OpenTelemetry (v1.0)** — Distributed tracing across proxy and MCP servers via OTLP
 - **HTTP/SSE proxy (v0.8.0)** — Full proxy support for remote HTTP/SSE-based MCP servers
+- **Payload normalization (v1.2.0)** — Multi-stage decoder defeats URL/hex/unicode/HTML entity/shell obfuscation bypass attacks before regex evaluation
+- **Semantic shell analysis (v1.2.0)** — AST-based tokenization detects command substitution, pipe chains, redirects, and 33 dangerous commands semantically
+- **Dashboard authentication (v1.2.0)** — JWT session tokens, API key auth, CSRF protection, and rate-limited login for the web dashboard
+- **mTLS zero-trust networking (v1.3.0)** — Mutual TLS with client certificates for proxy ↔ upstream MCP server communication
+- **E2E proxy tests (v1.3.0)** — Real proxy spawns with `default-policy.yaml`, sends JSON-RPC, verifies block/pass/deny
+- **Supply chain CI (v1.3.0)** — GitHub Actions pipeline with `npm audit --audit-level=high`, CycloneDX SBOM generation, and `.npmrc` enforcement
+- **Operational runbooks (v1.3.0)** — 7 production runbooks covering circuit breaker, Redis, policy corruption, dashboard auth, latency, DB corruption, and token spikes with SLOs
+- **Disaster recovery plan (v1.3.0)** — RTO/RPO for all state types, backup strategy, recovery drills, and rollback procedures
 
 ---
 
@@ -817,12 +825,16 @@ Token counting uses `tiktoken` with the `o200k_base` encoding (used by GPT-4o an
 - [x] Command injection validation (10 suspicious patterns)
 - [x] Active policy engine — YAML-based pass/block/flag with allowlists, regex, rate limiting, token budgets
 - [x] Structured JSON logging (pino) for SIEM ingestion
-- [x] STRIDE threat model (SECURITY.md)
-- [x] 97 tests (13 suites)
-- [x] GitHub Actions CI (Node 18/20/22 matrix)
+- [x] STRIDE threat model (SECURITY.md) + formal THREAT_MODEL.md
+- [x] Payload normalization — multi-stage encode/decode bypass defense
+- [x] Semantic shell AST analysis — command substitution, pipe, and dangerous command detection
+- [x] Dashboard authentication — JWT sessions, API keys, CSRF protection
+- [x] mTLS zero-trust networking for proxy ↔ upstream communication
+- [x] 168 tests across 16 suites (unit, fuzz, integration, E2E)
+- [x] GitHub Actions CI (Node 18/20/22 matrix) + supply chain audit
 - [x] Performance benchmarks (p50: 5ms baseline, +25.78ms proxy overhead, +0.15ms policy)
 - [x] Helm chart + production deployment guide (K8s, fail-open/closed, sidecar pattern, scaling)
-- [x] Published to npm as [`@mcp-guardian/server@1.1.0`](https://www.npmjs.com/package/@mcp-guardian/server)
+- [x] Published to npm as [`@mcp-guardian/server@1.3.3`](https://www.npmjs.com/package/@mcp-guardian/server)
 - [x] OAuth 2.1 / OIDC proxy authentication (v0.5.0)
 - [x] RBAC — scope & client-ID-based access control (v0.5.1)
 - [x] Circuit breaker — 3-state protection for upstream servers (v0.5.2)
@@ -838,10 +850,16 @@ Token counting uses `tiktoken` with the `o200k_base` encoding (used by GPT-4o an
 - [x] DPoP support — RFC 9449 sender-constrained tokens (v1.0)
 - [x] OpenTelemetry tracing — distributed request tracking (v1.0)
 - [x] HTTP/SSE proxy server — remote MCP transport support (v0.8.0)
-- [ ] OPA integration for Rego policies
+- [x] E2E proxy tests — real CLI spawn with policy file (v1.3.0)
+- [x] Supply chain CI — npm audit, CycloneDX SBOM, npm provenance (v1.3.0)
+- [x] Operational runbooks — 7 scenarios with SLOs (v1.3.0)
+- [x] Disaster recovery plan — RTO/RPO, backup strategy, recovery drills (v1.3.0)
+- [x] GitHub primary language corrected to TypeScript (v1.3.3)
+- [x] npm keywords expanded to 22 terms for discoverability (v1.3.3)
+- [ ] OPA/Rego policy integration
 - [ ] Slack/Discord alerting
-- [ ] Prometheus metrics endpoint
 - [ ] Multi-user proxy
+- [ ] Hosted SaaS version
 
 ---
 
@@ -849,4 +867,4 @@ Token counting uses `tiktoken` with the `o200k_base` encoding (used by GPT-4o an
 
 MIT — see [LICENSE](LICENSE) for details.
 
-**Built with TypeScript, @modelcontextprotocol/sdk, tiktoken, sql.js, commander, chalk, and zod.**
+**Built with TypeScript, @modelcontextprotocol/sdk, tiktoken, sql.js, commander, chalk, zod, jose, pino, and prom-client.**

package/SECURITY.md

@@ -0,0 +1,131 @@
+# Security Policy
+
+## Threat Model (STRIDE per MCP Interaction)
+
+MCP Guardian's security posture is modeled against the STRIDE framework for each MCP interaction vector.
+
+### 1. Spoofing (Identity Forgery)
+
+| Threat | Mitigation |
+|---|---|
+| Typo-squatted MCP server packages | Typo-squat detector with Levenshtein distance against 24 known official packages |
+| Fake MCP server responding to health probes | TLS certificate validation for SSE/HTTP transports |
+| Malicious server impersonating a trusted tool | Command validation flags non-standard executables |
+
+### 2. Tampering (Data/Command Injection)
+
+| Threat | Mitigation |
+|---|---|
+| Shell injection via tool arguments | Active policy engine blocks patterns (rm -rf, shell chaining, backtick substitution) |
+| Encoded payload bypasses (URL, hex, unicode, HTML entities) | PayloadNormalizer (v1.2) — multi-stage decode before regex evaluation |
+| Shell obfuscation (ANSI-C quoting, quote splitting, backslash escapes) | ShellTokenizer (v1.2) — semantic AST analysis of command structure |
+| Path traversal | Active policy engine blocks ../ patterns |
+| Supply chain compromise of MCP server package | CVE checker queries OSV.dev and NVD for known vulnerabilities |
+
+### 3. Repudiation (Deniability)
+
+| Threat | Mitigation |
+|---|---|
+| No audit trail for blocked/allowed tool calls | Structured JSON logging (pino) captures every policy_decision |
+| Policy changes without audit | PolicyAuditor (v1.0.1) records every policy change with hash verification |
+| Denied access attempts not recorded | tool_blocked events logged at WARN level for SIEM alerting |
+
+### 4. Information Disclosure (Secrets/Data Leakage)
+
+| Threat | Mitigation |
+|---|---|
+| Hardcoded API keys, tokens, passwords in MCP config | Secret scanner (6 regex patterns) |
+| Unauthenticated dashboard access | DashboardAuth (v1.2) — JWT sessions, API keys, CSRF protection, rate-limited login |
+| Unencrypted transport | Auth prober flags unencrypted transports |
+| Sensitive data in generated reports | Reports use config names, not raw secrets |
+
+### 5. Denial of Service (Availability)
+
+| Threat | Mitigation |
+|---|---|
+| Token bombs | Token budget rule (maxTokens) flags/blocks oversized calls |
+| Tool overload (>15 tools) | Health monitor detects overload; --fail-on-overload CLI flag |
+| Rate abuse | Rate limiting rule (maxCallsPerMinute) per server+tool |
+| API ban on CVE lookup services | Token-bucket rate limiter on OSV.dev (5 req/min) and NVD (20 req/min with key) |
+
+### 6. Elevation of Privilege (Agent Hijacking)
+
+| Threat | Mitigation |
+|---|---|
+| Confused deputy attack | Tool allowlist/denylist in policy engine; argument pattern blocking |
+| Agent tricked into calling dangerous tools | Default policy denies execute_command, bash, sh, eval, exec |
+| Missing authentication on MCP servers | OAuth 2.1/OIDC JWT validation with RBAC (scopes, client IDs) |
+
+## Supported Versions
+
+| Version | Status | Security Updates |
+|---|---|---|
+| 1.0.x | ✅ Current | All updates |
+| 0.7.x | ✅ Supported | Critical only |
+| <0.7.0 | ❌ Unsupported | None |
+
+## Reporting a Vulnerability
+
+**Do not open a public issue for security vulnerabilities.**
+
+Email **rudraneel93@gmail.com** with:
+- Description of the vulnerability
+- Steps to reproduce
+- Affected version(s)
+- Any proof-of-concept or crash data
+
+Response timeline:
+- **24 hours:** Acknowledgement
+- **72 hours:** Initial assessment
+- **7 days:** Patch or mitigation plan
+
+## Incident Response
+
+### Severity Classification
+
+| Level | Example | Response |
+|---|---|---|
+| **Critical** | RCE via proxy, auth bypass, secret leak | Patch within 24 hours, CVE disclosure |
+| **High** | Policy bypass, DoS vulnerability | Patch within 72 hours |
+| **Medium** | Information disclosure, limited impact | Patch in next release |
+| **Low** | Minor configuration issues | Documented workaround |
+
+### Emergency Patch Process
+
+1. **Isolate:** If a vulnerability is confirmed, immediately document the affected versions and attack vector
+2. **Mitigate:** Provide a temporary workaround (policy rule, config change) within 24 hours
+3. **Patch:** Release a fix with full test coverage
+4. **Disclose:** Publish advisory in GitHub Security Advisories and npm audit
+
+### Dependency Supply Chain
+
+- All dependencies are pinned via `package-lock.json`
+- CI pipeline runs `npm audit` on every commit
+- Critical dependencies (`@modelcontextprotocol/sdk`, `jose`, `pg`) are reviewed on each major version bump
+- OTel gRPC exporter removed (v1.0.1) due to critical CVE in protobufjs dependency chain
+
+## Security Design Principles
+
+1. **Least Privilege:** The policy engine denies by default when configured with allowlists
+2. **Defense in Depth:** Static scanning (config audit) + runtime enforcement (proxy policy) + SIEM logging
+3. **Fail Secure:** Graceful shutdown flushes DB before exit; blocked calls return explicit errors
+4. **Auditability:** Every policy decision, block, and proxy event is logged as structured JSON. Policy changes are recorded via PolicyAuditor
+5. **Zero Trust on Input:** All tool arguments are pattern-checked regardless of source
+
+## Dependencies
+
+MCP Guardian requires these critical dependencies:
+
+| Dependency | Purpose | Security Notes |
+|---|---|---|
+| `@modelcontextprotocol/sdk` | MCP protocol implementation | Keep updated to latest; CVE monitoring |
+| `tiktoken` | Token counting (o200k_base encoding) | Pure JS, no native bindings |
+| `sql.js` | SQLite storage | WASM-based, no native compilation |
+| `pino` | Structured logging | High-performance JSON logger |
+| `js-yaml` | YAML policy parsing | Policy files only |
+| `jose` | JWT/JWK validation | OAuth 2.1/OIDC support |
+| `ioredis` | Redis client | Session cache and rate limit store |
+| `pg` | PostgreSQL client | Production DB backend |
+| `prom-client` | Prometheus metrics | Monitoring |
+
+Run `npm audit` regularly and update dependencies through Dependabot or similar tools.

package/default-policy.yaml

@@ -0,0 +1,53 @@
+---
+# MCP Guardian — Default Policy Configuration
+# Use with: mcp-guardian proxy --policy ./default-policy.yaml
+
+version: "1.0"
+policy:
+  # Mode: audit (passive, log only), warn (block → flag), block (active enforcement)
+  mode: warn
+
+  rules:
+    # ── Block shell injection patterns ──────────────────────────
+    - name: "block-shell-injection"
+      description: "Block tool calls containing shell injection or command chaining"
+      action: block
+      patterns:
+        - "curl\\s|wget\\s"           # Network download tools
+        - "rm\\s+-rf"                 # Destructive commands
+        - ";\\s*\\w"                  # Shell chaining
+        - "&&|\\|\\|"                 # Shell logical operators
+        - "\\$\\{"                    # Shell variable expansion
+        - "`[^`]+`"                   # Backtick command substitution
+        - "/etc/passwd|/etc/shadow"   # Sensitive system files
+
+    # ── Block path traversal ─────────────────────────────────────
+    - name: "block-path-traversal"
+      description: "Block tool calls with path traversal attempts"
+      action: block
+      patterns:
+        - "\\.\\.\\/"                 # Path traversal
+
+    # ── Deny dangerous tools ─────────────────────────────────────
+    - name: "deny-dangerous-tools"
+      description: "Explicitly deny tools that can execute arbitrary code"
+      action: block
+      tools:
+        deny:
+          - "execute_command"
+          - "bash"
+          - "sh"
+          - "eval"
+          - "exec"
+
+    # ── Rate limit ───────────────────────────────────────────────
+    - name: "rate-limit-tool-calls"
+      description: "Limit tool calls to 120 per minute per server+tool"
+      action: flag
+      maxCallsPerMinute: 120
+
+    # ── Token budget ─────────────────────────────────────────────
+    - name: "token-budget"
+      description: "Flag tool calls exceeding 50K input tokens"
+      action: flag
+      maxTokens: 50000

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@mcp-guardian/server",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Security, cost, and health audit for MCP infrastructure",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "default-policy.yaml"
   ],
   "bin": {
     "mcp-guardian": "./dist/cli.js"