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

package/dist/evaluator.d.ts

@@ -68,7 +68,25 @@ export declare class ProxyEvaluator {
      * 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) */
+    /**
+     * Evaluate a tool response (PostToolUse) — the indirect-prompt-injection path.
+     *
+     * The event MUST be typed 'tool_response' (NOT 'mcp_exchange'). A poisoned MCP /
+     * tool / RAG output is where indirect prompt injection rides in, and the ATR
+     * engine handles that case only for a 'tool_response'-typed event:
+     *   1. EVENT_TYPE_TO_SOURCE['tool_response'] === 'mcp_exchange', which fires the
+     *      engine's llmIoOverToolResponse exception so the whole llm_io family
+     *      (system-prompt-override, SSRF-via-URL, SQLi-in-natural-language,
+     *      shell-injection) is allowed to run against the response.
+     *   2. getFieldValue() routes event.content into the user_input / agent_output
+     *      fields ONLY when event.type === 'tool_response'. The ~200 llm_io rules
+     *      that target user_input/agent_output therefore see the response text and
+     *      can match.
+     * Passing 'mcp_exchange' (the old value) is NOT a key in EVENT_TYPE_TO_SOURCE, so
+     * eventSourceType is undefined: the source-type filter is bypassed (llm_io rules
+     * run) but getFieldValue leaves user_input/agent_output undefined, so those rules
+     * silently match nothing — defeating the entire indirect-injection scan.
+     */
     evaluateToolResponse(toolName: string, response: string): Promise<EvalResult>;
     private evaluate;
 }

package/dist/evaluator.js

@@ -162,11 +162,29 @@ export class ProxyEvaluator {
         };
         return this.evaluate(event, start);
     }
-    /** Evaluate a tool response (PostToolUse) */
+    /**
+     * Evaluate a tool response (PostToolUse) — the indirect-prompt-injection path.
+     *
+     * The event MUST be typed 'tool_response' (NOT 'mcp_exchange'). A poisoned MCP /
+     * tool / RAG output is where indirect prompt injection rides in, and the ATR
+     * engine handles that case only for a 'tool_response'-typed event:
+     *   1. EVENT_TYPE_TO_SOURCE['tool_response'] === 'mcp_exchange', which fires the
+     *      engine's llmIoOverToolResponse exception so the whole llm_io family
+     *      (system-prompt-override, SSRF-via-URL, SQLi-in-natural-language,
+     *      shell-injection) is allowed to run against the response.
+     *   2. getFieldValue() routes event.content into the user_input / agent_output
+     *      fields ONLY when event.type === 'tool_response'. The ~200 llm_io rules
+     *      that target user_input/agent_output therefore see the response text and
+     *      can match.
+     * Passing 'mcp_exchange' (the old value) is NOT a key in EVENT_TYPE_TO_SOURCE, so
+     * eventSourceType is undefined: the source-type filter is bypassed (llm_io rules
+     * run) but getFieldValue leaves user_input/agent_output undefined, so those rules
+     * silently match nothing — defeating the entire indirect-injection scan.
+     */
     async evaluateToolResponse(toolName, response) {
         const start = Date.now();
         const event = {
-            type: 'mcp_exchange',
+            type: 'tool_response',
             timestamp: new Date().toISOString(),
             content: response,
             fields: {

package/dist/proxy.d.ts

@@ -48,6 +48,12 @@ export declare class MCPProxy {
     private readonly riskStore;
     /** Confidence at/above which an evaluator deny escalates the whole session. */
     private static readonly ESCALATE_CONFIDENCE;
+    /** Max background attempts to re-fetch the tool list after a listTools() failure. */
+    private static readonly SCOPE_RETRY_MAX;
+    /** Base backoff (ms) for the exponential scope re-fetch retry (capped). */
+    private static readonly SCOPE_RETRY_BASE_MS;
+    /** Ceiling (ms) for the exponential scope re-fetch backoff. */
+    private static readonly SCOPE_RETRY_MAX_MS;
     /**
      * One stdio session per proxy process. Defaults to a per-process unique id
      * (not the old hardcoded constant) so verdict lines from distinct runs are
@@ -58,6 +64,19 @@ export declare class MCPProxy {
     private readonly agentId;
     /** Upstream tool names = the Layer 0 capability scope (populated in start()). */
     private upstreamToolNames;
+    /**
+     * True once listTools() succeeds (any count) → the scope is KNOWN. False means
+     * the list has not been fetched or the fetch FAILED → scope unknown (degraded,
+     * fail-open by tool name). A known-but-empty scope is resolved=true with an
+     * empty set, which DENIES every call — not the same as unresolved.
+     */
+    private capabilityScopeResolved;
+    /** One-shot throttle so the per-call degraded warning does not spam stderr. */
+    private warnedScopeDegraded;
+    /** Count of background scope re-fetch attempts made after a listTools() failure. */
+    private scopeRetryAttempts;
+    /** True while a background scope re-fetch is in flight (prevents pile-up). */
+    private scopeRetryInFlight;
     /** Tamper-evident chain over proxy-verdicts.jsonl (lazily keyed in connect()). */
     private chain;
     constructor(config: ProxyConfig, deps?: {
@@ -70,11 +89,30 @@ export declare class MCPProxy {
      * in-memory transports without spawning a process.
      */
     connect(upstreamTransport: Transport, agentTransport: Transport): Promise<void>;
+    /**
+     * Fetch the upstream tool list and cache it as the Layer 0 capability scope.
+     * Returns true on success (scope RESOLVED, regardless of count — a successful
+     * empty list is a known-empty scope that DENIES every call), false if
+     * listTools() throws (scope left UNRESOLVED). Never throws. Shared by connect()
+     * and the background retry so both paths update the scope identically.
+     */
+    private resolveCapabilityScope;
+    /**
+     * Schedule a bounded, exponential-backoff background re-fetch of the tool list
+     * so a transient listTools() failure self-heals instead of latching a degraded
+     * capability scope for the whole proxy lifetime. Fire-and-forget (never blocks a
+     * tool call); at most one attempt is in flight at a time and total attempts are
+     * capped by SCOPE_RETRY_MAX.
+     */
+    private scheduleScopeRetry;
+    /** Execute one background scope re-fetch attempt, then reschedule if needed. */
+    private runScopeRetry;
     /**
      * 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.
+     * set (Layer 0 scope); when the scope is unresolved the fallback honors
+     * this.failMode — fail-CLOSED (default) DENIES, fail-open allows by name.
+     * Exposed so the wiring is testable.
      */
     gateCheck(name: string, toolArgs: Record<string, unknown>): McpGateVerdict;
     /**

package/dist/proxy.js

@@ -36,6 +36,12 @@ export class MCPProxy {
     riskStore;
     /** Confidence at/above which an evaluator deny escalates the whole session. */
     static ESCALATE_CONFIDENCE = 95;
+    /** Max background attempts to re-fetch the tool list after a listTools() failure. */
+    static SCOPE_RETRY_MAX = 5;
+    /** Base backoff (ms) for the exponential scope re-fetch retry (capped). */
+    static SCOPE_RETRY_BASE_MS = 500;
+    /** Ceiling (ms) for the exponential scope re-fetch backoff. */
+    static SCOPE_RETRY_MAX_MS = 30_000;
     /**
      * One stdio session per proxy process. Defaults to a per-process unique id
      * (not the old hardcoded constant) so verdict lines from distinct runs are
@@ -46,6 +52,19 @@ export class MCPProxy {
     agentId;
     /** Upstream tool names = the Layer 0 capability scope (populated in start()). */
     upstreamToolNames = new Set();
+    /**
+     * True once listTools() succeeds (any count) → the scope is KNOWN. False means
+     * the list has not been fetched or the fetch FAILED → scope unknown (degraded,
+     * fail-open by tool name). A known-but-empty scope is resolved=true with an
+     * empty set, which DENIES every call — not the same as unresolved.
+     */
+    capabilityScopeResolved = false;
+    /** One-shot throttle so the per-call degraded warning does not spam stderr. */
+    warnedScopeDegraded = false;
+    /** Count of background scope re-fetch attempts made after a listTools() failure. */
+    scopeRetryAttempts = 0;
+    /** True while a background scope re-fetch is in flight (prevents pile-up). */
+    scopeRetryInFlight = false;
     /** Tamper-evident chain over proxy-verdicts.jsonl (lazily keyed in connect()). */
     chain = null;
     constructor(config, deps = {}) {
@@ -109,14 +128,23 @@ export class MCPProxy {
         await this.client.connect(upstreamTransport);
         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 */
+        // only call tools the upstream actually exposes. If the list can't be fetched
+        // we do NOT latch a permanent fail-open: a bounded background retry re-tries
+        // the fetch (so a transient failure self-heals) and, until it resolves, the
+        // gate honors this.failMode — fail-CLOSED (the default) DENIES rather than
+        // waving unknown-scope calls through. See resolveCapabilityScope + gateCheck.
+        const resolved = await this.resolveCapabilityScope();
+        if (!resolved) {
+            // listTools failed → the Layer-0 capability scope is UNKNOWN (unresolved).
+            // Loudly flag it (a silent pass was indistinguishable from a real allow in
+            // logs) and start the background re-fetch so the scope can self-heal.
+            process.stderr.write(`[panguard-proxy] WARNING: upstream listTools() failed — Layer-0 capability-scope enforcement is DEGRADED. ` +
+                `Fail-mode='${this.failMode}': ` +
+                (this.failMode === 'closed'
+                    ? 'tool calls are DENIED until the scope resolves.'
+                    : 'tools are allowed by name (fail-open opt-in) until the scope resolves.') +
+                ' A bounded background retry is re-fetching the tool list.\n');
+            this.scheduleScopeRetry();
         }
         this.server = new Server({ name: 'panguard-mcp-proxy', version: '0.1.0' }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
         this.registerHandlers();
@@ -135,19 +163,115 @@ export class MCPProxy {
         // "FLAGGED (ask)". Document it here so operators know flagged calls still run.
         process.stderr.write("[panguard-proxy] Note: 'ask' verdicts are logged-and-forwarded (no MCP user prompt); watch stderr for FLAGGED (ask) lines.\n");
     }
+    /**
+     * Fetch the upstream tool list and cache it as the Layer 0 capability scope.
+     * Returns true on success (scope RESOLVED, regardless of count — a successful
+     * empty list is a known-empty scope that DENIES every call), false if
+     * listTools() throws (scope left UNRESOLVED). Never throws. Shared by connect()
+     * and the background retry so both paths update the scope identically.
+     */
+    async resolveCapabilityScope() {
+        if (!this.client)
+            return false;
+        try {
+            const upstream = await this.client.listTools();
+            this.upstreamToolNames = new Set(upstream.tools.map((t) => t.name));
+            this.capabilityScopeResolved = true;
+            // Reset the degraded-warning throttle so a later re-failure warns again.
+            this.warnedScopeDegraded = false;
+            return true;
+        }
+        catch {
+            this.capabilityScopeResolved = false;
+            return false;
+        }
+    }
+    /**
+     * Schedule a bounded, exponential-backoff background re-fetch of the tool list
+     * so a transient listTools() failure self-heals instead of latching a degraded
+     * capability scope for the whole proxy lifetime. Fire-and-forget (never blocks a
+     * tool call); at most one attempt is in flight at a time and total attempts are
+     * capped by SCOPE_RETRY_MAX.
+     */
+    scheduleScopeRetry() {
+        if (this.capabilityScopeResolved || this.scopeRetryInFlight)
+            return;
+        if (this.scopeRetryAttempts >= MCPProxy.SCOPE_RETRY_MAX)
+            return;
+        this.scopeRetryInFlight = true;
+        const attempt = this.scopeRetryAttempts;
+        const delay = Math.min(MCPProxy.SCOPE_RETRY_BASE_MS * 2 ** attempt, MCPProxy.SCOPE_RETRY_MAX_MS);
+        const timer = setTimeout(() => {
+            void this.runScopeRetry();
+        }, delay);
+        // Do not keep the event loop alive solely for this retry timer.
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    }
+    /** Execute one background scope re-fetch attempt, then reschedule if needed. */
+    async runScopeRetry() {
+        this.scopeRetryAttempts += 1;
+        const ok = await this.resolveCapabilityScope();
+        this.scopeRetryInFlight = false;
+        if (ok) {
+            process.stderr.write(`[panguard-proxy] Layer-0 capability scope RESOLVED after retry (${this.upstreamToolNames.size} tools); tool-scope enforcement restored.\n`);
+            return;
+        }
+        // Still failing — back off and try again until the attempt cap is reached.
+        this.scheduleScopeRetry();
+    }
     /**
      * 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.
+     * set (Layer 0 scope); when the scope is unresolved the fallback honors
+     * this.failMode — fail-CLOSED (default) DENIES, fail-open allows by name.
+     * Exposed so the wiring is testable.
      */
     gateCheck(name, toolArgs) {
+        // Decide the capability set from whether the scope is RESOLVED, never from
+        // its size — that was the bug: a successful-but-empty list looked identical
+        // to "no list yet" and fell through to a silent allow.
+        if (this.capabilityScopeResolved) {
+            // Known scope. If it is empty, the upstream exposes no tools, so every call
+            // is out-of-scope and applyMcpGate DENIES it. No fallback, no silent allow.
+            return applyMcpGate(this.guard, {
+                name,
+                args: toolArgs,
+                sessionId: this.sessionId,
+                agentId: this.agentId,
+                capabilities: this.upstreamToolNames,
+            });
+        }
+        // Unknown scope (listTools failed / not yet run). Nudge a bounded background
+        // re-fetch so a transient failure does not permanently disable tool-scope,
+        // then decide THIS call by failMode — never an unconditional fail-open.
+        this.scheduleScopeRetry();
+        if (!this.warnedScopeDegraded) {
+            this.warnedScopeDegraded = true;
+            process.stderr.write(`[panguard-proxy] scope-degraded: capability scope unresolved (fail-${this.failMode}) — ` +
+                (this.failMode === 'closed'
+                    ? `tools (starting with '${name}') are DENIED until the upstream tool list resolves.`
+                    : `tools (starting with '${name}') pass Layer-0 by name fallback (fail-open opt-in). Content rules still evaluate them; tool-scope is NOT enforced until the upstream tool list is available.`) +
+                '\n');
+        }
+        if (this.failMode === 'closed') {
+            // Fail-CLOSED default (security-first, mirrors the evaluator): an unknown
+            // capability scope must not wave calls through. Deny until it resolves.
+            return {
+                allow: false,
+                reason: 'Capability scope is unresolved (upstream tool list unavailable); denying under fail-closed policy. ' +
+                    'Set PANGUARD_PROXY_FAIL_MODE=open to allow tools by name while degraded.',
+                escalated: false,
+            };
+        }
+        // Fail-open opt-in: allow by name to preserve availability. This gap is
+        // capability-scope only; the inline content gate below still runs.
         return applyMcpGate(this.guard, {
             name,
             args: toolArgs,
             sessionId: this.sessionId,
             agentId: this.agentId,
-            capabilities: this.upstreamToolNames.size > 0 ? this.upstreamToolNames : new Set([name]),
+            capabilities: new Set([name]),
         });
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panguard-ai/panguard-mcp-proxy",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "MCP Proxy — runtime interception for AI agent tool calls using ATR rules",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,12 +21,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "agent-threat-rules": "^3.5.6",
-    "@panguard-ai/panguard-guard": "1.8.0",
+    "@panguard-ai/atr": "1.8.2",
     "@panguard-ai/containment": "0.1.0",
-    "@panguard-ai/atr": "1.8.0"
+    "@panguard-ai/panguard-guard": "1.8.2"
   },
   "peerDependencies": {
-    "@panguard-ai/atr": "1.8.0"
+    "@panguard-ai/atr": "1.8.2"
   },
   "files": [
     "dist",