@oculum/scanner 1.0.0

package/src/layer2/ai-prompt-hygiene.ts

@@ -0,0 +1,411 @@
+/**
+ * Layer 2: AI Prompt Hygiene Detection
+ * Detects prompt injection vulnerabilities and secrets in LLM prompts
+ *
+ * Covers:
+ * - B1: Prompt & template hygiene (LLM01)
+ * - B3: Secrets & sensitive data in prompts (LLM06)
+ */
+
+import type { Vulnerability, VulnerabilitySeverity } from '../types'
+import {
+  isComment,
+  isTestOrMockFile,
+  isDocumentationFile,
+  isScannerOrFixtureFile,
+} from '../utils/context-helpers'
+
+/**
+ * Check if a file is in an LLM/AI context based on path and content
+ */
+function isLLMContextFile(filePath: string, content: string): boolean {
+  // File path indicators of AI/LLM code
+  const llmPathPatterns = [
+    /\/(ai|llm|chat|openai|anthropic|gpt|claude)\//i,
+    /\/(assistants?|agents?|prompts?)\//i,
+    /(chat|ai|llm|prompt|assistant|agent).*\.(ts|js|tsx|jsx|py)$/i,
+  ]
+
+  if (llmPathPatterns.some(p => p.test(filePath))) {
+    return true
+  }
+
+  // Content patterns suggesting LLM API usage
+  const llmContentPatterns = [
+    /\.create\s*\(\s*\{[^}]*messages\s*:/i,          // OpenAI/Anthropic SDK
+    /from\s+['"](@anthropic-ai|openai|langchain|llama[-_]?index)/i, // Imports
+    /\bsystem\s*:\s*['"`]/i,                         // System message definition
+    /role:\s*['"`](user|assistant|system)['"`]/i,    // Message roles
+    /\b(systemPrompt|userPrompt|assistantPrompt)\b/i, // Prompt variables
+    /messages\s*:\s*\[/i,                            // Messages array
+    /\.chat\.completions?\.create/i,                 // OpenAI chat completion
+    /\.messages\.create/i,                           // Anthropic messages
+    /ChatCompletion|MessageCreate/i,                 // SDK types
+  ]
+
+  return llmContentPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if user input delimiter/fence patterns are present
+ */
+function hasPromptDelimiters(lineContent: string, contextLines: string[]): boolean {
+  const context = [lineContent, ...contextLines].join('\n')
+
+  const delimiterPatterns = [
+    /```/,                          // Triple backticks
+    /<user>|<\/user>/i,             // XML-style user tags
+    /<human>|<\/human>/i,           // Human tags
+    /---+/,                         // Horizontal rules
+    /\[USER\]|\[\/USER\]/i,         // Bracket tags
+    /\{\{user\}\}/i,                // Template variable
+    /###\s*User|###\s*Input/i,      // Markdown headers
+    /INPUT:|OUTPUT:/i,              // Section markers
+  ]
+
+  return delimiterPatterns.some(p => p.test(context))
+}
+
+/**
+ * Check if content looks like proper parameterization rather than concatenation
+ */
+function isProperlyParameterized(lineContent: string): boolean {
+  const safePatterns = [
+    /\{\{.*\}\}/,                    // Handlebars/mustache templates
+    /\{[a-zA-Z_]+\}/,               // Python format strings (positional)
+    /\$\{.*\}.*sanitize|escape/i,   // Template with sanitization
+    /placeholder|PLACEHOLDER/,       // Explicit placeholders
+  ]
+
+  return safePatterns.some(p => p.test(lineContent))
+}
+
+// ============================================================================
+// Pattern Definitions
+// ============================================================================
+
+interface PromptHygienePattern {
+  name: string
+  pattern: RegExp
+  severity: VulnerabilitySeverity
+  description: string
+  suggestedFix: string
+  checkDelimiters?: boolean  // If true, downgrade if delimiters found
+}
+
+/**
+ * B1: Unsafe prompt interpolation patterns
+ */
+const UNSAFE_INTERPOLATION_PATTERNS: PromptHygienePattern[] = [
+  // Template literals with user input in system prompts
+  {
+    name: 'User input in system prompt',
+    pattern: /system\s*[=:]\s*`[^`]*\$\{.*(?:user|input|req|request|body|query|params|data).*\}[^`]*`/gi,
+    severity: 'high',
+    description: 'User input is directly interpolated into a system prompt. This creates a prompt injection vulnerability where attackers can manipulate the AI\'s behavior.',
+    suggestedFix: 'Use clear delimiters (```, <user>, ---) between system instructions and user content. Consider using structured input rather than string interpolation.',
+    checkDelimiters: true,
+  },
+  // String concatenation in prompt building
+  {
+    name: 'Prompt string concatenation with user input',
+    pattern: /(?:system|prompt|instruction)\s*[=+]\s*.*\+\s*(?:user|input|req|request|body|query|params)(?:\.|Input|\[)/gi,
+    severity: 'high',
+    description: 'User input is concatenated into prompt strings. Attackers can inject malicious instructions.',
+    suggestedFix: 'Use delimiters to clearly separate system instructions from user content. Example: ```user input here```',
+    checkDelimiters: true,
+  },
+  // Messages array with dynamic user content in system role
+  {
+    name: 'Dynamic content in system message',
+    pattern: /role:\s*['"`]system['"`]\s*,\s*content:\s*`[^`]*\$\{/gi,
+    severity: 'medium',
+    description: 'System message content includes dynamic values. If user-controlled, this enables prompt injection.',
+    suggestedFix: 'Keep system messages static. Place user input in messages with role: "user" instead.',
+    checkDelimiters: true,
+  },
+  // f-strings in Python with user input
+  {
+    name: 'Python f-string prompt with user input',
+    pattern: /f['"][^'"]*\{.*(?:user|input|request|body).*\}[^'"]*['"]/gi,
+    severity: 'high',
+    description: 'User input in Python f-string prompt creates prompt injection risk.',
+    suggestedFix: 'Use explicit delimiters: f"System instructions...\n---\n{user_input}\n---"',
+    checkDelimiters: true,
+  },
+]
+
+/**
+ * B3: Secrets in prompt context patterns
+ */
+const SECRETS_IN_PROMPTS_PATTERNS: PromptHygienePattern[] = [
+  // API keys in message content
+  {
+    name: 'API key in prompt content',
+    pattern: /(?:messages|prompt|system|content)\s*[=:][^;]*(?:sk-[a-zA-Z0-9]{20,}|api[_-]?key\s*[:=]\s*['"][^'"]{16,}['"])/gi,
+    severity: 'critical',
+    description: 'API key appears to be hardcoded in prompt content. Keys in prompts may be logged, cached, or sent to model providers.',
+    suggestedFix: 'Never include API keys in prompts. Use environment variables and keep them server-side only.',
+  },
+  // AWS keys in prompts
+  {
+    name: 'AWS credentials in prompt',
+    pattern: /(?:messages|prompt|system|content)\s*[=:][^;]*(?:AKIA[A-Z0-9]{16}|aws[_-]?(?:secret|access)[_-]?key)/gi,
+    severity: 'critical',
+    description: 'AWS credentials detected in prompt content.',
+    suggestedFix: 'Remove credentials from prompts. Use IAM roles or environment variables instead.',
+  },
+  // Database URLs with credentials
+  {
+    name: 'Database credentials in prompt',
+    pattern: /(?:messages|prompt|system|content).*(?:mongodb|postgres|mysql|redis):\/\/[^:]+:[^@]+@/gi,
+    severity: 'critical',
+    description: 'Database connection string with credentials in prompt. This exposes database access.',
+    suggestedFix: 'Never include connection strings in prompts. Reference data by ID instead.',
+  },
+  // Passwords in prompt context
+  {
+    name: 'Password in prompt content',
+    pattern: /(?:messages|prompt|content)\s*[=:].*(?:password|passwd|pwd)\s*[:=]\s*['"`][^'"`]{8,}/gi,
+    severity: 'high',
+    description: 'Password appears in prompt content. This may be logged or exposed to model providers.',
+    suggestedFix: 'Remove passwords from prompts. Use authentication tokens or session references instead.',
+  },
+  // Private keys
+  {
+    name: 'Private key in prompt',
+    pattern: /(?:messages|prompt|content).*(?:-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----)/gi,
+    severity: 'critical',
+    description: 'Private key material detected in prompt context.',
+    suggestedFix: 'Never include private keys in prompts. Sign data server-side instead.',
+  },
+  // Generic token patterns
+  {
+    name: 'Access token in prompt',
+    pattern: /(?:messages|prompt|content)\s*[=:].*(?:access[_-]?token|auth[_-]?token|bearer)\s*[:=]\s*['"`][a-zA-Z0-9_.-]{20,}/gi,
+    severity: 'high',
+    description: 'Access token detected in prompt content. Tokens in prompts risk exposure.',
+    suggestedFix: 'Do not include tokens in prompts. Pass token context through secure server-side channels.',
+  },
+]
+
+/**
+ * Missing boundary patterns - prompts without clear user/system separation
+ */
+const MISSING_BOUNDARY_PATTERNS: PromptHygienePattern[] = [
+  // Direct concatenation without any markers
+  {
+    name: 'Missing prompt boundaries',
+    pattern: /(?:content|prompt)\s*[:=]\s*(?:systemInstructions?|instructions?)\s*\+\s*(?:userMessage|userInput|input)/gi,
+    severity: 'medium',
+    description: 'Prompt concatenates system instructions with user input without clear boundaries.',
+    suggestedFix: 'Add delimiters between instructions and user content: "Instructions...\n---\n" + userInput + "\n---"',
+  },
+  // Template literals building prompts without delimiters
+  {
+    name: 'Unbounded template prompt',
+    pattern: /`(?:You are|As an|Your task)[^`]{20,}\$\{(?!.*(?:```|<user|---|\[USER))/gi,
+    severity: 'medium',
+    description: 'Prompt template interpolates values without clear delimiter boundaries.',
+    suggestedFix: 'Wrap interpolated user content with delimiters: ```${userInput}```',
+  },
+  // M5: RAG-specific prompt injection patterns
+  {
+    name: 'Retrieved context in system prompt',
+    pattern: /role:\s*['"`]system['"`]\s*,\s*content:\s*`[^`]*\$\{.*(?:context|chunks|documents|retrieved|sources)/gi,
+    severity: 'high',
+    description: 'Retrieved documents injected into system prompt. Poisoned documents could hijack model behavior.',
+    suggestedFix: 'Place retrieved context in user messages with clear delimiters. Use structured prompts separating instructions from data.',
+    checkDelimiters: true,
+  },
+  {
+    name: 'Mixed user input and retrieved context',
+    pattern: /\$\{.*(?:userInput|query|question).*\}[^`]*\$\{.*(?:context|chunks|documents).*\}|\$\{.*(?:context|chunks|documents).*\}[^`]*\$\{.*(?:userInput|query|question).*\}/gi,
+    severity: 'medium',
+    description: 'User input and retrieved context concatenated without clear separation. Both could contain injection attempts.',
+    suggestedFix: 'Clearly separate user input from retrieved context using XML tags or delimiters: <user_query>...</user_query><context>...</context>',
+    checkDelimiters: true,
+  },
+  {
+    name: 'RAG context directly interpolated',
+    pattern: /(?:system|prompt)\s*[:=].*(?:retrievedContext|ragContext|documentContext|knowledgeBase)\s*(?:\+|,)/gi,
+    severity: 'medium',
+    description: 'RAG context directly concatenated into prompt. Could enable data poisoning attacks.',
+    suggestedFix: 'Use structured prompt format with clear boundaries between instructions, context, and user input.',
+    checkDelimiters: true,
+  },
+]
+
+// ============================================================================
+// Detection Functions
+// ============================================================================
+
+/**
+ * Get surrounding context lines for analysis
+ */
+function getSurroundingContext(content: string, lineIndex: number, windowSize: number = 10): string[] {
+  const lines = content.split('\n')
+  const start = Math.max(0, lineIndex - windowSize)
+  const end = Math.min(lines.length, lineIndex + windowSize)
+  return lines.slice(start, end)
+}
+
+/**
+ * Main detection function for AI prompt hygiene issues
+ */
+export function detectAIPromptHygiene(
+  content: string,
+  filePath: string
+): Vulnerability[] {
+  const vulnerabilities: Vulnerability[] = []
+
+  // Skip non-applicable files
+  if (isScannerOrFixtureFile(filePath)) return vulnerabilities
+  if (isDocumentationFile(filePath)) return vulnerabilities
+
+  // Only scan files that appear to be in LLM context
+  if (!isLLMContextFile(filePath, content)) {
+    return vulnerabilities
+  }
+
+  const lines = content.split('\n')
+  const isTestFile = isTestOrMockFile(filePath)
+
+  // Scan for unsafe interpolation patterns (B1)
+  for (const pattern of UNSAFE_INTERPOLATION_PATTERNS) {
+    const regex = new RegExp(pattern.pattern.source, pattern.pattern.flags)
+    let match
+
+    while ((match = regex.exec(content)) !== null) {
+      const lineNumber = content.substring(0, match.index).split('\n').length
+      const lineContent = lines[lineNumber - 1]?.trim() || ''
+
+      // Skip comments
+      if (isComment(lineContent)) continue
+
+      // Skip if properly parameterized
+      if (isProperlyParameterized(lineContent)) continue
+
+      // Check for delimiters if applicable
+      let severity = pattern.severity
+      let description = pattern.description
+      const contextLines = getSurroundingContext(content, lineNumber - 1, 15)
+
+      if (pattern.checkDelimiters && hasPromptDelimiters(lineContent, contextLines)) {
+        // Delimiters present - downgrade severity
+        severity = 'info'
+        description += ' (Note: Delimiters detected in context, which mitigates this risk.)'
+      }
+
+      // Downgrade test files
+      if (isTestFile) {
+        severity = 'info'
+        description += ' (in test file)'
+      }
+
+      vulnerabilities.push({
+        id: `ai-prompt-${filePath}-${lineNumber}-${pattern.name.replace(/\s+/g, '-')}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'ai_prompt_injection',
+        title: pattern.name,
+        description,
+        suggestedFix: pattern.suggestedFix,
+        confidence: severity === 'info' ? 'low' : 'medium',
+        layer: 2,
+        requiresAIValidation: severity !== 'info',
+      })
+    }
+  }
+
+  // Scan for secrets in prompts (B3)
+  for (const pattern of SECRETS_IN_PROMPTS_PATTERNS) {
+    const regex = new RegExp(pattern.pattern.source, pattern.pattern.flags)
+    let match
+
+    while ((match = regex.exec(content)) !== null) {
+      const lineNumber = content.substring(0, match.index).split('\n').length
+      const lineContent = lines[lineNumber - 1]?.trim() || ''
+
+      // Skip comments
+      if (isComment(lineContent)) continue
+
+      // Check if it's an env var reference (safe pattern)
+      const isEnvRef = /process\.env|import\.meta\.env|os\.environ|getenv/i.test(lineContent)
+      if (isEnvRef) continue
+
+      let severity = pattern.severity
+      let description = pattern.description
+
+      // Downgrade test files but still flag
+      if (isTestFile) {
+        severity = severity === 'critical' ? 'medium' : 'low'
+        description += ' (in test file - still review for accidental commits)'
+      }
+
+      vulnerabilities.push({
+        id: `ai-secret-prompt-${filePath}-${lineNumber}-${pattern.name.replace(/\s+/g, '-')}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'hardcoded_secret', // Use existing category for consistency
+        title: pattern.name + ' (in LLM context)',
+        description: description + ' Secrets in prompts are especially risky as they may be logged, shared, or sent to external AI providers.',
+        suggestedFix: pattern.suggestedFix,
+        confidence: 'high',
+        layer: 2,
+        requiresAIValidation: false, // Secrets don't need AI validation - they're definitive
+      })
+    }
+  }
+
+  // Scan for missing boundary patterns (B1 continued)
+  for (const pattern of MISSING_BOUNDARY_PATTERNS) {
+    const regex = new RegExp(pattern.pattern.source, pattern.pattern.flags)
+    let match
+
+    while ((match = regex.exec(content)) !== null) {
+      const lineNumber = content.substring(0, match.index).split('\n').length
+      const lineContent = lines[lineNumber - 1]?.trim() || ''
+
+      // Skip comments
+      if (isComment(lineContent)) continue
+
+      const contextLines = getSurroundingContext(content, lineNumber - 1, 10)
+
+      // Skip if delimiters are present
+      if (hasPromptDelimiters(lineContent, contextLines)) continue
+
+      let severity = pattern.severity
+      let description = pattern.description
+
+      if (isTestFile) {
+        severity = 'info'
+        description += ' (in test file)'
+      }
+
+      vulnerabilities.push({
+        id: `ai-boundary-${filePath}-${lineNumber}-${pattern.name.replace(/\s+/g, '-')}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'ai_prompt_injection',
+        title: pattern.name,
+        description,
+        suggestedFix: pattern.suggestedFix,
+        confidence: 'medium',
+        layer: 2,
+        requiresAIValidation: true,
+      })
+    }
+  }
+
+  return vulnerabilities
+}
+
+// Export helper for use in other modules
+export { isLLMContextFile }