@panguard-ai/panguard-mcp-proxy 1.5.6 → 1.6.1

package/dist/proxy.d.ts

@@ -11,6 +11,9 @@
  *
  * @module @panguard-ai/panguard-mcp-proxy/proxy
  */
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { EvalResult } from './evaluator.js';
+import type { McpGateVerdict } from '@panguard-ai/containment';
 export interface ProxyConfig {
     /** Command to start the upstream MCP server */
     readonly upstreamCommand: string;
@@ -21,6 +24,12 @@ export interface ProxyConfig {
     /** Fail mode: 'closed' blocks on error (safer), 'open' allows on error (default for availability) */
     readonly failMode?: 'open' | 'closed';
 }
+/** 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>;
+    evaluateToolResponse(toolName: string, response: string): Promise<EvalResult>;
+}
 export declare class MCPProxy {
     private readonly config;
     private readonly evaluator;
@@ -28,7 +37,44 @@ export declare class MCPProxy {
     private server;
     private readonly evalTimeout;
     private readonly failMode;
-    constructor(config: ProxyConfig);
+    /** Layer 1 inline gate. The ProxyEvaluator stays the Layer 2 brain. */
+    private readonly guard;
+    /** Session risk: the brain (evaluator verdicts) writes, the inline gate reads. */
+    private readonly riskStore;
+    /** Confidence at/above which an evaluator deny escalates the whole session. */
+    private static readonly ESCALATE_CONFIDENCE;
+    /** One stdio session per proxy process. */
+    private readonly sessionId;
+    /** Upstream tool names = the Layer 0 capability scope (populated in start()). */
+    private upstreamToolNames;
+    constructor(config: ProxyConfig, deps?: {
+        evaluator?: ProxyEvaluatorLike;
+    });
     start(): Promise<void>;
+    /**
+     * Wire the proxy between an upstream (client) transport and an agent (server)
+     * transport. Extracted from start() so tests can drive the full flow over
+     * in-memory transports without spawning a process.
+     */
+    connect(upstreamTransport: Transport, agentTransport: Transport): Promise<void>;
+    /**
+     * Run the Layer 1 inline gate for a tool call (sync, sub-ms): build the
+     * ActionContext and apply the gate. Capabilities default to the upstream tool
+     * set (Layer 0 scope); when unknown, the requested tool is allowed so the gate
+     * only adds block-on-sight + risk gating. Exposed so the wiring is testable.
+     */
+    gateCheck(name: string, toolArgs: Record<string, unknown>): McpGateVerdict;
+    /**
+     * Feed an async-evaluator verdict back into session risk — the dual-path
+     * loop. A high-confidence deny escalates the session so the inline gate
+     * fast-blocks subsequent calls without re-evaluating. The threshold is
+     * deliberately high (ATR precision is ~99.6%) so a single false positive
+     * cannot lock out a legitimate agent.
+     */
+    recordEvalVerdict(verdict: {
+        outcome: string;
+        confidence: number;
+        matchedRules: readonly string[];
+    }): void;
     private registerHandlers;
 }

package/dist/proxy.js

@@ -20,6 +20,7 @@ import { appendFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { ProxyEvaluator } from './evaluator.js';
+import { GuardGate, InlineGate, RiskAnalyzer, InMemoryRiskStore, NoopContainmentController, applyMcpGate, } from '@panguard-ai/containment';
 const VERDICT_LOG = join(homedir(), '.panguard-guard', 'proxy-verdicts.jsonl');
 function logVerdict(entry) {
     try {
@@ -37,33 +38,100 @@ export class MCPProxy {
     server = null;
     evalTimeout;
     failMode;
-    constructor(config) {
+    /** Layer 1 inline gate. The ProxyEvaluator stays the Layer 2 brain. */
+    guard;
+    /** Session risk: the brain (evaluator verdicts) writes, the inline gate reads. */
+    riskStore;
+    /** Confidence at/above which an evaluator deny escalates the whole session. */
+    static ESCALATE_CONFIDENCE = 95;
+    /** One stdio session per proxy process. */
+    sessionId = 'mcp-proxy-session';
+    /** Upstream tool names = the Layer 0 capability scope (populated in start()). */
+    upstreamToolNames = new Set();
+    constructor(config, deps = {}) {
         this.config = config;
-        this.evaluator = new ProxyEvaluator();
-        this.failMode = config.failMode ?? 'closed';
+        this.evaluator = deps.evaluator ?? new ProxyEvaluator();
+        // Fail-OPEN by default: PanGuard must never become the failure point in the
+        // agent's hot path. If the async evaluator times out or errors (e.g. rules
+        // still loading on cold start), the tool call proceeds — the sync pre-check
+        // (GuardGate, below) still blocks the worst payloads instantly regardless of
+        // this mode. Opt into 'closed' only for high-assurance deployments that
+        // accept blocking the agent when the evaluator is unavailable.
+        this.failMode = config.failMode ?? 'open';
         this.evalTimeout = config.evalTimeout ?? 5000;
+        // 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 — even
+        // if the async evaluator times out fail-open.
+        this.riskStore = new InMemoryRiskStore();
+        this.guard = new GuardGate({
+            gate: new InlineGate(),
+            analyzer: new RiskAnalyzer({ detect: () => [] }),
+            riskStore: this.riskStore,
+            containment: new NoopContainmentController(),
+        });
     }
     async start() {
-        // Load ATR rules
-        const ruleCount = await this.evaluator.loadRules();
-        process.stderr.write(`[panguard-proxy] Loaded ${ruleCount} ATR rules\n`);
-        // Connect to upstream MCP server
         const upstreamTransport = new StdioClientTransport({
             command: this.config.upstreamCommand,
             args: [...this.config.upstreamArgs],
             stderr: 'pipe',
         });
+        const agentTransport = new StdioServerTransport();
+        await this.connect(upstreamTransport, agentTransport);
+    }
+    /**
+     * Wire the proxy between an upstream (client) transport and an agent (server)
+     * transport. Extracted from start() so tests can drive the full flow over
+     * in-memory transports without spawning a process.
+     */
+    async connect(upstreamTransport, agentTransport) {
+        const ruleCount = await this.evaluator.loadRules();
+        process.stderr.write(`[panguard-proxy] Loaded ${ruleCount} ATR rules\n`);
         this.client = new Client({ name: 'panguard-mcp-proxy', version: '0.1.0' }, { capabilities: {} });
         await this.client.connect(upstreamTransport);
-        process.stderr.write(`[panguard-proxy] Connected to upstream: ${this.config.upstreamCommand}\n`);
-        // Create proxy server facing the agent
+        process.stderr.write(`[panguard-proxy] Connected to upstream\n`);
+        // Cache upstream tool names as the Layer 0 capability scope: an agent may
+        // only call tools the upstream actually exposes. Best-effort — if the list
+        // can't be fetched, the gate falls back to allowing the requested tool.
+        try {
+            const upstream = await this.client.listTools();
+            this.upstreamToolNames = new Set(upstream.tools.map((t) => t.name));
+        }
+        catch {
+            /* leave empty; per-call fallback allows the requested tool */
+        }
         this.server = new Server({ name: 'panguard-mcp-proxy', version: '0.1.0' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
         this.registerHandlers();
-        // Connect to agent via stdio
-        const agentTransport = new StdioServerTransport();
         await this.server.connect(agentTransport);
         process.stderr.write(`[panguard-proxy] Proxy active. ${ruleCount} rules protecting all tool calls.\n`);
     }
+    /**
+     * Run the Layer 1 inline gate for a tool call (sync, sub-ms): build the
+     * ActionContext and apply the gate. Capabilities default to the upstream tool
+     * set (Layer 0 scope); when unknown, the requested tool is allowed so the gate
+     * only adds block-on-sight + risk gating. Exposed so the wiring is testable.
+     */
+    gateCheck(name, toolArgs) {
+        return applyMcpGate(this.guard, {
+            name,
+            args: toolArgs,
+            sessionId: this.sessionId,
+            agentId: 'mcp-agent',
+            capabilities: this.upstreamToolNames.size > 0 ? this.upstreamToolNames : new Set([name]),
+        });
+    }
+    /**
+     * Feed an async-evaluator verdict back into session risk — the dual-path
+     * loop. A high-confidence deny escalates the session so the inline gate
+     * fast-blocks subsequent calls without re-evaluating. The threshold is
+     * deliberately high (ATR precision is ~99.6%) so a single false positive
+     * cannot lock out a legitimate agent.
+     */
+    recordEvalVerdict(verdict) {
+        if (verdict.outcome === 'deny' && verdict.confidence >= MCPProxy.ESCALATE_CONFIDENCE) {
+            this.riskStore.set(this.sessionId, { level: 'high', reasons: [...verdict.matchedRules] });
+        }
+    }
     registerHandlers() {
         const client = this.client;
         const server = this.server;
@@ -76,6 +144,27 @@ export class MCPProxy {
         server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
             const toolArgs = (args ?? {});
+            // Layer 1 inline gate (sync, sub-ms) — runs BEFORE the async evaluator so
+            // the worst payloads (and any session the brain has flagged) are blocked
+            // instantly, even if the async evaluator times out fail-open.
+            const gateVerdict = this.gateCheck(name, toolArgs);
+            if (!gateVerdict.allow) {
+                logVerdict({
+                    phase: 'pre-gate',
+                    tool: name,
+                    outcome: 'deny',
+                    reason: gateVerdict.reason ?? '',
+                });
+                process.stderr.write(`[panguard-proxy] BLOCKED (inline gate): ${name} — ${gateVerdict.reason}\n`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `[BLOCKED by PanGuard] Tool call "${name}" was blocked.\nReason: ${gateVerdict.reason}`,
+                        },
+                    ],
+                };
+            }
             // PreToolUse: evaluate the call
             let preResult;
             try {
@@ -103,6 +192,8 @@ export class MCPProxy {
                 rules: preResult.matchedRules,
                 ms: preResult.durationMs,
             });
+            // Close the dual-path loop: a high-confidence deny escalates the session.
+            this.recordEvalVerdict(preResult);
             if (preResult.outcome === 'deny') {
                 process.stderr.write(`[panguard-proxy] BLOCKED: ${name} — ${preResult.reason}\n`);
                 return {
@@ -147,6 +238,7 @@ export class MCPProxy {
                     rules: postResult.matchedRules,
                     ms: postResult.durationMs,
                 });
+                this.recordEvalVerdict(postResult);
                 if (postResult.outcome === 'deny') {
                     process.stderr.write(`[panguard-proxy] BLOCKED response: ${name} — ${postResult.reason}\n`);
                     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panguard-ai/panguard-mcp-proxy",
-  "version": "1.5.6",
+  "version": "1.6.1",
   "description": "MCP Proxy — runtime interception for AI agent tool calls using ATR rules",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,11 +10,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "agent-threat-rules": "^2.1.1",
-    "@panguard-ai/atr": "1.5.6"
+    "agent-threat-rules": "^3.4.0",
+    "@panguard-ai/containment": "0.1.0",
+    "@panguard-ai/atr": "1.6.1"
   },
   "peerDependencies": {
-    "@panguard-ai/atr": "1.5.6"
+    "@panguard-ai/atr": "1.6.1"
   },
   "files": [
     "dist",
@@ -27,6 +28,7 @@
   "license": "MIT",
   "scripts": {
     "build": "tsc",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
   }
 }