@clear-capabilities/agentic-security-scanner 0.78.0 → 0.80.0

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,
+};

package/src/posture/pqc-migration-plan.js

@@ -0,0 +1,158 @@
+// PQC migration-plan artifact emitter.
+//
+// Aggregates pqc-migration findings (emitted by sast/post-quantum-crypto.js)
+// into a structured plan suitable for an engineering organization to use as
+// a project tracker:
+//
+//   .agentic-security/pqc-migration-plan.json
+//   .agentic-security/pqc-migration-plan.md
+//
+// Buckets findings by:
+//   - HNDL criticality (high-priority — data captured today is harvest-now-decrypt-later
+//     exposure when a CRQC arrives)
+//   - Use case (signing / encryption / KEX) — drives the replacement primitive
+//   - Recommended replacement (ML-KEM-768, ML-DSA-65, etc.)
+//   - File / package locality so the plan can be carved into milestones.
+//
+// Cleartext markdown summarises the top recommendations and milestone
+// suggestions; JSON-LD-shaped structured output is consumable by Vanta /
+// Drata / SecureFrame or any custom rollup dashboard.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function _byHndl(findings) {
+  return {
+    hndlCritical: findings.filter(f => f.hndlCritical),
+    standard: findings.filter(f => !f.hndlCritical),
+  };
+}
+
+function _byUseCase(findings) {
+  const map = new Map();
+  for (const f of findings) {
+    const k = f.pqcRecommendation?.primary || 'unspecified';
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(f);
+  }
+  return map;
+}
+
+function _byFile(findings) {
+  const map = new Map();
+  for (const f of findings) {
+    const k = f.file || 'unknown';
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(f);
+  }
+  return map;
+}
+
+export function buildMigrationPlan(allFindings) {
+  const pqc = (allFindings || []).filter(f => f.family === 'pqc-migration');
+  if (!pqc.length) return null;
+  const bySev = _byHndl(pqc);
+  const byPrimitive = _byUseCase(pqc);
+  const byFile = _byFile(pqc);
+  const summary = {
+    total: pqc.length,
+    hndlCritical: bySev.hndlCritical.length,
+    standard: bySev.standard.length,
+    filesAffected: byFile.size,
+    primitivesNeeded: Array.from(byPrimitive.keys()),
+  };
+  const milestones = [
+    {
+      id: 'M1',
+      title: 'Inventory & policy',
+      target: '90 days',
+      owner: 'security',
+      items: [
+        'Confirm scanner findings against design docs',
+        'Adopt PQC migration policy (CNSA 2.0 / NIST IR 8547 alignment)',
+        'Establish KMS support for hybrid keys',
+      ],
+    },
+    {
+      id: 'M2',
+      title: 'HNDL-critical paths to PQ-hybrid',
+      target: '180 days',
+      owner: 'platform',
+      items: bySev.hndlCritical.slice(0, 25).map(f => ({
+        finding: f.id, file: f.file, line: f.line,
+        replacement: f.pqcRecommendation?.hybrid || f.pqcRecommendation?.primary,
+      })),
+    },
+    {
+      id: 'M3',
+      title: 'Standard signing/KEX migration',
+      target: '12 months',
+      owner: 'platform',
+      items: bySev.standard.slice(0, 50).map(f => ({
+        finding: f.id, file: f.file, line: f.line,
+        replacement: f.pqcRecommendation?.primary,
+      })),
+    },
+    {
+      id: 'M4',
+      title: 'Deprecate classical primitives',
+      target: '24 months',
+      owner: 'security',
+      items: ['Remove dual-stack libraries once peers are PQ-capable', 'Rotate root CA / long-lived signing keys to ML-DSA'],
+    },
+  ];
+  return {
+    generatedAt: new Date().toISOString(),
+    summary,
+    milestones,
+    perFile: Object.fromEntries(
+      Array.from(byFile.entries()).map(([file, fs]) => [file, {
+        count: fs.length,
+        subfamilies: Array.from(new Set(fs.map(f => f.subfamily))),
+        hndlCritical: fs.some(f => f.hndlCritical),
+      }]),
+    ),
+  };
+}
+
+export function persistMigrationPlan(scanRoot, plan) {
+  if (!plan) return null;
+  try { fs.mkdirSync(path.join(scanRoot, '.agentic-security'), { recursive: true }); } catch {}
+  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'pqc-migration-plan.json'), JSON.stringify(plan, null, 2)); } catch {}
+  try { fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'pqc-migration-plan.md'), _markdown(plan)); } catch {}
+  return plan;
+}
+
+function _markdown(plan) {
+  const lines = [];
+  lines.push('# Post-quantum cryptography migration plan');
+  lines.push('');
+  lines.push(`Generated ${plan.generatedAt.slice(0, 10)}.`);
+  lines.push('');
+  lines.push(`**${plan.summary.total}** pre-quantum primitive sites across **${plan.summary.filesAffected}** files.  `);
+  lines.push(`HNDL-critical: **${plan.summary.hndlCritical}** | Standard: **${plan.summary.standard}**`);
+  lines.push('');
+  lines.push('## Recommended PQ primitives');
+  for (const p of plan.summary.primitivesNeeded) lines.push(`- ${p}`);
+  lines.push('');
+  for (const m of plan.milestones) {
+    lines.push(`## ${m.id} — ${m.title} (target ${m.target}, owner ${m.owner})`);
+    if (Array.isArray(m.items) && m.items.length) {
+      for (const it of m.items.slice(0, 20)) {
+        if (typeof it === 'string') lines.push(`- ${it}`);
+        else lines.push(`- \`${it.file}:${it.line}\` → ${it.replacement || '(see finding)'}`);
+      }
+      if (m.items.length > 20) lines.push(`- … ${m.items.length - 20} more`);
+    }
+    lines.push('');
+  }
+  lines.push('## References');
+  lines.push('- NIST FIPS 203 (ML-KEM), FIPS 204 (ML-DSA), FIPS 205 (SLH-DSA)');
+  lines.push('- NIST IR 8547 — Transition to Post-Quantum Cryptographic Standards');
+  lines.push('- CNSA 2.0 — Commercial National Security Algorithm Suite, Sept 2022');
+  lines.push('- RFC 9794 — X25519MLKEM768 hybrid key exchange for TLS 1.3');
+  lines.push('- Open Quantum Safe project (liboqs, oqs-provider for OpenSSL 3)');
+  return lines.join('\n');
+}
+
+export const _internals = { _byHndl, _byUseCase, _byFile, _markdown };

package/src/posture/profile.js

@@ -6,6 +6,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'js-yaml';
+import { statePath, safeWriteState, resolveProjectRoot } from './state-dir.js';
 
 export const PROFILES = ['vibecoder', 'pro'];
 
@@ -35,7 +36,7 @@ export const DEFAULTS = {
 };
 
 function _profilePath(scanRoot) {
-  return path.join(scanRoot || process.cwd(), '.agentic-security', 'profile.yml');
+  return statePath(scanRoot, 'profile.yml');
 }
 
 export function loadProfile(scanRoot) {
@@ -52,10 +53,8 @@ export function loadProfile(scanRoot) {
 
 export function saveProfile(scanRoot, updates) {
   const fp = _profilePath(scanRoot);
-  fs.mkdirSync(path.dirname(fp), { recursive: true });
   const current = loadProfile(scanRoot);
   const next = { ...current, ...updates };
-  // Strip values equal to defaults so the file stays minimal.
   const defaults = DEFAULTS[next.profile];
   const out = {};
   for (const k of Object.keys(next)) {
@@ -63,7 +62,7 @@ export function saveProfile(scanRoot, updates) {
     out[k] = next[k];
   }
   if (!('profile' in out)) out.profile = next.profile;
-  fs.writeFileSync(fp, yaml.dump(out));
+  safeWriteState(fp, yaml.dump(out));
   return next;
 }
 
@@ -71,7 +70,7 @@ export function saveProfile(scanRoot, updates) {
 // Returns 'pro' if the repo has signals indicating professional security work,
 // otherwise 'vibecoder'. Run only on first scan.
 export function detectProfile(scanRoot) {
-  const root = scanRoot || process.cwd();
+  const root = resolveProjectRoot(scanRoot);
   const signals = ['SECURITY.md', '.github/workflows/security.yml', '.semgrep.yml',
                    '.snyk', 'codeql-config.yml', 'compliance/', 'docs/threat-model.md'];
   for (const s of signals) {

package/src/posture/reachability-filter.js

@@ -5,6 +5,11 @@
 // module turns that signal into a precision lever: findings marked reachable=
 // false are demoted to severity 'info' with f.unreachable = true.
 //
+// Phase 2 / Item 4 (SCA improvement plan): also demote SCA findings whose
+// reachabilityTier indicates the vulnerable code is not reached by any route
+// handler. Critical+manifest-only on a 500-dep transitive graph would
+// otherwise drown out real reachable bugs.
+//
 // Disabled when scanRoot/--include-unreachable signals are present, or when
 // AGENTIC_SECURITY_INCLUDE_UNREACHABLE=1 is set.
 
@@ -15,6 +20,19 @@ const SEVERITY_DEMOTE = {
   low: 'info',
 };
 
+// SCA reachability tiers, ordered from highest urgency to lowest. A tier
+// in DEMOTE_SCA_TIERS triggers severity demotion; a tier NOT in the set
+// keeps full severity. route-reachable-via-function and function-reachable
+// both keep full severity because the vulnerable function is provably
+// called; import-reachable also keeps full severity (imported = uncertain
+// but plausible). The lower three tiers get demoted.
+const DEMOTE_SCA_TIERS = new Set([
+  'unreachable',       // function never called from project
+  'build-only',        // dev/build-time dependency only
+  'manifest-only',     // declared, but no use observed
+  'transitive-only',   // transitive dep, scope unclear
+]);
+
 export function demoteUnreachable(findings, opts = {}) {
   if (!Array.isArray(findings)) return;
   if (opts.includeUnreachable || process.env.AGENTIC_SECURITY_INCLUDE_UNREACHABLE === '1') return;
@@ -26,9 +44,22 @@ export function demoteUnreachable(findings, opts = {}) {
   if (!haveRoutes) return;
   for (const f of findings) {
     if (!f || typeof f !== 'object') continue;
-    if (f.reachable !== false) continue;
-    if (f.type === 'vulnerable_dep') continue;
     if (f.unreachable) continue;
+    // SCA findings: demote based on reachabilityTier instead of f.reachable
+    // (the latter isn't meaningful for an SCA finding — components don't
+    // have call sites in the SAST sense).
+    if (f.type === 'vulnerable_dep') {
+      if (!DEMOTE_SCA_TIERS.has(f.reachabilityTier)) continue;
+      const beforeSca = f.severity;
+      const afterSca = SEVERITY_DEMOTE[beforeSca];
+      if (!afterSca || beforeSca === afterSca) continue;
+      f.severity = afterSca;
+      f.unreachable = true;
+      f._reachabilityDemoted = beforeSca;
+      f._reachabilityDemoteReason = `tier:${f.reachabilityTier}`;
+      continue;
+    }
+    if (f.reachable !== false) continue;
     // Source has an explicit HTTP/DOM/Form/URL category → engine is confident
     // it's a user-input source even though no route was linked. Don't demote.
     if (f.source && f.source.category && /HTTP|DOM|Form|URL|Query/i.test(f.source.category)) continue;