@clear-capabilities/agentic-security-scanner 0.79.0 → 0.84.1

package/src/posture/git-history.js

@@ -0,0 +1,141 @@
+// Git-history-aware finding annotation.
+//
+// For each finding, looks up the introducing commit via `git blame -L
+// <line>,<line>`. Adds:
+//
+//   introducedBy        — author name (or 'AI' if commit message marks it)
+//   introducedIn        — commit SHA (12 chars)
+//   introducedAt        — commit ISO date
+//   introducedInMessage — commit subject line (cap 120 chars)
+//   originatingPrompt   — extracted from commit body when present
+//
+// Then can render a Slack-ready / PR-comment-ready author-ping draft.
+//
+// Conservative: any subprocess error / non-git repo / file-not-tracked
+// leaves the finding unannotated. Caps blame to 1 line per finding (so
+// 200 findings = 200 blame calls). Set AGENTIC_SECURITY_NO_GIT_HISTORY=1
+// to skip entirely.
+
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const MAX_BLAME_PER_SCAN = 500;
+const SUBPROC_TIMEOUT_MS = 1500;
+const PROMPT_MARKER_RE = /(?:^|\n)(?:Prompt|User asked|Original request|Co-Authored-By:\s*Claude)/i;
+
+function _isGitRepo(scanRoot) {
+  try {
+    cp.execFileSync('git', ['rev-parse', '--git-dir'], { cwd: scanRoot, stdio: 'ignore', timeout: SUBPROC_TIMEOUT_MS });
+    return true;
+  } catch { return false; }
+}
+
+function _blame(scanRoot, file, line) {
+  if (!file || !line || line < 1) return null;
+  const rel = path.isAbsolute(file) ? path.relative(scanRoot, file) : file;
+  if (rel.startsWith('..')) return null;
+  try {
+    const stdout = cp.execFileSync(
+      'git',
+      ['blame', '-L', `${line},${line}`, '--porcelain', '--', rel],
+      { cwd: scanRoot, encoding: 'utf8', timeout: SUBPROC_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+    return _parsePorcelain(stdout);
+  } catch { return null; }
+}
+
+function _parsePorcelain(out) {
+  if (!out) return null;
+  const lines = out.split('\n');
+  // First line: <sha> <orig-line> <final-line> <num-lines>
+  const head = lines[0].split(' ');
+  const sha = head[0];
+  if (!sha || sha === '0000000000000000000000000000000000000000') return null;
+  const meta = { sha: sha.slice(0, 12) };
+  for (const ln of lines) {
+    if (ln.startsWith('author '))         meta.author = ln.slice(7);
+    else if (ln.startsWith('author-mail '))  meta.email = ln.slice(12).replace(/[<>]/g, '');
+    else if (ln.startsWith('author-time '))  meta.ts = parseInt(ln.slice(12), 10);
+    else if (ln.startsWith('summary '))      meta.summary = ln.slice(8);
+  }
+  if (meta.ts) meta.at = new Date(meta.ts * 1000).toISOString();
+  return meta;
+}
+
+function _fullMessage(scanRoot, sha) {
+  try {
+    return cp.execFileSync(
+      'git', ['show', '-s', '--format=%B', sha],
+      { cwd: scanRoot, encoding: 'utf8', timeout: SUBPROC_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+  } catch { return ''; }
+}
+
+function _extractPrompt(body) {
+  if (!body || !PROMPT_MARKER_RE.test(body)) return null;
+  // Take the line(s) that follow a "Prompt:" or "User asked:" marker, up to
+  // the next blank line. Truncate to 280 chars.
+  const m = body.match(/(?:Prompt|User asked|Original request)\s*[:\-]\s*([\s\S]*?)(?=\n\s*\n|$)/i);
+  if (!m) return null;
+  return m[1].trim().slice(0, 280);
+}
+
+/**
+ * Annotate findings with git blame + commit context. Returns
+ * { annotated, cached, skipped } counts.
+ */
+export function annotateGitHistory(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_GIT_HISTORY === '1') return { annotated: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { annotated: 0 };
+  if (!_isGitRepo(scanRoot)) return { annotated: 0, reason: 'not-a-git-repo' };
+
+  const messageCache = new Map();  // sha → body
+  let annotated = 0, skipped = 0;
+
+  for (let i = 0; i < findings.length && i < MAX_BLAME_PER_SCAN; i++) {
+    const f = findings[i];
+    if (!f || !f.file || !f.line) { skipped++; continue; }
+    const blame = _blame(scanRoot, f.file, f.line);
+    if (!blame) { skipped++; continue; }
+
+    f.introducedBy = blame.author || null;
+    f.introducedIn = blame.sha;
+    f.introducedAt = blame.at || null;
+
+    let body = messageCache.get(blame.sha);
+    if (body === undefined) {
+      body = _fullMessage(scanRoot, blame.sha);
+      messageCache.set(blame.sha, body);
+    }
+    if (body) {
+      const subj = body.split('\n')[0].slice(0, 120);
+      f.introducedInMessage = subj;
+      const prompt = _extractPrompt(body);
+      if (prompt) f.originatingPrompt = prompt;
+      // Mark AI-authored when commit message carries the Claude co-author trailer.
+      if (/Co-Authored-By:\s*Claude/i.test(body)) f.aiAuthored = true;
+    }
+    annotated++;
+  }
+  return { annotated, skipped, capped: findings.length > MAX_BLAME_PER_SCAN };
+}
+
+/**
+ * Generate a Slack-ready / PR-comment author-ping for a finding. Returns
+ * a Markdown string with a per-finding callout.
+ */
+export function generateAuthorPing(finding) {
+  if (!finding || !finding.introducedBy) return null;
+  const where = `${finding.file || '?'}:${finding.line || 0}`;
+  const lines = [];
+  lines.push(`Hey @${finding.introducedBy.replace(/\s+/g, '.')} — heads-up on \`${where}\`:`);
+  lines.push('');
+  lines.push(`- **${(finding.severity || '?').toUpperCase()}** ${finding.vuln || finding.family || 'finding'}`);
+  if (finding.introducedIn) lines.push(`- Introduced in \`${finding.introducedIn}\`${finding.introducedInMessage ? ` — _"${finding.introducedInMessage}"_` : ''}`);
+  if (finding.originatingPrompt) lines.push(`- Originating prompt: _"${finding.originatingPrompt}"_`);
+  lines.push(`- Could you take a look?`);
+  return lines.join('\n');
+}
+
+export const _internals = { _parsePorcelain, _extractPrompt, _isGitRepo };

package/src/posture/intent-context.js

@@ -0,0 +1,175 @@
+// Intent-aware false-positive suppression.
+//
+// Reads project / file / Claude-session context to detect when code is
+// deliberately vulnerable (CTF challenge, sandbox, tutorial, example,
+// fixture) so the scanner can demote findings rather than presenting them
+// as production-grade issues.
+//
+// Signal sources (in order of strength):
+//
+//   1. .agentic-security/current-intent.md
+//      A file Claude (or the user) writes to declare the current
+//      session's intent. The PreToolUse / SessionStart hook can populate
+//      this from the recent transcript. Format:
+//        # Intent
+//        - tutorial: building an intentional SQLi demo for our security training
+//        - excluded-paths: ["examples/sqli-demo/**"]
+//
+//   2. File header comments (first ~1500 chars):
+//      @sandbox / @example / @intentionally-vulnerable / @ctf-challenge /
+//      @demo / @tutorial / // INTENTIONALLY VULNERABLE
+//
+//   3. Path patterns: examples/, demo/, demos/, tutorial/, sandbox/,
+//      playground/, challenges/, ctf/
+//
+//   4. CLAUDE.md section headed "Intentionally vulnerable" / "Out of scope"
+//
+// Opt-out: AGENTIC_SECURITY_NO_INTENT_CTX=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const INTENT_PATH_RE = /(?:^|\/)(?:examples?|demos?|tutorials?|sandbox|playground|challenges?|ctf)(?:\/|$)/i;
+
+const FILE_HEADER_MARKERS = [
+  /@sandbox\b/i,
+  /@example\b/i,
+  /@intentionally[-_]?vulnerable\b/i,
+  /@ctf[-_]?challenge\b/i,
+  /@demo\b/i,
+  /@tutorial\b/i,
+  /(?:^|[^A-Za-z])INTENTIONALLY[- ]?VULNERABLE(?:[^A-Za-z]|$)/,
+  /(?:^|[^A-Za-z])DELIBERATELY[- ]?UNSAFE(?:[^A-Za-z]|$)/,
+];
+
+const HEADER_BUDGET = 1500;
+
+function _readSafely(fp) {
+  try { return fs.readFileSync(fp, 'utf8'); } catch { return ''; }
+}
+
+function _readIntentDeclaration(scanRoot) {
+  const fp = path.join(scanRoot, '.agentic-security', 'current-intent.md');
+  if (!fs.existsSync(fp)) return null;
+  const body = _readSafely(fp);
+  if (!body) return null;
+  const exMatch = body.match(/excluded-paths\s*:\s*\[([\s\S]*?)\]/);
+  let excludedPaths = [];
+  if (exMatch) {
+    excludedPaths = (exMatch[1].match(/"([^"]+)"|'([^']+)'/g) || [])
+      .map(s => s.replace(/['"]/g, ''));
+  }
+  return { body, excludedPaths };
+}
+
+function _claudeMdHasOutOfScope(scanRoot) {
+  const fp = path.join(scanRoot, 'CLAUDE.md');
+  if (!fs.existsSync(fp)) return [];
+  const body = _readSafely(fp);
+  const out = [];
+  const re = /^#{1,3}\s+(?:Out[- ]of[- ]scope|Intentionally vulnerable|Sandbox|Examples?)[\s\S]*?(?=\n#{1,3}\s|$(?![\s\S]))/gim;
+  let m;
+  while ((m = re.exec(body))) {
+    const sec = m[0];
+    // Pull file globs / paths from the section.
+    const paths = (sec.match(/`([^`]+)`/g) || []).map(s => s.replace(/`/g, ''));
+    out.push(...paths.filter(p => /\/|\*/.test(p)));
+  }
+  return out;
+}
+
+function _fileHeaderHasIntent(file) {
+  if (!file) return false;
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(HEADER_BUDGET);
+    fs.readSync(fd, buf, 0, HEADER_BUDGET, 0);
+    fs.closeSync(fd);
+    const head = buf.toString('utf8');
+    return FILE_HEADER_MARKERS.some(re => re.test(head));
+  } catch { return false; }
+}
+
+function _globMatch(pattern, p) {
+  // Minimal glob: `**` → `.*`, `*` → `[^/]*`. Path separators normalized.
+  const norm = String(p).replace(/\\/g, '/');
+  const re = new RegExp(
+    '^' + String(pattern).replace(/\\/g, '/')
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '###DSTAR###')
+      .replace(/\*/g, '[^/]*')
+      .replace(/###DSTAR###/g, '.*')
+    + '$',
+  );
+  return re.test(norm);
+}
+
+/**
+ * Extract intent signals once per scan.
+ */
+export function extractIntentSignals(scanRoot) {
+  if (process.env.AGENTIC_SECURITY_NO_INTENT_CTX === '1') {
+    return { declaredExcludedPaths: [], claudeMdExcludedPaths: [], intent: null };
+  }
+  const decl = _readIntentDeclaration(scanRoot);
+  const claudeMdPaths = _claudeMdHasOutOfScope(scanRoot);
+  return {
+    declaredExcludedPaths: decl ? decl.excludedPaths : [],
+    claudeMdExcludedPaths: claudeMdPaths,
+    intent: decl ? decl.body : null,
+  };
+}
+
+/**
+ * Per-finding suppression. Returns the count of findings demoted.
+ * Findings are mutated in place — sets `intentSuppressed=true`, drops
+ * confidence by 50%, adds 'intent-suppressed' tag.
+ */
+export function suppressByIntent(scanRoot, findings) {
+  if (process.env.AGENTIC_SECURITY_NO_INTENT_CTX === '1') return { applied: 0 };
+  if (!Array.isArray(findings) || findings.length === 0) return { applied: 0 };
+  const signals = extractIntentSignals(scanRoot);
+  const allExcluded = [...signals.declaredExcludedPaths, ...signals.claudeMdExcludedPaths];
+
+  let applied = 0;
+  const fileHeaderCache = new Map();
+
+  for (const f of findings) {
+    const file = f.file || '';
+    const rel = path.isAbsolute(file) ? path.relative(scanRoot, file) : file;
+    let suppress = false;
+    let reason = null;
+
+    if (INTENT_PATH_RE.test(rel)) { suppress = true; reason = 'intent-path-pattern'; }
+
+    if (!suppress && allExcluded.length) {
+      for (const pat of allExcluded) {
+        if (_globMatch(pat, rel)) { suppress = true; reason = 'intent-declared-exclusion'; break; }
+      }
+    }
+
+    if (!suppress && file) {
+      let hdr = fileHeaderCache.get(file);
+      if (hdr === undefined) {
+        hdr = _fileHeaderHasIntent(file);
+        fileHeaderCache.set(file, hdr);
+      }
+      if (hdr) { suppress = true; reason = 'intent-file-header'; }
+    }
+
+    if (suppress) {
+      f.intentSuppressed = true;
+      f.intentReason = reason;
+      if (typeof f.confidence === 'number') f.confidence = Math.max(0.15, f.confidence * 0.5);
+      f.tags = Array.isArray(f.tags) ? f.tags : [];
+      if (!f.tags.includes('intent-suppressed')) f.tags.push('intent-suppressed');
+      applied++;
+    }
+  }
+  return { applied, total: findings.length };
+}
+
+export const _internals = {
+  INTENT_PATH_RE, FILE_HEADER_MARKERS,
+  _readIntentDeclaration, _claudeMdHasOutOfScope, _fileHeaderHasIntent, _globMatch,
+};

package/src/posture/license-attributions.js

@@ -0,0 +1,94 @@
+// Attributions emitter — companion to license-graph.js.
+//
+// Generates two artifacts under .agentic-security/:
+//
+//   ATTRIBUTIONS.md — Markdown table of every component with its
+//                     license, version, copyright holder (when known),
+//                     and source URL.
+//   NOTICE          — Apache-style NOTICE file (only when Apache-2.0
+//                     licensed components are present).
+//
+// The emitter is deterministic — sorts by ecosystem, name, version —
+// so commits don't churn between scans.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function _sortKey(c) {
+  return `${c.ecosystem || 'zz'}:${c.name || ''}:${c.version || ''}`;
+}
+
+function _safeStr(s) { return String(s || '').replace(/\s+/g, ' ').trim(); }
+
+function _inferRepoUrl(c) {
+  if (c.repository?.url) return c.repository.url;
+  if (typeof c.repository === 'string') return c.repository;
+  if (c.homepage) return c.homepage;
+  // Common conventions for ecosystem package pages.
+  switch (c.ecosystem) {
+    case 'npm':  return `https://www.npmjs.com/package/${c.name}`;
+    case 'pypi': return `https://pypi.org/project/${c.name}/`;
+    case 'rubygems': return `https://rubygems.org/gems/${c.name}`;
+    case 'cargo': return `https://crates.io/crates/${c.name}`;
+    case 'maven': return `https://search.maven.org/artifact/${(c.name || '').replace(':', '/')}`;
+    case 'packagist': return `https://packagist.org/packages/${c.name}`;
+    case 'pub': return `https://pub.dev/packages/${c.name}`;
+    case 'golang': return `https://pkg.go.dev/${c.name}`;
+    default: return '';
+  }
+}
+
+export function generateAttributions(components, options) {
+  const opts = options || {};
+  const list = (components || []).slice().sort((a, b) => _sortKey(a).localeCompare(_sortKey(b)));
+  if (!list.length) return { markdown: '', notice: '' };
+
+  const lines = [];
+  lines.push('# Third-party attributions');
+  lines.push('');
+  lines.push(`Generated by agentic-security on ${new Date().toISOString().slice(0, 10)}.`);
+  lines.push('');
+  lines.push(`This project incorporates **${list.length}** third-party components. Each is listed with its license and source URL. See the linked source for the full license text.`);
+  lines.push('');
+  lines.push('| Package | Version | License | Ecosystem | Source |');
+  lines.push('|---------|---------|---------|-----------|--------|');
+  for (const c of list) {
+    const url = _inferRepoUrl(c);
+    const urlMd = url ? `[link](${url})` : '—';
+    lines.push(`| ${_safeStr(c.name)} | ${_safeStr(c.version)} | ${_safeStr(c.license || '—')} | ${_safeStr(c.ecosystem)} | ${urlMd} |`);
+  }
+  lines.push('');
+  const markdown = lines.join('\n');
+
+  // Apache NOTICE: include only Apache-2.0 components per § 4(d) requirement.
+  const apache = list.filter(c => /APACHE-2\.0/i.test(c.license || ''));
+  let notice = '';
+  if (apache.length) {
+    const nl = [];
+    nl.push(`${opts.projectName || 'This product'} includes software developed by third parties under the Apache 2.0 license:`);
+    nl.push('');
+    for (const c of apache) {
+      nl.push(`* ${c.name} (${c.version || 'unknown version'})`);
+      if (c.copyright) nl.push(`  Copyright: ${_safeStr(c.copyright)}`);
+      const url = _inferRepoUrl(c);
+      if (url) nl.push(`  Source: ${url}`);
+    }
+    nl.push('');
+    nl.push('See LICENSE / ATTRIBUTIONS.md for full license text.');
+    notice = nl.join('\n');
+  }
+
+  return { markdown, notice, componentCount: list.length };
+}
+
+export function persistAttributions(scanRoot, result) {
+  if (!result || !result.markdown) return null;
+  try { fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true }); } catch {}
+  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'ATTRIBUTIONS.md'), result.markdown); } catch {}
+  if (result.notice) {
+    try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'NOTICE'), result.notice); } catch {}
+  }
+  return result;
+}
+
+export const _internals = { _inferRepoUrl, _sortKey, _safeStr };

package/src/posture/license-graph.js

@@ -0,0 +1,238 @@
+// License-graph supply-chain analyzer — Item #5 of the world-class+3 plan.
+//
+// Extends posture/license-policy.js (per-component allow/deny/review) with:
+//
+//   1. TRANSITIVE COPYLEFT CONTAMINATION
+//      An MIT-licensed direct dep that pulls in a GPL/AGPL transitive
+//      dep. Today's per-component check passes because the direct dep is
+//      MIT — but the GPL is the actual exposure.
+//
+//   2. RELICENSING-RISK LICENSES
+//      BSL, SSPL, Elastic 2.0, Common Clause, Server Side Public License,
+//      Functional Source License, Sustainable Use License, etc.
+//      Permissive at first install — later versions or downstream usage
+//      may breach the additional terms.
+//
+//   3. DISTRIBUTION-MODE-AWARE POLICY
+//      "SaaS" vs "Binary" vs "Library" have radically different obligations.
+//      AGPL is fine for proprietary internal usage but kills SaaS;
+//      GPL is fine for a SaaS web app but kills a published library;
+//      LGPL static-link concerns only apply to native binary distribution.
+//
+//   4. DUAL-LICENSE TRAP DETECTION
+//      Packages declared as `(MIT OR Apache-2.0)` are usually fine, but
+//      `(GPL-2.0 OR Commercial)` are a contractual trap — the open option
+//      auto-converts your code to GPL unless you've signed a commercial
+//      agreement.
+//
+//   5. LICENSE-CHANGE DETECTION
+//      Packages known to have relicensed (Elastic, Redis, Sentry,
+//      HashiCorp Terraform, MongoDB) — flag the boundary version.
+//
+// Default mode: SaaS. Override via
+// .agentic-security/license-policy.yml `distributionMode:`.
+//
+// Opt-out: AGENTIC_SECURITY_NO_LICENSE_GRAPH=1
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ── License taxonomy ───────────────────────────────────────────────────────
+
+const LICENSE_FAMILIES = {
+  permissive:      new Set(['MIT', 'APACHE-2.0', 'BSD-2-CLAUSE', 'BSD-3-CLAUSE', 'BSD-4-CLAUSE', 'ISC', '0BSD', 'CC0-1.0', 'UNLICENSE', 'WTFPL', 'ZLIB', 'PSF-2.0', 'PYTHON-2.0', 'POSTGRESQL', 'OPENSSL', 'X11']),
+  weak_copyleft:   new Set(['LGPL-2.0', 'LGPL-2.1', 'LGPL-3.0', 'LGPL-2.1-OR-LATER', 'LGPL-3.0-OR-LATER', 'MPL-1.1', 'MPL-2.0', 'EPL-1.0', 'EPL-2.0', 'CDDL-1.0', 'CDDL-1.1']),
+  strong_copyleft: new Set(['GPL-2.0', 'GPL-2.0-ONLY', 'GPL-2.0-OR-LATER', 'GPL-3.0', 'GPL-3.0-ONLY', 'GPL-3.0-OR-LATER']),
+  network_copyleft: new Set(['AGPL-1.0', 'AGPL-3.0', 'AGPL-3.0-ONLY', 'AGPL-3.0-OR-LATER']),
+  source_available: new Set(['BSL-1.1', 'SSPL-1.0', 'ELASTIC-2.0', 'ELASTIC-1.0', 'COMMONS-CLAUSE', 'FSL-1.0', 'FSL-1.1', 'CONFLUENT-COMMUNITY', 'BUSL-1.1', 'PARITY-7.0.0', 'POLYFORM-NONCOMMERCIAL', 'POLYFORM-PERIMETER', 'POLYFORM-INTERNAL-USE']),
+  proprietary:     new Set(['UNLICENSED', 'NOLICENSE', 'PROPRIETARY', 'COMMERCIAL']),
+};
+
+const KNOWN_RELICENSED = [
+  // pkg-name regex → { from, to, atVersion, ecosystem }
+  { pkg: /^elasticsearch$/i,  from: 'Apache-2.0',  to: 'Elastic-2.0 / SSPL', atVersion: '>=7.11.0', ecosystem: 'java/npm' },
+  { pkg: /^@elastic\/elasticsearch$/i, from: 'Apache-2.0', to: 'Elastic-2.0 / SSPL', atVersion: '>=8.0.0', ecosystem: 'npm' },
+  { pkg: /^redis$/i,          from: 'BSD-3-Clause', to: 'RSALv2 / SSPL',     atVersion: '>=7.4',      ecosystem: 'multi' },
+  { pkg: /^@sentry\/.*$/i,    from: 'BSD-3-Clause', to: 'FSL-1.1',           atVersion: '>=8.0.0',    ecosystem: 'npm' },
+  { pkg: /^terraform.*$/i,    from: 'MPL-2.0',      to: 'BSL-1.1',           atVersion: '>=1.6.0',    ecosystem: 'multi' },
+  { pkg: /^mongodb$/i,        from: 'AGPL-3.0',     to: 'SSPL-1.0',          atVersion: '>=4.4',      ecosystem: 'multi' },
+  { pkg: /^vault$/i,          from: 'MPL-2.0',      to: 'BSL-1.1',           atVersion: '>=1.15.0',   ecosystem: 'go' },
+  { pkg: /^consul$/i,         from: 'MPL-2.0',      to: 'BSL-1.1',           atVersion: '>=1.17.0',   ecosystem: 'go' },
+  { pkg: /^cockroachdb?$/i,   from: 'Apache-2.0',   to: 'CCL (modified)',    atVersion: '>=19.2',     ecosystem: 'go' },
+];
+
+function _normLicense(s) { return String(s || '').toUpperCase().replace(/[()]/g, '').trim(); }
+
+function _classify(license) {
+  if (!license) return 'unknown';
+  const l = _normLicense(license);
+  // Compound: pick worst family.
+  if (/\s(?:AND|OR|WITH)\s/i.test(l)) {
+    const parts = l.split(/\s+(?:AND|OR|WITH)\s+/i).map(p => p.trim()).filter(Boolean);
+    const families = parts.map(_classify);
+    // Worst → best: source_available > network_copyleft > strong > weak > permissive > unknown.
+    for (const f of ['source_available', 'network_copyleft', 'strong_copyleft', 'weak_copyleft', 'permissive']) {
+      if (families.includes(f)) return f;
+    }
+    return 'unknown';
+  }
+  for (const [fam, set] of Object.entries(LICENSE_FAMILIES)) {
+    if (set.has(l)) return fam;
+  }
+  return 'unknown';
+}
+
+// ── Distribution-mode policy ───────────────────────────────────────────────
+
+const DEFAULT_DIST_MODE = 'saas';
+
+const DIST_MODE_MATRIX = {
+  saas: {
+    permissive:       { verdict: 'allow', why: 'Compatible with SaaS distribution.' },
+    weak_copyleft:    { verdict: 'allow', why: 'Weak-copyleft (LGPL/MPL/CDDL/EPL) — SaaS distribution does not trigger reciprocity for unmodified usage.' },
+    strong_copyleft:  { verdict: 'review', why: 'GPL/CGPL is compatible with SaaS (no distribution of binary) but propagates if you ever publish the source or a derived binary. Confirm internal-only.' },
+    network_copyleft: { verdict: 'deny', why: 'AGPL "network use as distribution" — SaaS deployment triggers source-disclosure obligations.' },
+    source_available: { verdict: 'deny', why: 'Source-available licenses (BSL/SSPL/Elastic/CommonsClause) restrict competitive SaaS offerings.' },
+    proprietary:      { verdict: 'deny', why: 'Component has no license / declares proprietary — cannot redistribute.' },
+    unknown:          { verdict: 'review', why: 'Unknown license — verify via upstream repo.' },
+  },
+  binary: {
+    permissive:       { verdict: 'allow', why: 'Compatible with binary distribution.' },
+    weak_copyleft:    { verdict: 'review', why: 'LGPL has static-linking obligations; MPL has file-level reciprocity. Confirm linkage model.' },
+    strong_copyleft:  { verdict: 'deny', why: 'GPL copyleft propagates to the entire distributed binary.' },
+    network_copyleft: { verdict: 'deny', why: 'AGPL is even more restrictive than GPL for distribution.' },
+    source_available: { verdict: 'deny', why: 'Source-available licenses (BSL/SSPL/Elastic/CommonsClause) impose use restrictions that often conflict with binary distribution to customers.' },
+    proprietary:      { verdict: 'deny', why: 'Component has no license / declares proprietary — cannot bundle.' },
+    unknown:          { verdict: 'review', why: 'Unknown license — verify via upstream repo.' },
+  },
+  library: {
+    permissive:       { verdict: 'allow', why: 'Compatible with library publishing.' },
+    weak_copyleft:    { verdict: 'review', why: 'LGPL/MPL transitive deps complicate downstream users of YOUR library.' },
+    strong_copyleft:  { verdict: 'deny', why: 'GPL locks all downstream users of your library into GPL.' },
+    network_copyleft: { verdict: 'deny', why: 'AGPL forces downstream users into AGPL.' },
+    source_available: { verdict: 'deny', why: 'Source-available licenses block downstream commercial use of your library.' },
+    proprietary:      { verdict: 'deny', why: 'Component has no license — cannot redistribute via your library.' },
+    unknown:          { verdict: 'review', why: 'Unknown license — verify via upstream repo.' },
+  },
+};
+
+// ── Transitive walker ──────────────────────────────────────────────────────
+
+function _depPathLabel(c) {
+  return `${c.ecosystem || '?'}:${c.name}@${c.version || '?'}`;
+}
+
+/**
+ * Build the dep graph + collect transitive contamination paths.
+ *
+ * components — list of component objects (already produced by the engine).
+ *              expects: { ecosystem, name, version, license, transitive (boolean),
+ *              importedBy: string[] (optional) }.
+ */
+export function analyzeLicenseGraph(components, options) {
+  const opts = options || {};
+  const mode = (opts.distributionMode || DEFAULT_DIST_MODE).toLowerCase();
+  const matrix = DIST_MODE_MATRIX[mode] || DIST_MODE_MATRIX[DEFAULT_DIST_MODE];
+  if (!Array.isArray(components) || components.length === 0) {
+    return { findings: [], summary: { total: 0, deny: 0, review: 0, allow: 0, unknown: 0 }, distributionMode: mode };
+  }
+  const byKey = new Map();
+  for (const c of components) byKey.set(_depPathLabel(c), c);
+  const findings = [];
+  const summary = { total: components.length, deny: 0, review: 0, allow: 0, unknown: 0 };
+
+  for (const c of components) {
+    const family = _classify(c.license);
+    const verdict = matrix[family] || matrix.unknown;
+    summary[verdict.verdict] = (summary[verdict.verdict] || 0) + 1;
+    if (verdict.verdict === 'allow') continue;
+
+    const isTransitive = !!c.transitive;
+    let path = [_depPathLabel(c)];
+    if (isTransitive && Array.isArray(c.importedBy) && c.importedBy.length) {
+      // Walk up the graph (one hop in v1 — sufficient for "direct dep that
+      // pulled in this offender").
+      path = [c.importedBy[0], _depPathLabel(c)];
+    }
+
+    findings.push({
+      id: `license-graph:${_depPathLabel(c)}:${family}:${verdict.verdict}`,
+      kind: 'license', family: 'license-graph',
+      severity: verdict.verdict === 'deny' ? 'high' : 'low',
+      file: c.filePath || 'package.json', line: 0,
+      vuln: `${verdict.verdict === 'deny' ? 'License-incompatible' : 'License-review-needed'}: ${c.name}@${c.version || '?'} (${c.license || 'no license'}) under ${mode} distribution mode`,
+      description: verdict.why + (isTransitive ? ` Transitive dep pulled in via ${path.slice(0, -1).join(' → ')}.` : ''),
+      remediation: verdict.verdict === 'deny'
+        ? `Replace ${c.name}@${c.version || '?'} with a permissively-licensed alternative, OR switch to a different distribution mode (set distributionMode: in .agentic-security/license-policy.yml), OR negotiate a commercial license with the upstream.`
+        : `Have legal review confirm ${c.license} compatibility with ${mode} distribution. Once approved, add ${c.name} to the policy allow-list.`,
+      package: c.name,
+      version: c.version,
+      ecosystem: c.ecosystem,
+      license: c.license || null,
+      licenseFamily: family,
+      distributionMode: mode,
+      isTransitive,
+      depPath: path,
+    });
+  }
+
+  // ── Dual-license trap detection ─────────────────────────────────────────
+  for (const c of components) {
+    if (!c.license) continue;
+    const lic = _normLicense(c.license);
+    if (!/\bOR\b/i.test(lic)) continue;
+    const atoms = lic.split(/\s+OR\s+/i).map(s => s.trim());
+    const hasCommercial = atoms.some(a => /COMMERCIAL|PROPRIETARY|ENTERPRISE/.test(a));
+    const hasStrongCopyleft = atoms.some(a => LICENSE_FAMILIES.strong_copyleft.has(a) || LICENSE_FAMILIES.network_copyleft.has(a));
+    if (hasCommercial && hasStrongCopyleft) {
+      findings.push({
+        id: `license-graph:dual-license-trap:${_depPathLabel(c)}`,
+        kind: 'license', family: 'license-dual-trap',
+        severity: 'high',
+        file: c.filePath || 'package.json', line: 0,
+        vuln: `Dual-license trap: ${c.name}@${c.version} offers ${c.license} — the open option is copyleft, the alternative requires a commercial agreement`,
+        description: 'Dual GPL-OR-Commercial licensing means: if you have not signed a commercial agreement with the upstream, your usage falls under GPL/AGPL and propagates to your codebase. Common pattern with Qt LGPL/Commercial, MongoDB AGPL/Commercial pre-SSPL, GraalVM.',
+        remediation: 'Verify with legal whether a commercial agreement is in place. If not, you are bound by the copyleft option — propagate that to your distribution mode policy.',
+        package: c.name, version: c.version, license: c.license,
+      });
+      summary.deny = (summary.deny || 0) + 1;
+    }
+  }
+
+  // ── Known relicensed packages ───────────────────────────────────────────
+  for (const c of components) {
+    for (const r of KNOWN_RELICENSED) {
+      if (!r.pkg.test(c.name)) continue;
+      findings.push({
+        id: `license-graph:relicensed:${_depPathLabel(c)}`,
+        kind: 'license', family: 'license-relicense',
+        severity: 'medium',
+        file: c.filePath || 'package.json', line: 0,
+        vuln: `${c.name}@${c.version}: upstream relicensed from ${r.from} → ${r.to} (boundary ${r.atVersion})`,
+        description: `Upstream relicensing event for ${c.name}. Older versions were ${r.from}; ${r.atVersion} and later are ${r.to}. Verify which side of the boundary your version is on, and update your policy.`,
+        remediation: `Pin to a pre-relicense version if the new terms are unacceptable, OR adopt a fork (e.g. OpenSearch for Elasticsearch, Valkey for Redis, OpenTofu for Terraform).`,
+        package: c.name, version: c.version, license: c.license, relicenseInfo: r,
+      });
+    }
+  }
+
+  return { findings, summary, distributionMode: mode };
+}
+
+// ── Policy file loader (extends posture/license-policy.js shape) ───────────
+
+export function loadLicenseGraphPolicy(scanRoot) {
+  if (!scanRoot) return { distributionMode: DEFAULT_DIST_MODE };
+  const fp = path.join(scanRoot, '.agentic-security', 'license-policy.yml');
+  if (!fs.existsSync(fp)) return { distributionMode: DEFAULT_DIST_MODE };
+  try {
+    const raw = fs.readFileSync(fp, 'utf8');
+    const m = /\bdistributionMode\s*:\s*['"]?(saas|binary|library)['"]?/i.exec(raw);
+    return { distributionMode: m ? m[1].toLowerCase() : DEFAULT_DIST_MODE };
+  } catch { return { distributionMode: DEFAULT_DIST_MODE }; }
+}
+
+export const _internals = {
+  LICENSE_FAMILIES, DIST_MODE_MATRIX, KNOWN_RELICENSED,
+  _classify, _normLicense,
+};