@oculum/scanner 1.0.9 → 1.0.11

package/src/rules/__tests__/metadata.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Tests for Rule Metadata Registry (PRO-82)
+ */
+
+import { RULE_REGISTRY, getRuleMetadata, getAllCategories, hasMetadata, type RuleMetadata } from '../metadata'
+import type { VulnerabilityCategory } from '../../types'
+
+// All vulnerability categories that should have metadata
+const ALL_CATEGORIES: VulnerabilityCategory[] = [
+  'hardcoded_secret',
+  'high_entropy_string',
+  'sensitive_variable',
+  'security_bypass',
+  'dangerous_function',
+  'sql_injection',
+  'xss',
+  'command_injection',
+  'insecure_config',
+  'missing_auth',
+  'suspicious_package',
+  'cors_misconfiguration',
+  'root_container',
+  'dangerous_file',
+  'ai_pattern',
+  'sensitive_url',
+  'weak_crypto',
+  'data_exposure',
+  'ai_prompt_injection',
+  'ai_unsafe_execution',
+  'ai_overpermissive_tool',
+  'ai_rag_exfiltration',
+  'ai_endpoint_unprotected',
+  'ai_schema_mismatch',
+  // AI Detection Roadmap Phase 1
+  'ai_package_hallucination',
+  'ai_rag_corpus_poisoning',
+  'ai_rag_pii_leakage',
+  'ai_mcp_tool_poisoning',
+  'ai_mcp_credential_issue',
+  'ai_mcp_confused_deputy',
+  // Phase 1 Enhancement Backlog
+  'ai_mcp_description_injection',
+  'ai_mcp_server_shadowing',
+  'ai_mcp_config_secrets',
+  'ai_mcp_config_permissions',
+  'ai_rag_query_injection',
+  'ai_rag_embedding_poisoning',
+  'ai_rag_chunk_injection',
+  'ai_package_typosquat',
+  'ai_package_malicious',
+  // AI Detection Roadmap Phase 2
+  'ai_unsafe_model_load',
+  'ai_unverified_model',
+  'ai_unsafe_finetuning',
+  'ai_excessive_agency',
+]
+
+describe('Rule Metadata Registry', () => {
+  describe('RULE_REGISTRY coverage', () => {
+    it('should have metadata for all vulnerability categories', () => {
+      for (const category of ALL_CATEGORIES) {
+        expect(RULE_REGISTRY[category]).toBeDefined()
+        expect(RULE_REGISTRY[category].name).toBeTruthy()
+      }
+    })
+
+    it('should have all required fields for each category', () => {
+      for (const category of ALL_CATEGORIES) {
+        const metadata = RULE_REGISTRY[category]
+
+        expect(metadata.name).toBeDefined()
+        expect(typeof metadata.name).toBe('string')
+        expect(metadata.name.length).toBeGreaterThan(0)
+
+        expect(metadata.whyItMatters).toBeDefined()
+        expect(typeof metadata.whyItMatters).toBe('string')
+        expect(metadata.whyItMatters.length).toBeGreaterThan(20)
+
+        expect(metadata.fixSteps).toBeDefined()
+        expect(Array.isArray(metadata.fixSteps)).toBe(true)
+        expect(metadata.fixSteps.length).toBeGreaterThan(0)
+
+        expect(metadata.evidence).toBeDefined()
+        expect(typeof metadata.evidence).toBe('string')
+        expect(metadata.evidence.length).toBeGreaterThan(0)
+
+        expect(metadata.references).toBeDefined()
+        expect(Array.isArray(metadata.references)).toBe(true)
+        expect(metadata.references.length).toBeGreaterThan(0)
+      }
+    })
+
+    it('should have valid OWASP/CWE reference URLs', () => {
+      for (const category of ALL_CATEGORIES) {
+        const metadata = RULE_REGISTRY[category]
+
+        for (const ref of metadata.references) {
+          expect(ref).toMatch(/^https?:\/\//)
+          // Should be OWASP, CWE, or other recognized security references
+          expect(
+            ref.includes('owasp.org') ||
+            ref.includes('cwe.mitre.org') ||
+            ref.includes('docker.com') ||
+            ref.includes('genai.owasp.org') ||
+            ref.includes('arxiv.org') ||  // Academic research
+            ref.includes('modelcontextprotocol.io') ||  // MCP official docs
+            ref.includes('invariantlabs.ai') ||  // Security research
+            ref.includes('snyk.io') ||  // Dependency security
+            ref.includes('osv.dev') ||  // Open Source Vulnerabilities
+            ref.includes('socket.dev') ||  // npm malware research
+            ref.includes('huggingface.co') ||  // ML model security docs
+            ref.includes('atlas.mitre.org') ||  // MITRE ATLAS (AI threat matrix)
+            ref.includes('docs.crewai.com')  // CrewAI security docs
+          ).toBe(true)
+        }
+      }
+    })
+  })
+
+  describe('getRuleMetadata', () => {
+    it('should return metadata for valid category', () => {
+      const metadata = getRuleMetadata('sql_injection')
+
+      expect(metadata).toBeDefined()
+      expect(metadata?.name).toBe('SQL Injection')
+      expect(metadata?.whyItMatters).toContain('database')
+      expect(metadata?.fixSteps.length).toBeGreaterThan(0)
+    })
+
+    it('should return undefined for invalid category', () => {
+      // @ts-expect-error - testing invalid input
+      const metadata = getRuleMetadata('invalid_category')
+      expect(metadata).toBeUndefined()
+    })
+  })
+
+  describe('getAllCategories', () => {
+    it('should return all categories', () => {
+      const categories = getAllCategories()
+
+      expect(categories.length).toBe(ALL_CATEGORIES.length)
+      for (const category of ALL_CATEGORIES) {
+        expect(categories).toContain(category)
+      }
+    })
+  })
+
+  describe('hasMetadata', () => {
+    it('should return true for valid categories', () => {
+      expect(hasMetadata('hardcoded_secret')).toBe(true)
+      expect(hasMetadata('ai_prompt_injection')).toBe(true)
+    })
+
+    it('should return false for invalid categories', () => {
+      // @ts-expect-error - testing invalid input
+      expect(hasMetadata('invalid_category')).toBe(false)
+    })
+  })
+
+  describe('metadata quality', () => {
+    it('whyItMatters should explain business impact', () => {
+      // Check a few key categories have meaningful impact descriptions
+      const hardcodedSecret = RULE_REGISTRY.hardcoded_secret
+      expect(hardcodedSecret.whyItMatters).toMatch(/unauthorized|extract|access|credential/i)
+
+      const sqlInjection = RULE_REGISTRY.sql_injection
+      expect(sqlInjection.whyItMatters).toMatch(/read|modify|delete|database/i)
+
+      const missingAuth = RULE_REGISTRY.missing_auth
+      expect(missingAuth.whyItMatters).toMatch(/access|authentication|anyone/i)
+    })
+
+    it('fixSteps should be actionable', () => {
+      // Check fix steps are actionable (start with verbs)
+      for (const category of ALL_CATEGORIES) {
+        const metadata = RULE_REGISTRY[category]
+
+        for (const step of metadata.fixSteps) {
+          // Each step should start with an action verb (capitalized)
+          expect(step[0]).toBe(step[0].toUpperCase())
+          expect(step.length).toBeGreaterThan(10)
+        }
+      }
+    })
+
+    it('AI-specific categories should have OWASP LLM Top 10 references', () => {
+      const aiCategories: VulnerabilityCategory[] = [
+        'ai_prompt_injection',
+        'ai_unsafe_execution',
+        'ai_overpermissive_tool',
+        'ai_rag_exfiltration',
+        'ai_endpoint_unprotected',
+        'ai_schema_mismatch',
+        // AI Detection Roadmap Phase 1
+        'ai_rag_corpus_poisoning',
+        'ai_rag_pii_leakage',
+        'ai_mcp_tool_poisoning',
+        'ai_mcp_credential_issue',
+        'ai_mcp_confused_deputy',
+        // AI Detection Roadmap Phase 2
+        'ai_unsafe_model_load',
+        'ai_unverified_model',
+        'ai_unsafe_finetuning',
+        'ai_excessive_agency',
+      ]
+
+      for (const category of aiCategories) {
+        const metadata = RULE_REGISTRY[category]
+        const hasLlmReference = metadata.references.some(
+          ref => ref.includes('genai.owasp.org') ||
+                 ref.includes('large-language-model') ||
+                 ref.includes('modelcontextprotocol.io')  // MCP has its own docs
+        )
+        expect(hasLlmReference).toBe(true)
+      }
+    })
+  })
+})

package/src/rules/framework-fixes.ts

@@ -0,0 +1,470 @@
+/**
+ * Framework-Aware Fix Suggestions Registry (PRO-83)
+ *
+ * Provides framework-specific fix suggestions that transform generic advice
+ * into actionable guidance based on the user's detected tech stack.
+ *
+ * When a Next.js + Prisma project has a SQL injection finding, this registry
+ * provides Prisma-specific fixes instead of generic SQL advice.
+ *
+ * Falls back gracefully to generic fixes (from metadata.ts) when no match.
+ */
+
+import type { VulnerabilityCategory } from '../types'
+import type { FrameworkContext, DataAccessContext } from '../utils/project-context-builder'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type FrameworkKey =
+  | 'nextjs' | 'express' | 'fastify' | 'nestjs'
+  | 'prisma' | 'drizzle' | 'supabase' | 'mongoose' | 'knex'
+  | 'react' | 'vue'
+
+export interface FrameworkFix {
+  /** Step-by-step fix instructions specific to this framework */
+  fixSteps: string[]
+  /** Optional code example demonstrating the fix */
+  codeExample?: string
+}
+
+// ============================================================================
+// Framework Fix Registry
+// ============================================================================
+
+/**
+ * Registry mapping vulnerability categories to framework-specific fixes.
+ *
+ * Structure: category -> framework -> fix
+ *
+ * Priority categories (Tier 1):
+ * - sql_injection: Fixes vary dramatically by ORM
+ * - missing_auth: Framework-specific middleware patterns
+ * - xss: React/Vue/vanilla have different approaches
+ * - hardcoded_secret: Framework-specific env handling
+ * - cors_misconfiguration: Very framework-specific
+ */
+export const FRAMEWORK_FIX_REGISTRY: Partial<Record<VulnerabilityCategory, Partial<Record<FrameworkKey, FrameworkFix>>>> = {
+  // ==========================================================================
+  // SQL Injection - Fixes vary dramatically by ORM
+  // ==========================================================================
+  sql_injection: {
+    prisma: {
+      fixSteps: [
+        'Use Prisma query methods: prisma.user.findUnique({ where: { id } })',
+        'For raw SQL, use Prisma.$queryRaw with template literals (auto-parameterized)',
+        'Never concatenate user input into query strings',
+        'Validate input with Zod before passing to queries',
+      ],
+      codeExample: `// Safe: Prisma parameterized query
+const user = await prisma.user.findUnique({
+  where: { email: userInput }
+})
+
+// Safe: Raw query with parameters
+await prisma.$queryRaw\`SELECT * FROM users WHERE id = \${userId}\``,
+    },
+    drizzle: {
+      fixSteps: [
+        'Use Drizzle query builder with eq(), and(), or() operators',
+        'For raw SQL, use sql`` template literal (auto-parameterized)',
+        'Never concatenate user input into query strings',
+        'Validate input with Zod before passing to queries',
+      ],
+      codeExample: `// Safe: Drizzle query builder
+const users = await db.select().from(usersTable)
+  .where(eq(usersTable.email, userInput))
+
+// Safe: Raw query with parameters
+await db.execute(sql\`SELECT * FROM users WHERE id = \${userId}\`)`,
+    },
+    supabase: {
+      fixSteps: [
+        'Use Supabase client methods: supabase.from("users").select().eq("id", userId)',
+        'Rely on Row Level Security (RLS) for access control',
+        'For complex queries, use stored procedures with parameters',
+        'Never use .rpc() with string concatenation for query building',
+      ],
+      codeExample: `// Safe: Supabase client with RLS
+const { data } = await supabase
+  .from('users')
+  .select('*')
+  .eq('email', userInput)
+  .single()`,
+    },
+    mongoose: {
+      fixSteps: [
+        'Use Mongoose query methods with conditions object: User.find({ email: userInput })',
+        'Avoid $where with user input - it allows JavaScript execution',
+        'Validate ObjectIds before querying: mongoose.Types.ObjectId.isValid(id)',
+        'Use schema validation to ensure expected data types',
+      ],
+      codeExample: `// Safe: Mongoose query with conditions
+const user = await User.findOne({ email: userInput })
+
+// Validate ObjectId before use
+if (!mongoose.Types.ObjectId.isValid(id)) {
+  throw new Error('Invalid ID')
+}`,
+    },
+    knex: {
+      fixSteps: [
+        'Use Knex query builder: knex("users").where({ email: userInput })',
+        'For raw SQL, use knex.raw() with parameter binding: knex.raw("SELECT * FROM users WHERE id = ?", [userId])',
+        'Never use string concatenation in queries',
+        'Validate input types before passing to queries',
+      ],
+      codeExample: `// Safe: Knex query builder
+const user = await knex('users')
+  .where({ email: userInput })
+  .first()
+
+// Safe: Raw query with parameters
+await knex.raw('SELECT * FROM users WHERE id = ?', [userId])`,
+    },
+  },
+
+  // ==========================================================================
+  // Missing Authentication - Framework-specific middleware patterns
+  // ==========================================================================
+  missing_auth: {
+    nextjs: {
+      fixSteps: [
+        'Add auth check in middleware.ts with matcher config for protected routes',
+        'Call auth() or getServerSession() at the start of route handlers',
+        'Return 401/redirect for unauthenticated requests',
+        'Use throwing auth helpers (getCurrentUserId) that guarantee authenticated context',
+      ],
+      codeExample: `// middleware.ts
+export { auth as middleware } from '@/auth'
+export const config = { matcher: ['/dashboard/:path*', '/api/:path*'] }
+
+// In route handler
+import { auth } from '@/auth'
+
+export async function GET() {
+  const session = await auth()
+  if (!session) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+  // ... authenticated code
+}`,
+    },
+    express: {
+      fixSteps: [
+        'Use authentication middleware (passport, express-session, or custom)',
+        'Apply middleware to routes: app.use("/api", authMiddleware)',
+        'Verify JWT tokens or session cookies in middleware',
+        'Return 401 status for unauthenticated requests',
+      ],
+      codeExample: `// authMiddleware.js
+const authMiddleware = (req, res, next) => {
+  const token = req.headers.authorization?.split(' ')[1]
+  if (!token) {
+    return res.status(401).json({ error: 'Unauthorized' })
+  }
+  try {
+    req.user = jwt.verify(token, process.env.JWT_SECRET)
+    next()
+  } catch {
+    return res.status(401).json({ error: 'Invalid token' })
+  }
+}
+
+// Apply to routes
+app.use('/api', authMiddleware)`,
+    },
+    fastify: {
+      fixSteps: [
+        'Use @fastify/auth or @fastify/jwt for authentication',
+        'Register auth plugin and apply to routes with onRequest hook',
+        'Decorate request with user info after authentication',
+        'Return 401 status for unauthenticated requests',
+      ],
+      codeExample: `// Register JWT plugin
+await fastify.register(fastifyJwt, { secret: process.env.JWT_SECRET })
+
+// Auth decorator
+fastify.decorate('authenticate', async (request, reply) => {
+  try {
+    await request.jwtVerify()
+  } catch (err) {
+    reply.code(401).send({ error: 'Unauthorized' })
+  }
+})
+
+// Protected route
+fastify.get('/api/data', { onRequest: [fastify.authenticate] }, handler)`,
+    },
+    nestjs: {
+      fixSteps: [
+        'Use @nestjs/passport with Guards for authentication',
+        'Apply AuthGuard to controllers or routes with @UseGuards()',
+        'Implement custom guards for role-based access control',
+        'Use @Public() decorator for intentionally public endpoints',
+      ],
+      codeExample: `// auth.guard.ts
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {}
+
+// controller.ts
+@Controller('api')
+@UseGuards(JwtAuthGuard)
+export class ApiController {
+  @Get('data')
+  getData(@Request() req) {
+    return this.service.getData(req.user.id)
+  }
+}`,
+    },
+  },
+
+  // ==========================================================================
+  // XSS - React/Vue/vanilla have different approaches
+  // ==========================================================================
+  xss: {
+    react: {
+      fixSteps: [
+        'Use JSX expressions {variable} - React auto-escapes by default',
+        'Avoid dangerouslySetInnerHTML unless absolutely necessary',
+        'If you must use dangerouslySetInnerHTML, sanitize with DOMPurify first',
+        'Validate and sanitize user input on the server side as well',
+      ],
+      codeExample: `// Safe: JSX auto-escapes
+function Comment({ text }) {
+  return <div>{text}</div> // Safe - auto-escaped
+}
+
+// If HTML is required, sanitize first
+import DOMPurify from 'dompurify'
+
+function RichContent({ html }) {
+  const clean = DOMPurify.sanitize(html)
+  return <div dangerouslySetInnerHTML={{ __html: clean }} />
+}`,
+    },
+    vue: {
+      fixSteps: [
+        'Use v-text or {{ }} interpolation - Vue auto-escapes by default',
+        'Avoid v-html with user-controlled content',
+        'If you must use v-html, sanitize with DOMPurify first',
+        'Use Content Security Policy headers as additional protection',
+      ],
+      codeExample: `<!-- Safe: Vue interpolation auto-escapes -->
+<template>
+  <div>{{ userContent }}</div>
+</template>
+
+<!-- If HTML is required, sanitize first -->
+<script setup>
+import DOMPurify from 'dompurify'
+const sanitizedHtml = computed(() => DOMPurify.sanitize(props.html))
+</script>
+
+<template>
+  <div v-html="sanitizedHtml"></div>
+</template>`,
+    },
+  },
+
+  // ==========================================================================
+  // Hardcoded Secrets - Framework-specific env handling
+  // ==========================================================================
+  hardcoded_secret: {
+    nextjs: {
+      fixSteps: [
+        'Store secrets in .env.local (gitignored by default)',
+        'Access via process.env.SECRET_NAME in server components/API routes',
+        'Only use NEXT_PUBLIC_ prefix for intentionally client-exposed values',
+        'Use Vercel Environment Variables for production deployments',
+      ],
+      codeExample: `// .env.local
+DATABASE_URL=postgres://...
+API_SECRET=your-secret-here
+
+// Server-side code (API route, server component)
+const secret = process.env.API_SECRET
+
+// Client-safe public values only
+// NEXT_PUBLIC_ANALYTICS_ID=xxx`,
+    },
+    express: {
+      fixSteps: [
+        'Use dotenv package to load from .env files',
+        'Add .env to .gitignore immediately',
+        'Access secrets via process.env.SECRET_NAME',
+        'Use different .env files per environment (.env.production)',
+      ],
+      codeExample: `// At app entry point
+import 'dotenv/config'
+
+// .env (gitignored)
+DATABASE_URL=postgres://...
+JWT_SECRET=your-secret-here
+
+// Access in code
+const jwtSecret = process.env.JWT_SECRET
+if (!jwtSecret) throw new Error('JWT_SECRET required')`,
+    },
+  },
+
+  // ==========================================================================
+  // CORS Misconfiguration - Very framework-specific
+  // ==========================================================================
+  cors_misconfiguration: {
+    nextjs: {
+      fixSteps: [
+        'Configure CORS in next.config.js headers or middleware',
+        'Specify exact allowed origins instead of wildcard "*"',
+        'Use environment variables for origin configuration',
+        'Consider using middleware for dynamic origin validation',
+      ],
+      codeExample: `// next.config.js
+module.exports = {
+  async headers() {
+    return [{
+      source: '/api/:path*',
+      headers: [
+        { key: 'Access-Control-Allow-Origin', value: process.env.ALLOWED_ORIGIN },
+        { key: 'Access-Control-Allow-Methods', value: 'GET,POST,PUT,DELETE' },
+        { key: 'Access-Control-Allow-Headers', value: 'Content-Type,Authorization' },
+      ],
+    }]
+  },
+}
+
+// Or in middleware.ts for dynamic validation
+const allowedOrigins = ['https://app.example.com', 'https://admin.example.com']`,
+    },
+    express: {
+      fixSteps: [
+        'Use the cors package with specific origin configuration',
+        'Replace origin: "*" with an allowlist of origins',
+        'Use a function for dynamic origin validation',
+        'Disable credentials for cross-origin requests unless necessary',
+      ],
+      codeExample: `import cors from 'cors'
+
+const allowedOrigins = ['https://app.example.com', 'https://admin.example.com']
+
+app.use(cors({
+  origin: (origin, callback) => {
+    if (!origin || allowedOrigins.includes(origin)) {
+      callback(null, true)
+    } else {
+      callback(new Error('Not allowed by CORS'))
+    }
+  },
+  credentials: true, // Only if you need cookies/auth headers
+}))`,
+    },
+    fastify: {
+      fixSteps: [
+        'Use @fastify/cors with specific origin configuration',
+        'Specify allowed origins instead of true/wildcard',
+        'Use a function for dynamic origin validation',
+        'Configure allowed methods and headers explicitly',
+      ],
+      codeExample: `import cors from '@fastify/cors'
+
+const allowedOrigins = ['https://app.example.com']
+
+await fastify.register(cors, {
+  origin: (origin, cb) => {
+    if (!origin || allowedOrigins.includes(origin)) {
+      cb(null, true)
+    } else {
+      cb(new Error('Not allowed'), false)
+    }
+  },
+  credentials: true,
+})`,
+    },
+  },
+
+  // ==========================================================================
+  // Dangerous Function (eval, innerHTML) - Context-specific
+  // ==========================================================================
+  dangerous_function: {
+    react: {
+      fixSteps: [
+        'Replace innerHTML with React JSX (auto-escapes content)',
+        'Use textContent or innerText for plain text updates',
+        'If dynamic HTML is required, use DOMPurify before dangerouslySetInnerHTML',
+        'Consider using a markdown renderer (react-markdown) for rich content',
+      ],
+      codeExample: `// Instead of innerHTML
+const element = document.getElementById('content')
+element.innerHTML = userInput // Dangerous!
+
+// Use React JSX
+function SafeContent({ content }) {
+  return <div>{content}</div> // Safe - auto-escaped
+}`,
+    },
+    vue: {
+      fixSteps: [
+        'Use Vue template interpolation {{ }} instead of v-html',
+        'If HTML rendering is required, sanitize with DOMPurify first',
+        'Consider component-based approaches for dynamic content',
+        'Validate and sanitize on the server before sending to client',
+      ],
+    },
+  },
+}
+
+// ============================================================================
+// Lookup Function
+// ============================================================================
+
+/**
+ * Get framework-specific fix for a vulnerability category.
+ *
+ * Priority order for ORM-related categories (sql_injection):
+ * 1. ORM (prisma, drizzle, supabase, mongoose, knex)
+ * 2. Backend framework (nextjs, express, fastify, nestjs)
+ *
+ * Priority order for other categories:
+ * 1. Frontend framework for XSS (react, vue)
+ * 2. Backend framework for auth/cors/secrets
+ *
+ * @returns FrameworkFix if a match is found, undefined otherwise (falls back to generic)
+ */
+export function getFrameworkFix(
+  category: VulnerabilityCategory,
+  frameworks: FrameworkContext,
+  dataAccess?: DataAccessContext
+): FrameworkFix | undefined {
+  const categoryFixes = FRAMEWORK_FIX_REGISTRY[category]
+  if (!categoryFixes) {
+    return undefined
+  }
+
+  // For SQL injection, prioritize ORM-specific fixes
+  if (category === 'sql_injection' && dataAccess?.orm) {
+    const ormFix = categoryFixes[dataAccess.orm as FrameworkKey]
+    if (ormFix) {
+      return ormFix
+    }
+  }
+
+  // For XSS and dangerous_function, prioritize frontend framework
+  if ((category === 'xss' || category === 'dangerous_function') && frameworks.frontend) {
+    const frontendFix = categoryFixes[frameworks.frontend as FrameworkKey]
+    if (frontendFix) {
+      return frontendFix
+    }
+  }
+
+  // For other categories, try backend framework
+  if (frameworks.primary) {
+    const backendFix = categoryFixes[frameworks.primary as FrameworkKey]
+    if (backendFix) {
+      return backendFix
+    }
+  }
+
+  // No framework-specific fix found
+  return undefined
+}