@cdot65/prisma-airs-cursor-hooks 0.1.0

package/src/code-extractor.ts

@@ -0,0 +1,99 @@
+import type { ExtractedContent } from "./types.js";
+
+/** Regex matching fenced code blocks: ```lang\n...\n``` */
+const FENCED_BLOCK_RE = /^```(\w*)\n([\s\S]*?)^```$/gm;
+
+/** Heuristic: high density of syntax chars suggests code */
+const CODE_INDICATORS = [
+  /^import\s+/m,
+  /^from\s+\S+\s+import/m,
+  /^(?:function|const|let|var|class|def|async|export)\s/m,
+  /[{};]\s*$/m,
+  /^\s*(?:if|for|while|return|try|catch)\s*[\s(]/m,
+];
+
+const CODE_CHAR_THRESHOLD = 0.15;
+
+/** Extract code blocks from a mixed agent response */
+export function extractCode(agentResponse: string): ExtractedContent {
+  const codeBlocks: string[] = [];
+  const languages: string[] = [];
+  let naturalLanguage = agentResponse;
+
+  // Extract fenced code blocks
+  const matches = [...agentResponse.matchAll(FENCED_BLOCK_RE)];
+
+  if (matches.length > 0) {
+    for (const match of matches) {
+      const lang = match[1] || "unknown";
+      const code = match[2];
+      languages.push(lang);
+      codeBlocks.push(code);
+      naturalLanguage = naturalLanguage.replace(match[0], "");
+    }
+    naturalLanguage = naturalLanguage.replace(/\n{3,}/g, "\n\n").trim();
+    return { naturalLanguage, codeBlocks, languages };
+  }
+
+  // Secondary: detect indented code blocks (4+ spaces or tab after blank line)
+  const lines = agentResponse.split("\n");
+  let inBlock = false;
+  let currentBlock: string[] = [];
+  const nlLines: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const isIndented = /^(?:    |\t)/.test(line);
+    const prevBlank = i === 0 || lines[i - 1].trim() === "";
+
+    if (isIndented && (inBlock || prevBlank)) {
+      inBlock = true;
+      currentBlock.push(line.replace(/^(?:    |\t)/, ""));
+    } else {
+      if (inBlock && currentBlock.length > 0) {
+        codeBlocks.push(currentBlock.join("\n"));
+        languages.push("unknown");
+        currentBlock = [];
+      }
+      inBlock = false;
+      nlLines.push(line);
+    }
+  }
+  if (currentBlock.length > 0) {
+    codeBlocks.push(currentBlock.join("\n"));
+    languages.push("unknown");
+  }
+
+  if (codeBlocks.length > 0) {
+    return {
+      naturalLanguage: nlLines.join("\n").replace(/\n{3,}/g, "\n\n").trim(),
+      codeBlocks,
+      languages,
+    };
+  }
+
+  // Fallback heuristic: if response looks like code, treat it all as code
+  if (looksLikeCode(agentResponse)) {
+    return {
+      naturalLanguage: "",
+      codeBlocks: [agentResponse],
+      languages: ["unknown"],
+    };
+  }
+
+  return { naturalLanguage: agentResponse, codeBlocks: [], languages: [] };
+}
+
+/** Heuristic check: does the text look like source code? */
+function looksLikeCode(text: string): boolean {
+  const indicatorHits = CODE_INDICATORS.filter((re) => re.test(text)).length;
+  if (indicatorHits >= 2) return true;
+
+  const syntaxChars = (text.match(/[{}();=<>[\]]/g) || []).length;
+  return syntaxChars / text.length > CODE_CHAR_THRESHOLD;
+}
+
+/** Join multiple code blocks for the code_response field */
+export function joinCodeBlocks(blocks: string[]): string {
+  return blocks.join("\n\n---\n\n");
+}

package/src/config.ts

@@ -0,0 +1,126 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import type { AirsConfig, Mode } from "./types.js";
+
+const VALID_MODES: Mode[] = ["observe", "enforce", "bypass"];
+const DEFAULT_ENDPOINT = "https://service.api.aisecurity.paloaltonetworks.com";
+const DEFAULT_PROMPT_PROFILE = "cursor-ide-prompt-profile";
+const DEFAULT_RESPONSE_PROFILE = "cursor-ide-response-profile";
+
+/** Resolve environment variable references like ${VAR_NAME} */
+function resolveEnvVars(value: string): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "");
+}
+
+/** Validate a URL string */
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the config file path by searching (in order):
+ *   1. Explicit path argument
+ *   2. .cursor/hooks/airs-config.json in CURSOR_PROJECT_DIR (project-level)
+ *   3. .cursor/hooks/airs-config.json in cwd
+ *   4. ~/.cursor/hooks/airs-config.json (global/user-level)
+ *   5. airs-config.json in cwd (project root fallback)
+ */
+function resolveConfigPath(configPath?: string): string {
+  if (configPath) return configPath;
+
+  const candidates: string[] = [];
+
+  // Cursor injects CURSOR_PROJECT_DIR when running hooks
+  const cursorDir = process.env.CURSOR_PROJECT_DIR;
+  if (cursorDir) {
+    candidates.push(join(cursorDir, ".cursor", "hooks", "airs-config.json"));
+  }
+
+  candidates.push(
+    join(process.cwd(), ".cursor", "hooks", "airs-config.json"),
+    // Global/user-level config (for globally installed hooks)
+    join(homedir(), ".cursor", "hooks", "airs-config.json"),
+    resolve(process.cwd(), "airs-config.json"),
+  );
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // Return the first candidate for the error message
+  return candidates[0];
+}
+
+/** Load and validate AIRS configuration from a JSON file */
+export function loadConfig(configPath?: string): AirsConfig {
+  const resolved = resolveConfigPath(configPath);
+
+  let raw: string;
+  try {
+    raw = readFileSync(resolved, "utf-8");
+  } catch {
+    throw new Error(`Failed to read config file: ${resolved}`);
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Invalid JSON in config file: ${resolved}`);
+  }
+
+  const config = parsed as unknown as AirsConfig;
+
+  // Resolve env var references in endpoint, fall back to default US endpoint
+  config.endpoint = resolveEnvVars(config.endpoint);
+  if (!config.endpoint || config.endpoint === "${AIRS_API_ENDPOINT}") {
+    config.endpoint = DEFAULT_ENDPOINT;
+  }
+
+  // Resolve env var references in profile names, fall back to defaults
+  config.profiles.prompt = resolveEnvVars(config.profiles.prompt) || DEFAULT_PROMPT_PROFILE;
+  config.profiles.response = resolveEnvVars(config.profiles.response) || DEFAULT_RESPONSE_PROFILE;
+
+  // Validate mode
+  if (!VALID_MODES.includes(config.mode)) {
+    throw new Error(
+      `Invalid mode "${config.mode}". Must be one of: ${VALID_MODES.join(", ")}`,
+    );
+  }
+
+  // Validate endpoint URL
+  if (!isValidUrl(config.endpoint)) {
+    throw new Error(`Invalid endpoint URL: "${config.endpoint}"`);
+  }
+
+  // Validate API key env var is set
+  const apiKey = process.env[config.apiKeyEnvVar];
+  if (!apiKey || apiKey.trim() === "") {
+    throw new Error(
+      `API key environment variable "${config.apiKeyEnvVar}" is not set or empty`,
+    );
+  }
+
+  // Validate profiles
+  if (!config.profiles?.prompt || !config.profiles?.response) {
+    throw new Error("Config must include profiles.prompt and profiles.response");
+  }
+
+  // Validate timeout
+  if (typeof config.timeout_ms !== "number" || config.timeout_ms <= 0) {
+    throw new Error("timeout_ms must be a positive number");
+  }
+
+  return config;
+}
+
+/** Get the API key value from the environment */
+export function getApiKey(config: AirsConfig): string {
+  return process.env[config.apiKeyEnvVar] ?? "";
+}

package/src/dlp-masking.ts

@@ -0,0 +1,48 @@
+/** Enforcement action per detection service */
+export type EnforcementAction = "block" | "mask" | "allow";
+
+/** Default enforcement configuration */
+export const DEFAULT_ENFORCEMENT: Record<string, EnforcementAction> = {
+  prompt_injection: "block",
+  dlp: "block",
+  malicious_code: "block",
+  url_categorization: "block",
+  toxicity: "block",
+  custom_topic: "block",
+};
+
+interface Finding {
+  detection_service: string;
+  verdict: string;
+  detail: string;
+}
+
+/** Determine the enforcement action for a set of findings */
+export function getEnforcementAction(
+  findings: Finding[],
+  enforcement: Record<string, EnforcementAction> = DEFAULT_ENFORCEMENT,
+): EnforcementAction {
+  let hasMask = false;
+
+  for (const finding of findings) {
+    const action = enforcement[finding.detection_service] ?? "block";
+    if (action === "block") return "block";
+    if (action === "mask") hasMask = true;
+  }
+
+  return hasMask ? "mask" : "allow";
+}
+
+/** Simple masking: replace sensitive substrings with asterisks */
+export function maskContent(
+  content: string,
+  patterns: string[],
+): string {
+  let masked = content;
+  for (const pattern of patterns) {
+    if (pattern && masked.includes(pattern)) {
+      masked = masked.replaceAll(pattern, "*".repeat(pattern.length));
+    }
+  }
+  return masked;
+}

package/src/hooks/after-agent-response.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Cursor hook: afterAgentResponse
+ *
+ * Intercepts the AI agent's response before it is displayed to the developer.
+ * Extracts code blocks for dedicated malicious code scanning via code_response.
+ *
+ * Cursor contract:
+ *   stdin  → JSON { response, conversation_id, model, user_email, ... }
+ *   stdout → JSON { permission: "allow"|"deny", userMessage?, agentMessage? }
+ *   exit 0 = success, exit 2 = deny
+ *   stderr → debug logs (visible in Cursor "Hooks" output panel)
+ */
+import { loadConfig } from "../config.js";
+import { Logger } from "../logger.js";
+import { scanResponse } from "../scanner.js";
+import type { AfterAgentResponseInput, CursorHookOutput } from "../types.js";
+
+/** Read all of stdin as a string */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/** Write a Cursor hook response to stdout */
+function respond(output: CursorHookOutput): void {
+  process.stdout.write(JSON.stringify(output) + "\n");
+}
+
+/** Allow the response through (fail-open default) */
+function allowThrough(message?: string): void {
+  const output: CursorHookOutput = { permission: "allow" };
+  if (message) output.userMessage = message;
+  respond(output);
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+
+  let input: AfterAgentResponseInput;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    console.error("[AIRS] Failed to parse hook stdin as JSON, allowing through.");
+    allowThrough();
+    return;
+  }
+
+  // Expose Cursor-provided identity as env var for downstream use
+  if (input.user_email) {
+    process.env.CURSOR_USER_EMAIL = input.user_email;
+  }
+
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    console.error(`[AIRS] Config error: ${err}`);
+    allowThrough("Prisma AIRS: configuration error — scan skipped (fail-open).");
+    return;
+  }
+
+  const logger = new Logger(config.logging.path, config.logging.include_content);
+  const result = await scanResponse(config, input.text, logger);
+
+  if (result.action === "block") {
+    const output: CursorHookOutput = {
+      permission: "deny",
+      userMessage: result.message ?? "Prisma AIRS blocked this response.",
+    };
+    respond(output);
+    process.exit(2);
+  }
+
+  allowThrough(result.message);
+}
+
+main().catch((err) => {
+  console.error(`[AIRS] Unhandled hook error: ${err}`);
+  allowThrough();
+});

package/src/hooks/before-submit-prompt.ts

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Cursor hook: beforeSubmitPrompt
+ *
+ * Intercepts the developer's prompt before it is sent to the AI model.
+ * Reads structured JSON from stdin, scans the prompt via Prisma AIRS,
+ * and writes a JSON response to stdout telling Cursor to allow or deny.
+ *
+ * Cursor contract:
+ *   stdin  → JSON { prompt, conversation_id, model, user_email, ... }
+ *   stdout → JSON { permission: "allow"|"deny", userMessage?, agentMessage? }
+ *   exit 0 = success, exit 2 = deny
+ *   stderr → debug logs (visible in Cursor "Hooks" output panel)
+ */
+import { loadConfig } from "../config.js";
+import { Logger } from "../logger.js";
+import { scanPrompt } from "../scanner.js";
+import type { BeforeSubmitPromptInput, BeforeSubmitPromptOutput } from "../types.js";
+
+/** Read all of stdin as a string */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+/** Write a beforeSubmitPrompt response to stdout */
+function respond(output: BeforeSubmitPromptOutput): void {
+  process.stdout.write(JSON.stringify(output) + "\n");
+}
+
+/** Allow the prompt through (fail-open default) */
+function allowThrough(): void {
+  respond({ continue: true });
+}
+
+/** Block the prompt */
+function blockPrompt(message: string): void {
+  respond({ continue: false, user_message: message });
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+
+  let input: BeforeSubmitPromptInput;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    // stdin wasn't valid JSON — fail-open
+    console.error("[AIRS] Failed to parse hook stdin as JSON, allowing through.");
+    allowThrough();
+    return;
+  }
+
+  // Expose Cursor-provided identity as env var for downstream use
+  if (input.user_email) {
+    process.env.CURSOR_USER_EMAIL = input.user_email;
+  }
+
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    console.error(`[AIRS] Config error: ${err}`);
+    allowThrough();
+    return;
+  }
+
+  const logger = new Logger(config.logging.path, config.logging.include_content);
+  const result = await scanPrompt(config, input.prompt, logger);
+
+  if (result.action === "block") {
+    blockPrompt(result.message ?? "Prisma AIRS blocked this prompt.");
+    return;
+  }
+
+  allowThrough();
+}
+
+main().catch((err) => {
+  // Fail-open: never block the developer on unhandled errors
+  console.error(`[AIRS] Unhandled hook error: ${err}`);
+  allowThrough();
+});

package/src/log-rotation.ts

@@ -0,0 +1,27 @@
+import { existsSync, statSync, renameSync, unlinkSync } from "node:fs";
+
+const MAX_SIZE_BYTES = 10 * 1024 * 1024; // 10MB
+const MAX_ROTATIONS = 5;
+
+/** Rotate log file if it exceeds MAX_SIZE_BYTES */
+export function rotateIfNeeded(logPath: string): void {
+  try {
+    if (!existsSync(logPath)) return;
+    const stat = statSync(logPath);
+    if (stat.size < MAX_SIZE_BYTES) return;
+
+    // Shift existing rotated files
+    for (let i = MAX_ROTATIONS; i >= 1; i--) {
+      const from = i === 1 ? logPath : `${logPath}.${i - 1}`;
+      const to = `${logPath}.${i}`;
+      if (existsSync(from)) {
+        if (i === MAX_ROTATIONS && existsSync(to)) {
+          unlinkSync(to);
+        }
+        renameSync(from, to);
+      }
+    }
+  } catch {
+    // Never crash on rotation failure
+  }
+}

package/src/logger.ts

@@ -0,0 +1,55 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ScanLogEntry } from "./types.js";
+import { rotateIfNeeded } from "./log-rotation.js";
+
+/** Structured JSON Lines logger — appends one JSON object per line */
+export class Logger {
+  private logPath: string;
+  private includeContent: boolean;
+  private writeCount = 0;
+
+  constructor(logPath: string, includeContent = false) {
+    this.logPath = logPath;
+    this.includeContent = includeContent;
+  }
+
+  /** Log a scan result entry */
+  logScan(entry: Omit<ScanLogEntry, "timestamp">): void {
+    const full: ScanLogEntry = {
+      timestamp: new Date().toISOString(),
+      ...entry,
+    };
+
+    // Strip content field unless debug mode
+    if (!this.includeContent) {
+      delete full.content;
+    }
+
+    this.write(full);
+  }
+
+  /** Log a generic event */
+  logEvent(event: string, data: Record<string, unknown> = {}): void {
+    this.write({
+      timestamp: new Date().toISOString(),
+      event,
+      ...data,
+    });
+  }
+
+  private write(entry: object): void {
+    try {
+      // Check for log rotation every 100 writes to avoid stat() overhead
+      this.writeCount++;
+      if (this.writeCount % 100 === 0) {
+        rotateIfNeeded(this.logPath);
+      }
+
+      mkdirSync(dirname(this.logPath), { recursive: true });
+      appendFileSync(this.logPath, JSON.stringify(entry) + "\n", "utf-8");
+    } catch {
+      // Never crash the hook on log failure
+    }
+  }
+}