mcp-warden 0.1.5 → 1.1.0

package/README.md

@@ -8,12 +8,16 @@ High-performance security guardrails for MCP-compatible AI agents and tool execu
 
 ## Features
 
-- Policy-based tool authorization for MCP tool calls.
-- Filesystem path enforcement for blocked paths defined in policy.
-- Human-in-the-loop gating with `REQUIRES_APPROVAL` status when approval is mandated.
-- Prompt-injection scanning for high-risk control phrases.
-- Output redaction for email addresses, API keys, and IP addresses.
-- Built-in rate limiting and circuit-breaker protection.
+- Policy-based tool authorization (exact strings and regex patterns).
+- Filesystem path enforcement — `blocked` denies all access; `read-only` allows reads and denies write-intent tool calls.
+- Human-in-the-loop gating with `REQUIRES_APPROVAL` status.
+- Prompt-injection scanning with word-boundary-aware regex matching.
+- Output redaction for emails, API keys, IPv4/IPv6 addresses, and phone numbers — in a single regex pass.
+- Global and per-tool rate limiting with O(1) circular-buffer implementation.
+- Per-tool circuit-breaker protection with automatic TTL cleanup.
+- Input size limits (max nesting depth and max byte size) to guard against oversized payloads.
+- Metrics hook for observability (timing, allow/block decisions, violation codes).
+- Extensible middleware chain — register custom policy layers with `.use()`.
 - CLI audit workflow for identifying over-permissioned MCP servers.
 
 ## Table of Contents
@@ -21,6 +25,11 @@ High-performance security guardrails for MCP-compatible AI agents and tool execu
 - [Why Security Matters for AI Agents](#why-security-matters-for-ai-agents)
 - [Quick Start](#quick-start)
 - [Policy Configuration](#policy-configuration)
+- [Advanced Options](#advanced-options)
+- [Per-Tool Rate Limits](#per-tool-rate-limits)
+- [Metrics Hook](#metrics-hook)
+- [Input Size Limits](#input-size-limits)
+- [Custom Middleware](#custom-middleware)
 - [CLI Commands](#cli-commands)
 - [Development](#development)
 - [License](#license)
@@ -30,14 +39,16 @@ High-performance security guardrails for MCP-compatible AI agents and tool execu
 
 AI agents can execute tools with real-world side effects: reading files, modifying systems, calling external APIs, and handling sensitive data. Without guardrails, a single prompt injection or over-permissioned server can lead to data leakage, privilege escalation, or runaway tool loops.
 
-mcp-warden helps enforce a security boundary before and after tool execution:
+mcp-warden enforces a security boundary before and after every tool execution:
+
 - Blocks unauthorized tools using explicit policy rules.
-- Denies tool calls that target blocked filesystem paths from policy.
+- Denies tool calls targeting blocked filesystem paths; blocks write operations on read-only paths.
 - Returns `REQUIRES_APPROVAL` before execution when `approvalRequired` is enabled.
-- Detects prompt-injection signatures in tool arguments.
-- Enforces rate limits to reduce abuse and runaway call storms.
-- Applies circuit-breaker protection for repeated tool failures.
+- Detects prompt-injection signatures in tool arguments using word-boundary regex patterns.
+- Enforces global and per-tool rate limits to prevent abuse and runaway call storms.
+- Applies per-tool circuit-breaker protection for repeated failures.
 - Redacts sensitive output data before it reaches downstream systems.
+- Rejects oversized or deeply nested payloads before any other check runs.
 
 ## Quick Start
 
@@ -53,13 +64,11 @@ npm install mcp-warden
 {
   "allowedTools": ["list_dir", "read_file", "grep_search"],
   "restrictedPaths": [
-    {
-      "path": "/",
-      "mode": "blocked"
-    }
+    { "path": "/etc", "mode": "blocked" },
+    { "path": "/home", "mode": "read-only" }
   ],
   "maxCallsPerMinute": 60,
-  "approvalRequired": true
+  "approvalRequired": false
 }
 ```
 
@@ -70,12 +79,15 @@ import { McpGuardian, type GuardianPolicy } from "mcp-warden";
 
 const policy: GuardianPolicy = {
   allowedTools: ["read_file", /^search_/],
-  restrictedPaths: [{ path: "/", mode: "blocked" }],
+  restrictedPaths: [
+    { path: "/etc", mode: "blocked" },
+    { path: "/home", mode: "read-only" }
+  ],
   maxCallsPerMinute: 60,
-  approvalRequired: true
+  approvalRequired: false
 };
 
-const guardian = new McpGuardian(policy, { dryRun: false });
+const guardian = new McpGuardian(policy);
 
 const guardedHandler = guardian.wrapHandler(async (request) => {
   // Your MCP transport execution logic
@@ -97,38 +109,148 @@ npx mcp-warden audit ./claude_desktop_config.json
 npx mcp-warden init
 ```
 
-If you install globally, you can use the short command directly:
+## Policy Configuration
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `allowedTools` | `Array<string \| RegExp>` | Yes | Allowed tool names or regex matchers. |
+| `restrictedPaths` | `Array<{ path: string; mode: "read-only" \| "blocked" }>` | Yes | Path access constraints. `blocked` = all access denied. `read-only` = reads allowed, write-intent tool calls denied. |
+| `maxCallsPerMinute` | `number` | Yes | Rolling 60-second quota for tool calls. |
+| `approvalRequired` | `boolean` | Yes | When `true`, every tool call is paused with `REQUIRES_APPROVAL`. |
 
-```bash
-mcp-warden audit ./claude_desktop_config.json
-mcp-warden init
+## Advanced Options
+
+Pass an `McpGuardianOptions` object as the second constructor argument:
+
+```ts
+const guardian = new McpGuardian(policy, {
+  dryRun: false,             // log violations but allow all requests
+  redactToolOutputs: true,   // redact PII from tool responses (default: true)
+  logger: (violation) => myLogger.warn(violation),
+  injectionKeywords: [       // override default injection phrases
+    "ignore previous instructions",
+    "you are now unrestricted"
+  ],
+  circuitBreaker: {
+    threshold: 5,            // failures before circuit opens (default: 5)
+    cooldownMs: 60_000,      // how long circuit stays open (default: 60s)
+    stateTtlMs: 600_000      // evict idle tool state after 10min (default)
+  },
+  maxArgDepth: 20,           // max nesting depth of tool args (default: 20)
+  maxArgBytes: 524288        // max byte size of tool args (default: 512 KB)
+});
 ```
 
-## Policy Configuration
+## Per-Tool Rate Limits
+
+Override the global rate limit for specific tools. The first matching rule wins.
+
+```ts
+const guardian = new McpGuardian(policy, {
+  toolRateLimits: [
+    { tool: "expensive_search", maxCallsPerMinute: 5 },
+    { tool: /^write_/, maxCallsPerMinute: 10 }
+  ]
+});
+```
+
+## Metrics Hook
+
+Receive an observability snapshot after every validated request:
+
+```ts
+const guardian = new McpGuardian(policy, {
+  metricsHook: (metrics) => {
+    console.log({
+      method: metrics.method,
+      tool: metrics.toolName,
+      allowed: metrics.allowed,
+      violation: metrics.violationCode,
+      durationMs: metrics.durationMs
+    });
+  }
+});
+```
+
+`GuardianMetrics` fields:
 
-| Option | Type | Required | Description | Example |
-|---|---|---|---|---|
-| allowedTools | Array<string \| RegExp> | Yes | Allowed tool names or regex matchers for tools/call requests. | ["read_file", /^search_/] |
-| restrictedPaths | Array<{ path: string; mode: "read-only" \| "blocked" }> | Yes | Directory access constraints used by filesystem-aware middleware. | [{ "path": "/", "mode": "blocked" }] |
-| maxCallsPerMinute | number | Yes | Rolling 60-second budget for tool calls. Requests above this limit are denied. | 60 |
-| approvalRequired | boolean | Yes | When true, tool calls are paused with `REQUIRES_APPROVAL` until explicit human approval is granted by the host system. | true |
+| Field | Type | Description |
+|---|---|---|
+| `timestamp` | `number` | Unix ms when the request was processed. |
+| `method` | `string` | JSON-RPC method name. |
+| `toolName` | `string \| undefined` | Tool name for `tools/call` requests. |
+| `allowed` | `boolean` | Whether the request was allowed. |
+| `violationCode` | `"PERMISSION_DENIED" \| "REQUIRES_APPROVAL" \| undefined` | Set when blocked. |
+| `durationMs` | `number` | Processing time in milliseconds. |
+
+## Input Size Limits
+
+Requests with oversized or deeply nested arguments are rejected before any other middleware runs:
+
+```ts
+const guardian = new McpGuardian(policy, {
+  maxArgDepth: 10,     // reject args nested deeper than 10 levels
+  maxArgBytes: 65536   // reject args larger than 64 KB
+});
+```
+
+## Custom Middleware
+
+Register additional policy layers with `.use()`. Middleware runs after all built-in checks:
+
+```ts
+guardian.use(async (context, next) => {
+  if (context.toolName === "restricted_tool" && !context.isDryRun) {
+    return { allowed: false, reason: "This tool requires explicit opt-in." };
+  }
+  return next();
+});
+```
+
+`GuardianContext` properties:
+
+| Property | Type | Description |
+|---|---|---|
+| `request` | `JsonRpcRequest` | The raw JSON-RPC 2.0 request. |
+| `policy` | `GuardianPolicy` | Active policy configuration. |
+| `isDryRun` | `boolean` | Whether dry-run mode is active. |
+| `toolName` | `string \| undefined` | Extracted tool name. |
+| `toolArgs` | `unknown` | Extracted tool arguments. |
 
 ## CLI Commands
 
-- npx mcp-warden audit <config-path>
-- npx mcp-warden init [--output <path>] [--force]
+**Audit a config file:**
+
+```bash
+npx mcp-warden audit <config-path>
+```
+
+Scans `claude_desktop_config.json`, `cursor-settings.json`, or any MCP JSON config for over-permissioned servers. Exits with code `1` if critical findings are detected.
+
+Critical findings include:
+- Permissions granting full disk access (`*`, `all`, `filesystem:*`)
+- Broad filesystem paths (`/`, `~`, `/Users/...`)
+- Dangerous CLI flags (`--allow-all`, `--dangerously-skip-permissions`, etc.)
+- Environment variables enabling unrestricted access
+
+**Generate a default policy:**
+
+```bash
+npx mcp-warden init [--output <path>] [--force]
+```
 
-CLI output uses color-coded alerts:
-- Green: SAFE
-- Red: CRITICAL
+Creates a secure `mcp-policy.json` with conservative defaults. Use `--force` to overwrite an existing file.
 
 ## Development
 
 ```bash
 npm install
-npm run typecheck
-npm test
-npm run build
+npm run typecheck     # TypeScript type checking
+npm test              # Run test suite (26 tests)
+npm run coverage      # Run tests with v8 coverage report
+npm run lint          # ESLint
+npm run format        # Prettier
+npm run build         # Compile to dist/
 ```
 
 ## License
@@ -137,4 +259,4 @@ npm run build
 
 ## Security Disclaimer
 
-mcp-warden is a runtime governance layer designed to mitigate risks. It is not a replacement for OS-level permissions, network-level firewalls, or the principle of least privilege. Always run AI agents in isolated environments when possible.
+mcp-warden is a runtime governance layer designed to mitigate risks in AI agent tool execution. It is not a replacement for OS-level permissions, network-level firewalls, or the principle of least privilege. Always run AI agents in isolated environments with minimal permissions where possible.

package/dist/builder/policy-builder.d.ts

@@ -0,0 +1,61 @@
+import type { ArgSchema, GuardianPolicy } from "../types/policy.js";
+/**
+ * Fluent builder for constructing a `GuardianPolicy` without writing object literals.
+ *
+ * @example
+ * ```ts
+ * const policy = new PolicyBuilder()
+ *   .allow("read_file")
+ *   .allow(/^search_/)
+ *   .block("/etc")
+ *   .readOnly("/home")
+ *   .rateLimit(30)
+ *   .argSchema("read_file", {
+ *     type: "object",
+ *     required: ["path"],
+ *     properties: { path: { type: "string" } }
+ *   })
+ *   .build();
+ * ```
+ */
+export declare class PolicyBuilder {
+    private readonly _tools;
+    private readonly _paths;
+    private _limit;
+    private _approval;
+    private readonly _schemas;
+    /**
+     * Allow a tool by exact name or regex pattern.
+     * Call multiple times to allow multiple tools.
+     */
+    allow(tool: string | RegExp): this;
+    /**
+     * Block all access (reads and writes) to a filesystem path.
+     */
+    block(path: string): this;
+    /**
+     * Allow reads but deny write-intent tool calls on a filesystem path.
+     */
+    readOnly(path: string): this;
+    /**
+     * Set the global tool-call rate limit (calls per rolling minute).
+     * Default: 60.
+     */
+    rateLimit(maxPerMinute: number): this;
+    /**
+     * Require human approval before any tool call executes.
+     * Pass `false` to disable (useful when composing builders).
+     */
+    requireApproval(required?: boolean): this;
+    /**
+     * Attach an argument shape schema to a specific tool.
+     * Requests with non-conforming arguments will be rejected.
+     */
+    argSchema(tool: string, schema: ArgSchema): this;
+    /**
+     * Validate and return the constructed `GuardianPolicy`.
+     * Throws if the accumulated configuration is invalid.
+     */
+    build(): GuardianPolicy;
+}
+//# sourceMappingURL=policy-builder.d.ts.map

package/dist/builder/policy-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-builder.d.ts","sourceRoot":"","sources":["../../src/builder/policy-builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAA6B,MAAM,oBAAoB,CAAC;AAE/F;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD,OAAO,CAAC,MAAM,CAAM;IAEpB,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAE1D;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKlC;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B;;;OAGG;IACH,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAKrC;;;OAGG;IACH,eAAe,CAAC,QAAQ,UAAO,GAAG,IAAI;IAKtC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAKhD;;;OAGG;IACH,KAAK,IAAI,cAAc;CAUxB"}

package/dist/builder/policy-builder.js

@@ -0,0 +1,88 @@
+import { GuardianPolicySchema } from "../types/policy.js";
+/**
+ * Fluent builder for constructing a `GuardianPolicy` without writing object literals.
+ *
+ * @example
+ * ```ts
+ * const policy = new PolicyBuilder()
+ *   .allow("read_file")
+ *   .allow(/^search_/)
+ *   .block("/etc")
+ *   .readOnly("/home")
+ *   .rateLimit(30)
+ *   .argSchema("read_file", {
+ *     type: "object",
+ *     required: ["path"],
+ *     properties: { path: { type: "string" } }
+ *   })
+ *   .build();
+ * ```
+ */
+export class PolicyBuilder {
+    _tools = [];
+    _paths = [];
+    _limit = 60;
+    _approval = false;
+    _schemas = {};
+    /**
+     * Allow a tool by exact name or regex pattern.
+     * Call multiple times to allow multiple tools.
+     */
+    allow(tool) {
+        this._tools.push(tool);
+        return this;
+    }
+    /**
+     * Block all access (reads and writes) to a filesystem path.
+     */
+    block(path) {
+        this._paths.push({ path, mode: "blocked" });
+        return this;
+    }
+    /**
+     * Allow reads but deny write-intent tool calls on a filesystem path.
+     */
+    readOnly(path) {
+        this._paths.push({ path, mode: "read-only" });
+        return this;
+    }
+    /**
+     * Set the global tool-call rate limit (calls per rolling minute).
+     * Default: 60.
+     */
+    rateLimit(maxPerMinute) {
+        this._limit = maxPerMinute;
+        return this;
+    }
+    /**
+     * Require human approval before any tool call executes.
+     * Pass `false` to disable (useful when composing builders).
+     */
+    requireApproval(required = true) {
+        this._approval = required;
+        return this;
+    }
+    /**
+     * Attach an argument shape schema to a specific tool.
+     * Requests with non-conforming arguments will be rejected.
+     */
+    argSchema(tool, schema) {
+        this._schemas[tool] = schema;
+        return this;
+    }
+    /**
+     * Validate and return the constructed `GuardianPolicy`.
+     * Throws if the accumulated configuration is invalid.
+     */
+    build() {
+        const hasSchemas = Object.keys(this._schemas).length > 0;
+        return GuardianPolicySchema.parse({
+            allowedTools: [...this._tools],
+            restrictedPaths: [...this._paths],
+            maxCallsPerMinute: this._limit,
+            approvalRequired: this._approval,
+            ...(hasSchemas ? { toolArgSchemas: { ...this._schemas } } : {})
+        });
+    }
+}
+//# sourceMappingURL=policy-builder.js.map

package/dist/builder/policy-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-builder.js","sourceRoot":"","sources":["../../src/builder/policy-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,aAAa;IACP,MAAM,GAAe,EAAE,CAAC;IAExB,MAAM,GAAsB,EAAE,CAAC;IAExC,MAAM,GAAG,EAAE,CAAC;IAEZ,SAAS,GAAG,KAAK,CAAC;IAET,QAAQ,GAA8B,EAAE,CAAC;IAE1D;;;OAGG;IACH,KAAK,CAAC,IAAqB;QACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAY;QAChB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAY;QACnB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,YAAoB;QAC5B,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,QAAQ,GAAG,IAAI;QAC7B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,IAAY,EAAE,MAAiB;QACvC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACzD,OAAO,oBAAoB,CAAC,KAAK,CAAC;YAChC,YAAY,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YAC9B,eAAe,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACjC,iBAAiB,EAAE,IAAI,CAAC,MAAM;YAC9B,gBAAgB,EAAE,IAAI,CAAC,SAAS;YAChC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import { GuardianPolicySchema } from \"../types/policy.js\";\nimport type { ArgSchema, GuardianPolicy, PathRestriction, ToolRule } from \"../types/policy.js\";\n\n/**\n * Fluent builder for constructing a `GuardianPolicy` without writing object literals.\n *\n * @example\n * ```ts\n * const policy = new PolicyBuilder()\n *   .allow(\"read_file\")\n *   .allow(/^search_/)\n *   .block(\"/etc\")\n *   .readOnly(\"/home\")\n *   .rateLimit(30)\n *   .argSchema(\"read_file\", {\n *     type: \"object\",\n *     required: [\"path\"],\n *     properties: { path: { type: \"string\" } }\n *   })\n *   .build();\n * ```\n */\nexport class PolicyBuilder {\n  private readonly _tools: ToolRule[] = [];\n\n  private readonly _paths: PathRestriction[] = [];\n\n  private _limit = 60;\n\n  private _approval = false;\n\n  private readonly _schemas: Record<string, ArgSchema> = {};\n\n  /**\n   * Allow a tool by exact name or regex pattern.\n   * Call multiple times to allow multiple tools.\n   */\n  allow(tool: string | RegExp): this {\n    this._tools.push(tool);\n    return this;\n  }\n\n  /**\n   * Block all access (reads and writes) to a filesystem path.\n   */\n  block(path: string): this {\n    this._paths.push({ path, mode: \"blocked\" });\n    return this;\n  }\n\n  /**\n   * Allow reads but deny write-intent tool calls on a filesystem path.\n   */\n  readOnly(path: string): this {\n    this._paths.push({ path, mode: \"read-only\" });\n    return this;\n  }\n\n  /**\n   * Set the global tool-call rate limit (calls per rolling minute).\n   * Default: 60.\n   */\n  rateLimit(maxPerMinute: number): this {\n    this._limit = maxPerMinute;\n    return this;\n  }\n\n  /**\n   * Require human approval before any tool call executes.\n   * Pass `false` to disable (useful when composing builders).\n   */\n  requireApproval(required = true): this {\n    this._approval = required;\n    return this;\n  }\n\n  /**\n   * Attach an argument shape schema to a specific tool.\n   * Requests with non-conforming arguments will be rejected.\n   */\n  argSchema(tool: string, schema: ArgSchema): this {\n    this._schemas[tool] = schema;\n    return this;\n  }\n\n  /**\n   * Validate and return the constructed `GuardianPolicy`.\n   * Throws if the accumulated configuration is invalid.\n   */\n  build(): GuardianPolicy {\n    const hasSchemas = Object.keys(this._schemas).length > 0;\n    return GuardianPolicySchema.parse({\n      allowedTools: [...this._tools],\n      restrictedPaths: [...this._paths],\n      maxCallsPerMinute: this._limit,\n      approvalRequired: this._approval,\n      ...(hasSchemas ? { toolArgSchemas: { ...this._schemas } } : {})\n    });\n  }\n}\n"]}