@cdot65/prisma-airs-cursor-hooks 0.1.0

package/src/scanner.ts

@@ -0,0 +1,388 @@
+import type { ScanResponse } from "@cdot65/prisma-airs-sdk";
+import type { AirsConfig, HookResult, ScanDirection, ScanLogEntry } from "./types.js";
+import {
+  scanPromptContent,
+  scanResponseContent,
+  AISecSDKException,
+} from "./airs-client.js";
+import { extractCode, joinCodeBlocks } from "./code-extractor.js";
+import { Logger } from "./logger.js";
+import { getEnforcementAction, maskContent, DEFAULT_ENFORCEMENT } from "./dlp-masking.js";
+
+// ---------------------------------------------------------------------------
+// Human-readable detection labels for UX messages
+// ---------------------------------------------------------------------------
+const DETECTION_LABELS: Record<string, string> = {
+  prompt_injection: "Prompt Injection",
+  dlp: "Data Loss Prevention (DLP)",
+  toxicity: "Toxic Content",
+  url_categorization: "Suspicious URL",
+  malicious_code: "Malicious Code",
+  custom_topic: "Topic Policy Violation",
+};
+
+function friendlyDetectionName(key: string): string {
+  return DETECTION_LABELS[key] ?? key;
+}
+
+// ---------------------------------------------------------------------------
+// Detection extraction from SDK ScanResponse
+// ---------------------------------------------------------------------------
+
+interface DetectionInfo {
+  services: string[];
+  findings: { detection_service: string; verdict: string; detail: string }[];
+}
+
+function extractDetections(result: ScanResponse): DetectionInfo {
+  const services: string[] = [];
+  const findings: { detection_service: string; verdict: string; detail: string }[] = [];
+  const pd = result.prompt_detected;
+  if (pd) {
+    if (pd.injection) {
+      services.push("prompt_injection");
+      findings.push({ detection_service: "prompt_injection", verdict: "malicious", detail: "Prompt injection detected" });
+    }
+    if (pd.dlp) {
+      services.push("dlp");
+      findings.push({ detection_service: "dlp", verdict: "detected", detail: "Sensitive data detected in prompt" });
+    }
+    if (pd.toxic_content) {
+      services.push("toxicity");
+      findings.push({ detection_service: "toxicity", verdict: "toxic", detail: "Toxic content detected" });
+    }
+    if (pd.url_cats) {
+      services.push("url_categorization");
+      findings.push({ detection_service: "url_categorization", verdict: "suspicious", detail: "Suspicious URL detected" });
+    }
+    if (pd.malicious_code) {
+      services.push("malicious_code");
+      findings.push({ detection_service: "malicious_code", verdict: "malicious", detail: "Malicious code detected" });
+    }
+    if (pd.topic_violation) {
+      services.push("custom_topic");
+      findings.push({ detection_service: "custom_topic", verdict: "violation", detail: "Topic policy violation" });
+    }
+  }
+  const rd = result.response_detected;
+  if (rd) {
+    if (rd.malicious_code) {
+      services.push("malicious_code");
+      findings.push({ detection_service: "malicious_code", verdict: "malicious", detail: "Malicious code detected in response" });
+    }
+    if (rd.dlp) {
+      services.push("dlp");
+      findings.push({ detection_service: "dlp", verdict: "detected", detail: "Sensitive data detected in response" });
+    }
+    if (rd.toxic_content) {
+      services.push("toxicity");
+      findings.push({ detection_service: "toxicity", verdict: "toxic", detail: "Toxic content in response" });
+    }
+    if (rd.url_cats) {
+      services.push("url_categorization");
+      findings.push({ detection_service: "url_categorization", verdict: "suspicious", detail: "Suspicious URL in response" });
+    }
+  }
+  return { services, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Resolve the developer's identity
+// Cursor provides CURSOR_USER_EMAIL; fall back to git config then OS user.
+// ---------------------------------------------------------------------------
+
+function getAppUser(): string {
+  const cursorEmail = process.env.CURSOR_USER_EMAIL;
+  if (cursorEmail) return cursorEmail;
+
+  try {
+    const { execSync } = require("node:child_process");
+    return execSync("git config user.email", { encoding: "utf-8" }).trim();
+  } catch {
+    return process.env.USER ?? process.env.USERNAME ?? "unknown";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Build UX-friendly block messages
+// ---------------------------------------------------------------------------
+
+function buildPromptBlockMessage(
+  detections: string[],
+  category: string,
+  profileName: string,
+  scanId: string,
+): string {
+  const detectionList = detections.map(friendlyDetectionName).join(", ");
+  return [
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "  Prisma AIRS — Prompt Blocked",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+    `  What happened:  Your prompt was flagged by the ${detectionList} security check.`,
+    `  Category:       ${category}`,
+    `  Profile:        ${profileName}`,
+    "",
+    "  What to do:",
+    "    - Review your prompt for sensitive data, injection patterns, or policy violations.",
+    "    - Modify the prompt and try again.",
+    "    - If you believe this is a false positive, contact your security team",
+    `      and reference Scan ID: ${scanId}`,
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+  ].join("\n");
+}
+
+function buildResponseBlockMessage(
+  detections: string[],
+  category: string,
+  profileName: string,
+  scanId: string,
+): string {
+  const detectionList = detections.map(friendlyDetectionName).join(", ");
+  return [
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "  Prisma AIRS — Response Blocked",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+    `  What happened:  The AI response was flagged by the ${detectionList} security check.`,
+    `  Category:       ${category}`,
+    `  Profile:        ${profileName}`,
+    "",
+    "  What to do:",
+    "    - The response may have contained malicious code, sensitive data, or unsafe content.",
+    "    - Try rephrasing your original prompt to get a different response.",
+    "    - If you believe this is a false positive, contact your security team",
+    `      and reference Scan ID: ${scanId}`,
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+  ].join("\n");
+}
+
+function buildMaskedMessage(maskedServices: string[]): string {
+  const names = maskedServices.map(friendlyDetectionName).join(", ");
+  return [
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "  Prisma AIRS — Sensitive Data Masked",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+    `  ${names} detected sensitive data in your content.`,
+    "  The flagged patterns have been masked with asterisks.",
+    "",
+    "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
+    "",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// scanPrompt — called by beforeSubmitPrompt hook
+// ---------------------------------------------------------------------------
+
+export async function scanPrompt(
+  config: AirsConfig,
+  prompt: string,
+  logger: Logger,
+): Promise<HookResult> {
+  if (config.mode === "bypass") {
+    logger.logEvent("scan_bypassed", { direction: "prompt" });
+    return { action: "pass" };
+  }
+
+  if (!prompt.trim()) {
+    return { action: "pass" };
+  }
+
+  const appUser = getAppUser();
+
+  try {
+    const { result, latencyMs } = await scanPromptContent(config, prompt, appUser, logger);
+
+    const verdict = result.action === "block" ? "block" : "allow";
+    const { services: detections, findings } = extractDetections(result);
+
+    const actionTaken =
+      config.mode === "observe"
+        ? "observed"
+        : verdict === "block"
+          ? "blocked"
+          : "allowed";
+
+    logger.logScan({
+      event: "scan_complete",
+      scan_id: result.scan_id ?? "",
+      direction: "prompt" as ScanDirection,
+      verdict: verdict as "allow" | "block",
+      action_taken: actionTaken,
+      latency_ms: latencyMs,
+      detection_services_triggered: detections,
+      error: null,
+    });
+
+    if (config.mode === "enforce" && verdict === "block") {
+      // Check per-service enforcement — some services may be set to "mask" or "allow"
+      const enforcement = config.enforcement ?? DEFAULT_ENFORCEMENT;
+      const enforcementAction = getEnforcementAction(findings, enforcement);
+
+      if (enforcementAction === "allow") {
+        return { action: "pass" };
+      }
+
+      if (enforcementAction === "mask") {
+        // DLP masking: we can't mask prompt content that's already been sent,
+        // but we log it and warn the user
+        const maskedServices = findings
+          .filter((f) => (enforcement[f.detection_service] ?? "block") === "mask")
+          .map((f) => f.detection_service);
+        logger.logEvent("dlp_mask_applied", { direction: "prompt", services: maskedServices });
+        return { action: "pass", message: buildMaskedMessage(maskedServices) };
+      }
+
+      return {
+        action: "block",
+        message: buildPromptBlockMessage(
+          detections,
+          result.category ?? "policy violation",
+          config.profiles.prompt,
+          result.scan_id ?? "unknown",
+        ),
+      };
+    }
+
+    return { action: "pass" };
+  } catch (err) {
+    const isAuth =
+      err instanceof AISecSDKException && err.message.includes("401");
+
+    const message = isAuth
+      ? "AIRS authentication failed. Check your API key."
+      : "AIRS scan failed — allowing prompt (fail-open)";
+
+    logger.logScan({
+      event: "scan_error",
+      scan_id: "",
+      direction: "prompt",
+      verdict: "allow",
+      action_taken: "error",
+      latency_ms: 0,
+      detection_services_triggered: [],
+      error: message,
+    });
+
+    if (isAuth) {
+      return { action: "pass", message: `Warning: ${message}` };
+    }
+    return { action: "pass" };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// scanResponse — called by afterAgentResponse hook
+// ---------------------------------------------------------------------------
+
+export async function scanResponse(
+  config: AirsConfig,
+  responseText: string,
+  logger: Logger,
+): Promise<HookResult> {
+  if (config.mode === "bypass") {
+    logger.logEvent("scan_bypassed", { direction: "response" });
+    return { action: "pass" };
+  }
+
+  if (!responseText.trim()) {
+    return { action: "pass" };
+  }
+
+  const appUser = getAppUser();
+  const extracted = extractCode(responseText);
+  const codeResponse =
+    extracted.codeBlocks.length > 0
+      ? joinCodeBlocks(extracted.codeBlocks)
+      : undefined;
+
+  const nlText = codeResponse ? extracted.naturalLanguage : responseText;
+
+  try {
+    const { result, latencyMs } = await scanResponseContent(
+      config, nlText, codeResponse, appUser, logger,
+    );
+
+    const verdict = result.action === "block" ? "block" : "allow";
+    const { services: detections, findings } = extractDetections(result);
+
+    const actionTaken =
+      config.mode === "observe"
+        ? "observed"
+        : verdict === "block"
+          ? "blocked"
+          : "allowed";
+
+    logger.logScan({
+      event: "scan_complete",
+      scan_id: result.scan_id ?? "",
+      direction: "response",
+      verdict: verdict as "allow" | "block",
+      action_taken: actionTaken,
+      latency_ms: latencyMs,
+      detection_services_triggered: detections,
+      error: null,
+    });
+
+    if (config.mode === "enforce" && verdict === "block") {
+      const enforcement = config.enforcement ?? DEFAULT_ENFORCEMENT;
+      const enforcementAction = getEnforcementAction(findings, enforcement);
+
+      if (enforcementAction === "allow") {
+        return { action: "pass" };
+      }
+
+      if (enforcementAction === "mask") {
+        const maskedServices = findings
+          .filter((f) => (enforcement[f.detection_service] ?? "block") === "mask")
+          .map((f) => f.detection_service);
+        logger.logEvent("dlp_mask_applied", { direction: "response", services: maskedServices });
+        return { action: "pass", message: buildMaskedMessage(maskedServices) };
+      }
+
+      return {
+        action: "block",
+        message: buildResponseBlockMessage(
+          detections,
+          result.category ?? "policy violation",
+          config.profiles.response,
+          result.scan_id ?? "unknown",
+        ),
+      };
+    }
+
+    return { action: "pass" };
+  } catch (err) {
+    const isAuth =
+      err instanceof AISecSDKException && err.message.includes("401");
+
+    const message = isAuth
+      ? "AIRS authentication failed. Check your API key."
+      : "AIRS scan failed — allowing response (fail-open)";
+
+    logger.logScan({
+      event: "scan_error",
+      scan_id: "",
+      direction: "response",
+      verdict: "allow",
+      action_taken: "error",
+      latency_ms: 0,
+      detection_services_triggered: [],
+      error: message,
+    });
+
+    if (isAuth) {
+      return { action: "pass", message: `Warning: ${message}` };
+    }
+    return { action: "pass" };
+  }
+}

package/src/types.ts

@@ -0,0 +1,153 @@
+// Re-export SDK types we use directly
+export type {
+  ScanResponse,
+  Metadata,
+} from "@cdot65/prisma-airs-sdk";
+
+/** Operational mode */
+export type Mode = "observe" | "enforce" | "bypass";
+
+/** Retry configuration */
+export interface RetryConfig {
+  enabled: boolean;
+  max_attempts: number;
+  backoff_base_ms: number;
+}
+
+/** Logging configuration */
+export interface LoggingConfig {
+  path: string;
+  include_content: boolean;
+}
+
+/** Profile configuration */
+export interface ProfileConfig {
+  prompt: string;
+  response: string;
+}
+
+/** Per-detection-service enforcement action */
+export type EnforcementAction = "block" | "mask" | "allow";
+
+/** Per-service enforcement overrides (Phase 3) */
+export interface EnforcementConfig {
+  [detectionService: string]: EnforcementAction;
+}
+
+/** Circuit breaker configuration */
+export interface CircuitBreakerConfig {
+  enabled: boolean;
+  failure_threshold: number;
+  cooldown_ms: number;
+}
+
+/** Top-level AIRS configuration (airs-config.json) */
+export interface AirsConfig {
+  endpoint: string;
+  apiKeyEnvVar: string;
+  profiles: ProfileConfig;
+  mode: Mode;
+  timeout_ms: number;
+  retry: RetryConfig;
+  logging: LoggingConfig;
+  /** Per-service enforcement actions (only applies in enforce mode) */
+  enforcement?: EnforcementConfig;
+  /** Circuit breaker settings */
+  circuit_breaker?: CircuitBreakerConfig;
+}
+
+/** Scan direction */
+export type ScanDirection = "prompt" | "response";
+
+/** Log entry written by the structured logger */
+export interface ScanLogEntry {
+  timestamp: string;
+  event: string;
+  scan_id: string;
+  direction: ScanDirection;
+  verdict: "allow" | "block";
+  action_taken: "allowed" | "blocked" | "observed" | "bypassed" | "error";
+  latency_ms: number;
+  detection_services_triggered: string[];
+  error: string | null;
+  content?: string;
+}
+
+/** Result from code extraction */
+export interface ExtractedContent {
+  naturalLanguage: string;
+  codeBlocks: string[];
+  languages: string[];
+}
+
+/** Internal hook result from scanner logic */
+export interface HookResult {
+  action: "pass" | "block";
+  message?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Cursor Hooks API types (v1)
+// See: https://docs.cursor.com/configuration/hooks
+// ---------------------------------------------------------------------------
+
+/** Common fields Cursor injects into every hook's stdin JSON */
+export interface CursorHookInput {
+  conversation_id?: string;
+  generation_id?: string;
+  model?: string;
+  hook_event_name: string;
+  cursor_version?: string;
+  workspace_roots?: string[];
+  user_email?: string;
+  transcript_path?: string;
+}
+
+/** stdin for beforeSubmitPrompt hook */
+export interface BeforeSubmitPromptInput extends CursorHookInput {
+  prompt: string;
+  attachments?: unknown[];
+}
+
+/** stdin for afterAgentResponse hook */
+export interface AfterAgentResponseInput extends CursorHookInput {
+  text: string;
+}
+
+/**
+ * Cursor hook stdout JSON for beforeSubmitPrompt.
+ * Uses continue: true/false to allow/block the prompt.
+ */
+export interface BeforeSubmitPromptOutput {
+  continue: boolean;
+  user_message?: string;
+}
+
+/**
+ * Cursor hook stdout JSON for most other hooks.
+ * Uses permission: "allow"|"deny" to allow/block.
+ */
+export interface CursorHookOutput {
+  /** "allow" passes through, "deny" blocks */
+  permission: "allow" | "deny";
+  /** Message shown to the user in Cursor's UI */
+  userMessage?: string;
+  /** Message injected into the agent context (invisible to the user) */
+  agentMessage?: string;
+}
+
+/** Cursor hooks.json file format */
+export interface CursorHooksConfig {
+  version: 1;
+  hooks: {
+    [eventName: string]: CursorHookEntry[];
+  };
+}
+
+/** Single hook entry inside hooks.json */
+export interface CursorHookEntry {
+  command: string;
+  timeout?: number;
+  /** true = block the action if the hook fails; false = fail-open (default) */
+  failClosed?: boolean;
+}

package/tsconfig.build.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}