@panguard-ai/panguard-mcp-proxy 1.7.3 → 1.8.0

package/README.md

@@ -0,0 +1,18 @@
+# @panguard-ai/panguard-mcp-proxy
+
+MCP Proxy — runtime interception for AI agent tool calls using ATR (Agent Threat Rules).
+
+Transparent tool-call evaluation:
+
+- Intercepts MCP tool calls at runtime
+- Evaluates threats against 675+ ATR rules
+- Allows or blocks execution based on policy
+- Integration with Claude, Cursor, and other AI agents
+
+Part of the **PanGuard Community** suite — 100% free and open source (MIT).
+
+```bash
+npm install @panguard-ai/panguard-mcp-proxy
+```
+
+**License**: MIT

package/dist/evaluator.d.ts

@@ -6,6 +6,7 @@
  *
  * @module @panguard-ai/panguard-mcp-proxy/evaluator
  */
+import type { AgentEvent } from '@panguard-ai/atr';
 export interface EvalResult {
     readonly outcome: 'allow' | 'deny' | 'ask';
     readonly reason: string;
@@ -52,8 +53,21 @@ export declare class ProxyEvaluator {
     getRuleCount(): number;
     /** Flatten args into a readable string for ATR regex matching */
     private flattenArgs;
-    /** Evaluate a tool call (PreToolUse) */
-    evaluateToolCall(toolName: string, args: Record<string, unknown>): Promise<EvalResult>;
+    /**
+     * Evaluate a tool call (PreToolUse).
+     *
+     * `eventType` selects which ATR rules apply. The MCP proxy sees genuine
+     * MCP exchanges, so it keeps the 'mcp_exchange' default. The Claude-Code /
+     * Gemini / Codex PreToolUse hook wraps built-in tools (Bash, Edit, Write,
+     * WebFetch) — those are 'tool_call' events. Passing 'tool_call' makes the
+     * engine run the tool_call rule set (shell injection, credential theft,
+     * SSRF, RCE, privilege escalation) AND, via the engine's mcp-over-tool
+     * exception, the mcp_exchange rules — while correctly skipping
+     * multi_agent_comm and llm_io rules that never apply to a shell command.
+     * The old hardcoded 'mcp_exchange' both missed the tool_call attack rules
+     * and false-fired multi_agent_comm rules on ordinary commands.
+     */
+    evaluateToolCall(toolName: string, args: Record<string, unknown>, eventType?: AgentEvent['type']): Promise<EvalResult>;
     /** Evaluate a tool response (PostToolUse) */
     evaluateToolResponse(toolName: string, response: string): Promise<EvalResult>;
     private evaluate;

package/dist/evaluator.js

@@ -122,8 +122,21 @@ export class ProxyEvaluator {
         }
         return parts.join('\n');
     }
-    /** Evaluate a tool call (PreToolUse) */
-    async evaluateToolCall(toolName, args) {
+    /**
+     * Evaluate a tool call (PreToolUse).
+     *
+     * `eventType` selects which ATR rules apply. The MCP proxy sees genuine
+     * MCP exchanges, so it keeps the 'mcp_exchange' default. The Claude-Code /
+     * Gemini / Codex PreToolUse hook wraps built-in tools (Bash, Edit, Write,
+     * WebFetch) — those are 'tool_call' events. Passing 'tool_call' makes the
+     * engine run the tool_call rule set (shell injection, credential theft,
+     * SSRF, RCE, privilege escalation) AND, via the engine's mcp-over-tool
+     * exception, the mcp_exchange rules — while correctly skipping
+     * multi_agent_comm and llm_io rules that never apply to a shell command.
+     * The old hardcoded 'mcp_exchange' both missed the tool_call attack rules
+     * and false-fired multi_agent_comm rules on ordinary commands.
+     */
+    async evaluateToolCall(toolName, args, eventType = 'mcp_exchange') {
         const start = Date.now();
         // Check Guard blocklist first (instant deny, no regex needed)
         this.refreshBlocklist();
@@ -139,7 +152,7 @@ export class ProxyEvaluator {
         // Flatten args into natural text so ATR regexes can match content like paths and commands
         const flatContent = `${toolName} ${this.flattenArgs(args)}`;
         const event = {
-            type: 'mcp_exchange',
+            type: eventType,
             timestamp: new Date().toISOString(),
             content: flatContent,
             fields: {

package/dist/proxy.d.ts

@@ -32,7 +32,7 @@ export interface ProxyConfig {
 /** The subset of ProxyEvaluator the proxy uses — injectable for testing. */
 export interface ProxyEvaluatorLike {
     loadRules(): Promise<number>;
-    evaluateToolCall(toolName: string, args: Record<string, unknown>): Promise<EvalResult>;
+    evaluateToolCall(toolName: string, args: Record<string, unknown>, eventType?: string): Promise<EvalResult>;
     evaluateToolResponse(toolName: string, response: string): Promise<EvalResult>;
 }
 export declare class MCPProxy {

package/dist/proxy.js

@@ -64,12 +64,21 @@ export class MCPProxy {
             config.failMode ??
                 (envFailMode === 'open' || envFailMode === 'closed' ? envFailMode : 'closed');
         this.evalTimeout = config.evalTimeout ?? 5000;
-        this.sessionId =
-            config.sessionId ?? `mcp-proxy-${process.pid}-${Date.now().toString(36)}`;
+        this.sessionId = config.sessionId ?? `mcp-proxy-${process.pid}-${Date.now().toString(36)}`;
         this.agentId = config.agentId ?? process.env['PANGUARD_AGENT_ID'] ?? 'mcp-agent';
-        // Sync sub-ms pre-check. Runs in front of the async evaluator so the worst
-        // payloads (and any session the brain flags) are blocked instantly — and,
-        // with fail-closed as the default, an unavailable async evaluator denies.
+        // Sync sub-ms pre-check (InlineGate.onAction) that reads riskStore: once a
+        // session is escalated to 'high' it fast-blocks subsequent calls before the
+        // async evaluator even runs. That escalation is FED by recordEvalVerdict()
+        // (a real ATR deny -> riskStore.set high), so the session-risk loop is live.
+        //
+        // HONEST SCOPE (Community): the async behavioral brain — RiskAnalyzer.analyze
+        // via guard.onSessionActivity — is NOT driven here; it needs a real
+        // ContentDetector + per-session event feed and, more importantly, a real
+        // ContainmentController to act on its verdicts (Community ships Noop). So the
+        // detector is a deliberate no-op, not a forgotten wire: content detection is
+        // the ATR engine (evaluateToolCall/evaluateToolResponse) and session
+        // escalation is the sync riskStore path above. Wiring the behavioral brain +
+        // active containment is a Pro-tier layer, tracked separately.
         this.riskStore = new InMemoryRiskStore();
         this.guard = new GuardGate({
             gate: new InlineGate(),
@@ -149,7 +158,11 @@ export class MCPProxy {
      * cannot lock out a legitimate agent.
      */
     recordEvalVerdict(verdict) {
-        if (verdict.outcome === 'deny' && verdict.confidence >= MCPProxy.ESCALATE_CONFIDENCE) {
+        // Normalize confidence to a 0-100 scale before the threshold check: the ATR
+        // engine reports match confidence on a 0-1 scale, so comparing it raw to a
+        // 0-100 threshold (95) made this escalation NEVER fire for a real deny.
+        const conf = verdict.confidence <= 1 ? verdict.confidence * 100 : verdict.confidence;
+        if (verdict.outcome === 'deny' && conf >= MCPProxy.ESCALATE_CONFIDENCE) {
             this.riskStore.set(this.sessionId, { level: 'high', reasons: [...verdict.matchedRules] });
         }
     }
@@ -238,11 +251,17 @@ export class MCPProxy {
                     ],
                 };
             }
-            // PreToolUse: evaluate the call
+            // PreToolUse: evaluate the call as a 'tool_call' event so the full
+            // tool_call rule family (shell injection, SSRF, SQLi, credential theft,
+            // privilege escalation, tool poisoning) runs — an MCP tool call carries
+            // exactly those payloads in its args. Via the engine's mcp-over-tool
+            // exception this is a superset of the mcp_exchange rules, so nothing that
+            // 'mcp_exchange' caught is lost. (The old default silently skipped ~44
+            // tool_call rules on every MCP call.)
             let preResult;
             try {
                 preResult = await Promise.race([
-                    this.evaluator.evaluateToolCall(name, toolArgs),
+                    this.evaluator.evaluateToolCall(name, toolArgs, 'tool_call'),
                     new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), this.evalTimeout)),
                 ]);
             }
@@ -287,11 +306,25 @@ export class MCPProxy {
             }
             // Forward to upstream
             const result = await client.callTool({ name, arguments: toolArgs });
-            // PostToolUse: evaluate the response
+            // PostToolUse: evaluate the response. Serialize EVERY content block —
+            // text AND non-text (resource URIs, embedded resource.text/blob, image
+            // data) — so a malicious server cannot smuggle an exfil/injection payload
+            // through a resource/image block that a text-only extractor would silently
+            // drop. Cap is 256KB (not 10KB) so padding the payload past a tiny cap no
+            // longer evades the scan.
             const responseText = result.content
-                ?.map((c) => c.text ?? '')
+                ?.map((c) => {
+                if (typeof c['text'] === 'string')
+                    return c['text'];
+                try {
+                    return JSON.stringify(c);
+                }
+                catch {
+                    return '';
+                }
+            })
                 .join('\n')
-                .slice(0, 10000); // Cap at 10KB for evaluation
+                .slice(0, 262144);
             if (responseText) {
                 let postResult;
                 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panguard-ai/panguard-mcp-proxy",
-  "version": "1.7.3",
+  "version": "1.8.0",
   "description": "MCP Proxy — runtime interception for AI agent tool calls using ATR rules",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,13 +20,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "agent-threat-rules": "^3.5.0",
-    "@panguard-ai/atr": "1.7.3",
+    "agent-threat-rules": "^3.5.6",
+    "@panguard-ai/panguard-guard": "1.8.0",
     "@panguard-ai/containment": "0.1.0",
-    "@panguard-ai/panguard-guard": "1.7.3"
+    "@panguard-ai/atr": "1.8.0"
   },
   "peerDependencies": {
-    "@panguard-ai/atr": "1.7.3"
+    "@panguard-ai/atr": "1.8.0"
   },
   "files": [
     "dist",
@@ -34,6 +34,14 @@
     "README.md",
     "LICENSE"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/panguard-ai/panguard-ai.git",
+    "directory": "packages/panguard-mcp-proxy"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "access": "public"
   },