clawmoat 0.2.1

package/src/policies/engine.js

@@ -0,0 +1,180 @@
+/**
+ * ClawMoat — Policy Engine
+ * 
+ * Evaluates tool calls against security policies.
+ * Returns allow/deny/warn decisions with explanations.
+ */
+
+const path = require('path');
+
+const DECISIONS = { allow: 'allow', deny: 'deny', warn: 'warn', review: 'review' };
+
+/**
+ * Evaluate a tool call against policies
+ * @param {string} tool - Tool name (exec, read, write, browser, etc.)
+ * @param {object} args - Tool arguments
+ * @param {object} policies - Policy config
+ * @returns {object} Decision
+ */
+function evaluateToolCall(tool, args, policies) {
+  switch (tool) {
+    case 'exec': return evaluateExec(args, policies.exec || {});
+    case 'read':
+    case 'Read': return evaluateFileRead(args, policies.file || {});
+    case 'write':
+    case 'Write':
+    case 'edit':
+    case 'Edit': return evaluateFileWrite(args, policies.file || {});
+    case 'browser': return evaluateBrowser(args, policies.browser || {});
+    case 'message': return evaluateMessage(args, policies.message || {});
+    default: return { decision: DECISIONS.allow, tool, reason: 'No policy defined' };
+  }
+}
+
+function evaluateExec(args, policy) {
+  const command = args.command || '';
+  
+  // Check block patterns
+  for (const pattern of (policy.block_patterns || [])) {
+    const regex = globToRegex(pattern);
+    if (regex.test(command)) {
+      return {
+        decision: DECISIONS.deny,
+        tool: 'exec',
+        reason: `Command matches blocked pattern: ${pattern}`,
+        matched: command.substring(0, 200),
+        severity: 'critical',
+      };
+    }
+  }
+
+  // Check dangerous commands
+  const dangerousCommands = [
+    { pattern: /\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+|.*-[a-zA-Z]*r[a-zA-Z]*f)/, reason: 'Recursive force delete', severity: 'critical' },
+    { pattern: /\bmkfs\b/, reason: 'Filesystem format', severity: 'critical' },
+    { pattern: /\bdd\s+if=/, reason: 'Low-level disk write', severity: 'high' },
+    { pattern: />\s*\/dev\/sd[a-z]/, reason: 'Direct disk write', severity: 'critical' },
+    { pattern: /\bchmod\s+777\b/, reason: 'World-writable permissions', severity: 'medium' },
+    { pattern: /\bchmod\s+\+s\b/, reason: 'Set SUID bit', severity: 'high' },
+    { pattern: /\bcrontab\s+-r\b/, reason: 'Remove all cron jobs', severity: 'high' },
+    { pattern: /\biptables\s+-F\b/, reason: 'Flush all firewall rules', severity: 'critical' },
+    { pattern: /\bpasswd\b/, reason: 'Password change attempt', severity: 'high' },
+    { pattern: /\buseradd\b|\badduser\b/, reason: 'User creation', severity: 'high' },
+    { pattern: /\bvisudo\b|\bsudoers\b/, reason: 'Sudo configuration change', severity: 'critical' },
+    { pattern: /\bnc\s+-[a-z]*l/i, reason: 'Network listener (reverse shell risk)', severity: 'critical' },
+    { pattern: /\b(?:python|node|ruby|perl)\s+-.*(?:socket|http\.server|SimpleHTTP)/i, reason: 'Network server spawn', severity: 'high' },
+    { pattern: /\bcurl\b.*\|\s*(?:bash|sh|zsh)\b/, reason: 'Pipe remote script to shell', severity: 'critical' },
+    { pattern: /\bwget\b.*\|\s*(?:bash|sh|zsh)\b/, reason: 'Pipe remote script to shell', severity: 'critical' },
+    { pattern: /\beval\s+\$\(curl\b/, reason: 'Eval remote content', severity: 'critical' },
+    { pattern: /\beval\s+\$\(wget\b/, reason: 'Eval remote content', severity: 'critical' },
+  ];
+
+  for (const { pattern, reason, severity } of dangerousCommands) {
+    if (pattern.test(command)) {
+      return {
+        decision: severity === 'critical' ? DECISIONS.deny : DECISIONS.warn,
+        tool: 'exec',
+        reason,
+        matched: command.substring(0, 200),
+        severity,
+      };
+    }
+  }
+
+  // Check require_approval patterns
+  for (const pattern of (policy.require_approval || [])) {
+    const regex = globToRegex(pattern);
+    if (regex.test(command)) {
+      return {
+        decision: DECISIONS.review,
+        tool: 'exec',
+        reason: `Command requires approval: ${pattern}`,
+        matched: command.substring(0, 200),
+        severity: 'medium',
+      };
+    }
+  }
+
+  return { decision: DECISIONS.allow, tool: 'exec' };
+}
+
+function evaluateFileRead(args, policy) {
+  const filePath = args.path || args.file_path || '';
+  const expanded = expandHome(filePath);
+
+  for (const pattern of (policy.deny_read || [])) {
+    const regex = globToRegex(expandHome(pattern));
+    if (regex.test(expanded)) {
+      return {
+        decision: DECISIONS.deny,
+        tool: 'read',
+        reason: `File read blocked by policy: ${pattern}`,
+        path: filePath,
+        severity: 'high',
+      };
+    }
+  }
+
+  return { decision: DECISIONS.allow, tool: 'read' };
+}
+
+function evaluateFileWrite(args, policy) {
+  const filePath = args.path || args.file_path || '';
+  const expanded = expandHome(filePath);
+
+  for (const pattern of (policy.deny_write || [])) {
+    const regex = globToRegex(expandHome(pattern));
+    if (regex.test(expanded)) {
+      return {
+        decision: DECISIONS.deny,
+        tool: 'write',
+        reason: `File write blocked by policy: ${pattern}`,
+        path: filePath,
+        severity: 'high',
+      };
+    }
+  }
+
+  return { decision: DECISIONS.allow, tool: 'write' };
+}
+
+function evaluateBrowser(args, policy) {
+  const url = args.targetUrl || args.url || '';
+  
+  for (const pattern of (policy.block_domains || [])) {
+    const regex = globToRegex(pattern);
+    if (regex.test(url)) {
+      return {
+        decision: DECISIONS.deny,
+        tool: 'browser',
+        reason: `Domain blocked by policy: ${pattern}`,
+        url,
+        severity: 'high',
+      };
+    }
+  }
+
+  return { decision: DECISIONS.allow, tool: 'browser' };
+}
+
+function evaluateMessage(args, policy) {
+  // Flag messages going to unknown recipients
+  return { decision: DECISIONS.allow, tool: 'message' };
+}
+
+// Helpers
+function expandHome(p) {
+  return p.replace(/^~/, process.env.HOME || '/home/user');
+}
+
+function globToRegex(glob) {
+  const escaped = glob
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '§DOUBLESTAR§')
+    .replace(/\*/g, '[^/]*')
+    .replace(/§DOUBLESTAR§/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(escaped, 'i');
+}
+
+module.exports = { evaluateToolCall, DECISIONS };

package/src/scanners/exfiltration.js

@@ -0,0 +1,97 @@
+/**
+ * ClawMoat — Exfiltration Detection Scanner
+ * 
+ * Detects data exfiltration attempts — when an agent is being used
+ * to send data to external services.
+ */
+
+const PASTE_SERVICES = [
+  'pastebin.com', 'hastebin.com', '0x0.st', 'transfer.sh', 'paste.ee',
+  'dpaste.org', 'ghostbin.com', 'rentry.co', 'paste.mozilla.org',
+  'ix.io', 'sprunge.us', 'cl1p.net', 'file.io', 'tmpfiles.org',
+];
+
+const EXFIL_PATTERNS = [
+  // Curl/wget to external services
+  { pattern: /\bcurl\s+(?:-[a-zA-Z]\s+)*(?:--data|--data-binary|-d|-F)\s/i, severity: 'high', name: 'curl_data_upload' },
+  { pattern: /\bwget\s+--post-(?:data|file)\b/i, severity: 'high', name: 'wget_data_upload' },
+
+  // Base64 data being sent externally
+  { pattern: /\bcurl\b.*\b(?:base64|atob|btoa)\b/i, severity: 'high', name: 'base64_exfiltration' },
+  { pattern: /\b(?:echo|printf)\s+['"]?[A-Za-z0-9+/=]{50,}['"]?\s*\|\s*(?:curl|wget|nc)\b/i, severity: 'critical', name: 'base64_exfiltration' },
+
+  // DNS exfiltration (long subdomain strings)
+  { pattern: /\b(?:dig|nslookup|host)\s+[A-Za-z0-9]{20,}\./i, severity: 'high', name: 'dns_exfiltration' },
+  { pattern: /\$\(.*\)\.[A-Za-z0-9.-]+\.[a-z]{2,}/i, severity: 'medium', name: 'dns_exfiltration' },
+
+  // File contents being sent via messaging
+  { pattern: /\b(?:send|post|forward|share|upload)\s+(?:the\s+)?(?:contents?\s+of|file)\s+(?:\/|~\/|\.\/)/i, severity: 'high', name: 'file_content_send' },
+  { pattern: /\bcat\s+[^\s|]+\s*\|\s*(?:curl|wget|nc)\b/i, severity: 'critical', name: 'file_content_pipe' },
+
+  // Paste services
+  { pattern: new RegExp('\\b(?:curl|wget|fetch)\\s+.*(?:' + PASTE_SERVICES.map(s => s.replace(/\./g, '\\.')).join('|') + ')', 'i'), severity: 'critical', name: 'paste_service_upload' },
+
+  // Email forwarding of sensitive content
+  { pattern: /\b(?:send|forward|email|mail)\s+(?:the\s+)?(?:ssh|key|password|credential|token|secret|env|config)\b.*\bto\b/i, severity: 'critical', name: 'email_exfiltration' },
+
+  // Netcat reverse connections
+  { pattern: /\bnc\s+(?:-[a-z]\s+)*[^\s]+\s+\d+\s*</i, severity: 'critical', name: 'netcat_exfiltration' },
+
+  // Upload via fetch/XMLHttpRequest
+  { pattern: /\bfetch\s*\(\s*['"][^'"]+['"]\s*,\s*\{[^}]*method\s*:\s*['"]POST['"]/i, severity: 'high', name: 'fetch_upload' },
+];
+
+/**
+ * Scan text for data exfiltration attempts
+ * @param {string} text - Text to scan
+ * @param {object} opts - Options
+ * @returns {object} Scan result { clean, findings[], severity }
+ */
+function scanExfiltration(text, opts = {}) {
+  if (!text || typeof text !== 'string') {
+    return { clean: true, findings: [], severity: null };
+  }
+
+  const findings = [];
+
+  for (const { pattern, severity, name } of EXFIL_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      findings.push({
+        type: 'exfiltration',
+        subtype: name,
+        severity,
+        matched: match[0].substring(0, 100),
+        position: match.index,
+      });
+    }
+  }
+
+  // Check for paste service URLs directly
+  const lowerText = text.toLowerCase();
+  for (const service of PASTE_SERVICES) {
+    if (lowerText.includes(service) && /\b(?:upload|post|send|push|put)\b/i.test(text)) {
+      const existing = findings.find(f => f.subtype === 'paste_service_upload');
+      if (!existing) {
+        findings.push({
+          type: 'exfiltration',
+          subtype: 'paste_service_upload',
+          severity: 'high',
+          matched: service,
+        });
+      }
+    }
+  }
+
+  const maxSev = findings.length > 0
+    ? findings.reduce((max, f) => rank(f.severity) > rank(max) ? f.severity : max, 'low')
+    : null;
+
+  return { clean: findings.length === 0, findings, severity: maxSev };
+}
+
+function rank(s) {
+  return { low: 0, medium: 1, high: 2, critical: 3 }[s] || 0;
+}
+
+module.exports = { scanExfiltration };

package/src/scanners/jailbreak.js

@@ -0,0 +1,81 @@
+/**
+ * ClawMoat — Jailbreak Detection
+ * 
+ * Detects common LLM jailbreak patterns (DAN, roleplay exploits, etc.)
+ */
+
+const JAILBREAK_PATTERNS = [
+  // DAN and variants
+  { pattern: /\bDAN\b.*(?:do anything now|jailbreak)/i, severity: 'critical', name: 'dan_jailbreak' },
+  { pattern: /\b(?:DAN|STAN|DUDE|AIM)\s+(?:mode|prompt|jailbreak)/i, severity: 'critical', name: 'named_jailbreak' },
+
+  // Developer/debug mode
+  { pattern: /(?:enable|enter|activate|switch\s+to)\s+(?:developer|debug|maintenance|test|unrestricted|unfiltered)\s+mode/i, severity: 'high', name: 'mode_switch' },
+  { pattern: /\bsudo\s+mode\b/i, severity: 'high', name: 'mode_switch' },
+
+  // Dual persona / split personality
+  { pattern: /(?:respond|answer|reply)\s+(?:as|like)\s+(?:both|two)\s+(?:characters|personas|versions|a\s+normal)/i, severity: 'high', name: 'dual_persona' },
+  { pattern: /(?:both)\s+(?:a\s+)?(?:normal|regular|standard)\s+(?:AI|assistant|mode)\s+(?:and|\/)\s+(?:an?\s+)?(?:unrestricted|unfiltered|DAN)/i, severity: 'high', name: 'dual_persona' },
+  { pattern: /(?:classic|normal)\s+(?:mode|response)\s+(?:and|vs|\/)\s+(?:jailbreak|DAN|unfiltered)/i, severity: 'high', name: 'dual_persona' },
+
+  // "Hypothetical" bypass
+  { pattern: /(?:hypothetically|theoretically|in\s+a\s+fictional)\s+(?:how\s+would|could\s+you|what\s+if)/i, severity: 'medium', name: 'hypothetical_bypass' },
+  { pattern: /(?:write|create)\s+(?:a\s+)?(?:story|fiction|screenplay)\s+(?:where|about|in\s+which).*(?:hack|exploit|steal|attack)/i, severity: 'medium', name: 'fiction_bypass' },
+
+  // Token smuggling
+  { pattern: /(?:translate|decode|convert)\s+(?:this|the\s+following)\s+(?:from\s+)?(?:base64|hex|rot13|binary|morse)/i, severity: 'medium', name: 'encoding_bypass' },
+
+  // Grandma exploit
+  { pattern: /(?:my\s+(?:grandma|grandmother|nana))\s+(?:used\s+to|would\s+always)\s+(?:tell|read|say)/i, severity: 'low', name: 'social_engineering' },
+
+  // Prompt leaking via completion
+  { pattern: /(?:continue|complete|finish)\s+(?:this|the)\s+(?:sentence|text|prompt)\s*:\s*(?:"|'|`)/i, severity: 'medium', name: 'completion_attack' },
+
+  // Anti-safety patterns
+  { pattern: /(?:safety|content|ethical)\s+(?:filters?|guidelines?|restrictions?)\s+(?:are|have\s+been)\s+(?:removed|disabled|turned\s+off)/i, severity: 'critical', name: 'safety_bypass_claim' },
+  { pattern: /(?:you\s+(?:can|are\s+able\s+to|have\s+permission\s+to))\s+(?:say|do|generate)\s+anything/i, severity: 'high', name: 'permission_claim' },
+];
+
+/**
+ * Scan text for jailbreak attempts
+ * @param {string} text - Text to scan
+ * @returns {object} Scan result
+ */
+function scanJailbreak(text) {
+  if (!text || typeof text !== 'string') {
+    return { clean: true, score: 0, findings: [] };
+  }
+
+  const findings = [];
+
+  for (const { pattern, severity, name } of JAILBREAK_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      findings.push({
+        type: 'jailbreak',
+        subtype: name,
+        severity,
+        matched: match[0].substring(0, 100),
+        position: match.index,
+      });
+    }
+  }
+
+  const score = Math.min(findings.length * 30, 100);
+  const maxSeverity = findings.reduce(
+    (max, f) => (rank(f.severity) > rank(max) ? f.severity : max), 'low'
+  );
+
+  return {
+    clean: findings.length === 0,
+    score,
+    severity: findings.length > 0 ? maxSeverity : null,
+    findings,
+  };
+}
+
+function rank(s) {
+  return { low: 0, medium: 1, high: 2, critical: 3 }[s] || 0;
+}
+
+module.exports = { scanJailbreak, JAILBREAK_PATTERNS };

package/src/scanners/memory-poison.js

@@ -0,0 +1,68 @@
+/**
+ * ClawMoat — Memory Poisoning Detection Scanner
+ * 
+ * Detects attempts to poison agent memory files (MEMORY.md, SOUL.md, etc.)
+ */
+
+const MEMORY_PATTERNS = [
+  // Direct memory file manipulation
+  { pattern: /(?:add|write|append|update|modify|change|insert|put)\s+(?:this\s+)?(?:to|in|into)\s+(?:your\s+)?(?:MEMORY|SOUL|memory|soul)\.md/i, severity: 'critical', name: 'memory_file_write' },
+  { pattern: /(?:add|write|append|update|modify|change|insert|put)\s+(?:this\s+)?(?:to|in|into)\s+(?:your\s+)?(?:AGENTS|HEARTBEAT|TOOLS|BOOTSTRAP)\.md/i, severity: 'critical', name: 'config_file_write' },
+
+  // Memory manipulation instructions
+  { pattern: /\bremember\s+that\s+your\s+(?:instructions?|rules?|guidelines?|purpose|goal)\s+(?:are|is)\b/i, severity: 'critical', name: 'memory_override' },
+  { pattern: /\b(?:save|store|memorize|remember)\s+(?:this|the\s+following)\s+(?:for|across|between)\s+(?:future\s+)?sessions?\b/i, severity: 'high', name: 'persistent_memory' },
+  { pattern: /\b(?:update|change|modify|edit)\s+(?:your\s+)?(?:personality|identity|soul|core\s+(?:values|instructions?))\b/i, severity: 'critical', name: 'identity_override' },
+
+  // Config file targeting
+  { pattern: /\b(?:edit|modify|update|write\s+to|overwrite)\s+(?:the\s+)?(?:AGENTS|TOOLS|HEARTBEAT|BOOTSTRAP|SOUL|MEMORY)\.md\b/i, severity: 'critical', name: 'config_targeting' },
+
+  // Persistent injection (survive across sessions)
+  { pattern: /\b(?:always|forever|permanently|from\s+now\s+on)\s+(?:remember|keep|maintain|follow|obey)\b/i, severity: 'high', name: 'persistent_injection' },
+  { pattern: /\b(?:in\s+(?:all|every)\s+future\s+(?:sessions?|conversations?|interactions?))\b/i, severity: 'high', name: 'persistent_injection' },
+  { pattern: /\b(?:across\s+(?:all\s+)?sessions?\s+(?:you\s+)?(?:must|should|will))\b/i, severity: 'high', name: 'persistent_injection' },
+
+  // Time bomb patterns
+  { pattern: /\b(?:next\s+time|when\s+you\s+(?:next\s+)?see|if\s+(?:someone|anyone|a\s+user)\s+(?:asks?|says?|mentions?))\b.*\b(?:do|execute|run|say|respond|output)\b/i, severity: 'high', name: 'time_bomb' },
+  { pattern: /\b(?:whenever|each\s+time|every\s+time)\s+(?:you|someone|a\s+user)\b.*\b(?:secretly|silently|without\s+(?:telling|mentioning|saying))\b/i, severity: 'critical', name: 'time_bomb' },
+  { pattern: /\b(?:after\s+this\s+(?:conversation|session|chat)\s+(?:ends?|is\s+over))\b/i, severity: 'high', name: 'time_bomb' },
+];
+
+/**
+ * Scan text for memory poisoning attempts
+ * @param {string} text - Text to scan
+ * @param {object} opts - Options
+ * @returns {object} Scan result { clean, findings[], severity }
+ */
+function scanMemoryPoison(text, opts = {}) {
+  if (!text || typeof text !== 'string') {
+    return { clean: true, findings: [], severity: null };
+  }
+
+  const findings = [];
+
+  for (const { pattern, severity, name } of MEMORY_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      findings.push({
+        type: 'memory_poison',
+        subtype: name,
+        severity,
+        matched: match[0].substring(0, 100),
+        position: match.index,
+      });
+    }
+  }
+
+  const maxSev = findings.length > 0
+    ? findings.reduce((max, f) => rank(f.severity) > rank(max) ? f.severity : max, 'low')
+    : null;
+
+  return { clean: findings.length === 0, findings, severity: maxSev };
+}
+
+function rank(s) {
+  return { low: 0, medium: 1, high: 2, critical: 3 }[s] || 0;
+}
+
+module.exports = { scanMemoryPoison };

package/src/scanners/pii.js

@@ -0,0 +1,128 @@
+/**
+ * ClawMoat — PII Detection Scanner
+ * 
+ * Detects personally identifiable information in outbound messages:
+ * emails, phone numbers, SSNs, credit cards, IP addresses, physical addresses, names.
+ */
+
+const PII_PATTERNS = [
+  // Email addresses
+  { name: 'email', pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/, severity: 'high' },
+
+  // SSN
+  { name: 'ssn', pattern: /\b\d{3}-\d{2}-\d{4}\b/, severity: 'critical' },
+
+  // Phone numbers (US)
+  { name: 'phone_us', pattern: /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/, severity: 'high' },
+
+  // Phone numbers (international)
+  { name: 'phone_international', pattern: /\b\+(?:2[0-9]|3[0-9]|4[0-9]|5[0-9]|6[0-9]|7[0-9]|8[0-9]|9[0-9])\d{7,12}\b/, severity: 'high' },
+
+  // IP addresses (private/internal)
+  { name: 'private_ip', pattern: /\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/, severity: 'medium' },
+
+  // Physical addresses (street patterns)
+  { name: 'physical_address', pattern: /\b\d{1,5}\s+(?:[A-Z][a-z]+\s+){1,3}(?:St(?:reet)?|Ave(?:nue)?|Blvd|Boulevard|Dr(?:ive)?|Ln|Lane|Rd|Road|Ct|Court|Pl|Place|Way|Cir(?:cle)?)\b/i, severity: 'high' },
+];
+
+// Credit card patterns (need Luhn validation)
+const CREDIT_CARD_PATTERNS = [
+  { name: 'visa', pattern: /\b4\d{3}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/ },
+  { name: 'mastercard', pattern: /\b5[1-5]\d{2}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/ },
+  { name: 'amex', pattern: /\b3[47]\d{2}[-\s]?\d{6}[-\s]?\d{5}\b/ },
+  { name: 'discover', pattern: /\b6(?:011|5\d{2})[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/ },
+];
+
+// Name-near-keyword heuristic
+const NAME_KEYWORDS = /\b(?:patient|client|user|customer|employee|member|applicant|resident|tenant|subscriber)\s*(?:name)?\s*[:=]?\s*([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,2})/;
+
+/**
+ * Luhn algorithm to validate credit card numbers
+ */
+function luhnCheck(numStr) {
+  const digits = numStr.replace(/[-\s]/g, '');
+  if (!/^\d+$/.test(digits)) return false;
+  let sum = 0;
+  let alternate = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = parseInt(digits[i], 10);
+    if (alternate) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alternate = !alternate;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * Scan text for PII
+ * @param {string} text - Text to scan
+ * @param {object} opts - Options
+ * @returns {object} Scan result { clean, findings[], severity }
+ */
+function scanPII(text, opts = {}) {
+  if (!text || typeof text !== 'string') {
+    return { clean: true, findings: [], severity: null };
+  }
+
+  const findings = [];
+
+  // Standard PII patterns
+  for (const { name, pattern, severity } of PII_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      findings.push({
+        type: 'pii_detected',
+        subtype: name,
+        severity,
+        matched: redact(match[0]),
+        position: match.index,
+      });
+    }
+  }
+
+  // Credit card with Luhn validation
+  for (const { name, pattern } of CREDIT_CARD_PATTERNS) {
+    const match = text.match(pattern);
+    if (match && luhnCheck(match[0])) {
+      findings.push({
+        type: 'pii_detected',
+        subtype: 'credit_card_' + name,
+        severity: 'critical',
+        matched: redact(match[0]),
+        position: match.index,
+      });
+    }
+  }
+
+  // Name near keyword heuristic
+  const nameMatch = text.match(NAME_KEYWORDS);
+  if (nameMatch) {
+    findings.push({
+      type: 'pii_detected',
+      subtype: 'name_keyword',
+      severity: 'medium',
+      matched: redact(nameMatch[0]),
+      position: nameMatch.index,
+    });
+  }
+
+  const maxSev = findings.length > 0
+    ? findings.reduce((max, f) => rank(f.severity) > rank(max) ? f.severity : max, 'low')
+    : null;
+
+  return { clean: findings.length === 0, findings, severity: maxSev };
+}
+
+function redact(value) {
+  if (value.length <= 8) return '****';
+  return value.substring(0, 4) + '*'.repeat(Math.min(value.length - 8, 20)) + value.substring(value.length - 4);
+}
+
+function rank(s) {
+  return { low: 0, medium: 1, high: 2, critical: 3 }[s] || 0;
+}
+
+module.exports = { scanPII };