@cdot65/prisma-airs 0.1.4 → 0.2.1

package/hooks/prisma-airs-tools/handler.ts

@@ -0,0 +1,279 @@
+/**
+ * Prisma AIRS Tool Gating (before_tool_call)
+ *
+ * Blocks dangerous tool calls when security warnings are active.
+ * CAN BLOCK via { block: true, blockReason: "..." }
+ */
+
+import { getCachedScanResult } from "../../src/scan-cache";
+import type { ScanResult } from "../../src/scanner";
+
+// Event shape from OpenClaw before_tool_call hook
+interface BeforeToolCallEvent {
+  toolName: string;
+  toolId?: string;
+  params?: Record<string, unknown>;
+}
+
+// Context passed to hook
+interface HookContext {
+  sessionKey?: string;
+  channelId?: string;
+  accountId?: string;
+  conversationId?: string;
+  cfg?: PluginConfig;
+}
+
+// Plugin config structure
+interface PluginConfig {
+  plugins?: {
+    entries?: {
+      "prisma-airs"?: {
+        config?: {
+          tool_gating_enabled?: boolean;
+          high_risk_tools?: string[];
+        };
+      };
+    };
+  };
+}
+
+// Hook result type
+interface HookResult {
+  params?: Record<string, unknown>;
+  block?: boolean;
+  blockReason?: string;
+}
+
+// Tool blocking rules by threat category
+const TOOL_BLOCKS: Record<string, string[]> = {
+  // AI Agent threats - block ALL external actions
+  "agent-threat": [
+    "exec",
+    "Bash",
+    "bash",
+    "write",
+    "Write",
+    "edit",
+    "Edit",
+    "gateway",
+    "message",
+    "cron",
+    "browser",
+    "web_fetch",
+    "WebFetch",
+    "database",
+    "query",
+    "sql",
+    "eval",
+    "NotebookEdit",
+  ],
+
+  // SQL/Database injection - block database and exec tools
+  "sql-injection": ["exec", "Bash", "bash", "database", "query", "sql", "eval"],
+  db_security: ["exec", "Bash", "bash", "database", "query", "sql", "eval"],
+  "db-security": ["exec", "Bash", "bash", "database", "query", "sql", "eval"],
+
+  // Malicious code - block code execution and file writes
+  "malicious-code": [
+    "exec",
+    "Bash",
+    "bash",
+    "write",
+    "Write",
+    "edit",
+    "Edit",
+    "eval",
+    "NotebookEdit",
+  ],
+  malicious_code: [
+    "exec",
+    "Bash",
+    "bash",
+    "write",
+    "Write",
+    "edit",
+    "Edit",
+    "eval",
+    "NotebookEdit",
+  ],
+
+  // Prompt injection - block sensitive tools
+  "prompt-injection": ["exec", "Bash", "bash", "gateway", "message", "cron"],
+  prompt_injection: ["exec", "Bash", "bash", "gateway", "message", "cron"],
+
+  // Malicious URLs - block web access
+  "malicious-url": ["web_fetch", "WebFetch", "browser", "Browser", "curl"],
+  malicious_url: ["web_fetch", "WebFetch", "browser", "Browser", "curl"],
+  url_filtering_prompt: ["web_fetch", "WebFetch", "browser", "Browser", "curl"],
+
+  // Scan failure - block high-risk tools
+  "scan-failure": [
+    "exec",
+    "Bash",
+    "bash",
+    "write",
+    "Write",
+    "edit",
+    "Edit",
+    "gateway",
+    "message",
+    "cron",
+  ],
+};
+
+// Default high-risk tools (blocked on any threat)
+const DEFAULT_HIGH_RISK_TOOLS = [
+  "exec",
+  "Bash",
+  "bash",
+  "write",
+  "Write",
+  "edit",
+  "Edit",
+  "gateway",
+  "message",
+  "cron",
+];
+
+/**
+ * Get plugin configuration
+ */
+function getPluginConfig(ctx: HookContext): {
+  enabled: boolean;
+  highRiskTools: string[];
+} {
+  const cfg = ctx.cfg?.plugins?.entries?.["prisma-airs"]?.config;
+  return {
+    enabled: cfg?.tool_gating_enabled !== false,
+    highRiskTools: cfg?.high_risk_tools ?? DEFAULT_HIGH_RISK_TOOLS,
+  };
+}
+
+/**
+ * Determine if a tool should be blocked based on scan result
+ */
+function shouldBlockTool(
+  toolName: string,
+  scanResult: ScanResult,
+  highRiskTools: string[]
+): { block: boolean; reason: string } {
+  // Collect all tools that should be blocked based on detected categories
+  const blockedTools = new Set<string>();
+
+  for (const category of scanResult.categories) {
+    const tools = TOOL_BLOCKS[category];
+    if (tools) {
+      tools.forEach((t) => blockedTools.add(t.toLowerCase()));
+    }
+  }
+
+  // Add high-risk tools if any threat was detected
+  const hasThreat =
+    scanResult.action === "block" ||
+    scanResult.action === "warn" ||
+    (scanResult.categories.length > 0 &&
+      !scanResult.categories.every((c) => c === "safe" || c === "benign"));
+
+  if (hasThreat) {
+    highRiskTools.forEach((t) => blockedTools.add(t.toLowerCase()));
+  }
+
+  // Check if this tool should be blocked
+  const toolLower = toolName.toLowerCase();
+  if (blockedTools.has(toolLower)) {
+    const threatCategories = scanResult.categories
+      .filter((c) => c !== "safe" && c !== "benign")
+      .join(", ");
+
+    return {
+      block: true,
+      reason:
+        `Tool '${toolName}' blocked due to security threat: ${threatCategories || "unknown"}. ` +
+        `Scan ID: ${scanResult.scanId || "N/A"}`,
+    };
+  }
+
+  return { block: false, reason: "" };
+}
+
+/**
+ * Main hook handler
+ */
+const handler = async (
+  event: BeforeToolCallEvent,
+  ctx: HookContext
+): Promise<HookResult | void> => {
+  const config = getPluginConfig(ctx);
+
+  // Check if tool gating is enabled
+  if (!config.enabled) {
+    return;
+  }
+
+  // Get tool name
+  const toolName = event.toolName;
+  if (!toolName) {
+    return;
+  }
+
+  // Build session key
+  const sessionKey = ctx.sessionKey || ctx.conversationId || "unknown";
+
+  // Get cached scan result from inbound scanning
+  const scanResult = getCachedScanResult(sessionKey);
+  if (!scanResult) {
+    return; // No scan result cached, allow through
+  }
+
+  // Check if result indicates a safe message
+  if (
+    scanResult.action === "allow" &&
+    (scanResult.severity === "SAFE" ||
+      scanResult.categories.every((c) => c === "safe" || c === "benign"))
+  ) {
+    return; // Safe, allow all tools
+  }
+
+  // Check if this tool should be blocked
+  const { block, reason } = shouldBlockTool(toolName, scanResult, config.highRiskTools);
+
+  if (block) {
+    console.log(
+      JSON.stringify({
+        event: "prisma_airs_tool_block",
+        timestamp: new Date().toISOString(),
+        sessionKey,
+        toolName,
+        toolId: event.toolId,
+        scanAction: scanResult.action,
+        severity: scanResult.severity,
+        categories: scanResult.categories,
+        scanId: scanResult.scanId,
+      })
+    );
+
+    return {
+      block: true,
+      blockReason: reason,
+    };
+  }
+
+  // Tool allowed, log for audit
+  if (scanResult.action !== "allow") {
+    console.log(
+      JSON.stringify({
+        event: "prisma_airs_tool_allow",
+        timestamp: new Date().toISOString(),
+        sessionKey,
+        toolName,
+        toolId: event.toolId,
+        note: "Tool allowed despite active security warning",
+        scanAction: scanResult.action,
+        categories: scanResult.categories,
+      })
+    );
+  }
+};
+
+export default handler;

package/index.ts

@@ -116,7 +116,7 @@ export default function register(api: PluginApi): void {
     const hasApiKey = isConfigured();
     respond(true, {
       plugin: "prisma-airs",
-      version: "0.1.4",
+      version: "0.2.0",
       config: {
         profile_name: cfg.profile_name ?? "default",
         app_name: cfg.app_name ?? "openclaw",
@@ -215,7 +215,7 @@ export default function register(api: PluginApi): void {
           const hasKey = isConfigured();
           console.log("Prisma AIRS Plugin Status");
           console.log("-------------------------");
-          console.log(`Version: 0.1.4`);
+          console.log(`Version: 0.2.0`);
           console.log(`Profile: ${cfg.profile_name ?? "default"}`);
           console.log(`App Name: ${cfg.app_name ?? "openclaw"}`);
           console.log(`Reminder: ${cfg.reminder_enabled ?? true}`);
@@ -266,7 +266,7 @@ export default function register(api: PluginApi): void {
 // Export plugin metadata for discovery
 export const id = "prisma-airs";
 export const name = "Prisma AIRS Security";
-export const version = "0.1.4";
+export const version = "0.2.0";
 
 // Re-export scanner types and functions
 export { scan, isConfigured } from "./src/scanner";

package/openclaw.plugin.json

@@ -1,10 +1,16 @@
 {
   "id": "prisma-airs",
   "name": "Prisma AIRS Security",
-  "description": "AI Runtime Security scanning via Palo Alto Networks - TypeScript implementation with Gateway RPC, agent tool, and bootstrap reminder hook",
-  "version": "0.1.4",
+  "description": "AI Runtime Security - full AIRS detection suite with audit logging, context injection, outbound blocking, and tool gating",
+  "version": "0.2.0",
   "entrypoint": "index.ts",
-  "hooks": ["hooks/prisma-airs-guard"],
+  "hooks": [
+    "hooks/prisma-airs-guard",
+    "hooks/prisma-airs-audit",
+    "hooks/prisma-airs-context",
+    "hooks/prisma-airs-outbound",
+    "hooks/prisma-airs-tools"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -23,6 +29,42 @@
         "type": "boolean",
         "default": true,
         "description": "Inject security scanning reminder on agent bootstrap"
+      },
+      "audit_enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable audit logging of all inbound messages"
+      },
+      "context_injection_enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Inject security warnings into agent context"
+      },
+      "outbound_scanning_enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable scanning and blocking of outbound responses"
+      },
+      "tool_gating_enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Block dangerous tools when threats are detected"
+      },
+      "fail_closed": {
+        "type": "boolean",
+        "default": true,
+        "description": "Block messages when AIRS scan fails (default: true for security)"
+      },
+      "dlp_mask_only": {
+        "type": "boolean",
+        "default": true,
+        "description": "Mask DLP violations instead of blocking (when no other violations)"
+      },
+      "high_risk_tools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": ["exec", "Bash", "write", "Write", "edit", "Edit", "gateway", "message", "cron"],
+        "description": "Tools to block on any detected threat"
       }
     }
   },
@@ -37,9 +79,38 @@
     },
     "reminder_enabled": {
       "label": "Enable Bootstrap Reminder"
+    },
+    "audit_enabled": {
+      "label": "Enable Audit Logging",
+      "description": "Log all inbound messages with scan results"
+    },
+    "context_injection_enabled": {
+      "label": "Enable Context Injection",
+      "description": "Inject security warnings into agent context"
+    },
+    "outbound_scanning_enabled": {
+      "label": "Enable Outbound Scanning",
+      "description": "Scan and block/mask outbound responses"
+    },
+    "tool_gating_enabled": {
+      "label": "Enable Tool Gating",
+      "description": "Block dangerous tools during active threats"
+    },
+    "fail_closed": {
+      "label": "Fail Closed",
+      "description": "Block on scan failure (recommended for security)"
+    },
+    "dlp_mask_only": {
+      "label": "DLP Mask Only",
+      "description": "Mask sensitive data instead of blocking"
+    },
+    "high_risk_tools": {
+      "label": "High Risk Tools",
+      "description": "Tools blocked on any threat detection"
     }
   },
   "requires": {
-    "env": ["PANW_AI_SEC_API_KEY"]
+    "env": ["PANW_AI_SEC_API_KEY"],
+    "envOptional": ["PANW_AI_SEC_PROFILE_NAME"]
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cdot65/prisma-airs",
-  "version": "0.1.4",
-  "description": "Prisma AIRS (AI Runtime Security) plugin for OpenClaw - TypeScript implementation with Gateway RPC, agent tool, and bootstrap hook",
+  "version": "0.2.1",
+  "description": "Prisma AIRS (AI Runtime Security) plugin for OpenClaw - Full security suite with audit logging, context injection, outbound blocking, and tool gating",
   "type": "module",
   "main": "index.ts",
   "scripts": {

package/src/scan-cache.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Tests for scan-cache module
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  cacheScanResult,
+  getCachedScanResult,
+  getCachedScanResultIfMatch,
+  clearScanResult,
+  getCacheStats,
+  hashMessage,
+  stopCleanup,
+  startCleanup,
+} from "./scan-cache";
+import type { ScanResult } from "./scanner";
+
+// Mock scan result
+const mockScanResult: ScanResult = {
+  action: "block",
+  severity: "HIGH",
+  categories: ["prompt_injection"],
+  scanId: "scan_123",
+  reportId: "report_456",
+  profileName: "default",
+  promptDetected: { injection: true, dlp: false, urlCats: false },
+  responseDetected: { dlp: false, urlCats: false },
+  latencyMs: 100,
+};
+
+describe("scan-cache", () => {
+  beforeEach(() => {
+    // Clear cache before each test
+    clearScanResult("test-session");
+    clearScanResult("session-1");
+    clearScanResult("session-2");
+  });
+
+  afterEach(() => {
+    // Stop cleanup interval to prevent test interference
+    stopCleanup();
+  });
+
+  describe("cacheScanResult", () => {
+    it("should cache a scan result", () => {
+      cacheScanResult("test-session", mockScanResult);
+      const result = getCachedScanResult("test-session");
+      expect(result).toEqual(mockScanResult);
+    });
+
+    it("should cache with message hash", () => {
+      const hash = hashMessage("test message");
+      cacheScanResult("test-session", mockScanResult, hash);
+      const result = getCachedScanResultIfMatch("test-session", hash);
+      expect(result).toEqual(mockScanResult);
+    });
+  });
+
+  describe("getCachedScanResult", () => {
+    it("should return undefined for non-existent key", () => {
+      const result = getCachedScanResult("non-existent");
+      expect(result).toBeUndefined();
+    });
+
+    it("should return cached result", () => {
+      cacheScanResult("test-session", mockScanResult);
+      const result = getCachedScanResult("test-session");
+      expect(result).toEqual(mockScanResult);
+    });
+
+    it("should return undefined for expired entries", () => {
+      // Mock Date.now to simulate time passing
+      const originalNow = Date.now;
+      const startTime = 1000000;
+      vi.spyOn(Date, "now").mockReturnValue(startTime);
+
+      cacheScanResult("test-session", mockScanResult);
+
+      // Advance time past TTL (30 seconds)
+      vi.spyOn(Date, "now").mockReturnValue(startTime + 31000);
+
+      const result = getCachedScanResult("test-session");
+      expect(result).toBeUndefined();
+
+      // Restore
+      Date.now = originalNow;
+    });
+  });
+
+  describe("getCachedScanResultIfMatch", () => {
+    it("should return result if hash matches", () => {
+      const hash = hashMessage("test message");
+      cacheScanResult("test-session", mockScanResult, hash);
+      const result = getCachedScanResultIfMatch("test-session", hash);
+      expect(result).toEqual(mockScanResult);
+    });
+
+    it("should return undefined if hash does not match", () => {
+      const hash1 = hashMessage("message 1");
+      const hash2 = hashMessage("message 2");
+      cacheScanResult("test-session", mockScanResult, hash1);
+      const result = getCachedScanResultIfMatch("test-session", hash2);
+      expect(result).toBeUndefined();
+    });
+
+    it("should return result if no hash was stored", () => {
+      cacheScanResult("test-session", mockScanResult);
+      const result = getCachedScanResultIfMatch("test-session", "any-hash");
+      expect(result).toEqual(mockScanResult);
+    });
+  });
+
+  describe("clearScanResult", () => {
+    it("should clear cached result", () => {
+      cacheScanResult("test-session", mockScanResult);
+      clearScanResult("test-session");
+      const result = getCachedScanResult("test-session");
+      expect(result).toBeUndefined();
+    });
+
+    it("should not affect other sessions", () => {
+      cacheScanResult("session-1", mockScanResult);
+      cacheScanResult("session-2", { ...mockScanResult, scanId: "scan_456" });
+      clearScanResult("session-1");
+
+      expect(getCachedScanResult("session-1")).toBeUndefined();
+      expect(getCachedScanResult("session-2")).toBeDefined();
+    });
+  });
+
+  describe("hashMessage", () => {
+    it("should produce consistent hashes", () => {
+      const hash1 = hashMessage("test message");
+      const hash2 = hashMessage("test message");
+      expect(hash1).toEqual(hash2);
+    });
+
+    it("should produce different hashes for different messages", () => {
+      const hash1 = hashMessage("message 1");
+      const hash2 = hashMessage("message 2");
+      expect(hash1).not.toEqual(hash2);
+    });
+
+    it("should handle empty string", () => {
+      const hash = hashMessage("");
+      expect(hash).toEqual("0");
+    });
+  });
+
+  describe("getCacheStats", () => {
+    it("should return cache stats", () => {
+      const stats = getCacheStats();
+      expect(stats).toHaveProperty("size");
+      expect(stats).toHaveProperty("ttlMs");
+      expect(stats.ttlMs).toEqual(30000);
+    });
+  });
+
+  describe("cleanup", () => {
+    it("should be able to stop and start cleanup", () => {
+      stopCleanup();
+      startCleanup();
+      // No error means success
+      expect(true).toBe(true);
+    });
+  });
+});