@oculum/scanner 1.0.0

package/src/layer2/ai-endpoint-protection.ts

@@ -0,0 +1,387 @@
+/**
+ * Layer 2: AI Endpoint Protection Detection
+ * Detects AI/LLM endpoints without proper authentication or rate limiting
+ *
+ * Covers:
+ * - M5.2: AI endpoints without auth/rate limiting
+ * - Cost-bearing AI endpoints exposed publicly
+ * - Missing rate limiting on AI routes
+ */
+
+import type { Vulnerability, VulnerabilitySeverity } from '../types'
+import type { MiddlewareAuthConfig } from '../utils/middleware-detector'
+import {
+  isComment,
+  isTestOrMockFile,
+  isDocumentationFile,
+  isScannerOrFixtureFile,
+  isExampleDirectory,
+} from '../utils/context-helpers'
+
+// ============================================================================
+// Context Detection
+// ============================================================================
+
+/**
+ * Check if file is a route/API handler
+ */
+function isRouteFile(filePath: string): boolean {
+  const routePatterns = [
+    /\/api\/.*\.(ts|js)$/i,
+    /\/routes?\/.*\.(ts|js)$/i,
+    /route\.(ts|js)$/i,
+    /\/pages\/api\/.*\.(ts|js)$/i,
+    /\/app\/.*\/route\.(ts|js)$/i,
+    /\.(controller|handler)\.(ts|js)$/i,
+  ]
+  return routePatterns.some(p => p.test(filePath))
+}
+
+/**
+ * Check if content contains AI/LLM API calls
+ */
+function hasAIApiCalls(content: string): boolean {
+  const aiPatterns = [
+    // OpenAI
+    /openai\.chat\.completions?\.create/i,
+    /openai\.completions?\.create/i,
+    /openai\.embeddings?\.create/i,
+    // Anthropic
+    /anthropic\.messages\.create/i,
+    /anthropic\.completions?\.create/i,
+    // Vercel AI SDK
+    /\bgenerateText\s*\(/i,
+    /\bstreamText\s*\(/i,
+    /\bgenerateObject\s*\(/i,
+    /\bstreamObject\s*\(/i,
+    // Generic patterns
+    /\.create\s*\(\s*\{[^}]*model\s*:/i,
+    /ChatCompletion|MessageCreate/i,
+    // LangChain
+    /\.invoke\s*\([^)]*\)/i,
+    /ChatOpenAI|ChatAnthropic|ChatModel/i,
+    // Other providers
+    /replicate\.run/i,
+    /cohere\.(?:generate|chat)/i,
+    /mistral\.chat/i,
+  ]
+  return aiPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if there's authentication in the route
+ */
+function hasAuthentication(content: string): boolean {
+  const authPatterns = [
+    // Session/user checks
+    /getSession|getServerSession|getCurrentUser/i,
+    /auth\(\)|requireAuth|withAuth|ensureAuth/i,
+    /verifyToken|validateToken|checkToken/i,
+    /req\.user|request\.user|context\.user/i,
+    /isAuthenticated|checkAuth/i,
+    // Header checks
+    /Authorization.*Bearer/i,
+    /headers\[['"`]authorization['"`]\]/i,
+    /getHeader\(['"`]authorization['"`]\)/i,
+    // API key validation
+    /apiKey|api_key|x-api-key/i,
+    // Clerk/NextAuth/Auth0
+    /currentUser\(\)|auth\(\)\.protect/i,
+    /getAuth\(\)|clerkClient/i,
+    // User ID extraction (implies auth)
+    /userId|user\.id|currentUserId/i,
+    // 401/403 responses
+    /status\(401\)|status\(403\)/i,
+    /Unauthorized|Forbidden/i,
+  ]
+  return authPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if there's rate limiting
+ */
+function hasRateLimiting(content: string): boolean {
+  const rateLimitPatterns = [
+    // Rate limit middleware/libraries
+    /rateLimit|rateLimiter/i,
+    /express-rate-limit/i,
+    /upstash.*ratelimit|@upstash\/ratelimit/i,
+    /rate-limiter-flexible/i,
+    // Custom rate limiting
+    /throttle|Throttle/i,
+    /requestsPerMinute|requestsPerHour/i,
+    /maxRequests|requestLimit/i,
+    // Rate limit headers
+    /X-RateLimit|x-ratelimit/i,
+    /Retry-After/i,
+    // 429 responses
+    /status\(429\)|\.status === 429/i,
+    /Too Many Requests|TooManyRequests/i,
+    // Sliding window/token bucket
+    /slidingWindow|tokenBucket|fixedWindow/i,
+  ]
+  return rateLimitPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if this is a BYOK (Bring Your Own Key) endpoint
+ * BYOK endpoints have lower risk since user pays for their own usage
+ */
+function isBYOKEndpoint(content: string): boolean {
+  const byokPatterns = [
+    /req\.body\.(?:apiKey|api_key|openaiKey|anthropicKey)/i,
+    /request\.(?:apiKey|api_key|openaiKey|anthropicKey)/i,
+    /userApiKey|user_api_key|clientApiKey/i,
+    /['"`](?:apiKey|api_key|openai_key|anthropic_key)['"`]\s*:/i,
+    // Headers with user's key
+    /headers\[['"`]x-openai-key['"`]\]/i,
+    /headers\[['"`]x-api-key['"`]\]/i,
+  ]
+  return byokPatterns.some(p => p.test(content))
+}
+
+/**
+ * Check if route is protected by middleware (from config)
+ */
+function isProtectedByMiddleware(
+  filePath: string,
+  middlewareConfig?: MiddlewareAuthConfig
+): boolean {
+  if (!middlewareConfig?.protectedPaths) return false
+
+  // Extract route path from file path
+  const routePath = filePath
+    .replace(/.*\/(pages|app)\/api/, '/api')
+    .replace(/.*\/routes?/, '')
+    .replace(/\/route\.(ts|js)$/, '')
+    .replace(/\.(ts|js)$/, '')
+    .replace(/\[([^\]]+)\]/g, ':$1')
+
+  return middlewareConfig.protectedPaths.some(p => routePath.startsWith(p))
+}
+
+/**
+ * Check if this is an internal/admin-only route
+ */
+function isInternalRoute(filePath: string, content: string): boolean {
+  const internalPatterns = [
+    /\/internal\//i,
+    /\/admin\//i,
+    /\/_internal\//i,
+    // Content checks
+    /adminOnly|internalOnly|isAdmin/i,
+    /process\.env\.INTERNAL_SECRET/i,
+  ]
+  return internalPatterns.some(p => p.test(filePath) || p.test(content))
+}
+
+/**
+ * Get surrounding context
+ */
+function getSurroundingContext(content: string, lineIndex: number, windowSize: number = 50): 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).join('\n')
+}
+
+// ============================================================================
+// Pattern Definitions
+// ============================================================================
+
+interface EndpointProtectionPattern {
+  name: string
+  pattern: RegExp
+  framework: 'nextjs_app' | 'nextjs_pages' | 'express' | 'fastify' | 'generic'
+  description: string
+  suggestedFix: string
+}
+
+/**
+ * Route handler patterns by framework
+ */
+const ROUTE_HANDLER_PATTERNS: EndpointProtectionPattern[] = [
+  // Next.js App Router
+  {
+    name: 'Next.js App Router AI endpoint',
+    pattern: /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\s*\(/gi,
+    framework: 'nextjs_app',
+    description: 'Next.js App Router endpoint with AI API calls lacks protection.',
+    suggestedFix: 'Add authentication check at start of handler. Consider using middleware for auth and rate limiting.',
+  },
+  // Next.js Pages Router
+  {
+    name: 'Next.js Pages API route',
+    pattern: /export\s+default\s+(?:async\s+)?function\s*(?:\w+\s*)?\([^)]*req/gi,
+    framework: 'nextjs_pages',
+    description: 'Next.js Pages API route with AI calls lacks protection.',
+    suggestedFix: 'Add authentication: const session = await getServerSession(req, res, authOptions); if (!session) return res.status(401).json({error: "Unauthorized"})',
+  },
+  // Express
+  {
+    name: 'Express AI route',
+    pattern: /(?:app|router)\.(get|post|put|patch|delete)\s*\(\s*['"`][^'"`]+['"`]\s*,/gi,
+    framework: 'express',
+    description: 'Express route with AI API calls lacks middleware protection.',
+    suggestedFix: 'Add authentication and rate limiting middleware: app.post("/api/chat", authMiddleware, rateLimiter, handler)',
+  },
+  // Fastify
+  {
+    name: 'Fastify AI route',
+    pattern: /fastify\.(get|post|put|patch|delete)\s*\(\s*['"`][^'"`]+['"`]/gi,
+    framework: 'fastify',
+    description: 'Fastify route with AI calls lacks protection.',
+    suggestedFix: 'Add preHandler hooks for auth and rate limiting: { preHandler: [authenticate, rateLimit] }',
+  },
+  // Generic handler exports
+  {
+    name: 'API handler with AI calls',
+    pattern: /export\s+(?:const|async\s+function)\s+(?:handler|apiHandler)\s*[=:]/gi,
+    framework: 'generic',
+    description: 'API handler with AI calls may lack protection.',
+    suggestedFix: 'Ensure authentication and rate limiting are applied before AI API calls.',
+  },
+]
+
+// ============================================================================
+// Main Detection Function
+// ============================================================================
+
+export interface EndpointProtectionOptions {
+  middlewareConfig?: MiddlewareAuthConfig
+}
+
+/**
+ * Main detection function for AI endpoint protection issues
+ */
+export function detectAIEndpointProtection(
+  content: string,
+  filePath: string,
+  options: EndpointProtectionOptions = {}
+): Vulnerability[] {
+  const vulnerabilities: Vulnerability[] = []
+
+  // Skip non-applicable files
+  if (isScannerOrFixtureFile(filePath)) return vulnerabilities
+  if (isDocumentationFile(filePath)) return vulnerabilities
+
+  // Only scan route files that have AI API calls
+  if (!isRouteFile(filePath) || !hasAIApiCalls(content)) {
+    return vulnerabilities
+  }
+
+  const lines = content.split('\n')
+  const isTestFile = isTestOrMockFile(filePath)
+  const isExample = isExampleDirectory(filePath)
+
+  // Check file-level protection
+  const fileHasAuth = hasAuthentication(content)
+  const fileHasRateLimit = hasRateLimiting(content)
+  const isByok = isBYOKEndpoint(content)
+  const isInternal = isInternalRoute(filePath, content)
+  const isMiddlewareProtected = isProtectedByMiddleware(filePath, options.middlewareConfig)
+
+  // Scan for route handler patterns
+  for (const pattern of ROUTE_HANDLER_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 surrounding context
+      const context = getSurroundingContext(content, lineNumber - 1, 50)
+
+      // Check for local protection patterns (within handler)
+      const handlerHasAuth = hasAuthentication(context)
+      const handlerHasRateLimit = hasRateLimiting(context)
+
+      // Calculate severity based on protection status
+      let severity: VulnerabilitySeverity
+      const notes: string[] = []
+
+      if (isMiddlewareProtected || isInternal) {
+        severity = 'info'
+        notes.push(isMiddlewareProtected ? 'Protected by middleware' : 'Internal route')
+      } else if (handlerHasAuth || fileHasAuth) {
+        if (handlerHasRateLimit || fileHasRateLimit) {
+          // Has both auth and rate limiting
+          severity = 'info'
+          notes.push('Has authentication and rate limiting')
+        } else {
+          // Has auth but no rate limiting
+          severity = 'low'
+          notes.push('Has authentication but missing rate limiting')
+        }
+      } else if (handlerHasRateLimit || fileHasRateLimit) {
+        // Has rate limiting but no auth
+        severity = 'medium'
+        notes.push('Has rate limiting but missing authentication')
+      } else {
+        // No protection at all
+        severity = 'high'
+        notes.push('Missing authentication and rate limiting')
+      }
+
+      // BYOK endpoints have lower risk
+      if (isByok && severity !== 'info') {
+        severity = severity === 'high' ? 'medium' : (severity === 'medium' ? 'low' : severity)
+        notes.push('BYOK endpoint - user provides API key')
+      }
+
+      // Downgrade test files
+      if (isTestFile) {
+        severity = 'info'
+        notes.push('in test file')
+      }
+
+      // Downgrade example/demo directories - these are tutorials, not production code
+      if (isExample && severity !== 'info') {
+        severity = 'info'
+        notes.push('in example/demo directory - tutorial code')
+      }
+
+      // Build description
+      let description = pattern.description
+      if (notes.length > 0) {
+        description += ` (${notes.join('; ')})`
+      }
+
+      // Determine suggested fix based on what's missing
+      let suggestedFix = pattern.suggestedFix
+      if (handlerHasAuth && !handlerHasRateLimit) {
+        suggestedFix = 'Add rate limiting to prevent cost abuse: npm install express-rate-limit or use Upstash ratelimit for serverless.'
+      }
+
+      vulnerabilities.push({
+        id: `ai-endpoint-${filePath}-${lineNumber}-${pattern.name.replace(/\s+/g, '-')}`,
+        filePath,
+        lineNumber,
+        lineContent,
+        severity,
+        category: 'ai_endpoint_unprotected',
+        title: pattern.name,
+        description,
+        suggestedFix,
+        confidence: severity === 'info' ? 'low' : 'medium',
+        layer: 2,
+        requiresAIValidation: severity !== 'info',
+      })
+
+      // Only report one finding per file (file-level issue)
+      break
+    }
+
+    // Only process if we found a route handler (avoid duplicate patterns)
+    if (vulnerabilities.length > 0) break
+  }
+
+  return vulnerabilities
+}
+
+// Export helpers for use in other modules
+export { isRouteFile, hasAIApiCalls, hasAuthentication, hasRateLimiting }