@oculum/scanner 1.0.0

package/src/layer2/ai-agent-tools.ts

@@ -0,0 +1,601 @@
+/**
+ * Layer 2: AI Agent Tool Permission Detection
+ * Detects overly permissive agent tools and missing authorization checks
+ *
+ * Covers B4: Agent/tool orchestration logic
+ *
+ * Issues detected:
+ * - Tools with unrestricted file system access
+ * - Tools with unrestricted network access
+ * - Tools with shell/code execution capability
+ * - Tools without user/tenant context verification
+ * - Database tools without proper scoping
+ */
+
+import type { Vulnerability, VulnerabilitySeverity } from '../types'
+import {
+  isComment,
+  isTestOrMockFile,
+  isScannerOrFixtureFile,
+  isExampleDirectory,
+  isLibraryCode,
+} from '../utils/context-helpers'
+
+// ============================================================================
+// Agent/Tool Context Detection
+// ============================================================================
+
+/**
+ * Check if file contains agent or tool definitions
+ */
+function isAgentOrToolFile(filePath: string, content: string): boolean {
+  // File path indicators
+  const agentPathPatterns = [
+    /\/(agents?|tools?|functions?|actions?)\//i,
+    /\/(mcp|langchain|llamaindex|autogen)\//i,
+    /(agent|tool|function|action).*\.(ts|js|py)$/i,
+  ]
+
+  if (agentPathPatterns.some(p => p.test(filePath))) {
+    return true
+  }
+
+  // Content patterns indicating tool/agent definitions
+  const toolDefinitionPatterns = [
+    /@tool/i,                             // Python decorator
+    /def\s+\w+_tool\s*\(/i,              // Python tool function
+    /defineTool\s*\(/i,                   // JS/TS tool definition
+    /createTool\s*\(/i,                   // Tool creation
+    /\.registerTool\s*\(/i,               // Tool registration
+    /\.addTool\s*\(/i,                    // Adding tool to agent
+    /tools\s*:\s*\[/i,                    // Tools array
+    /FunctionTool|StructuredTool/i,       // LangChain tools
+    /tool_choice|function_call/i,         // OpenAI function calling
+    /Tool\s*\(\s*\{/i,                    // Tool configuration object
+    /type:\s*['"`]function['"`]/i,        // OpenAI function type
+    /mcpServer|McpServer/i,               // MCP server
+  ]
+
+  return toolDefinitionPatterns.some(p => p.test(content))
+}
+
+/**
+ * Find tool definition boundaries (start and end lines)
+ */
+function findToolDefinitionContext(
+  content: string,
+  lineNumber: number,
+  windowSize: number = 30
+): { context: string; startLine: number; endLine: number } {
+  const lines = content.split('\n')
+  const startLine = Math.max(0, lineNumber - windowSize)
+  const endLine = Math.min(lines.length, lineNumber + windowSize)
+
+  return {
+    context: lines.slice(startLine, endLine).join('\n'),
+    startLine,
+    endLine,
+  }
+}
+
+// ============================================================================
+// Authorization Detection
+// ============================================================================
+
+/**
+ * Check if user context is verified in tool
+ */
+function hasUserContextVerification(context: string): boolean {
+  const userContextPatterns = [
+    /user[_.]?id/i,
+    /userId/i,
+    /currentUser/i,
+    /req\.user/i,
+    /request\.user/i,
+    /session\.user/i,
+    /getUser\s*\(/i,
+    /getCurrentUser\s*\(/i,
+    /authenticatedUser/i,
+    /ctx\.user/i,
+    /context\.user/i,
+  ]
+
+  return userContextPatterns.some(p => p.test(context))
+}
+
+/**
+ * Check if tenant/organization context is verified
+ */
+function hasTenantContextVerification(context: string): boolean {
+  const tenantContextPatterns = [
+    /tenant[_.]?id/i,
+    /tenantId/i,
+    /org[_.]?id/i,
+    /orgId/i,
+    /organization[_.]?id/i,
+    /workspace[_.]?id/i,
+    /workspaceId/i,
+    /team[_.]?id/i,
+    /teamId/i,
+    /account[_.]?id/i,
+    /accountId/i,
+  ]
+
+  return tenantContextPatterns.some(p => p.test(context))
+}
+
+/**
+ * Patterns indicating strong/verified restrictions (actual implementation)
+ */
+const STRONG_RESTRICTION_PATTERNS = [
+  // Sandboxing libraries and environments
+  /\bvm2\b/i,
+  /\bisolated-vm\b/i,
+  /\bquickjs\b/i,
+  /\bsandboxed\b/i,
+  /\bRestrictedPython\b/i,
+  /\bnsjail\b/i,
+  /\bfirejail\b/i,
+  /\bgvisor\b/i,
+
+  // Explicit path/resource restrictions with arrays
+  /allowed(?:Paths|Files|Dirs|Hosts|Urls|Commands)\s*[=:]\s*\[/i,
+  /(?:white|allow)list\s*[=:]\s*\[/i,
+  /(?:blocked|denied|forbidden)(?:Paths|Hosts|Commands)\s*[=:]\s*\[/i,
+
+  // Path validation functions
+  /validatePath\s*\(/i,
+  /isAllowedPath\s*\(/i,
+  /checkPathAccess\s*\(/i,
+  /resolvePath.*allowed/i,
+  /path\.resolve.*includes/i,
+
+  // Sandbox configuration objects
+  /sandbox\s*[=:]\s*(?:true|\{)/i,
+  /readonly\s*[=:]\s*true/i,
+  /readOnly\s*[=:]\s*true/i,
+
+  // Container/isolation patterns
+  /\b(?:docker|podman)\s+run\b.*--read-only/i,
+  /seccomp/i,
+  /capabilities\s*[=:]\s*\[\s*\]/i,  // Empty capabilities = restricted
+
+  // Permission checking code
+  /if\s*\(\s*!?\s*(?:allowed|permitted|authorized)/i,
+  /(?:check|verify|validate)(?:Access|Permission|Capability)\s*\(/i,
+]
+
+/**
+ * Patterns indicating weak/unverified restriction mentions (comments, TODOs)
+ */
+const WEAK_RESTRICTION_PATTERNS = [
+  // Comments mentioning restrictions without implementation
+  /\/\/.*(?:sandbox|restrict|allowlist|whitelist|todo)/i,
+  /\/\*.*(?:sandbox|restrict|allowlist|whitelist|todo).*\*\//i,
+  /#.*(?:sandbox|restrict|allowlist|whitelist|todo)/i,
+
+  // TODOs and FIXMEs
+  /TODO.*(?:add|implement|enable).*(?:sandbox|restrict|allowlist)/i,
+  /FIXME.*(?:sandbox|restrict|security)/i,
+
+  // Variable names without assignment
+  /const\s+(?:sandbox|allowlist|whitelist)\s*;/i,
+]
+
+/**
+ * Check if tool has strong/verified access restrictions
+ * These are actual implementations, not just mentions
+ */
+function hasStrongRestrictions(context: string): boolean {
+  // Check for strong patterns
+  const hasStrong = STRONG_RESTRICTION_PATTERNS.some(p => p.test(context))
+  if (!hasStrong) return false
+
+  // Verify it's not just a weak mention
+  const isWeak = WEAK_RESTRICTION_PATTERNS.some(p => p.test(context))
+  return !isWeak
+}
+
+/**
+ * Check if tool has any access restrictions/allowlists (including weak mentions)
+ */
+function hasAccessRestrictions(context: string): boolean {
+  const restrictionPatterns = [
+    /allowedPaths/i,
+    /allowedFiles/i,
+    /allowedDirs/i,
+    /allowedHosts/i,
+    /allowedUrls/i,
+    /allowedCommands/i,
+    /allowedOperations/i,
+    /whitelist/i,
+    /allowlist/i,
+    /permissions?:/i,
+    /capabilities:/i,
+    /restrictions?:/i,
+    /constraints?:/i,
+    /sandbox/i,
+    /readonly/i,
+    /readOnly/i,
+  ]
+
+  return restrictionPatterns.some(p => p.test(context))
+}
+
+// ============================================================================
+// Pattern Definitions
+// ============================================================================
+
+type ToolRiskType = 'filesystem' | 'network' | 'code_execution' | 'database' | 'shell'
+
+interface ToolPattern {
+  name: string
+  pattern: RegExp
+  riskType: ToolRiskType
+  baseSeverity: VulnerabilitySeverity
+  description: string
+  suggestedFix: string
+  requiresUserContext?: boolean
+  requiresTenantContext?: boolean
+  requiresRestrictions?: boolean
+}
+
+const OVERPERMISSIVE_TOOL_PATTERNS: ToolPattern[] = [
+  // ========== Filesystem Access Tools ==========
+  {
+    name: 'Unrestricted file read tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:read|get).*file|(?:fs|filesystem).*(?:read|get)/gi,
+    riskType: 'filesystem',
+    baseSeverity: 'high',
+    description: 'Tool provides file system read access. Without restrictions, agents can access any file the process can read.',
+    suggestedFix: 'Add allowedPaths restriction. Example: { allowedPaths: ["/data/user-uploads"] }. Validate paths stay within allowed directories.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'Unrestricted file write tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:write|create|save).*file|(?:fs|filesystem).*(?:write|create)/gi,
+    riskType: 'filesystem',
+    baseSeverity: 'high',
+    description: 'Tool provides file system write access. Agents could overwrite critical files or create malicious files.',
+    suggestedFix: 'Restrict to specific directories. Validate file extensions. Implement size limits. Consider using signed URLs instead of direct file access.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'File deletion tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:delete|remove).*file|(?:fs|filesystem).*(?:delete|unlink|remove)/gi,
+    riskType: 'filesystem',
+    baseSeverity: 'high',
+    description: 'Tool provides file deletion capability. High risk of data loss if misused.',
+    suggestedFix: 'Implement soft-delete instead of hard delete. Require confirmation. Restrict to user-owned files only.',
+    requiresRestrictions: true,
+    requiresUserContext: true,
+  },
+
+  // ========== Network Access Tools ==========
+  {
+    name: 'Unrestricted HTTP/fetch tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:http|fetch|request|api)|tool.*(?:fetch|request)\s*\(/gi,
+    riskType: 'network',
+    baseSeverity: 'medium',
+    description: 'Tool provides network/HTTP access. Without restrictions, agents could make requests to internal services (SSRF) or exfiltrate data.',
+    suggestedFix: 'Add allowedHosts configuration. Block internal/private IP ranges. Implement request signing for sensitive operations.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'Web scraping tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:scrape|crawl|browse)/gi,
+    riskType: 'network',
+    baseSeverity: 'medium',
+    description: 'Tool provides web scraping capability. Could be used for SSRF or accessing internal resources.',
+    suggestedFix: 'Restrict to allowed domains. Block internal IP ranges. Implement rate limiting.',
+    requiresRestrictions: true,
+  },
+
+  // ========== Code Execution Tools ==========
+  {
+    name: 'Code execution tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:execute|run|eval).*(?:code|script)|tool.*(?:eval|exec)\s*\(/gi,
+    riskType: 'code_execution',
+    baseSeverity: 'critical',
+    description: 'Tool provides code execution capability. This is extremely dangerous without sandboxing.',
+    suggestedFix: 'Use vm2, isolated-vm, or similar sandboxing. Implement timeout and memory limits. Restrict available APIs/modules.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'Python interpreter tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*python.*(?:exec|run|interpret)|PythonREPL|python_repl/gi,
+    riskType: 'code_execution',
+    baseSeverity: 'critical',
+    description: 'Tool provides Python execution capability. Can execute arbitrary system commands.',
+    suggestedFix: 'Use RestrictedPython or sandboxed environments. Block dangerous modules (os, subprocess, socket). Implement resource limits.',
+    requiresRestrictions: true,
+  },
+
+  // ========== Shell/Command Tools ==========
+  {
+    name: 'Shell command tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:shell|command|terminal|bash)|ShellTool|BashTool/gi,
+    riskType: 'shell',
+    baseSeverity: 'critical',
+    description: 'Tool provides shell command execution. Allows arbitrary system commands.',
+    suggestedFix: 'Implement strict command allowlisting. Use parameterized commands (execFile, not exec). Consider removing this capability entirely.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'System command tool',
+    pattern: /(?:@tool|defineTool|createTool)[^)]*(?:system|exec|spawn|subprocess)/gi,
+    riskType: 'shell',
+    baseSeverity: 'critical',
+    description: 'Tool with system command execution capability.',
+    suggestedFix: 'Restrict to specific commands via allowlist. Validate all arguments. Log all command executions.',
+    requiresRestrictions: true,
+  },
+
+  // ========== Database Tools ==========
+  {
+    name: 'Database query tool',
+    pattern: /(?:@tool|defineTool|createTool|Tool\s*\()[^)]*(?:query|sql|database)|tool.*(?:query|execute)\s*\(/gi,
+    riskType: 'database',
+    baseSeverity: 'high',
+    description: 'Tool provides database query access. Without scoping, agents could access any data.',
+    suggestedFix: 'Always scope queries to current user/tenant. Use row-level security (RLS). Implement read-only mode for most operations.',
+    requiresUserContext: true,
+    requiresTenantContext: true,
+  },
+  {
+    name: 'Raw SQL tool',
+    pattern: /(?:@tool|defineTool|createTool)[^)]*(?:raw.*sql|execute.*sql)/gi,
+    riskType: 'database',
+    baseSeverity: 'critical',
+    description: 'Tool allows raw SQL execution. High risk of SQL injection and unauthorized data access.',
+    suggestedFix: 'Use parameterized queries only. Implement query validation. Consider using an ORM instead of raw SQL.',
+    requiresUserContext: true,
+    requiresTenantContext: true,
+  },
+
+  // ========== M5: MCP Server Tools ==========
+  {
+    name: 'MCP server tool registration',
+    pattern: /(?:McpServer|Server)\s*\([^)]*\).*(?:setRequestHandler|tool|registerTool)|server\.tool\s*\(/gi,
+    riskType: 'code_execution',
+    baseSeverity: 'high',
+    description: 'MCP (Model Context Protocol) server registering tools. Verify tool capabilities are appropriately restricted.',
+    suggestedFix: 'Add capability restrictions to MCP server. Implement allowlists for file paths, network hosts, and commands.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'MCP tool with shell access',
+    pattern: /server\.tool\s*\([^)]*(?:name:\s*['"`](?:run|exec|shell|command)[^)]*|(?:exec|spawn|shell)\s*\()/gi,
+    riskType: 'shell',
+    baseSeverity: 'critical',
+    description: 'MCP tool with shell command execution capability. Extremely dangerous without restrictions.',
+    suggestedFix: 'Use allowlist of permitted commands. Never allow arbitrary command execution. Consider read-only alternatives.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'MCP file system tool',
+    pattern: /server\.tool\s*\([^)]*(?:name:\s*['"`](?:read|write|create|delete|list).*(?:file|dir)[^)]*|fs\.|readFile|writeFile)/gi,
+    riskType: 'filesystem',
+    baseSeverity: 'high',
+    description: 'MCP tool with file system access. Agents could access or modify arbitrary files.',
+    suggestedFix: 'Restrict to specific directories with allowedPaths. Implement path validation. Consider read-only access.',
+    requiresRestrictions: true,
+  },
+
+  // ========== M5: Vercel AI SDK Tools ==========
+  {
+    name: 'Vercel AI SDK tool definition',
+    pattern: /tool\s*\(\s*\{[^}]*(?:execute|parameters)/gi,
+    riskType: 'code_execution',
+    baseSeverity: 'medium',
+    description: 'Vercel AI SDK tool definition. Review the execute function for dangerous operations.',
+    suggestedFix: 'Validate tool parameters against expected schema. Implement proper access controls within execute function.',
+    requiresUserContext: true,
+  },
+  {
+    name: 'AI SDK tool with dangerous execute',
+    pattern: /tool\s*\(\s*\{[^}]*execute\s*:\s*async[^}]*(?:exec|spawn|eval|fs\.|fetch\s*\()[^}]*\}/gi,
+    riskType: 'code_execution',
+    baseSeverity: 'high',
+    description: 'Vercel AI SDK tool with potentially dangerous execute function (shell, eval, fs, or network access).',
+    suggestedFix: 'Add validation and restrictions in execute function. Implement allowlists for external operations.',
+    requiresRestrictions: true,
+  },
+  {
+    name: 'StreamableUI tool action',
+    pattern: /createStreamableUI.*tool.*\{.*action/gi,
+    riskType: 'code_execution',
+    baseSeverity: 'medium',
+    description: 'Streamable UI tool with server action. Ensure proper authorization before state mutations.',
+    suggestedFix: 'Verify user authentication and authorization before executing actions. Validate all inputs.',
+    requiresUserContext: true,
+  },
+]
+
+/**
+ * Patterns for missing authorization in tools
+ */
+const MISSING_AUTH_PATTERNS: ToolPattern[] = [
+  {
+    name: 'Tool without user context',
+    pattern: /(?:@tool|defineTool|createTool|\.registerTool|\.addTool)\s*\([^)]*(?:async\s+)?(?:function|\().*(?:create|update|delete|modify|write|send)/gi,
+    riskType: 'database',
+    baseSeverity: 'medium',
+    description: 'Tool performs write operations but may not verify user context. Actions could be performed as wrong user.',
+    suggestedFix: 'Pass userId as required parameter. Verify user owns/can access the resource before modification.',
+    requiresUserContext: true,
+  },
+]
+
+// ============================================================================
+// Main Detection Function
+// ============================================================================
+
+/**
+ * Main detection function for AI agent tool permission issues
+ */
+export function detectAIAgentTools(
+  content: string,
+  filePath: string
+): Vulnerability[] {
+  const vulnerabilities: Vulnerability[] = []
+
+  // Skip non-applicable files
+  if (isScannerOrFixtureFile(filePath)) return vulnerabilities
+
+  // Only scan files that appear to have agent/tool definitions
+  if (!isAgentOrToolFile(filePath, content)) {
+    return vulnerabilities
+  }
+
+  const lines = content.split('\n')
+  const isTestFile = isTestOrMockFile(filePath)
+  const isExample = isExampleDirectory(filePath)
+  const isLibrary = isLibraryCode(filePath)
+
+  // Scan for overly permissive tool patterns
+  for (const pattern of OVERPERMISSIVE_TOOL_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
+
+      // Get tool context
+      const { context } = findToolDefinitionContext(content, lineNumber)
+
+      // Check for mitigations (strong vs weak)
+      const hasStrong = hasStrongRestrictions(context)
+      const hasWeak = hasAccessRestrictions(context)
+      const hasUserContext = hasUserContextVerification(context)
+      const hasTenantContext = hasTenantContextVerification(context)
+
+      // Determine if issue is fully mitigated
+      let isMitigated = true
+      let hasPartialMitigation = false
+      const missingMitigations: string[] = []
+
+      if (pattern.requiresRestrictions) {
+        if (hasStrong) {
+          // Strong restrictions = fully mitigated for this requirement
+        } else if (hasWeak) {
+          // Weak restrictions = partial mitigation
+          hasPartialMitigation = true
+          missingMitigations.push('verified access restrictions (found mentions but not implementation)')
+          isMitigated = false
+        } else {
+          isMitigated = false
+          missingMitigations.push('access restrictions')
+        }
+      }
+      if (pattern.requiresUserContext && !hasUserContext) {
+        isMitigated = false
+        missingMitigations.push('user context verification')
+      }
+      if (pattern.requiresTenantContext && !hasTenantContext) {
+        isMitigated = false
+        missingMitigations.push('tenant/org context verification')
+      }
+
+      // Skip if all required mitigations are present with strong verification
+      if (isMitigated) continue
+
+      // Calculate severity
+      let severity = pattern.baseSeverity
+      if (isTestFile) {
+        severity = 'info'
+      } else if (isExample) {
+        // Example/demo code - downgrade to info
+        severity = 'info'
+      } else if (isLibrary) {
+        // Library code - tool definitions are intentionally flexible
+        // Consumers add restrictions when they use the tools
+        severity = 'info'
+      } else if (hasPartialMitigation || hasUserContext || hasTenantContext) {
+        // Partial mitigation - downgrade
+        if (severity === 'critical') severity = 'high'
+        else if (severity === 'high') severity = 'medium'
+      }
+
+      // Build description
+      let description = pattern.description
+      if (missingMitigations.length > 0) {
+        description += ` Missing: ${missingMitigations.join(', ')}.`
+      }
+      if (isTestFile) {
+        description += ' (In test file.)'
+      } else if (isExample) {
+        description += ' (In example/demo directory - not production code.)'
+      } else if (isLibrary) {
+        description += ' (Library code - tool definitions are generic; consumers add restrictions.)'
+      }
+
+      vulnerabilities.push({
+        id: `ai-tool-${filePath}-${lineNumber}-${pattern.riskType}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'ai_overpermissive_tool',
+        title: pattern.name,
+        description,
+        suggestedFix: pattern.suggestedFix,
+        confidence: 'medium',
+        layer: 2,
+        requiresAIValidation: true, // Always validate - context dependent
+      })
+    }
+  }
+
+  // Scan for missing authorization patterns
+  for (const pattern of MISSING_AUTH_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
+
+      // Get tool context
+      const { context } = findToolDefinitionContext(content, lineNumber)
+
+      // Check if user context is verified
+      const hasUserContext = hasUserContextVerification(context)
+
+      // Skip if user context is present
+      if (hasUserContext) continue
+
+      let severity = pattern.baseSeverity
+      let description = pattern.description
+
+      if (isTestFile) {
+        severity = 'info'
+        description += ' (In test file.)'
+      }
+
+      vulnerabilities.push({
+        id: `ai-tool-auth-${filePath}-${lineNumber}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'ai_overpermissive_tool',
+        title: pattern.name,
+        description,
+        suggestedFix: pattern.suggestedFix,
+        confidence: 'low', // Lower confidence - needs context
+        layer: 2,
+        requiresAIValidation: true,
+      })
+    }
+  }
+
+  return vulnerabilities
+}