agent-security-scanner-mcp 3.7.0 → 3.8.0

package/src/context.js

@@ -0,0 +1,289 @@
+// Context-aware filtering to reduce false positives.
+// Suppresses findings on import-only lines for known standard/popular modules.
+
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+// Known safe standard library and popular modules per language
+const KNOWN_MODULES = {
+  javascript: new Set([
+    // Node.js builtins
+    'assert', 'buffer', 'child_process', 'cluster', 'crypto', 'dgram',
+    'dns', 'events', 'fs', 'http', 'http2', 'https', 'net', 'os',
+    'path', 'perf_hooks', 'process', 'querystring', 'readline', 'stream',
+    'string_decoder', 'timers', 'tls', 'tty', 'url', 'util', 'v8',
+    'vm', 'worker_threads', 'zlib',
+    // Popular frameworks/libraries
+    'express', 'koa', 'fastify', 'hapi', 'next', 'nuxt',
+    'react', 'react-dom', 'vue', 'angular', 'svelte',
+    'lodash', 'underscore', 'ramda',
+    'axios', 'node-fetch', 'got', 'superagent',
+    'moment', 'dayjs', 'date-fns', 'luxon',
+    'winston', 'morgan', 'pino', 'bunyan',
+    'helmet', 'cors', 'body-parser', 'cookie-parser', 'compression',
+    'passport', 'jsonwebtoken', 'bcrypt', 'bcryptjs',
+    'jest', 'mocha', 'chai', 'vitest', 'sinon', 'tape',
+    'typescript', 'webpack', 'vite', 'esbuild', 'rollup', 'parcel',
+    'mysql', 'mysql2', 'pg', 'mongodb', 'mongoose', 'redis', 'ioredis',
+    'sequelize', 'knex', 'prisma', 'typeorm', 'drizzle-orm',
+    'zod', 'joi', 'yup', 'ajv',
+    'dotenv', 'config', 'commander', 'yargs',
+    'chalk', 'debug', 'uuid', 'nanoid',
+    'socket.io', 'ws',
+  ]),
+  typescript: new Set([
+    // Same as JavaScript - TS shares the same ecosystem
+    'assert', 'buffer', 'child_process', 'cluster', 'crypto', 'dgram',
+    'dns', 'events', 'fs', 'http', 'http2', 'https', 'net', 'os',
+    'path', 'process', 'querystring', 'readline', 'stream', 'tls',
+    'url', 'util', 'worker_threads', 'zlib',
+    'express', 'koa', 'fastify', 'next', 'nuxt',
+    'react', 'react-dom', 'vue', 'angular', 'svelte',
+    'lodash', 'axios', 'node-fetch',
+    'helmet', 'cors', 'body-parser',
+    'jest', 'mocha', 'vitest',
+    'typescript', 'webpack', 'vite', 'esbuild',
+    'mysql', 'mysql2', 'pg', 'mongodb', 'mongoose', 'redis',
+    'sequelize', 'knex', 'prisma', 'typeorm',
+    'zod', 'joi',
+  ]),
+  python: new Set([
+    // Standard library
+    'os', 'sys', 'json', 'math', 'datetime', 'collections', 're',
+    'pathlib', 'typing', 'abc', 'io', 'subprocess', 'shutil',
+    'hashlib', 'hmac', 'secrets', 'sqlite3', 'csv', 'xml',
+    'urllib', 'http', 'socket', 'ssl', 'email', 'logging',
+    'unittest', 'argparse', 'configparser', 'functools', 'itertools',
+    'contextlib', 'dataclasses', 'enum', 'struct', 'copy', 'pprint',
+    'textwrap', 'string', 'codecs', 'base64', 'binascii',
+    'threading', 'multiprocessing', 'asyncio', 'concurrent',
+    'pickle', 'shelve', 'marshal', 'dbm',
+    'tempfile', 'glob', 'fnmatch', 'stat',
+    'time', 'calendar', 'locale', 'gettext',
+    'random', 'statistics',
+    // Popular packages
+    'pytest', 'mock', 'coverage',
+    'flask', 'django', 'fastapi', 'starlette', 'uvicorn', 'gunicorn',
+    'requests', 'httpx', 'aiohttp', 'urllib3',
+    'sqlalchemy', 'alembic', 'psycopg2', 'pymongo',
+    'celery', 'redis', 'boto3', 'botocore',
+    'numpy', 'pandas', 'scipy', 'matplotlib',
+    'pydantic', 'marshmallow', 'attrs',
+    'click', 'typer', 'rich',
+    'yaml', 'toml', 'dotenv',
+  ]),
+  ruby: new Set([
+    'rails', 'sinatra', 'rack', 'puma', 'unicorn',
+    'bundler', 'rake', 'rspec', 'minitest',
+    'activerecord', 'activesupport', 'actionpack',
+    'devise', 'pundit', 'cancancan',
+    'json', 'yaml', 'csv', 'net/http', 'uri', 'openssl',
+    'fileutils', 'pathname', 'tempfile', 'logger',
+  ]),
+  go: new Set([
+    'fmt', 'os', 'io', 'net', 'net/http', 'encoding/json',
+    'encoding/xml', 'crypto', 'crypto/tls', 'database/sql',
+    'sync', 'context', 'errors', 'strings', 'strconv',
+    'path', 'path/filepath', 'log', 'testing', 'time',
+    'math', 'sort', 'regexp', 'reflect', 'bufio',
+  ]),
+};
+
+// Patterns that identify import-only lines (no actual code execution)
+const IMPORT_ONLY_PATTERNS = [
+  // JS/TS require
+  /^\s*(const|let|var)\s+\w+\s*=\s*require\s*\(\s*['"][^'"]+['"]\s*\)\s*;?\s*$/,
+  /^\s*(const|let|var)\s+\{[^}]+\}\s*=\s*require\s*\(\s*['"][^'"]+['"]\s*\)\s*;?\s*$/,
+  // JS/TS import
+  /^\s*import\s+.*\s+from\s+['"][^'"]+['"]\s*;?\s*$/,
+  /^\s*import\s+['"][^'"]+['"]\s*;?\s*$/,
+  /^\s*import\s+\w+\s*$/,
+  // Python import
+  /^\s*import\s+[a-zA-Z_][\w.]*\s*(,\s*[a-zA-Z_][\w.]*)*\s*$/,
+  /^\s*from\s+[a-zA-Z_][\w.]*\s+import\s+/,
+  // Ruby require
+  /^\s*require\s+['"][^'"]+['"]\s*$/,
+  /^\s*require_relative\s+['"][^'"]+['"]\s*$/,
+  // Go import (single line)
+  /^\s*"[a-zA-Z_][\w/.]*"\s*$/,
+];
+
+export function isImportOnly(line) {
+  let trimmed = line.trim();
+  if (!trimmed) return false;
+  // Strip trailing single-line comments (JS/Python/Ruby)
+  trimmed = trimmed.replace(/\s*\/\/.*$/, '').replace(/\s*#(?!!).*$/, '').trim();
+  if (!trimmed) return false;
+  return IMPORT_ONLY_PATTERNS.some(p => p.test(trimmed));
+}
+
+export function isKnownModule(moduleName, language) {
+  const modules = KNOWN_MODULES[language];
+  if (!modules) return false;
+  // Handle scoped packages (@org/pkg -> check full name)
+  // Handle subpath imports (child_process -> child_process)
+  const baseName = moduleName.split('/')[0];
+  return modules.has(moduleName) || modules.has(baseName);
+}
+
+// Extract module name from a line of code
+function extractModuleName(line) {
+  // JS/TS: require("module") or require('module')
+  const requireMatch = line.match(/require\s*\(\s*['"]([^'"]+)['"]\s*\)/);
+  if (requireMatch) return requireMatch[1];
+
+  // JS/TS: import ... from "module"
+  const importFromMatch = line.match(/from\s+['"]([^'"]+)['"]/);
+  if (importFromMatch) return importFromMatch[1];
+
+  // Python: import module or from module import ...
+  const pyImportMatch = line.match(/^\s*import\s+([a-zA-Z_][\w]*)/);
+  if (pyImportMatch) return pyImportMatch[1];
+
+  const pyFromMatch = line.match(/^\s*from\s+([a-zA-Z_][\w]*)/);
+  if (pyFromMatch) return pyFromMatch[1];
+
+  return null;
+}
+
+// Variable names that indicate non-security use of weak hashing (MD5/SHA1)
+const NON_SECURITY_HASH_VARS = new Set([
+  'checksum', 'digest', 'etag', 'e_tag', 'hash_value', 'file_hash',
+  'content_hash', 'cache_key', 'fingerprint', 'hex_digest', 'hexdigest',
+]);
+
+// Inline suppression comments
+const NOSEC_PATTERN = /(?:\/\/|#|\/\*)\s*nosec\b/i;
+
+// Test file path patterns
+const TEST_FILE_PATTERNS = [
+  /[/\\]tests?[/\\]/i,
+  /[/\\]__tests__[/\\]/i,
+  /[/\\]spec[/\\]/i,
+  /[._](?:test|spec)\.[^.]+$/i,
+  /[/\\]test[-_]?files?[/\\]/i,
+  /[/\\]fixtures?[/\\]/i,
+  /[/\\]demo[/\\]/i,
+];
+
+// Check if a file path looks like a test file
+export function isTestFile(filePath) {
+  return TEST_FILE_PATTERNS.some(p => p.test(filePath));
+}
+
+// Check if a line has a nosec suppression comment
+export function hasNosecComment(line) {
+  return NOSEC_PATTERN.test(line);
+}
+
+// Check if a variable name on a line suggests non-security hash usage
+function isNonSecurityHashUsage(line) {
+  const lower = line.toLowerCase();
+  for (const varName of NON_SECURITY_HASH_VARS) {
+    if (lower.includes(varName)) return true;
+  }
+  return false;
+}
+
+// Filter findings based on context awareness
+export function applyContextFilter(findings, filePath, language) {
+  if (!Array.isArray(findings) || findings.length === 0) return findings;
+
+  let lines = [];
+  try {
+    if (existsSync(filePath)) {
+      lines = readFileSync(filePath, 'utf-8').split('\n');
+    }
+  } catch {
+    return findings;
+  }
+
+  const inTestFile = isTestFile(filePath);
+
+  return findings.filter(finding => {
+    const line = lines[finding.line] || '';
+    const ruleId = finding.ruleId?.toLowerCase() || '';
+
+    // Inline suppression: // nosec or # nosec
+    if (hasNosecComment(line)) {
+      return false;
+    }
+
+    // Variable-name heuristic: MD5/SHA1 used for checksums → downgrade to info
+    if ((ruleId.includes('md5') || ruleId.includes('sha1')) && isNonSecurityHashUsage(line)) {
+      finding.severity = 'info';
+      finding.contextNote = 'Non-security hash usage (checksum/digest/etag)';
+    }
+
+    // Test file heuristic: downgrade hardcoded secrets in test files to warning
+    if (inTestFile && (ruleId.includes('hardcoded') || ruleId.includes('secret') || ruleId.includes('password') || ruleId.includes('api-key'))) {
+      if (finding.severity === 'error') {
+        finding.severity = 'warning';
+        finding.contextNote = 'Hardcoded secret in test file';
+      }
+    }
+
+    // Import-only filter
+    if (!isImportOnly(line)) return true;
+
+    // Check if the module is known/safe
+    const moduleName = extractModuleName(line);
+    if (moduleName && isKnownModule(moduleName, language)) {
+      return false; // Suppress finding on known module import
+    }
+
+    return true;
+  });
+}
+
+// Framework/middleware detection patterns
+const FRAMEWORK_PATTERNS = {
+  helmet: { pattern: /require\s*\(\s*['"]helmet['"]\s*\)|from\s+['"]helmet['"]|import\s+.*helmet/, languages: ['javascript', 'typescript'] },
+  dompurify: { pattern: /require\s*\(\s*['"](?:dompurify|isomorphic-dompurify)['"]\s*\)|from\s+['"](?:dompurify|isomorphic-dompurify)['"]|import\s+.*(?:dompurify|DOMPurify)/, languages: ['javascript', 'typescript'] },
+  csurf: { pattern: /require\s*\(\s*['"]csurf['"]\s*\)|from\s+['"]csurf['"]/, languages: ['javascript', 'typescript'] },
+  cors: { pattern: /require\s*\(\s*['"]cors['"]\s*\)|from\s+['"]cors['"]/, languages: ['javascript', 'typescript'] },
+  prisma: { pattern: /from\s+prisma|import\s+prisma|@prisma\/client/, languages: ['javascript', 'typescript', 'python'] },
+  bcrypt: { pattern: /import\s+bcrypt|from\s+bcrypt|require\s*\(\s*['"]bcryptjs?['"]\s*\)/, languages: ['javascript', 'typescript', 'python'] },
+};
+
+// Maps framework -> which rule categories it mitigates -> downgraded severity
+const SEVERITY_DOWNGRADE = {
+  helmet: { mitigates: ['xss', 'innerhtml', 'outerhtml', 'document-write', 'cors-wildcard'], to: 'warning' },
+  dompurify: { mitigates: ['xss', 'innerhtml', 'outerhtml', 'dangerouslysetinnerhtml', 'insertadjacenthtml', 'document-write'], to: 'warning' },
+  csurf: { mitigates: ['csrf'], to: 'warning' },
+  cors: { mitigates: ['cors-wildcard'], to: 'info' },
+  prisma: { mitigates: ['sql-injection', 'nosql-injection', 'raw-query'], to: 'warning' },
+  bcrypt: { mitigates: ['md5', 'sha1', 'weak-hash', 'weak-cipher'], to: 'info' },
+};
+
+export function detectFrameworks(filePath, language) {
+  const detected = [];
+  try {
+    if (!existsSync(filePath)) return detected;
+    const content = readFileSync(filePath, 'utf-8');
+    for (const [name, config] of Object.entries(FRAMEWORK_PATTERNS)) {
+      if (config.languages.includes(language) && config.pattern.test(content)) {
+        detected.push(name);
+      }
+    }
+  } catch {
+    // Ignore read errors
+  }
+  return detected;
+}
+
+export function applyFrameworkAdjustments(findings, frameworks) {
+  if (!Array.isArray(findings) || findings.length === 0 || frameworks.length === 0) return findings;
+
+  return findings.map(finding => {
+    const ruleId = finding.ruleId?.toLowerCase() || '';
+    for (const fw of frameworks) {
+      const downgrade = SEVERITY_DOWNGRADE[fw];
+      if (!downgrade) continue;
+      if (downgrade.mitigates.some(m => ruleId.includes(m))) {
+        return { ...finding, severity: downgrade.to, frameworkMitigated: fw };
+      }
+    }
+    return finding;
+  });
+}

package/src/daemon-client.js

@@ -0,0 +1,233 @@
+// src/daemon-client.js — Node.js client managing daemon lifecycle and JSONL communication.
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+let __dirname;
+try {
+  __dirname = dirname(fileURLToPath(import.meta.url));
+} catch {
+  __dirname = process.cwd();
+}
+
+const DAEMON_SCRIPT = join(__dirname, '..', 'daemon.py');
+const READY_TIMEOUT = 15000;   // 15s to wait for __ready__ signal
+const REQUEST_TIMEOUT = 30000; // 30s per request
+const MAX_RESTARTS = 3;
+const RESTART_WINDOW = 60000;  // 60s window for restart counting
+
+let _reqCounter = 0;
+function nextId() {
+  return `req-${++_reqCounter}`;
+}
+
+class DaemonClient {
+  constructor() {
+    this._proc = null;
+    this._rl = null;
+    this._pending = new Map(); // id -> { resolve, reject, timer }
+    this._dead = false;        // permanently dead after too many restarts
+    this._restarts = [];       // timestamps of recent restarts
+    this._starting = null;     // promise while startup in progress
+  }
+
+  get isAvailable() {
+    return !this._dead;
+  }
+
+  async ensureRunning() {
+    if (this._dead) throw new Error('Daemon permanently unavailable');
+    if (this._proc && !this._proc.killed && this._proc.exitCode === null) return;
+    if (this._starting) return this._starting;
+
+    this._starting = this._spawn();
+    try {
+      await this._starting;
+    } finally {
+      this._starting = null;
+    }
+  }
+
+  _spawn() {
+    return new Promise((resolve, reject) => {
+      // Track restarts
+      const now = Date.now();
+      this._restarts = this._restarts.filter(t => now - t < RESTART_WINDOW);
+      if (this._restarts.length >= MAX_RESTARTS) {
+        this._dead = true;
+        reject(new Error('Daemon exceeded max restarts, falling back to sync'));
+        return;
+      }
+      this._restarts.push(now);
+
+      // Cleanup any previous process
+      this._cleanup();
+
+      const proc = spawn('python3', [DAEMON_SCRIPT], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, PYTHONUNBUFFERED: '1' },
+      });
+
+      this._proc = proc;
+
+      // stderr goes to process.stderr for debug logging
+      proc.stderr.on('data', (chunk) => {
+        if (process.env.DAEMON_DEBUG) {
+          process.stderr.write(`[daemon] ${chunk}`);
+        }
+      });
+
+      // Handle process exit
+      proc.on('exit', (code, signal) => {
+        // Reject all pending requests
+        for (const [id, entry] of this._pending) {
+          clearTimeout(entry.timer);
+          entry.reject(new Error(`Daemon exited (code=${code}, signal=${signal})`));
+        }
+        this._pending.clear();
+        this._proc = null;
+        this._rl = null;
+      });
+
+      proc.on('error', (err) => {
+        this._dead = true;
+        reject(err);
+      });
+
+      // Read JSONL from stdout
+      const rl = createInterface({ input: proc.stdout });
+      this._rl = rl;
+
+      // Wait for __ready__ signal with timeout
+      const readyTimer = setTimeout(() => {
+        this._cleanup();
+        reject(new Error('Daemon startup timed out'));
+      }, READY_TIMEOUT);
+
+      let readyResolved = false;
+
+      rl.on('line', (line) => {
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch {
+          return; // skip non-JSON lines
+        }
+
+        // Handle ready signal
+        if (!readyResolved && msg.id === '__ready__') {
+          readyResolved = true;
+          clearTimeout(readyTimer);
+          resolve();
+          return;
+        }
+
+        // Route response to pending request
+        const id = msg.id;
+        if (id && this._pending.has(id)) {
+          const entry = this._pending.get(id);
+          this._pending.delete(id);
+          clearTimeout(entry.timer);
+          if (msg.success) {
+            entry.resolve(msg);
+          } else {
+            entry.reject(new Error(msg.error || 'Daemon request failed'));
+          }
+        }
+      });
+
+      rl.on('close', () => {
+        if (!readyResolved) {
+          clearTimeout(readyTimer);
+          reject(new Error('Daemon stdout closed before ready'));
+        }
+      });
+    });
+  }
+
+  _cleanup() {
+    if (this._rl) {
+      try { this._rl.close(); } catch { /* ignore */ }
+      this._rl = null;
+    }
+    if (this._proc) {
+      try { this._proc.kill(); } catch { /* ignore */ }
+      this._proc = null;
+    }
+  }
+
+  _send(obj) {
+    return new Promise((resolve, reject) => {
+      const id = obj.id || nextId();
+      obj.id = id;
+
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new Error(`Daemon request timed out (id=${id})`));
+      }, REQUEST_TIMEOUT);
+
+      this._pending.set(id, { resolve, reject, timer });
+
+      try {
+        this._proc.stdin.write(JSON.stringify(obj) + '\n');
+      } catch (err) {
+        this._pending.delete(id);
+        clearTimeout(timer);
+        reject(err);
+      }
+    });
+  }
+
+  async analyze(filePath, engine = 'auto') {
+    await this.ensureRunning();
+    const resp = await this._send({
+      action: 'analyze',
+      file_path: filePath,
+      engine,
+    });
+    return resp.result;
+  }
+
+  async crossFileAnalyze(filePaths) {
+    await this.ensureRunning();
+    const resp = await this._send({
+      action: 'cross_file_analyze',
+      file_paths: filePaths,
+    });
+    return resp.result;
+  }
+
+  async health() {
+    await this.ensureRunning();
+    const resp = await this._send({ action: 'health' });
+    return resp.result;
+  }
+
+  async shutdown() {
+    if (!this._proc || this._proc.killed || this._proc.exitCode !== null) return;
+    try {
+      await this._send({ action: 'shutdown' });
+    } catch {
+      // ignore — process may already be gone
+    }
+    this._cleanup();
+  }
+}
+
+// Singleton instance
+let _instance = null;
+
+export function getDaemonClient() {
+  if (!_instance) {
+    _instance = new DaemonClient();
+  }
+  return _instance;
+}
+
+export async function shutdownDaemon() {
+  if (_instance) {
+    await _instance.shutdown();
+    _instance = null;
+  }
+}

package/src/dedup.js

@@ -0,0 +1,129 @@
+// Cross-engine deduplication for security findings.
+// When AST and regex engines flag the same vulnerability on the same line
+// with different ruleIds, this module merges them into a single finding.
+
+// Maps ruleId substrings to vulnerability classes for cross-engine dedup.
+// Order matters: more specific patterns must come before generic ones.
+const VULN_CLASS_PATTERNS = [
+  // XSS variants
+  ['innerhtml', 'xss-innerhtml'],
+  ['outerhtml', 'xss-outerhtml'],
+  ['document-write', 'xss-document-write'],
+  ['document.write', 'xss-document-write'],
+  ['insertadjacenthtml', 'xss-insertadjacenthtml'],
+  ['dangerouslysetinnerhtml', 'xss-dangerouslysetinnerhtml'],
+  ['mustache-escape', 'xss-innerhtml'],
+  ['insecure-document-method', 'xss-document-write'],
+  ['dom-based-xss', 'xss-dom'],
+  ['xss-echo', 'xss-echo'],
+  ['xss-raw', 'xss-raw'],
+  ['xss-response-write', 'xss-response-write'],
+
+  // SQL Injection
+  ['sql-injection', 'sqli'],
+  ['nosql-injection', 'nosqli'],
+
+  // Command Injection
+  ['child-process-exec', 'cmdi-exec'],
+  ['spawn-shell', 'cmdi-spawn'],
+  ['dangerous-subprocess', 'cmdi-subprocess'],
+  ['dangerous-system-call', 'cmdi-system'],
+  ['command-injection', 'cmdi'],
+  ['backticks-exec', 'cmdi-backticks'],
+  ['libc-system-call', 'cmdi-libc'],
+
+  // Code Injection
+  ['eval-detected', 'code-eval'],
+  ['eval-usage', 'code-eval'],
+  ['exec-detected', 'code-exec'],
+  ['function-constructor', 'code-function-constructor'],
+
+  // Deserialization
+  ['pickle-load', 'deser-pickle'],
+  ['unsafe-unserialize', 'deser-unserialize'],
+  ['unsafe-yaml-load', 'deser-yaml'],
+  ['yaml-load', 'deser-yaml'],
+  ['unsafe-marshal', 'deser-marshal'],
+  ['insecure-deserialization', 'deser'],
+
+  // Crypto
+  ['md5', 'weak-hash-md5'],
+  ['sha1', 'weak-hash-sha1'],
+  ['insecure-hash', 'weak-hash'],
+  ['weak-hash', 'weak-hash'],
+  ['weak-cipher', 'weak-cipher'],
+
+  // Secrets
+  ['hardcoded-password', 'hardcoded-password'],
+  ['hardcoded-secret', 'hardcoded-secret'],
+  ['hardcoded-api-key', 'hardcoded-api-key'],
+  ['hardcoded-connection-string', 'hardcoded-connection-string'],
+
+  // Path traversal
+  ['path-traversal', 'path-traversal'],
+
+  // SSL
+  ['ssl-verify-disabled', 'ssl-verify-disabled'],
+
+  // Random
+  ['insecure-random', 'insecure-random'],
+  ['weak-random', 'weak-random'],
+];
+
+// Engine priority (higher = more trusted analysis)
+const ENGINE_PRIORITY = {
+  'taint': 3,
+  'ast': 2,
+  'regex': 1,
+  'regex-fallback': 0,
+};
+
+const SEVERITY_ORDER = { error: 3, warning: 2, info: 1 };
+
+export function classifyFinding(ruleId) {
+  const lower = ruleId.toLowerCase();
+  for (const [pattern, vulnClass] of VULN_CLASS_PATTERNS) {
+    if (lower.includes(pattern)) return vulnClass;
+  }
+  return lower;
+}
+
+export function deduplicateFindings(findings) {
+  if (!Array.isArray(findings)) return findings;
+
+  // Group by (vulnClass, line)
+  const groups = new Map();
+  for (const finding of findings) {
+    const vulnClass = classifyFinding(finding.ruleId);
+    const key = `${vulnClass}:${finding.line}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(finding);
+  }
+
+  const deduped = [];
+  for (const group of groups.values()) {
+    if (group.length === 1) {
+      deduped.push(group[0]);
+      continue;
+    }
+
+    // Sort by engine priority (highest first)
+    group.sort((a, b) =>
+      (ENGINE_PRIORITY[b.engine] || 0) - (ENGINE_PRIORITY[a.engine] || 0)
+    );
+
+    const best = { ...group[0] };
+
+    // Preserve highest severity across group
+    for (const f of group) {
+      if ((SEVERITY_ORDER[f.severity] || 0) > (SEVERITY_ORDER[best.severity] || 0)) {
+        best.severity = f.severity;
+      }
+    }
+
+    best.engines_matched = [...new Set(group.map(f => f.engine))];
+    deduped.push(best);
+  }
+
+  return deduped;
+}