@cdot65/prisma-airs 0.1.3 → 0.2.0

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

@@ -0,0 +1,341 @@
+/**
+ * Prisma AIRS Outbound Security Scanner (message_sending)
+ *
+ * Scans ALL outbound responses for:
+ * - WildFire: malicious URLs and content
+ * - Toxicity: harmful/abusive content
+ * - URL Filtering: disallowed URL categories
+ * - DLP: sensitive data leakage
+ * - Malicious Code: malware/exploits
+ * - Custom Topics: org-specific policy violations
+ * - Grounding: hallucination detection
+ *
+ * CAN BLOCK via { cancel: true } or modify via { content: "..." }
+ */
+
+import { scan, type ScanResult } from "../../src/scanner";
+
+// Event shape from OpenClaw message_sending hook
+interface MessageSendingEvent {
+  content?: string;
+  to?: string;
+  channel?: string;
+  metadata?: {
+    sessionKey?: string;
+    messageId?: string;
+  };
+}
+
+// Context passed to hook
+interface HookContext {
+  channelId?: string;
+  accountId?: string;
+  conversationId?: string;
+  cfg?: PluginConfig;
+}
+
+// Plugin config structure
+interface PluginConfig {
+  plugins?: {
+    entries?: {
+      "prisma-airs"?: {
+        config?: {
+          outbound_scanning_enabled?: boolean;
+          profile_name?: string;
+          app_name?: string;
+          fail_closed?: boolean;
+          dlp_mask_only?: boolean;
+        };
+      };
+    };
+  };
+}
+
+// Hook result type - can modify content or cancel
+interface HookResult {
+  content?: string;
+  cancel?: boolean;
+}
+
+// Map AIRS categories to user-friendly messages
+const CATEGORY_MESSAGES: Record<string, string> = {
+  // Core detections
+  prompt_injection: "prompt injection attempt",
+  dlp_prompt: "sensitive data in input",
+  dlp_response: "sensitive data leakage",
+  url_filtering_prompt: "disallowed URL in input",
+  url_filtering_response: "disallowed URL in response",
+  malicious_url: "malicious URL detected",
+  toxicity: "inappropriate content",
+  toxic_content: "inappropriate content",
+  malicious_code: "malicious code detected",
+  agent_threat: "AI agent threat",
+  grounding: "response grounding violation",
+  ungrounded: "ungrounded response",
+  custom_topic: "policy violation",
+  topic_violation: "policy violation",
+  db_security: "database security threat",
+  safe: "safe",
+  benign: "safe",
+  api_error: "security scan error",
+  "scan-failure": "security scan failed",
+};
+
+// Categories that can be masked instead of blocked
+const MASKABLE_CATEGORIES = ["dlp_response", "dlp_prompt", "dlp"];
+
+// Categories that always require full block
+const ALWAYS_BLOCK_CATEGORIES = [
+  "malicious_code",
+  "malicious_url",
+  "toxicity",
+  "toxic_content",
+  "agent_threat",
+  "prompt_injection",
+  "db_security",
+  "scan-failure",
+];
+
+/**
+ * Get plugin configuration
+ */
+function getPluginConfig(ctx: HookContext): {
+  enabled: boolean;
+  profileName: string;
+  appName: string;
+  failClosed: boolean;
+  dlpMaskOnly: boolean;
+} {
+  const cfg = ctx.cfg?.plugins?.entries?.["prisma-airs"]?.config;
+  return {
+    enabled: cfg?.outbound_scanning_enabled !== false,
+    profileName: cfg?.profile_name ?? "default",
+    appName: cfg?.app_name ?? "openclaw",
+    failClosed: cfg?.fail_closed ?? true, // Default fail-closed
+    dlpMaskOnly: cfg?.dlp_mask_only ?? true, // Default mask instead of block for DLP
+  };
+}
+
+/**
+ * Mask sensitive data in content
+ *
+ * Uses regex patterns for common PII types.
+ * TODO: Use AIRS API match offsets for precision masking when available.
+ */
+function maskSensitiveData(content: string): string {
+  let masked = content;
+
+  // Social Security Numbers (XXX-XX-XXXX)
+  masked = masked.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[SSN REDACTED]");
+
+  // Credit Card Numbers (with or without spaces/dashes)
+  masked = masked.replace(/\b(?:\d{4}[-\s]?){3}\d{4}\b/g, "[CARD REDACTED]");
+
+  // Email addresses
+  masked = masked.replace(
+    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+    "[EMAIL REDACTED]"
+  );
+
+  // API keys and tokens (common patterns)
+  masked = masked.replace(
+    /\b(?:sk-|pk-|api[_-]?key[_-]?|token[_-]?|secret[_-]?|password[_-]?)[a-zA-Z0-9_-]{16,}\b/gi,
+    "[API KEY REDACTED]"
+  );
+
+  // AWS keys
+  masked = masked.replace(/\b(?:AKIA|ABIA|ACCA|ASIA)[A-Z0-9]{16}\b/g, "[AWS KEY REDACTED]");
+
+  // Generic long alphanumeric strings that look like secrets (40+ chars)
+  masked = masked.replace(/\b[a-zA-Z0-9_-]{40,}\b/g, (match) => {
+    // Only redact if it looks like a key (has mixed case or numbers)
+    if (/[a-z]/.test(match) && /[A-Z]/.test(match) && /[0-9]/.test(match)) {
+      return "[SECRET REDACTED]";
+    }
+    return match;
+  });
+
+  // US Phone numbers
+  masked = masked.replace(
+    /\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+    "[PHONE REDACTED]"
+  );
+
+  // IP addresses (private ranges especially)
+  masked = masked.replace(
+    /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b/g,
+    "[IP REDACTED]"
+  );
+
+  return masked;
+}
+
+/**
+ * Build user-friendly block message
+ */
+function buildBlockMessage(result: ScanResult): string {
+  const reasons = result.categories
+    .map((cat) => CATEGORY_MESSAGES[cat] || cat.replace(/_/g, " "))
+    .filter((r) => r !== "safe")
+    .join(", ");
+
+  return (
+    `I apologize, but I'm unable to provide that response due to security policy` +
+    (reasons ? ` (${reasons})` : "") +
+    `. Please rephrase your request or contact support if you believe this is an error.`
+  );
+}
+
+/**
+ * Determine if result should be masked vs blocked
+ */
+function shouldMaskOnly(result: ScanResult, config: { dlpMaskOnly: boolean }): boolean {
+  if (!config.dlpMaskOnly) return false;
+
+  // Check if any always-block categories are present
+  const hasBlockingCategory = result.categories.some((cat) =>
+    ALWAYS_BLOCK_CATEGORIES.includes(cat)
+  );
+  if (hasBlockingCategory) return false;
+
+  // Check if all categories are maskable
+  const allMaskable = result.categories.every(
+    (cat) => MASKABLE_CATEGORIES.includes(cat) || cat === "safe" || cat === "benign"
+  );
+
+  return allMaskable;
+}
+
+/**
+ * Main hook handler
+ */
+const handler = async (
+  event: MessageSendingEvent,
+  ctx: HookContext
+): Promise<HookResult | void> => {
+  const config = getPluginConfig(ctx);
+
+  // Check if outbound scanning is enabled
+  if (!config.enabled) {
+    return;
+  }
+
+  // Validate we have content to scan
+  const content = event.content;
+  if (!content || typeof content !== "string" || content.trim().length === 0) {
+    return;
+  }
+
+  const sessionKey = event.metadata?.sessionKey || ctx.conversationId || "unknown";
+
+  let result: ScanResult;
+
+  try {
+    // Scan the outbound response
+    result = await scan({
+      response: content,
+      profileName: config.profileName,
+      appName: config.appName,
+    });
+  } catch (err) {
+    console.error(
+      JSON.stringify({
+        event: "prisma_airs_outbound_scan_error",
+        timestamp: new Date().toISOString(),
+        sessionKey,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    );
+
+    // Fail-closed: block on scan failure
+    if (config.failClosed) {
+      return {
+        content:
+          "I apologize, but I'm unable to provide a response at this time due to a security verification issue. Please try again.",
+      };
+    }
+
+    return; // Fail-open
+  }
+
+  // Log the scan result
+  console.log(
+    JSON.stringify({
+      event: "prisma_airs_outbound_scan",
+      timestamp: new Date().toISOString(),
+      sessionKey,
+      action: result.action,
+      severity: result.severity,
+      categories: result.categories,
+      scanId: result.scanId,
+      reportId: result.reportId,
+      latencyMs: result.latencyMs,
+      responseDetected: result.responseDetected,
+    })
+  );
+
+  // Handle allow - no modification needed
+  if (result.action === "allow") {
+    return;
+  }
+
+  // Handle warn - log but allow through
+  if (result.action === "warn") {
+    console.log(
+      JSON.stringify({
+        event: "prisma_airs_outbound_warn",
+        timestamp: new Date().toISOString(),
+        sessionKey,
+        severity: result.severity,
+        categories: result.categories,
+        scanId: result.scanId,
+      })
+    );
+    return; // Allow through with warning logged
+  }
+
+  // Handle block
+  if (result.action === "block") {
+    // Check if we should mask instead of block (DLP-only)
+    if (shouldMaskOnly(result, config)) {
+      const maskedContent = maskSensitiveData(content);
+
+      // Only return modified content if masking actually changed something
+      if (maskedContent !== content) {
+        console.log(
+          JSON.stringify({
+            event: "prisma_airs_outbound_mask",
+            timestamp: new Date().toISOString(),
+            sessionKey,
+            categories: result.categories,
+            scanId: result.scanId,
+          })
+        );
+
+        return {
+          content: maskedContent,
+        };
+      }
+    }
+
+    // Full block - replace content entirely
+    console.log(
+      JSON.stringify({
+        event: "prisma_airs_outbound_block",
+        timestamp: new Date().toISOString(),
+        sessionKey,
+        action: result.action,
+        severity: result.severity,
+        categories: result.categories,
+        scanId: result.scanId,
+        reportId: result.reportId,
+      })
+    );
+
+    return {
+      content: buildBlockMessage(result),
+    };
+  }
+};
+
+export default handler;

package/hooks/prisma-airs-tools/HOOK.md

@@ -0,0 +1,40 @@
+---
+name: prisma-airs-tools
+description: "Block dangerous tool calls when security threats are detected"
+metadata: { "openclaw": { "emoji": "🛑", "events": ["before_tool_call"] } }
+---
+
+# Prisma AIRS Tool Gating
+
+Blocks dangerous tool calls when security warnings are active from inbound scanning.
+
+## Behavior
+
+This hook runs before each tool call and checks if the current session has an active security warning (from `message_received` or `before_agent_start` scanning). Based on the detected threat categories, it blocks specific tools that could be dangerous.
+
+## Tool Blocking Matrix
+
+| Threat Category                 | Blocked Tools                 |
+| ------------------------------- | ----------------------------- |
+| `agent-threat`                  | ALL external tools            |
+| `sql-injection` / `db-security` | exec, database, query, sql    |
+| `malicious-code`                | exec, write, edit, eval, bash |
+| `prompt-injection`              | exec, gateway, message, cron  |
+| `malicious-url`                 | web_fetch, browser, curl      |
+
+## High-Risk Tools (Default)
+
+These tools are blocked on ANY detected threat:
+
+- `exec` - Command execution
+- `Bash` - Shell access
+- `write` - File writing
+- `edit` - File editing
+- `gateway` - Gateway operations
+- `message` - Sending messages
+- `cron` - Scheduled tasks
+
+## Configuration
+
+- `tool_gating_enabled`: Enable/disable (default: true)
+- `high_risk_tools`: List of tools to block on any threat

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;