@clear-capabilities/agentic-security-scanner 0.118.2 → 0.119.2

package/src/sast/event-entrypoint.js

@@ -0,0 +1,90 @@
+// R6 (PRD §5) — non-HTTP entrypoint taint. Route-rooted analysis goes blind to
+// message-queue consumers, scheduled tasks, and serverless handlers — exactly
+// where high-severity backend bugs live. This recognizes those entrypoints,
+// treats their payload parameter as an untrusted source, and flags when it
+// reaches a code/command/SQL sink without sanitization.
+//
+// Precision-first: gated to files that register such an entrypoint; tracks the
+// handler's payload parameter (+ common member accesses) into a dangerous sink.
+
+import { blankComments } from './_comment-strip.js';
+
+// Entrypoint registrations → the untrusted payload parameter name they bind.
+const ENTRYPOINTS = [
+  // JS: queue/stream consumers — .on('message', (msg)=>…) / .subscribe((msg)=>…)
+  { re: /\.(?:on|subscribe|consume|process)\s*\(\s*(?:['"][^'"]*['"]\s*,\s*)?(?:async\s*)?\(?\s*([A-Za-z_$][\w$]*)/g, lang: 'js' },
+  // JS serverless: exports.handler = async (event) => … / module.exports.handler = (event)
+  { re: /(?:exports\.\w+|module\.exports(?:\.\w+)?)\s*=\s*(?:async\s*)?\(?\s*([A-Za-z_$][\w$]*)/g, lang: 'js' },
+  // Python Celery / serverless: @app.task / @shared_task / def handler(event, context)
+  { re: /@(?:app|celery|shared)\w*\.task[^\n]*\n\s*def\s+\w+\s*\(\s*([A-Za-z_]\w*)/g, lang: 'py' },
+  { re: /\bdef\s+(?:handler|lambda_handler|handle|consume|on_message|process)\s*\(\s*([A-Za-z_]\w*)/g, lang: 'py' },
+];
+
+// Context markers that indicate an event/queue/serverless file.
+const CONTEXT = /(kafka|rabbit|amqp|sqs|sns|pubsub|kinesis|@app\.task|shared_task|lambda_handler|exports\.handler|celery|bull|bullmq|@SqsListener|@KafkaListener|@RabbitListener|@Scheduled|consumer|EventBridge|cloudevent)/i;
+
+const SINKS = [
+  { re: /\b(?:exec|execSync|spawn|spawnSync)\s*\(/, label: 'command exec', cwe: '78', fam: 'command-injection' },
+  { re: /\beval\s*\(|\bnew\s+Function\s*\(/, label: 'eval', cwe: '94', fam: 'code-injection' },
+  { re: /\bos\.system\s*\(|\bsubprocess\.(?:run|call|Popen|check_output)\s*\(/, label: 'command exec', cwe: '78', fam: 'command-injection' },
+  { re: /\.(?:query|execute|raw)\s*\(\s*[`'"][^`'"]*\$?\{?\s*\+?/, label: 'SQL query (concatenated)', cwe: '89', fam: 'sql-injection' },
+];
+
+const SANITIZER = /\b(sanitiz|validate|escape|allowlist|allow_list|whitelist|schema\.(?:parse|validate)|zod|joi|pydantic|is_safe|verify)/i;
+
+const PAYLOAD_MEMBER = /\.(?:body|value|data|message|payload|Records|detail|content|text)\b/;
+
+export function scanEventEntrypoints(fp, raw) {
+  if (typeof raw !== 'string' || !raw) return [];
+  if (!/\.(?:js|jsx|ts|tsx|mjs|cjs|py)$/i.test(fp)) return [];
+  const code = blankComments(raw);
+  if (!CONTEXT.test(code)) return [];
+  const isPy = /\.py$/i.test(fp);
+  const lines = code.split('\n');
+
+  // Collect payload variable names from entrypoint registrations.
+  const payloads = new Set();
+  for (const ep of ENTRYPOINTS) {
+    if (ep.lang === 'py' !== isPy) continue;
+    const re = new RegExp(ep.re.source, ep.re.flags);
+    let m;
+    while ((m = re.exec(code))) {
+      const name = m[1];
+      if (name && !['async', 'function', 'context', 'self', 'cls'].includes(name)) payloads.add(name);
+    }
+  }
+  if (!payloads.size) return [];
+
+  const findings = [];
+  const seen = new Set();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const sink of SINKS) {
+      if (!sink.re.test(line)) continue;
+      const arg = line.slice(line.search(sink.re));
+      const hit = [...payloads].some((p) => new RegExp(`\\b${p}\\b`).test(arg));
+      if (!hit) continue;
+      // Sanitizer anywhere in a small window above suppresses.
+      const near = lines.slice(Math.max(0, i - 6), i + 1).join('\n');
+      if (SANITIZER.test(near)) continue;
+      const key = `${i + 1}:${sink.fam}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      findings.push({
+        id: `event-entrypoint:${fp}:${i + 1}`,
+        severity: 'high',
+        file: fp,
+        line: i + 1,
+        vuln: `Untrusted event/message payload reaches ${sink.label}`,
+        cwe: `CWE-${sink.cwe}`,
+        family: sink.fam,
+        parser: 'EVENT-FLOW',
+        description: `A non-HTTP entrypoint (queue consumer / scheduled task / serverless handler) passes its untrusted payload into ${sink.label} without validation. Message/event bodies are attacker-influenceable just like HTTP input.`,
+        remediation: 'Validate/parse the event payload against a schema before use, and avoid passing it to a command/code/SQL sink (parameterize, use argv-form exec).',
+      });
+    }
+  }
+  return findings;
+}
+
+export const _internals = { PAYLOAD_MEMBER };

package/src/sast/iac-terraform.js

@@ -0,0 +1,107 @@
+// R18 (PRD §5) — semantic IaC (Terraform), variable-resolving.
+//
+// Regex IaC (engine.js scanIaC) matches literals on one line. Its blind spot is
+// indirection: `cidr_blocks = [var.ingress]` where `variable "ingress"` defaults
+// to "0.0.0.0/0" is wide-open, but the literal never appears on the resource
+// line. This resolves `variable` defaults and `local` values, then evaluates a
+// few high-signal misconfigurations on the RESOLVED value — catching what the
+// literal scan misses, and reporting when the exposure arrives via a variable.
+//
+// Regex-based HCL (no new dep, consistent with the repo); bounded to the
+// highest-signal AWS checks. Real `terraform plan` ingestion is the remainder.
+
+const VAR_DEFAULT = /variable\s+"([^"]+)"\s*\{[^{}]*?default\s*=\s*(?:"([^"]*)"|(\[[^\]]*\]|true|false|[\w.\-]+))/g;
+const LOCAL_BLOCK = /locals\s*\{([\s\S]*?)\n\}/g;
+
+function buildResolver(text) {
+  const vars = new Map();
+  let m;
+  VAR_DEFAULT.lastIndex = 0;
+  while ((m = VAR_DEFAULT.exec(text))) vars.set(m[1], (m[2] !== undefined ? m[2] : m[3] || '').trim());
+  const locals = new Map();
+  LOCAL_BLOCK.lastIndex = 0;
+  while ((m = LOCAL_BLOCK.exec(text))) {
+    for (const line of m[1].split('\n')) {
+      const lm = line.match(/^\s*([A-Za-z_][\w-]*)\s*=\s*(?:"([^"]*)"|([\w.\-]+))/);
+      if (lm) locals.set(lm[1], (lm[2] !== undefined ? lm[2] : lm[3] || '').trim());
+    }
+  }
+  // Resolve a raw attribute value (possibly `var.x`, `local.y`, a list, or literal).
+  return function resolve(raw) {
+    if (raw == null) return { value: '', viaVar: false };
+    // Strip bracket/brace/quote noise anywhere (the attr capture can include a
+    // trailing `}` / `]`), so a `var.x` token matches the resolver exactly.
+    let v = String(raw).replace(/[[\]{}'"]/g, '').trim();
+    const vm = v.match(/^var\.([\w-]+)$/);
+    if (vm && vars.has(vm[1])) return { value: vars.get(vm[1]), viaVar: true, varName: vm[1] };
+    const lm = v.match(/^local\.([\w-]+)$/);
+    if (lm && locals.has(lm[1])) return { value: locals.get(lm[1]), viaVar: true, varName: `local.${lm[1]}` };
+    return { value: v, viaVar: false };
+  };
+}
+
+function lineOf(text, idx) { return text.slice(0, idx).split('\n').length; }
+
+const CHECKS = [
+  {
+    id: 'open-ingress', cwe: 'CWE-284', sev: 'high',
+    attr: /\b(?:cidr_blocks|ipv6_cidr_blocks)\s*=\s*(\[?[^\n]+)/g,
+    bad: (val) => /\b0\.0\.0\.0\/0\b|::\/0\b/.test(val),
+    vuln: 'Terraform: security-group ingress open to the world (0.0.0.0/0)',
+    fix: 'Restrict cidr_blocks to known networks; never default an ingress CIDR to 0.0.0.0/0.',
+  },
+  {
+    id: 'public-bucket', cwe: 'CWE-732', sev: 'high',
+    attr: /\bacl\s*=\s*(\S+)/g,
+    bad: (val) => /^public-read(?:-write)?$/.test(val),
+    vuln: 'Terraform: S3 bucket ACL is public',
+    fix: 'Set acl = "private" and use bucket policies / least-privilege grants instead of a public ACL.',
+  },
+  {
+    id: 'public-db', cwe: 'CWE-668', sev: 'high',
+    attr: /\bpublicly_accessible\s*=\s*(\S+)/g,
+    bad: (val) => /^true$/i.test(val),
+    vuln: 'Terraform: database instance is publicly accessible',
+    fix: 'Set publicly_accessible = false; place the DB in a private subnet.',
+  },
+];
+
+export function scanTerraform(fp, raw) {
+  if (typeof raw !== 'string' || !raw) return [];
+  if (!/\.tf$/i.test(fp)) return [];
+  const resolve = buildResolver(raw);
+  const findings = [];
+  const seen = new Set();
+  for (const check of CHECKS) {
+    const re = new RegExp(check.attr.source, check.attr.flags);
+    let m;
+    while ((m = re.exec(raw))) {
+      const rawVal = m[1];
+      // A literal list may hold several entries; resolve each token.
+      const tokens = rawVal.replace(/^\[|\]$/g, '').split(',').map(t => t.trim()).filter(Boolean);
+      let hit = null;
+      for (const tok of tokens.length ? tokens : [rawVal]) {
+        const r = resolve(tok);
+        if (check.bad(r.value)) { hit = r; break; }
+      }
+      if (!hit) continue;
+      const line = lineOf(raw, m.index);
+      const key = `${check.id}:${line}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      findings.push({
+        id: `iac-tf:${check.id}:${fp}:${line}`,
+        severity: check.sev,
+        file: fp,
+        line,
+        vuln: check.vuln,
+        cwe: check.cwe,
+        family: 'iac-misconfig',
+        parser: 'IAC-TF',
+        description: `${check.vuln}.${hit.viaVar ? ` The unsafe value arrives via \`${hit.varName}\` (resolved to "${hit.value}") — a literal-only scan would miss this.` : ''}`,
+        remediation: check.fix,
+      });
+    }
+  }
+  return findings;
+}

package/src/sast/rbac-consistency.js

@@ -0,0 +1,113 @@
+// R21 (PRD §5) — RBAC role-tier authorization model.
+//
+// R19 (api-authz.js) flags missing AUTHENTICATION among authenticated siblings.
+// This goes one level deeper to AUTHORIZATION TIER: it extracts the role/
+// permission a route requires (from middleware/annotations near the handler) and
+// flags two broken-access-control shapes the route inventory alone can't see:
+//   1. A state-changing route that enforces NO role while sibling routes on the
+//      same resource DO  → missing function-level authorization (BFLA).
+//   2. A state-changing route gated at a STRICTLY LOWER tier than a read sibling
+//      → privilege tier inversion (delete allowed below the tier that can read).
+//
+// Pure cross-route analysis (routes + file contents). Precision-first: fires
+// only on inconsistency within a resource group that uses roles at all.
+
+// Inline role checks — on the route's OWN registration line (middleware args).
+const INLINE_PATTERNS = [
+  /\b(?:requireRole|hasRole|hasAnyRole|checkRole|ensureRole|restrictTo|requireScope|hasAuthority|hasPermission|requirePermission)\s*\(\s*\[?\s*['"]([A-Za-z0-9_.:-]+)['"]/i,
+  /\brole\s*(?:===?|==)\s*['"]([A-Za-z0-9_.:-]+)['"]/i,
+];
+// Decorator/attribute role checks — on the line(s) directly ABOVE the handler.
+const DECORATOR_PATTERNS = [
+  /@(?:PreAuthorize|Secured|RolesAllowed)\s*\(\s*[^)]*['"]([A-Za-z0-9_.:-]+)['"]/i,
+  /\[Authorize\s*\(\s*Roles\s*=\s*"([A-Za-z0-9_.,:-]+)"/i,
+  /@(?:roles_required|permission_required)\s*\(\s*['"]([A-Za-z0-9_.:-]+)['"]/i,
+];
+
+// Coarse tier ranking (higher = more privileged). Unknown roles → tier 1 (mid).
+function tierOf(role) {
+  const r = String(role || '').toLowerCase();
+  if (/\b(super.?admin|root|owner|sysadmin)\b/.test(r) || r === 'superadmin') return 3;
+  if (/\b(admin|administrator|manager|staff|moderator|mod)\b/.test(r)) return 2;
+  if (/\b(user|member|authenticated|customer|editor|contributor)\b/.test(r)) return 1;
+  if (/\b(guest|public|anon|anonymous|viewer|reader)\b/.test(r)) return 0;
+  return 1;
+}
+
+const STATE_CHANGING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+function roleOf(route, fileContents) {
+  const content = fileContents[route.file];
+  if (typeof content !== 'string') return { hasRole: false, role: null };
+  const lines = content.split('\n');
+  const idx = (route.line || 1) - 1;
+  // 1. Inline middleware / role check on the route's OWN line (don't look at
+  //    siblings — that would leak an adjacent route's role into this one).
+  const own = lines[idx] || '';
+  for (const re of INLINE_PATTERNS) { const m = own.match(re); if (m) return { hasRole: true, role: m[1] }; }
+  // 2. Stacked decorators/attributes directly ABOVE the handler; stop at the
+  //    first non-decorator line so we never cross into the previous route.
+  for (let j = idx - 1; j >= 0 && j >= idx - 4; j--) {
+    const l = (lines[j] || '').trim();
+    if (!l) continue;
+    if (/^@\w|^\[Authorize/i.test(l)) {
+      for (const re of DECORATOR_PATTERNS) { const m = l.match(re); if (m) return { hasRole: true, role: m[1] }; }
+      continue; // an unrecognized decorator — keep scanning the stack upward
+    }
+    break; // hit a non-decorator line → stop
+  }
+  return { hasRole: false, role: null };
+}
+
+// Resource key: path with dynamic segments collapsed (so /users and /users/:id
+// group together as one resource).
+function resourceKey(p) {
+  return String(p || '').split('/').map((s) => (/^(:|\{|<|\d)/.test(s) ? '*' : s)).join('/').replace(/\/\*$/, '') || '/';
+}
+
+function mk(route, kind, cwe, why) {
+  return {
+    id: `rbac:${kind}:${route.file}:${route.line}`,
+    severity: 'high',
+    file: route.file, line: route.line || 0,
+    vuln: kind === 'inversion'
+      ? 'Authorization tier inversion (state-change allowed below the read tier)'
+      : 'Missing role-based authorization on a state-changing route',
+    cwe, family: 'broken-access-control', parser: 'RBAC',
+    description: why,
+    remediation: 'Enforce a role/permission check on the route at least as strong as its sibling routes; gate state-changing actions at the appropriate privilege tier.',
+  };
+}
+
+export function scanRbacConsistency(routes, fileContents) {
+  if (!Array.isArray(routes) || routes.length < 2) return [];
+  const groups = new Map();
+  for (const r of routes) {
+    if (!r || r.path === '(file-based)' || !r.path) continue;
+    const key = `${r.file}::${resourceKey(r.path)}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push({ ...r, ...roleOf(r, fileContents) });
+  }
+  const findings = [];
+  const seen = new Set();
+  const push = (f) => { const k = `${f.file}:${f.line}`; if (!seen.has(k)) { seen.add(k); findings.push(f); } };
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    const roled = group.filter((r) => r.hasRole);
+    if (!roled.length) continue; // resource doesn't use roles at all → not our signal
+    const maxReadTier = Math.max(...group.filter((r) => !STATE_CHANGING.has(r.method) && r.hasRole).map((r) => tierOf(r.role)), -1);
+    for (const r of group) {
+      if (!STATE_CHANGING.has(r.method)) continue;
+      if (!r.hasRole) {
+        push(mk(r, 'missing', '285',
+          `${r.method} ${r.path} enforces no role check, while ${roled.length} sibling route(s) on this resource require one — a state-changing action left at a lower authorization tier (BFLA).`));
+      } else if (maxReadTier >= 0 && tierOf(r.role) < maxReadTier) {
+        push(mk(r, 'inversion', '269',
+          `${r.method} ${r.path} requires role "${r.role}" (tier ${tierOf(r.role)}), but reading this resource requires a higher tier (${maxReadTier}). A lower-privileged user can mutate what they may not even read.`));
+      }
+    }
+  }
+  return findings;
+}
+
+export const _internals = { tierOf, resourceKey };

package/src/sast/wrong-context-sanitizer.js

@@ -48,6 +48,61 @@ function lineOf(raw, idx) { return raw.substring(0, idx).split('\n').length; }
 function isJsLike(fp) { return /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i.test(fp); }
 function isPhp(fp) { return /\.php$/i.test(fp); }
 
+// R5 (PRD §5) — context-aware sanitizer ADEQUACY. The model: a sanitizer
+// neutralizes a specific context; using it before a sink of a DIFFERENT context
+// is a no-op that looks safe. The highest-signal mismatches beyond the URL case
+// above: an HTML-entity encoder applied to a value that then reaches a SHELL or
+// SQL sink — HTML-escaping does nothing for command/SQL injection.
+const _SHELL_SINK = /\b(?:exec|execSync|execFile|execFileSync|spawn|spawnSync|system|popen|shell_exec|child_process\.\w+)\s*\(/;
+const _SQL_SINK = /\.(?:query|execute|raw|exec)\s*\(|\bdb\.raw\s*\(|sequelize\.query\s*\(/i;
+const _HTML_ENC_CALL = new RegExp(HTML_ENCODER + "\\s*\\(", "g");
+
+export function scanSanitizerContextMismatch(fp, raw) {
+  if (!raw || raw.length > 500_000) return [];
+  if (!isJsLike(fp) && !isPhp(fp) && !/\.py$/i.test(fp)) return [];
+  if (!/escapeHtml|escapeHTML|htmlspecialchars|htmlentities|he\.encode|he\.escape|_\.escape|lodash\.escape/i.test(raw)) return [];
+  if (!_SHELL_SINK.test(raw) && !_SQL_SINK.test(raw)) return [];
+  const code = blankComments(raw);
+  const lines = code.split('\n');
+  const findings = [];
+  const seen = new Set();
+  // Track vars assigned directly from an HTML encoder (one hop).
+  const htmlVars = new Set();
+  const VAR_ASSIGN = new RegExp("(?:\\b(?:const|let|var)\\s+)?([A-Za-z_$][\\w$]*)\\s*=\\s*" + HTML_ENCODER + "\\s*\\(", "g");
+  let m;
+  while ((m = VAR_ASSIGN.exec(code))) htmlVars.add(m[1]);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const isShell = _SHELL_SINK.test(line);
+    const isSql = !isShell && _SQL_SINK.test(line);
+    if (!isShell && !isSql) continue;
+    const argRegion = line.slice(line.search(isShell ? _SHELL_SINK : _SQL_SINK));
+    _HTML_ENC_CALL.lastIndex = 0;
+    const inline = _HTML_ENC_CALL.test(argRegion);
+    const viaVar = !inline && [...htmlVars].some((v) => new RegExp(`\\b${v}\\b`).test(argRegion));
+    if (!inline && !viaVar) continue;
+    if (seen.has(i + 1)) continue;
+    seen.add(i + 1);
+    const ctx = isShell ? { cwe: 'CWE-78', kind: 'command', vuln: 'Command Injection' }
+      : { cwe: 'CWE-89', kind: 'SQL', vuln: 'SQL Injection' };
+    findings.push({
+      id: `wrong-context-sanitizer:sink:${fp}:${i + 1}`,
+      severity: 'high',
+      file: fp,
+      line: i + 1,
+      vuln: `Wrong-context sanitizer (HTML-encoded value used in a ${ctx.kind} sink)`,
+      cwe: ctx.cwe,
+      family: ctx.kind === 'command' ? 'command-injection' : 'sql-injection',
+      parser: 'SAST',
+      description: `An HTML-entity encoder was applied to a value that then flows into a ${ctx.kind} sink. HTML escaping neutralizes HTML markup, NOT ${ctx.kind} metacharacters — the value is still ${ctx.vuln}-exploitable while appearing sanitized.`,
+      remediation: ctx.kind === 'command'
+        ? 'Use an argv-form API (execFile/spawn with an args array), never a shell string; HTML escaping is irrelevant here.'
+        : 'Use parameterized queries / prepared statements; HTML escaping does not prevent SQL injection.',
+    });
+  }
+  return findings;
+}
+
 export function scanWrongContextSanitizer(fp, raw) {
   if (!raw || raw.length > 500_000) return [];
   if (!isJsLike(fp) && !isPhp(fp)) return [];

package/src/sca/image-packages.js

@@ -0,0 +1,74 @@
+// R8 (PRD §5) — container-image OS-package inventory.
+//
+// container.js reads the Dockerfile (FROM + apt/apk install lines). This reads
+// the ACTUAL installed-package databases from an extracted image filesystem
+// (or the host), catching packages baked into the base image that the
+// Dockerfile never names. Components flow into the existing OSV pipeline + SBOM.
+//
+// Pure parsers (unit-tested) + a path-matching extractor. No daemon; reads the
+// package-DB files that appear when an image layer/tarball is unpacked.
+
+// Debian/Ubuntu: /var/lib/dpkg/status — RFC822-style blocks separated by blank
+// lines. Only "install ok installed" entries count (not removed/config-files).
+export function parseDpkgStatus(text) {
+  const out = [];
+  for (const block of String(text || '').split(/\n\s*\n/)) {
+    const name = (block.match(/^Package:\s*(.+)$/m) || [])[1];
+    const version = (block.match(/^Version:\s*(.+)$/m) || [])[1];
+    const status = (block.match(/^Status:\s*(.+)$/m) || [])[1] || '';
+    if (!name || !version) continue;
+    if (!/\binstalled\b/.test(status)) continue;
+    out.push({ name: name.trim(), version: version.trim(), ecosystem: 'Debian' });
+  }
+  return out;
+}
+
+// Alpine: /lib/apk/db/installed — blocks separated by blank lines; P:=name V:=version.
+export function parseApkInstalled(text) {
+  const out = [];
+  for (const block of String(text || '').split(/\n\s*\n/)) {
+    const name = (block.match(/^P:(.+)$/m) || [])[1];
+    const version = (block.match(/^V:(.+)$/m) || [])[1];
+    if (!name || !version) continue;
+    out.push({ name: name.trim(), version: version.trim(), ecosystem: 'Alpine' });
+  }
+  return out;
+}
+
+const _PURL = { Debian: (n, v) => `pkg:deb/debian/${n}@${v}`, Alpine: (n, v) => `pkg:apk/alpine/${n}@${v}` };
+
+// File-path tells for an unpacked image. Match on path suffix so it works
+// whether the scan root is the rootfs or a subdirectory of it.
+function _dbKind(path) {
+  const p = path.replace(/\\/g, '/');
+  if (/(?:^|\/)var\/lib\/dpkg\/status$/.test(p)) return 'dpkg';
+  if (/(?:^|\/)lib\/apk\/db\/installed$/.test(p)) return 'apk';
+  return null;
+}
+
+/**
+ * Extract OS-package components from any image package-DBs present in the scanned
+ * files. Returns components in the engine's component shape so they ride the
+ * existing OSV/SBOM pipeline. De-dups by ecosystem:name:version.
+ */
+export function extractImagePackages(fileContents) {
+  const comps = [];
+  const seen = new Set();
+  for (const [file, content] of Object.entries(fileContents || {})) {
+    const kind = _dbKind(file);
+    if (!kind) continue;
+    const pkgs = kind === 'dpkg' ? parseDpkgStatus(content) : parseApkInstalled(content);
+    for (const p of pkgs) {
+      const key = `${p.ecosystem}:${p.name}:${p.version}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      comps.push({
+        name: p.name, version: p.version, group: '', ecosystem: p.ecosystem,
+        purl: (_PURL[p.ecosystem] || (() => null))(p.name, p.version),
+        filePath: file, isUnpinned: false, isTransitive: false, isOsPackage: true,
+        scope: 'required', reachable: true,
+      });
+    }
+  }
+  return comps;
+}