@panguard-ai/panguard-mcp-proxy 1.8.3 → 1.8.5

package/dist/evaluator.d.ts

@@ -13,7 +13,26 @@ export interface EvalResult {
     readonly matchedRules: readonly string[];
     readonly confidence: number;
     readonly durationMs: number;
+    /**
+     * Gap A slice 2: true when a non-'allow' outcome is driven ONLY by advise-only
+     * (fresh, untrusted auto-pulled) rules — i.e. no bundled/trusted rule justifies
+     * it. A caller MUST NOT escalate such an outcome to a hard block (even under an
+     * enforce posture), so a fresh rule can never wall off a tool call until the
+     * user trusts it. Always false for 'deny' (deny only ever comes from a trusted
+     * rule) and for 'allow'.
+     */
+    readonly adviseOnly: boolean;
 }
+/**
+ * The synthetic matchedRules id the evaluator emits when its OWN evaluation
+ * throws (a fail-closed 'deny' produced by the catch below, NOT a real rule
+ * match). Exported as the single source of truth so the tool-call hook can
+ * detect an engine crash and fail OPEN (never brick the agent) instead of
+ * treating it as a real block — see panguard/cli/commands/hook.ts. Keep the two
+ * sides coupled through THIS constant, never a bare string, so a rename can't
+ * silently break the fail-open contract.
+ */
+export declare const EVALUATION_ERROR_SENTINEL = "evaluation-error";
 /** Minimal rule shape the deny policy needs. */
 interface RuleLike {
     readonly severity: string;
@@ -42,6 +61,15 @@ export declare class ProxyEvaluator {
     private readonly engine;
     private rulesLoaded;
     private ruleCount;
+    /**
+     * Gap A slice 2: IDs of auto-pulled rules that are ADVISE-ONLY — loaded fresh
+     * from a not-yet-trusted bundle. They may surface an 'ask' advisory but are
+     * EXCLUDED from the hard-deny decision, so a fresh rule can never silently
+     * block the user's tool. Once the user trusts the bundle version, the hook
+     * loads them with adviseOnly=false and they are absent from this set (i.e.
+     * they arm). Bundled/shipped rules are never in this set.
+     */
+    private readonly adviseOnlyIds;
     private blockedTools;
     private readonly blocklistPath;
     private blocklistMtime;
@@ -50,7 +78,21 @@ export declare class ProxyEvaluator {
     /** Reload blocklist from disk if modified (called before each evaluation) */
     private refreshBlocklist;
     loadRules(): Promise<number>;
+    /**
+     * Gap A slice 2: merge auto-pulled rules (staged + integrity-verified by the
+     * daemon) into the engine. ONLY rules whose id is not already bundled are
+     * added — a newer bundle re-ships existing ids, and those stay as their trusted
+     * bundled copy. `adviseOnly` marks the fresh ids so evaluate() lets them advise
+     * but never hard-deny (see adviseOnlyIds). Best-effort: a failure here must
+     * never break the enforce path, so it is caught and the proxy keeps running on
+     * the bundled ruleset alone. Returns the number of fresh rules added.
+     */
+    loadAutoRules(rulesDir: string, opts: {
+        adviseOnly: boolean;
+    }): Promise<number>;
     getRuleCount(): number;
+    /** Number of auto-pulled rules currently held advise-only (not yet trusted). */
+    getAdviseOnlyCount(): number;
     /** Flatten args into a readable string for ATR regex matching */
     private flattenArgs;
     /**

package/dist/evaluator.js

@@ -28,6 +28,16 @@ function findRulesDir() {
     }
     throw new Error('Cannot find ATR rules directory. Install agent-threat-rules.');
 }
+/**
+ * The synthetic matchedRules id the evaluator emits when its OWN evaluation
+ * throws (a fail-closed 'deny' produced by the catch below, NOT a real rule
+ * match). Exported as the single source of truth so the tool-call hook can
+ * detect an engine crash and fail OPEN (never brick the agent) instead of
+ * treating it as a real block — see panguard/cli/commands/hook.ts. Keep the two
+ * sides coupled through THIS constant, never a bare string, so a rename can't
+ * silently break the fail-open contract.
+ */
+export const EVALUATION_ERROR_SENTINEL = 'evaluation-error';
 /**
  * Whether a single rule match is strong enough to HARD-DENY a live tool call
  * (vs. degrade to 'ask'). This is the proxy's false-positive control point: the
@@ -56,6 +66,15 @@ export class ProxyEvaluator {
     engine;
     rulesLoaded = false;
     ruleCount = 0;
+    /**
+     * Gap A slice 2: IDs of auto-pulled rules that are ADVISE-ONLY — loaded fresh
+     * from a not-yet-trusted bundle. They may surface an 'ask' advisory but are
+     * EXCLUDED from the hard-deny decision, so a fresh rule can never silently
+     * block the user's tool. Once the user trusts the bundle version, the hook
+     * loads them with adviseOnly=false and they are absent from this set (i.e.
+     * they arm). Bundled/shipped rules are never in this set.
+     */
+    adviseOnlyIds = new Set();
     blockedTools = new Set();
     blocklistPath;
     blocklistMtime = 0;
@@ -110,9 +129,46 @@ export class ProxyEvaluator {
         }
         return this.ruleCount;
     }
+    /**
+     * Gap A slice 2: merge auto-pulled rules (staged + integrity-verified by the
+     * daemon) into the engine. ONLY rules whose id is not already bundled are
+     * added — a newer bundle re-ships existing ids, and those stay as their trusted
+     * bundled copy. `adviseOnly` marks the fresh ids so evaluate() lets them advise
+     * but never hard-deny (see adviseOnlyIds). Best-effort: a failure here must
+     * never break the enforce path, so it is caught and the proxy keeps running on
+     * the bundled ruleset alone. Returns the number of fresh rules added.
+     */
+    async loadAutoRules(rulesDir, opts) {
+        try {
+            if (!existsSync(rulesDir))
+                return 0;
+            const existing = new Set(this.engine.getRules().map((r) => r.id));
+            const sub = new ATREngine({ rulesDir });
+            await sub.loadRules();
+            let added = 0;
+            for (const rule of sub.getRules()) {
+                if (existing.has(rule.id))
+                    continue; // already have this id from the bundled set
+                this.engine.addRule(rule);
+                if (opts.adviseOnly)
+                    this.adviseOnlyIds.add(rule.id);
+                added++;
+            }
+            this.ruleCount += added;
+            return added;
+        }
+        catch (err) {
+            process.stderr.write(`[panguard-proxy] auto-rules load skipped (ignored, bundled rules unaffected): ${err instanceof Error ? err.message : String(err)}\n`);
+            return 0;
+        }
+    }
     getRuleCount() {
         return this.ruleCount;
     }
+    /** Number of auto-pulled rules currently held advise-only (not yet trusted). */
+    getAdviseOnlyCount() {
+        return this.adviseOnlyIds.size;
+    }
     /** Flatten args into a readable string for ATR regex matching */
     flattenArgs(args) {
         const parts = [];
@@ -147,6 +203,7 @@ export class ProxyEvaluator {
                 matchedRules: ['guard-blocklist'],
                 confidence: 100,
                 durationMs: Date.now() - start,
+                adviseOnly: false,
             };
         }
         // Flatten args into natural text so ATR regexes can match content like paths and commands
@@ -205,21 +262,50 @@ export class ProxyEvaluator {
                     matchedRules: [],
                     confidence: 0,
                     durationMs,
+                    adviseOnly: false,
                 };
             }
-            // Hard-DENY only on a trusted match (see shouldHardDeny); every other
-            // match is still surfaced as 'ask' (user-in-the-loop), never silently
-            // allowed. This is the proxy's false-positive control point — the engine
-            // runs full 'hunt' detection so nothing is missed.
-            const blockMatch = matches.find((m) => shouldHardDeny(m.rule));
-            const outcome = blockMatch ? 'deny' : 'ask';
-            const topMatch = blockMatch ?? matches[0];
+            // FALSE-POSITIVE CONTROL POINT (this is a SYNCHRONOUS per-tool-call gate).
+            //  1. Hard-DENY on a trusted match (shouldHardDeny: critical, or high+stable).
+            //  2. Otherwise surface an 'ask' advisory ONLY for a high-severity match —
+            //     something serious enough to warrant a per-call heads-up even if
+            //     unproven.
+            //  3. Medium/low matches are demoted to a SILENT allow here. The engine
+            //     runs full 'hunt' detection, and many broad rules (e.g. keyword-
+            //     presence rules that fire on any `curl`/`rm`/`env`, severity=medium,
+            //     condition:any) would otherwise spam an advisory on routine tool calls
+            //     — the dominant false-positive source. Their matches are still
+            //     returned in matchedRules and the async daemon path keeps them for
+            //     offline review; we just do not raise a per-call advisory/block on an
+            //     unactionable low-severity broad match. Real attacks are
+            //     critical/high-stable and hard-deny at step 1, so are unaffected.
+            // Gap A slice 2: an advise-only auto-pulled rule (fresh, not yet trusted)
+            // is EXCLUDED from the hard-deny decision — it can still surface as an
+            // 'ask' advisory below, but it can never silently block the user's tool.
+            // Bundled/trusted rules are unaffected. This is the arm gate for the
+            // enforce path.
+            const blockMatch = matches.find((m) => shouldHardDeny(m.rule) && !this.adviseOnlyIds.has(m.rule.id));
+            const askMatch = blockMatch ??
+                matches.find((m) => m.rule.severity === 'high' || m.rule.severity === 'critical');
+            const outcome = blockMatch ? 'deny' : askMatch ? 'ask' : 'allow';
+            const topMatch = blockMatch ?? askMatch ?? matches[0];
+            // An 'ask' is advise-only-driven when NO trusted (non-advise-only)
+            // high/critical rule justifies it — i.e. the only rules asking for
+            // attention are fresh, untrusted auto-pulled ones. The caller must not
+            // escalate such an 'ask' to a block. A 'deny' is never advise-only (the
+            // block gate above already excluded advise-only rules).
+            const adviseOnly = outcome === 'ask' &&
+                !matches.some((m) => (m.rule.severity === 'high' || m.rule.severity === 'critical') &&
+                    !this.adviseOnlyIds.has(m.rule.id));
             return {
                 outcome,
-                reason: `${topMatch.rule.title} (${topMatch.rule.severity})`,
+                reason: outcome === 'allow'
+                    ? `No actionable threat (low-severity match suppressed: ${topMatch.rule.title}, ${topMatch.rule.severity})`
+                    : `${topMatch.rule.title} (${topMatch.rule.severity})`,
                 matchedRules: matches.map((m) => m.rule.id),
-                confidence: topMatch.confidence,
+                confidence: outcome === 'allow' ? 0 : topMatch.confidence,
                 durationMs,
+                adviseOnly,
             };
         }
         catch (err) {
@@ -228,9 +314,10 @@ export class ProxyEvaluator {
             return {
                 outcome: 'deny',
                 reason: 'Evaluation error (fail-closed for safety)',
-                matchedRules: ['evaluation-error'],
+                matchedRules: [EVALUATION_ERROR_SENTINEL],
                 confidence: 100,
                 durationMs: Date.now() - start,
+                adviseOnly: false,
             };
         }
     }

package/dist/proxy.js

@@ -398,6 +398,7 @@ export class MCPProxy {
                     matchedRules: [],
                     confidence: 0,
                     durationMs: this.evalTimeout,
+                    adviseOnly: false,
                 };
             }
             this.logVerdict({
@@ -465,6 +466,7 @@ export class MCPProxy {
                         matchedRules: [],
                         confidence: 0,
                         durationMs: this.evalTimeout,
+                        adviseOnly: false,
                     };
                 }
                 this.logVerdict({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panguard-ai/panguard-mcp-proxy",
-  "version": "1.8.3",
+  "version": "1.8.5",
   "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.6",
-    "@panguard-ai/atr": "1.8.3",
-    "@panguard-ai/panguard-guard": "1.8.3",
-    "@panguard-ai/containment": "0.1.0"
+    "agent-threat-rules": "^3.5.8",
+    "@panguard-ai/atr": "1.8.5",
+    "@panguard-ai/containment": "0.1.0",
+    "@panguard-ai/panguard-guard": "1.8.5"
   },
   "peerDependencies": {
-    "@panguard-ai/atr": "1.8.3"
+    "@panguard-ai/atr": "1.8.5"
   },
   "files": [
     "dist",