@oculum/scanner 1.0.11 → 1.0.13

package/src/__tests__/context-engine/route-discovery/nextjs.test.ts

@@ -0,0 +1,138 @@
+import { extractNextJSRoutes } from '../../../model/route-discovery/nextjs'
+import type { ScanFile } from '../../../shared/types'
+
+function makeFile(path: string, content: string): ScanFile {
+  return { path, content, language: 'typescript' }
+}
+
+describe('Next.js Route Extractor', () => {
+  it('extracts App Router GET export', () => {
+    const files = [
+      makeFile('src/app/api/users/route.ts', `
+export async function GET(request: Request) {
+  return Response.json({ users: [] })
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    expect(routes[0].methods).toEqual(['GET'])
+    expect(routes[0].path).toBe('/api/users')
+    expect(routes[0].framework).toBe('nextjs_app')
+  })
+
+  it('extracts multiple HTTP method exports', () => {
+    const files = [
+      makeFile('src/app/api/items/route.ts', `
+export async function GET(request: Request) {
+  return Response.json([])
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  return Response.json({ created: true })
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(2)
+    expect(routes.map(r => r.methods[0]).sort()).toEqual(['GET', 'POST'])
+  })
+
+  it('handles dynamic segments [id] → :id', () => {
+    const files = [
+      makeFile('src/app/api/users/[id]/route.ts', `
+export async function GET(request: Request, { params }: { params: { id: string } }) {
+  return Response.json({ id: params.id })
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    expect(routes[0].path).toBe('/api/users/:id')
+  })
+
+  it('handles catch-all [...slug]', () => {
+    const files = [
+      makeFile('src/app/api/docs/[...slug]/route.ts', `
+export async function GET() {
+  return Response.json({})
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    expect(routes[0].path).toBe('/api/docs/:slug*')
+  })
+
+  it('strips route groups from path', () => {
+    const files = [
+      makeFile('src/app/(dashboard)/api/settings/route.ts', `
+export async function GET() {
+  return Response.json({})
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    expect(routes[0].path).toBe('/api/settings')
+  })
+
+  it('detects protected route groups', () => {
+    const files = [
+      makeFile('src/app/(authenticated)/api/profile/route.ts', `
+export async function GET() {
+  return Response.json({})
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    // Route hierarchy should detect (authenticated) group
+    expect(routes[0].authMiddleware.length).toBeGreaterThan(0)
+  })
+
+  it('extracts Pages Router default export', () => {
+    const files = [
+      makeFile('src/pages/api/search.ts', `
+export default function handler(req, res) {
+  if (req.method === 'GET') {
+    const q = req.query.q
+    res.json({ results: [] })
+  }
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    expect(routes[0].framework).toBe('nextjs_pages')
+    expect(routes[0].path).toBe('/api/search')
+    expect(routes[0].methods).toEqual(['GET'])
+  })
+
+  it('detects input sources in App Router', () => {
+    const files = [
+      makeFile('src/app/api/items/route.ts', `
+export async function POST(request: Request) {
+  const body = await request.json()
+  const url = new URL(request.url)
+  const page = url.searchParams.get('page')
+  return Response.json({ ok: true })
+}
+`),
+    ]
+    const routes = extractNextJSRoutes(files, 'nextjs')
+    expect(routes).toHaveLength(1)
+    const sources = routes[0].inputs.map(i => i.source)
+    expect(sources).toContain('body')
+    expect(sources).toContain('query')
+  })
+
+  it('skips non-nextjs frameworks', () => {
+    const files = [
+      makeFile('src/app/api/test/route.ts', `export function GET() {}`),
+    ]
+    const routes = extractNextJSRoutes(files, 'express')
+    expect(routes).toHaveLength(0)
+  })
+})

package/src/__tests__/context-engine/route-discovery/python.test.ts

@@ -0,0 +1,95 @@
+import { extractPythonRoutes } from '../../../model/route-discovery/python'
+
+describe('Python Route Extractor', () => {
+  describe('Flask routes', () => {
+    it('extracts @app.route with default GET', () => {
+      const content = `
+from flask import Flask
+app = Flask(__name__)
+
+@app.route('/api/users')
+def get_users():
+    return jsonify(users)
+`
+      const routes = extractPythonRoutes(content, 'app.py')
+      expect(routes).toHaveLength(1)
+      expect(routes[0].methods).toEqual(['GET'])
+      expect(routes[0].path).toBe('/api/users')
+      expect(routes[0].framework).toBe('flask')
+      expect(routes[0].handler).toBe('get_users')
+    })
+
+    it('extracts @app.route with explicit methods', () => {
+      const content = `
+@app.route('/api/items', methods=['GET', 'POST'])
+def items():
+    pass
+`
+      const routes = extractPythonRoutes(content, 'views.py')
+      expect(routes).toHaveLength(1)
+      expect(routes[0].methods).toEqual(['GET', 'POST'])
+    })
+
+    it('detects @login_required decorator', () => {
+      const content = `
+@app.route('/api/profile')
+@login_required
+def profile():
+    pass
+`
+      const routes = extractPythonRoutes(content, 'views.py')
+      expect(routes).toHaveLength(1)
+      expect(routes[0].authMiddleware).toContain('@login_required')
+    })
+
+    it('converts Flask path params to :param format', () => {
+      const content = `
+@app.route('/api/users/<int:user_id>')
+def get_user(user_id):
+    pass
+`
+      const routes = extractPythonRoutes(content, 'views.py')
+      expect(routes).toHaveLength(1)
+      expect(routes[0].path).toBe('/api/users/:user_id')
+    })
+
+    it('detects Flask input sources', () => {
+      const content = `
+@app.route('/api/search', methods=['POST'])
+def search():
+    data = request.json
+    q = request.args.get('q')
+    return jsonify(results=[])
+`
+      const routes = extractPythonRoutes(content, 'views.py')
+      expect(routes).toHaveLength(1)
+      const sources = routes[0].inputs.map(i => i.source)
+      expect(sources).toContain('body')
+      expect(sources).toContain('query')
+    })
+  })
+
+  describe('Django routes', () => {
+    it('extracts Django path() in urlpatterns', () => {
+      const content = `
+from django.urls import path
+from . import views
+
+urlpatterns = [
+    path('api/search/', views.search_view, name='search'),
+    path('api/users/<int:pk>/', views.UserDetailView.as_view(), name='user-detail'),
+]
+`
+      const routes = extractPythonRoutes(content, 'urls.py')
+      expect(routes).toHaveLength(2)
+      expect(routes[0].path).toBe('/api/search/')
+      expect(routes[0].framework).toBe('django')
+      expect(routes[1].path).toBe('/api/users/:pk/')
+    })
+  })
+
+  it('skips non-Python files', () => {
+    const routes = extractPythonRoutes('app.get("/test", handler)', 'server.js')
+    expect(routes).toHaveLength(0)
+  })
+})

package/src/__tests__/context-engine/sanitiser-detection.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for sanitiser detection — identifying sanitisation functions in code.
+ */
+
+import { detectSanitisers, isSanitiserCall } from '../../model/sanitiser-detection'
+
+describe('detectSanitisers', () => {
+  describe('DOMPurify', () => {
+    it('detects DOMPurify.sanitize when imported', () => {
+      const code = `
+import DOMPurify from 'dompurify'
+const clean = DOMPurify.sanitize(dirty)
+`
+      const sanitisers = detectSanitisers(code, 'src/utils.ts')
+      expect(sanitisers.some(s => s.name === 'DOMPurify.sanitize')).toBe(true)
+      expect(sanitisers.find(s => s.name === 'DOMPurify.sanitize')?.sanitises).toBe('html')
+      expect(sanitisers.find(s => s.name === 'DOMPurify.sanitize')?.detection).toBe('known_library')
+    })
+
+    it('does not detect DOMPurify.sanitize without import', () => {
+      const code = `const clean = DOMPurify.sanitize(dirty)`
+      const sanitisers = detectSanitisers(code, 'src/utils.ts')
+      expect(sanitisers.some(s => s.name === 'DOMPurify.sanitize' && s.detection === 'known_library')).toBe(false)
+    })
+  })
+
+  describe('validator.js', () => {
+    it('detects validator.escape when imported', () => {
+      const code = `
+import validator from 'validator'
+const safe = validator.escape(input)
+`
+      const sanitisers = detectSanitisers(code, 'src/utils.ts')
+      expect(sanitisers.some(s => s.name === 'validator.escape')).toBe(true)
+    })
+  })
+
+  describe('Zod/Joi/Yup', () => {
+    it('detects zod .parse() when imported', () => {
+      const code = `
+import { z } from 'zod'
+const schema = z.object({ name: z.string() })
+const data = schema.parse(input)
+`
+      const sanitisers = detectSanitisers(code, 'src/validation.ts')
+      expect(sanitisers.some(s => s.name === 'zod.parse' && s.sanitises === 'all')).toBe(true)
+    })
+
+    it('detects joi .validate() when imported', () => {
+      const code = `
+import joi from 'joi'
+const result = schema.validate(input)
+`
+      const sanitisers = detectSanitisers(code, 'src/validation.ts')
+      expect(sanitisers.some(s => s.name === 'joi.validate')).toBe(true)
+    })
+
+    it('detects yup .validate() when imported', () => {
+      const code = `
+import * as yup from 'yup'
+const result = await schema.validate(input)
+`
+      const sanitisers = detectSanitisers(code, 'src/validation.ts')
+      expect(sanitisers.some(s => s.name === 'yup.validate')).toBe(true)
+    })
+  })
+
+  describe('Type coercion (universal)', () => {
+    it('detects Number()', () => {
+      const code = `const id = Number(input)`
+      const sanitisers = detectSanitisers(code, 'src/api.ts')
+      expect(sanitisers.some(s => s.name === 'Number' && s.sanitises === 'all')).toBe(true)
+    })
+
+    it('detects parseInt()', () => {
+      const code = `const id = parseInt(input, 10)`
+      const sanitisers = detectSanitisers(code, 'src/api.ts')
+      expect(sanitisers.some(s => s.name === 'parseInt')).toBe(true)
+    })
+
+    it('detects parseFloat()', () => {
+      const code = `const price = parseFloat(input)`
+      const sanitisers = detectSanitisers(code, 'src/api.ts')
+      expect(sanitisers.some(s => s.name === 'parseFloat')).toBe(true)
+    })
+
+    it('detects Boolean()', () => {
+      const code = `const flag = Boolean(input)`
+      const sanitisers = detectSanitisers(code, 'src/api.ts')
+      expect(sanitisers.some(s => s.name === 'Boolean')).toBe(true)
+    })
+  })
+
+  describe('Parameterised queries', () => {
+    it('detects ? placeholder parameterised queries', () => {
+      const code = `db.query('SELECT * FROM users WHERE id = ?', [userId])`
+      const sanitisers = detectSanitisers(code, 'src/db.ts')
+      expect(sanitisers.some(s => s.name === 'parameterised_query' && s.sanitises === 'sql')).toBe(true)
+    })
+
+    it('detects $1 placeholder parameterised queries', () => {
+      const code = `db.query('SELECT * FROM users WHERE id = $1', [userId])`
+      const sanitisers = detectSanitisers(code, 'src/db.ts')
+      expect(sanitisers.some(s => s.name === 'parameterised_query')).toBe(true)
+    })
+
+    it('detects Sequelize replacements', () => {
+      const code = `sequelize.query('SELECT * FROM users', { replacements: { id } })`
+      const sanitisers = detectSanitisers(code, 'src/db.ts')
+      expect(sanitisers.some(s => s.name === 'parameterised_query')).toBe(true)
+    })
+  })
+
+  describe('Path sanitisers', () => {
+    it('detects path.normalize()', () => {
+      const code = `const safe = path.normalize(input)`
+      const sanitisers = detectSanitisers(code, 'src/fs.ts')
+      expect(sanitisers.some(s => s.name === 'path.normalize' && s.sanitises === 'path')).toBe(true)
+    })
+  })
+
+  describe('Python sanitisers', () => {
+    it('detects shlex.quote()', () => {
+      const code = `safe = shlex.quote(user_input)`
+      const sanitisers = detectSanitisers(code, 'app/utils.py')
+      expect(sanitisers.some(s => s.name === 'shlex.quote' && s.sanitises === 'command')).toBe(true)
+    })
+
+    it('detects html.escape()', () => {
+      const code = `safe = html.escape(user_input)`
+      const sanitisers = detectSanitisers(code, 'app/utils.py')
+      expect(sanitisers.some(s => s.name === 'html.escape' && s.sanitises === 'html')).toBe(true)
+    })
+  })
+
+  describe('Name heuristic', () => {
+    it('detects functions with "sanitize" in name', () => {
+      const code = `const safe = sanitizeInput(dirty)`
+      const sanitisers = detectSanitisers(code, 'src/utils.ts')
+      expect(sanitisers.some(s => s.detection === 'name_heuristic')).toBe(true)
+    })
+  })
+
+  describe('Edge cases', () => {
+    it('skips comments', () => {
+      const code = `// DOMPurify.sanitize(dirty)`
+      const sanitisers = detectSanitisers(code, 'src/utils.ts')
+      expect(sanitisers).toHaveLength(0)
+    })
+
+    it('deduplicates sanitisers on same line', () => {
+      const code = `const id = Number(parseInt(input))`
+      const sanitisers = detectSanitisers(code, 'src/api.ts')
+      const lineOnes = sanitisers.filter(s => s.line === 1)
+      const uniqueNames = new Set(lineOnes.map(s => s.name))
+      expect(uniqueNames.size).toBe(lineOnes.length)
+    })
+  })
+})
+
+describe('isSanitiserCall', () => {
+  it('detects Number() as sanitiser', () => {
+    const result = isSanitiserCall('const id = Number(input)', [])
+    expect(result.sanitised).toBe(true)
+    expect(result.method).toBe('Number')
+    expect(result.target).toBe('all')
+  })
+
+  it('detects parseInt() as sanitiser', () => {
+    const result = isSanitiserCall('const id = parseInt(input, 10)', [])
+    expect(result.sanitised).toBe(true)
+  })
+
+  it('returns false for non-sanitiser calls', () => {
+    const result = isSanitiserCall('const data = someFunction(input)', [])
+    expect(result.sanitised).toBe(false)
+  })
+
+  it('detects file-level sanitisers', () => {
+    const fileSanitisers = [
+      { name: 'DOMPurify.sanitize', line: 5, sanitises: 'html' as const, detection: 'known_library' as const, library: 'dompurify' }
+    ]
+    const result = isSanitiserCall('const safe = DOMPurify.sanitize(dirty)', fileSanitisers)
+    expect(result.sanitised).toBe(true)
+    expect(result.target).toBe('html')
+  })
+})

package/src/__tests__/context-engine/sink-matcher.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Tests for sink matching — matching tainted variables to dangerous sinks.
+ */
+
+import { matchSinks } from '../../model/sink-matcher'
+import type { TaintedVariable, UserInputSource, SanitiserInfo } from '../../model/taint-types'
+
+function makeSource(overrides: Partial<UserInputSource> = {}): UserInputSource {
+  return {
+    line: 1,
+    expression: 'req.body',
+    variable: 'userInput',
+    sourceType: 'http_body',
+    confidence: 'high',
+    ...overrides,
+  }
+}
+
+function makeTaintedVar(name: string, overrides: Partial<TaintedVariable> = {}): TaintedVariable {
+  return {
+    name,
+    taintedAt: 2,
+    source: makeSource(),
+    propagation: 'direct_assignment',
+    sanitised: false,
+    scopeDepth: 0,
+    ...overrides,
+  }
+}
+
+describe('matchSinks', () => {
+  describe('SQL injection', () => {
+    it('matches tainted variable in .query() call', () => {
+      const code = `
+const userInput = req.body
+db.query("SELECT * FROM users WHERE id = " + userInput)
+`
+      const taintedVars = [makeTaintedVar('userInput')]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('sql_query')
+      expect(paths[0].sanitised).toBe(false)
+      expect(paths[0].confidence).toBe('high')
+    })
+
+    it('marks parameterised queries as sanitised', () => {
+      const code = `
+const userId = req.query
+db.query('SELECT * FROM users WHERE id = ?', [userId])
+`
+      const taintedVars = [makeTaintedVar('userId')]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sanitised).toBe(true)
+    })
+  })
+
+  describe('XSS', () => {
+    it('matches tainted variable in innerHTML assignment', () => {
+      const code = `
+const userInput = req.body
+el.innerHTML = userInput
+`
+      const taintedVars = [makeTaintedVar('userInput')]
+      const paths = matchSinks(code, 'src/render.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('inner_html')
+    })
+
+    it('matches dangerouslySetInnerHTML', () => {
+      const code = `
+const userInput = req.body
+return <div dangerouslySetInnerHTML={{ __html: userInput }} />
+`
+      const taintedVars = [makeTaintedVar('userInput')]
+      const paths = matchSinks(code, 'src/component.tsx', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('inner_html')
+    })
+  })
+
+  describe('Command injection', () => {
+    it('matches tainted variable in exec() call', () => {
+      const code = `
+const cmd = req.body
+exec(cmd)
+`
+      const taintedVars = [makeTaintedVar('cmd')]
+      const paths = matchSinks(code, 'src/utils.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('exec')
+    })
+
+    it('matches Python subprocess.run()', () => {
+      const code = `
+cmd = request.args
+subprocess.run(cmd, shell=True)
+`
+      const taintedVars = [makeTaintedVar('cmd')]
+      const paths = matchSinks(code, 'app/utils.py', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('command_exec')
+    })
+  })
+
+  describe('SSRF', () => {
+    it('matches tainted variable in fetch() call', () => {
+      const code = `
+const url = req.body
+fetch(url)
+`
+      const taintedVars = [makeTaintedVar('url')]
+      const paths = matchSinks(code, 'src/api.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('http_request')
+    })
+
+    it('matches tainted variable in axios call', () => {
+      const code = `
+const url = req.body
+axios.get(url)
+`
+      const taintedVars = [makeTaintedVar('url')]
+      const paths = matchSinks(code, 'src/api.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('http_request')
+    })
+  })
+
+  describe('Code execution', () => {
+    it('matches tainted variable in eval()', () => {
+      const code = `
+const code = req.body
+eval(code)
+`
+      const taintedVars = [makeTaintedVar('code')]
+      const paths = matchSinks(code, 'src/api.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('eval')
+    })
+  })
+
+  describe('File system', () => {
+    it('matches tainted variable in fs.readFile', () => {
+      const code = `
+const filePath = req.body
+fs.readFile(filePath)
+`
+      const taintedVars = [makeTaintedVar('filePath')]
+      const paths = matchSinks(code, 'src/fs.ts', taintedVars, [])
+      expect(paths.some(p => p.sink.sinkType === 'path_access')).toBe(true)
+    })
+  })
+
+  describe('Redirect', () => {
+    it('matches tainted variable in res.redirect()', () => {
+      const code = `
+const target = req.body
+res.redirect(target)
+`
+      const taintedVars = [makeTaintedVar('target')]
+      const paths = matchSinks(code, 'src/routes.ts', taintedVars, [])
+      expect(paths).toHaveLength(1)
+      expect(paths[0].sink.sinkType).toBe('redirect')
+    })
+  })
+
+  describe('Sanitised paths', () => {
+    it('marks path as sanitised when sanitiser wraps sink', () => {
+      const code = `
+const userInput = req.body
+const id = Number(userInput)
+db.query("SELECT * FROM users WHERE id = " + id)
+`
+      // id is sanitised (Number)
+      const taintedVars = [
+        makeTaintedVar('userInput'),
+        makeTaintedVar('id', { sanitised: true, sanitisedAt: 3, sanitisationMethod: 'Number' }),
+      ]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      // Only unsanitised vars should match sinks
+      // 'id' is sanitised so it shouldn't be in activeTaintedVars
+      // 'userInput' doesn't appear on the query line, only 'id' does
+      expect(paths).toHaveLength(0)
+    })
+  })
+
+  describe('Static data (no match)', () => {
+    it('does not create path when no tainted variable reaches sink', () => {
+      const code = `
+const hardcodedId = "12345"
+db.query("SELECT * FROM users WHERE id = " + hardcodedId)
+`
+      const taintedVars: TaintedVariable[] = []
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      expect(paths).toHaveLength(0)
+    })
+  })
+
+  describe('Confidence computation', () => {
+    it('assigns high confidence for short chain with high-confidence source', () => {
+      const code = `
+const userInput = req.body
+db.query(userInput)
+`
+      const taintedVars = [makeTaintedVar('userInput')]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      expect(paths[0].confidence).toBe('high')
+    })
+
+    it('assigns medium confidence for medium-confidence source', () => {
+      const code = `
+const userInput = searchParams
+db.query(userInput)
+`
+      const taintedVars = [makeTaintedVar('userInput', {
+        source: makeSource({ confidence: 'medium' }),
+      })]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      expect(paths[0].confidence).toBe('medium')
+    })
+
+    it('assigns low confidence for low-confidence source', () => {
+      const code = `
+const args = process.argv
+db.query(args)
+`
+      const taintedVars = [makeTaintedVar('args', {
+        source: makeSource({ confidence: 'low' }),
+      })]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      expect(paths[0].confidence).toBe('low')
+    })
+  })
+
+  describe('Deduplication', () => {
+    it('deduplicates paths with same source, sink type, and line', () => {
+      const code = `
+const userInput = req.body
+db.query(userInput)
+`
+      // Two tainted vars pointing to the same source
+      const taintedVars = [
+        makeTaintedVar('userInput'),
+      ]
+      const paths = matchSinks(code, 'src/db.ts', taintedVars, [])
+      // Should only produce one path
+      expect(paths).toHaveLength(1)
+    })
+  })
+})