@clear-capabilities/agentic-security-scanner 0.172.1 → 0.174.0

package/src/posture/scan-checkpoint.js

@@ -84,6 +84,9 @@ const FORMAT = 'agentic-security-scan-checkpoint/2';
 // what it would find.
 const RUN_KEY_ENV_EXCLUDE = new Set([
   'AGENTIC_SECURITY_RESUME',
+  // E6-04: these choose WHETHER a cache is used, or only how fast shared helpers run; neither changes what any file's analysis produces
+  'AGENTIC_SECURITY_ANALYSIS_CACHE',
+  'AGENTIC_SECURITY_NO_STRING_MEMO',
   'AGENTIC_SECURITY_CHECKPOINT_ABORT_AFTER',
   'AGENTIC_SECURITY_HMAC_KEY',
 ]);
@@ -126,7 +129,7 @@ export function bundleShaForRunKey() {
  */
 export function computeRunKey({
   engineVersion, rulesetVersion, bundleSha,
-  fileContents = {}, depFileContents = {}, env = process.env,
+  fileContents = {}, depFileContents = {}, env = process.env, extra = null,
 } = {}) {
   const h = crypto.createHash('sha256');
   h.update(FORMAT); h.update('\n');
@@ -142,6 +145,8 @@ export function computeRunKey({
       h.update('\n');
     }
   }
+  // E6-04: cross-file inputs a single file's analysis reads (project constants, custom rules, ...). Absent means the key is unchanged from before.
+  if (extra !== null && extra !== undefined) { h.update('x'); h.update(String(extra)); h.update('\n'); }
   const envKeys = Object.keys(env || {})
     .filter(k => k.startsWith('AGENTIC_SECURITY_') && !RUN_KEY_ENV_EXCLUDE.has(k))
     .sort();
@@ -160,8 +165,8 @@ export function computeRunKey({
  * no per-file granularity to offer there; any manifest change invalidates
  * everything, same as before this change.
  */
-export function computeGlobalKey({ engineVersion, rulesetVersion, bundleSha, depFileContents = {}, env = process.env } = {}) {
-  return computeRunKey({ engineVersion, rulesetVersion, bundleSha, fileContents: {}, depFileContents, env });
+export function computeGlobalKey({ engineVersion, rulesetVersion, bundleSha, depFileContents = {}, env = process.env, extra = null } = {}) {
+  return computeRunKey({ engineVersion, rulesetVersion, bundleSha, fileContents: {}, depFileContents, env, extra });
 }
 
 /**
@@ -228,11 +233,16 @@ function _emptyHandle(reason) {
     enabled: false, file: null, fd: null, globalKey: null,
     recovered: new Map(), order: [], written: new Set(),
     discarded: false, reason, invalidatedFiles: [], fileContents: {},
+    // E6-04: persistent (cross-scan) mode. `sign` authenticates records with the install key; `lines` keeps the latest verified line per file for compaction.
+    persistent: false, sign: null, lines: new Map(),
   };
 }
 
-function _headerLine(globalKey, meta) {
-  return JSON.stringify({ v: FORMAT, gk: globalKey, meta: meta || {} }) + '\n';
+function _headerMac(sign, globalKey) { return sign ? sign(`hdr\0${FORMAT}\0${globalKey}`) : undefined; }
+function _recordMac(sign, f, h, globalKey, d) { return sign ? sign(`rec\0${f}\0${h ?? ''}\0${globalKey}\0${d}`) : _sha(d); }
+
+function _headerLine(globalKey, meta, sign = null) {
+  return JSON.stringify({ v: FORMAT, gk: globalKey, meta: meta || {}, ...(sign ? { hm: _headerMac(sign, globalKey) } : {}) }) + '\n';
 }
 
 // Read forward from a byte offset, keeping records while they verify. Returns
@@ -258,6 +268,9 @@ function _recover(handle, file, globalKey, meta, fileContents) {
   try { header = JSON.parse(text.slice(0, nl)); } catch { return { offset: 0, discardReason: 'corrupt checkpoint header' }; }
   if (!header || header.v !== FORMAT) return { offset: 0, discardReason: 'checkpoint format changed' };
   if (header.gk !== globalKey) return { offset: 0, discardReason: _explainGlobalMismatch(header.meta, meta) };
+  // E6-04: a persistent cache is read back on later scans, possibly in a checkout someone else prepared. Only a header made with THIS install's key counts;
+  // a file carried in from elsewhere (or planted in a repository) is discarded whole, never trusted.
+  if (handle.sign && header.hm !== _headerMac(handle.sign, globalKey)) return { offset: 0, discardReason: 'cache was not written by this installation (header signature does not verify)' };
 
   let offset = Buffer.byteLength(text.slice(0, nl + 1), 'utf8');
   let cursor = nl + 1;
@@ -270,7 +283,7 @@ function _recover(handle, file, globalKey, meta, fileContents) {
     let rec;
     try { rec = JSON.parse(line); } catch { break; }
     if (!rec || typeof rec.f !== 'string' || typeof rec.d !== 'string') break;
-    if (rec.c !== _sha(rec.d)) break;         // tampered or torn-then-patched
+    if (rec.c !== _recordMac(handle.sign, rec.f, rec.h ?? null, globalKey, rec.d)) break;         // tampered or torn-then-patched (or, with a key, not ours)
     let payload;
     try { payload = JSON.parse(rec.d); } catch { break; }
     // Structurally intact and parseable — advance past it regardless of what
@@ -294,6 +307,7 @@ function _recover(handle, file, globalKey, meta, fileContents) {
     }
     if (!handle.recovered.has(rec.f)) handle.order.push(rec.f);
     handle.recovered.set(rec.f, payload);
+    handle.lines.set(rec.f, line + '\n');
   }
   return { offset, discardReason: null };
 }
@@ -315,7 +329,7 @@ function _recover(handle, file, globalKey, meta, fileContents) {
  * `meta`: a plaintext summary of the inputs behind `globalKey` (see
  * `globalKeyMeta`), stored in the header purely to explain a mismatch later.
  */
-export function openCheckpoint(scanRoot, { globalKey, meta = {}, fileContents = {} } = {}) {
+export function openCheckpoint(scanRoot, { globalKey, meta = {}, fileContents = {}, persistent = false, fileName = null, sign = null } = {}) {
   if (!scanRoot || !globalKey) return _emptyHandle('no-global-key');
   // A read-only scan cannot checkpoint, and must not try. Resume is purely an
   // optimisation — without it the scan recomputes, which is slower and
@@ -328,9 +342,11 @@ export function openCheckpoint(scanRoot, { globalKey, meta = {}, fileContents =
   try {
     const dir = path.join(scanRoot, STATE_DIR);
     fs.mkdirSync(dir, { recursive: true });
-    const file = checkpointPath(scanRoot);
+    const file = fileName ? path.join(dir, fileName) : checkpointPath(scanRoot);
     handle.file = file;
     handle.globalKey = globalKey;
+    handle.persistent = !!persistent; handle.sign = typeof sign === 'function' ? sign : null;
+    handle.meta = meta || {};
 
     const { offset: keepBytes, discardReason } = _recover(handle, file, globalKey, meta, handle.fileContents);
     if (keepBytes <= 0) {
@@ -340,9 +356,10 @@ export function openCheckpoint(scanRoot, { globalKey, meta = {}, fileContents =
       handle.recovered.clear();
       handle.order.length = 0;
       handle.invalidatedFiles = [];
+      handle.lines.clear();
       handle.discarded = keepBytes === 0;
       handle.reason = keepBytes === 0 ? discardReason : null;
-      fs.writeFileSync(file, _headerLine(globalKey, meta));
+      fs.writeFileSync(file, _headerLine(globalKey, meta, handle.sign));
     } else {
       // Drop any torn tail so appends land after the last verified record.
       try {
@@ -381,10 +398,11 @@ export function recordFileDone(handle, relPath, findings) {
     if (typeof d !== 'string') return false;
     const src = handle.fileContents ? handle.fileContents[relPath] : undefined;
     const h = typeof src === 'string' ? _sha(src) : null;
-    const line = JSON.stringify({ f: relPath, h, c: _sha(d), d }) + '\n';
+    const line = JSON.stringify({ f: relPath, h, c: _recordMac(handle.sign, relPath, h, handle.globalKey, d), d }) + '\n';
     fs.writeSync(handle.fd, line);
     fs.fsyncSync(handle.fd);
     handle.written.add(relPath);
+    handle.lines.set(relPath, line);
     return true;
   } catch {
     return false;
@@ -430,6 +448,16 @@ export function closeCheckpoint(handle, { complete = false } = {}) {
   try { if (handle.fd !== null) fs.closeSync(handle.fd); } catch { ok = false; }
   handle.fd = null;
   handle.enabled = false;
+  if (complete && handle.file && handle.persistent) {
+    // A persistent cache is kept for the next scan, compacted to one line per file still in scope so it cannot grow without bound.
+    try {
+      const keep = [...handle.lines.entries()].filter(([f]) => typeof handle.fileContents[f] === 'string').map(([, l]) => l);
+      const tmp = `${handle.file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, _headerLine(handle.globalKey, handle.meta || {}, handle.sign) + keep.join(''));
+      fs.renameSync(tmp, handle.file);
+    } catch { ok = false; }
+    return ok;
+  }
   if (complete && handle.file) {
     try { fs.rmSync(handle.file, { force: true }); } catch { ok = false; }
   }

package/src/posture/waf-ingest.js

@@ -33,6 +33,7 @@
 //
 //  AWS WAF list-rules JSON: same expression-based heuristic.
 
+import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
@@ -81,9 +82,13 @@ function parseNormalized(obj) {
   }));
 }
 
+// A rule with no id of its own gets one derived from its content, so the same export always yields the same ids (a random suffix made every
+// ingestion of an unnamed rule a different rule).
+function _contentId(r) { return createHash('sha256').update(JSON.stringify(r)).digest('hex').slice(0, 8); }
+
 function parseCloudflare(arr) {
   return arr.filter(r => r && (r.action === 'block' || r.action === 'managed_challenge')).map((r) => ({
-    id: r.id || r.ref || 'cf-' + Math.random().toString(36).slice(2, 8),
+    id: r.id || r.ref || 'cf-' + _contentId(r),
     pattern: r.description || r.expression || '',
     families: inferFamilyFromExpression(r.expression || r.description || ''),
     vendor: 'cloudflare',
@@ -93,7 +98,7 @@ function parseCloudflare(arr) {
 function parseAwsWaf(obj) {
   const rules = obj.Rules || obj.rules || [];
   return rules.map((r) => ({
-    id: r.Name || r.name || 'aws-' + Math.random().toString(36).slice(2, 8),
+    id: r.Name || r.name || 'aws-' + _contentId(r),
     pattern: JSON.stringify(r.Statement || r.statement || {}).slice(0, 200),
     families: inferFamilyFromExpression(JSON.stringify(r.Statement || r.statement || {})),
     vendor: 'aws-waf',

package/src/report/index.js

@@ -391,6 +391,8 @@ export function normalizeFindings(scan){
       // introduced this finding. A different question, and a different field,
       // from the two lines above it (see the import comment at the top).
       findingProvenance: _normalizedProvenance(f),
+      // E5-07: only present when a caller attached a runtime explanation, so findings without one keep exactly their previous shape
+      ...(f.runtimeExplanationSummary && typeof f.runtimeExplanationSummary === 'object' ? { runtimeExplanationSummary: f.runtimeExplanationSummary } : {}),
       typeNarrowed: f.typeNarrowed || null,
       strideCategory: f.strideCategory || null,
       personaScores: f.personaScores || null,
@@ -1191,6 +1193,8 @@ export function toSARIF(scan, meta={}){
           ...(f.unvalidated ? { unvalidated: true } : {}),
           ...(f.cross_language ? { crossLanguage: true } : {}),
           ...(f.family ? { family: f.family } : {}),
+          // E5-07: compact static/runtime explanation (digest-tied to the full object); present only when a caller attached one
+          ...(f.runtimeExplanationSummary ? { runtimeExplanation: f.runtimeExplanationSummary } : {}),
           // Premortem 3R-6 + 4R-10: emit the single signatureStatus tri-state
           // (verified | unsigned | pass-through). The legacy bool flags are
           // emitted alongside for one release of grace so existing dashboards

package/src/report/oscal.js

@@ -442,7 +442,45 @@ export function complianceRowsFromPrivacy(assessment) {
   }));
 }
 
+/**
+ * Adapter for `posture/compliance-truth.js#assessFrameworkTruth`: six states, of which only `assessed_satisfied` and `assessed_not_satisfied` become OSCAL
+ * findings. Every other state becomes an observation with its own remark, so an incomplete, unverifiable or human-owned control never carries a verdict.
+ */
+const TRUTH_DECISION = Object.freeze({
+  assessed_satisfied: 'satisfied',
+  assessed_not_satisfied: 'not-satisfied',
+  not_assessed: 'unassessed',
+  not_applicable: 'unassessed',
+  requires_human_review: 'unassessed',
+  insufficient_evidence: 'unassessed',
+});
+
+export function complianceRowsFromTruth(assessment) {
+  return ((assessment && assessment.controls) || []).map(c => ({
+    id: c.id,
+    title: c.title || '',
+    decision: TRUTH_DECISION[c.state] || 'unassessed',
+    statusLabel: c.state,
+    known: Object.prototype.hasOwnProperty.call(TRUTH_DECISION, c.state),
+    observations: [...(c.reasons || []), ...(c.observations || [])],
+    props: [
+      _prop('truth-state', c.state),
+      ...(c.codeTestable ? [_prop('code-testable', c.codeTestable)] : []),
+      ...(c.evaluatorStatus ? [_prop('evaluator-status', c.evaluatorStatus)] : []),
+    ],
+  }));
+}
+
 const UNASSESSED_REMARK = {
+  not_assessed:
+    'Not assessed: nothing examined this control. The publisher rates it checkable by code but this tool has no check for it, or the evaluator reported a status this model does not recognise. '
+    + 'This is a gap in the tool, not a finding about the system.',
+  not_applicable:
+    'Declared not applicable by a named person with a reason. The tool never infers this; the declaration is on the observation.',
+  requires_human_review:
+    'Requires human review: the control needs judgement or organisational evidence the scanner cannot supply. Automated signals that cleared are context, not a verdict.',
+  insufficient_evidence:
+    'Insufficient evidence: signals exist for this control but cannot carry a verdict (an incomplete scan, an unverifiable mapping or weak evidence). No satisfied or not-satisfied claim is made.',
   unrecognised:
     'Not assessed: the evaluator reported a status this exporter does not recognise, so no satisfied/'
     + 'not-satisfied claim is made. The raw status is on the assessment-status property. This is a defect '

package/src/report/perspectives.js

@@ -0,0 +1,150 @@
+// Three views of one release (E7-07): what a developer needs, what a CISO needs, what an auditor needs, all built from the SAME canonical list of findings so they
+// cannot disagree.
+//
+//   developer  where the problem is, why it is one, how to fix it, and whether a fix was verified
+//   CISO       what is proven and what is not, what changed since the previous release, how risky and how complete
+//   auditor    for each assertion and each unknown, the evidence it rests on (by digest) and why anything is unknown; the issuer and what the signature does not prove
+//
+// One list, three projections. `canonicalFindings` is computed once from the release package; every view only selects and arranges its fields, and each entry
+// carries the same finding id, status, evidence hash and confidence wherever it appears. Nothing is recomputed per view.
+//
+// The package is DATA from a repository we do not control: every string is escaped before it reaches HTML, the page loads nothing from anywhere and runs no script, and a
+// content security policy says so.
+import { createHash } from 'node:crypto';
+import { releaseVerdict } from '../posture/assurance/release-verdict.js';
+
+const esc = (v) => String(v ?? '').replace(/[&<>"'`]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;', '`': '&#96;' }[c]));
+const sevRank = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+
+function confidenceOf(f) {
+  if (typeof f.confidence === 'number') return f.confidence >= 0.8 ? 'high' : f.confidence >= 0.5 ? 'medium' : 'low';
+  return typeof f.confidenceTier === 'string' ? f.confidenceTier : 'unknown';
+}
+
+/**
+ * @param {object} pkg a release package (E7-03). It is assumed to have been verified by the caller; the views carry `verification` as the caller states it.
+ * @param {{previous?:object, ranking?:object, verification?:{ok:boolean, errors?:object[]}}} opts `previous` is the previous release's package; `ranking` is a result of rankFleetExposure
+ */
+export function buildCanonicalFindings(pkg) {
+  const entries = Array.isArray(pkg && pkg.evidence) ? pkg.evidence : [];
+  const byKind = (k) => entries.filter((e) => e.ref && e.ref.kind === k);
+  const fixes = byKind('fix-verification');
+  const out = [];
+  for (const e of byKind('finding')) {
+    const f = e.payload || {};
+    const id = e.ref.payloadId || f.stableId || f.id;
+    const fixesFor = fixes.filter((x) => x.payload && (x.payload.findingStableId === id || x.payload.findingId === id || x.payload.findingId === f.id) );
+    const fix = fixesFor.find((x) => x.payload.verifiedFull === true) || fixesFor[0] || null;
+    const status = !fix ? 'open' : fix.payload.verifiedFull === true ? 'fix-verified' : 'fix-unverified';
+    out.push({
+      id, evidenceHash: e.ref.digest, status, confidence: confidenceOf(f), severity: f.severity || 'info', proofTier: typeof f.proofTier === 'string' ? f.proofTier : 'unproven',
+      where: { file: f.file ?? null, line: Number.isInteger(f.line) ? f.line : null }, title: f.vuln || f.title || 'finding', cwe: f.cwe || null,
+      why: f.description || f.reason || null, how: f.remediation || null,
+      fix: fix ? { evidenceHash: fix.ref.digest, verifiedFull: fix.payload.verifiedFull === true, completeness: fix.payload.fixCompleteness || null, degradedLegs: Array.isArray(fix.payload.degradedLegs) ? fix.payload.degradedLegs.map((d) => (typeof d === 'string' ? d : d && d.leg) ).filter(Boolean) : [] } : null,
+    });
+  }
+  return out.sort((a, b) => (sevRank[b.severity] - sevRank[a.severity]) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+export function buildViews(pkg, { previous = null, ranking = null, verification = null } = {}) {
+  const findings = buildCanonicalFindings(pkg);
+  const packageDigest = `sha256:${createHash('sha256').update(JSON.stringify(pkg && pkg.lineageOrder || [])).digest('hex')}`;
+  const prev = previous ? buildCanonicalFindings(previous) : null;
+  const prevById = prev ? new Map(prev.map((f) => [f.id, f])) : null;
+  const ids = new Set(findings.map((f) => f.id));
+  const change = prev ? {
+    new: findings.filter((f) => !prevById.has(f.id)).map((f) => f.id),
+    resolved: prev.filter((f) => !ids.has(f.id)).map((f) => f.id),
+    statusChanged: findings.filter((f) => prevById.has(f.id) && prevById.get(f.id).status !== f.status).map((f) => ({ id: f.id, from: prevById.get(f.id).status, to: f.status })),
+    unchanged: findings.filter((f) => prevById.has(f.id) && prevById.get(f.id).status === f.status).length,
+  } : null;
+  const rankById = ranking ? new Map(ranking.ranked.map((r) => [r.id, r])) : null;
+  const tier = (t) => findings.filter((f) => f.proofTier === t).length;
+  const completeness = pkg && pkg.completeness ? { verdict: pkg.completeness.verdict, scanStatus: pkg.completeness.scanStatus, conditions: pkg.completeness.conditions || [] } : { verdict: 'unknown', scanStatus: 'unknown', conditions: [] };
+  const unknowns = [];
+  if (completeness.verdict !== 'complete') for (const c of completeness.conditions.length ? completeness.conditions : ['the scan did not report that it finished']) unknowns.push({ about: 'scan completeness', reason: c, evidence: pkg.completeness && pkg.completeness.source ? [pkg.completeness.source] : [] });
+  for (const a of (pkg && pkg.assertions) || []) if (a.status !== 'supported') unknowns.push({ about: a.text, reason: a.reason || `the assertion is ${a.status}`, evidence: a.evidence || [] });
+  for (const f of findings) if (f.proofTier !== 'execution-proven') unknowns.push({ about: `exploitability of ${f.id}`, reason: `proof tier is ${f.proofTier}: it has not been shown to be exploitable`, evidence: [f.evidenceHash] });
+
+  const developer = findings.map((f) => ({ id: f.id, evidenceHash: f.evidenceHash, status: f.status, confidence: f.confidence, severity: f.severity, where: f.where, why: f.why, how: f.how, title: f.title, cwe: f.cwe, fix: f.fix }));
+  const verdict = releaseVerdict(pkg);
+  const ciso = {
+    verdict: { verdict: verdict.verdict, statement: verdict.statement, blockers: verdict.blockers.map((b) => b.message), unknowns: verdict.unknowns.map((u) => u.message) },
+    verified: verification ? verification.ok === true : null,
+    scan: completeness,
+    proven: { executionProven: tier('execution-proven'), taintProven: tier('taint-proven'), unproven: findings.length - tier('execution-proven') - tier('taint-proven'), total: findings.length },
+    bySeverity: Object.fromEntries(['critical', 'high', 'medium', 'low', 'info'].map((s) => [s, findings.filter((f) => f.severity === s).length])),
+    fixes: { verified: findings.filter((f) => f.status === 'fix-verified').length, unverified: findings.filter((f) => f.status === 'fix-unverified').length, open: findings.filter((f) => f.status === 'open').length },
+    changeSinceLast: change,
+    risk: ranking ? { byPriority: ranking.summary.byPriority, incompleteCoverage: ranking.summary.incompleteCoverage, top: ranking.ranked.slice(0, 5).map((r) => ({ id: r.id, priority: r.priority, rule: r.rule })) } : null,
+    findings: findings.map((f) => ({ id: f.id, evidenceHash: f.evidenceHash, status: f.status, confidence: f.confidence, severity: f.severity, proofTier: f.proofTier, priority: rankById && rankById.get(f.id) ? rankById.get(f.id).priority : null })),
+  };
+  const auditor = {
+    package: { lineageDigest: packageDigest, snapshot: pkg && pkg.snapshot ? { commit: pkg.snapshot.commit, immutable: pkg.snapshot.immutable, digest: pkg.snapshot.digest } : null },
+    issuer: pkg && pkg.issuance ? { trustBasis: pkg.issuance.trustBasis, independentlyCertified: pkg.issuance.independentlyCertified, keyFingerprint: pkg.issuance.issuer && pkg.issuance.issuer.keyFingerprint } : null,
+    verification: verification ? { ok: verification.ok === true, errors: (verification.errors || []).map((e) => `${e.code}: ${e.message}`) } : { ok: null, errors: ['no verification was performed by this view'] },
+    proves: pkg && pkg.proves || null, doesNotProve: pkg && pkg.doesNotProve || null,
+    assertions: ((pkg && pkg.assertions) || []).map((a) => ({ id: a.id, text: a.text, status: a.status, evidence: a.evidence || [], reason: a.reason || null })),
+    unknowns,
+    findings: findings.map((f) => ({ id: f.id, evidenceHash: f.evidenceHash, status: f.status, confidence: f.confidence, proofTier: f.proofTier, fixEvidence: f.fix ? f.fix.evidenceHash : null })),
+    policyDecisions: (pkg && pkg.policy && pkg.policy.decisions) || [],
+  };
+  return { canonical: findings, developer, ciso, auditor };
+}
+
+// ---- text ------------------------------------------------------------------------------------------------------------------------
+
+export function renderText(views, view = 'all') {
+  const L = [];
+  const dev = () => { L.push('DEVELOPER VIEW'); for (const f of views.developer) { L.push(`  [${f.severity}] ${f.title}  ${f.where.file ?? '?'}:${f.where.line ?? '?'}  id=${f.id}  status=${f.status}  confidence=${f.confidence}  evidence=${f.evidenceHash.slice(0, 19)}`); if (f.why) L.push(`      why: ${String(f.why).slice(0, 300)}`); if (f.how) L.push(`      fix: ${String(f.how).slice(0, 300)}`); if (f.fix) L.push(`      fix check: ${f.fix.verifiedFull ? 'verified' : 'not fully verified'}${f.fix.degradedLegs.length ? ` (not passed: ${f.fix.degradedLegs.join(', ')})` : ''}`); } if (!views.developer.length) L.push('  no findings'); };
+  const ciso = () => { const c = views.ciso; L.push('CISO VIEW'); L.push(`  release verdict: ${c.verdict.verdict}. ${c.verdict.statement}`); for (const b of c.verdict.blockers) L.push(`    blocks: ${b}`); for (const u of c.verdict.unknowns) L.push(`    unknown: ${u}`); L.push(`  scan: ${c.scan.verdict} (${c.scan.scanStatus})${c.scan.conditions.length ? ' - ' + c.scan.conditions.join('; ') : ''}`); L.push(`  proven: ${c.proven.executionProven} executed, ${c.proven.taintProven} taint path, ${c.proven.unproven} unproven, of ${c.proven.total}`); L.push(`  fixes: ${c.fixes.verified} verified, ${c.fixes.unverified} unverified, ${c.fixes.open} open`); if (c.changeSinceLast) L.push(`  since last release: ${c.changeSinceLast.new.length} new, ${c.changeSinceLast.resolved.length} resolved, ${c.changeSinceLast.statusChanged.length} changed status`); else L.push('  since last release: no previous release was supplied'); if (c.risk) L.push(`  risk: ${JSON.stringify(c.risk.byPriority)}; ${c.risk.incompleteCoverage} with incomplete coverage`); L.push(`  verification: ${c.verified === null ? 'not performed here' : c.verified ? 'signature and contents verified' : 'FAILED'}`); };
+  const aud = () => { const a = views.auditor; L.push('AUDITOR VIEW'); L.push(`  snapshot: ${a.package.snapshot ? `${a.package.snapshot.commit ?? 'no commit'} (${a.package.snapshot.immutable ? 'immutable' : 'NOT immutable'})` : 'none'}`); L.push(`  issuer: ${a.issuer ? `${a.issuer.trustBasis}, independently certified: ${a.issuer.independentlyCertified}` : 'none'}`); L.push(`  verification: ${a.verification.ok === null ? 'not performed here' : a.verification.ok ? 'ok' : 'FAILED: ' + a.verification.errors.join('; ')}`); for (const x of a.assertions) L.push(`  assertion ${x.id} [${x.status}]: ${x.text}  evidence=${x.evidence.map((d) => d.slice(0, 19)).join(',') || 'none'}`); for (const u of a.unknowns) L.push(`  unknown: ${u.about} - ${u.reason}`); L.push(`  does not prove: ${a.doesNotProve}`); };
+  if (view === 'developer' || view === 'all') dev();
+  if (view === 'ciso' || view === 'all') ciso();
+  if (view === 'auditor' || view === 'all') aud();
+  return L.join('\n') + '\n';
+}
+
+// ---- html ------------------------------------------------------------------------------------------------------------------------
+
+/** One self-contained page, no script, nothing loaded from elsewhere. Every value is escaped. */
+export function renderHtml(views, { title = 'Release assurance report' } = {}) {
+  const c = views.ciso; const a = views.auditor;
+  const row = (f, cols) => `<tr data-finding="${esc(f.id)}" data-evidence="${esc(f.evidenceHash)}" data-status="${esc(f.status)}" data-confidence="${esc(f.confidence)}">${cols.map((x) => `<td>${x}</td>`).join('')}</tr>`;
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src data:">
+<title>${esc(title)}</title>
+<style>
+:root{--bg:#fff;--fg:#1a1a1a;--muted:#555;--line:#d0d0d0;--bad:#a40000;--ok:#0a6b2b}
+@media (prefers-color-scheme: dark){:root{--bg:#14161a;--fg:#e8e8e8;--muted:#a0a0a0;--line:#3a3d44;--bad:#ff8080;--ok:#6fd48e}}
+body{background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,sans-serif;margin:0 auto;max-width:72rem;padding:1rem 16px}
+h1,h2{line-height:1.2}table{border-collapse:collapse;width:100%;overflow-wrap:anywhere}th,td{border:1px solid var(--line);padding:.35rem .5rem;text-align:left;vertical-align:top}
+code{font-family:ui-monospace,monospace;font-size:.9em}.muted{color:var(--muted)}.bad{color:var(--bad)}.ok{color:var(--ok)}details{margin:1rem 0}summary{cursor:pointer;font-weight:600}
+</style></head><body>
+<h1>${esc(title)}</h1>
+<p class="muted">Snapshot ${esc(a.package.snapshot ? a.package.snapshot.commit : 'none')} (${a.package.snapshot && a.package.snapshot.immutable ? 'immutable' : 'not immutable'}). Verification: <span class="${a.verification.ok === true ? 'ok' : 'bad'}">${esc(a.verification.ok === null ? 'not performed by this page' : a.verification.ok ? 'passed' : 'FAILED')}</span>.</p>
+<details open><summary>Developer: where, why, how to fix</summary>
+<table><thead><tr><th>Finding</th><th>Where</th><th>Why</th><th>How to fix</th><th>Status</th><th>Confidence</th></tr></thead><tbody>
+${views.developer.map((f) => row(f, [`<code>${esc(f.id)}</code> ${esc(f.title)}<br><span class="muted">${esc(f.severity)}${f.cwe ? ' ' + esc(f.cwe) : ''}</span>`, `<code>${esc(f.where.file ?? '?')}:${esc(f.where.line ?? '?')}</code>`, esc(f.why ?? ''), esc(f.how ?? ''), esc(f.status), esc(f.confidence)])).join('\n') || '<tr><td colspan="6">No findings.</td></tr>'}
+</tbody></table></details>
+<details open><summary>CISO: what is proven, what changed, risk and coverage</summary>
+<p><strong>Release verdict: ${esc(c.verdict.verdict)}.</strong> ${esc(c.verdict.statement)}</p>
+<ul>${c.verdict.blockers.map((b) => `<li class="bad">Blocks: ${esc(b)}</li>`).join('')}${c.verdict.unknowns.map((u) => `<li>Unknown: ${esc(u)}</li>`).join('')}</ul>
+<p>Scan: <strong>${esc(c.scan.verdict)}</strong> (${esc(c.scan.scanStatus)}). ${c.scan.conditions.map((x) => esc(x)).join('; ')}</p>
+<p>Proven: ${esc(c.proven.executionProven)} by execution, ${esc(c.proven.taintProven)} by a taint path, ${esc(c.proven.unproven)} unproven, of ${esc(c.proven.total)}. Fixes: ${esc(c.fixes.verified)} verified, ${esc(c.fixes.unverified)} unverified, ${esc(c.fixes.open)} open.</p>
+<p>${c.changeSinceLast ? `Since the previous release: ${esc(c.changeSinceLast.new.length)} new, ${esc(c.changeSinceLast.resolved.length)} resolved, ${esc(c.changeSinceLast.statusChanged.length)} changed status.` : 'No previous release was supplied, so no change is reported.'}</p>
+<table><thead><tr><th>Finding</th><th>Severity</th><th>Proof</th><th>Priority</th><th>Status</th><th>Confidence</th></tr></thead><tbody>
+${c.findings.map((f) => row(f, [`<code>${esc(f.id)}</code>`, esc(f.severity), esc(f.proofTier), esc(f.priority ?? 'not ranked'), esc(f.status), esc(f.confidence)])).join('\n') || '<tr><td colspan="6">No findings.</td></tr>'}
+</tbody></table></details>
+<details open><summary>Auditor: evidence behind each statement, and what is unknown</summary>
+<p>Issuer: ${esc(a.issuer ? a.issuer.trustBasis : 'none')}; independently certified: ${esc(a.issuer ? a.issuer.independentlyCertified : 'n/a')}.</p>
+<p class="muted">Proves: ${esc(a.proves)}<br>Does not prove: ${esc(a.doesNotProve)}</p>
+<table><thead><tr><th>Finding</th><th>Evidence hash</th><th>Fix evidence</th><th>Status</th><th>Confidence</th></tr></thead><tbody>
+${a.findings.map((f) => row(f, [`<code>${esc(f.id)}</code>`, `<code>${esc(f.evidenceHash)}</code>`, `<code>${esc(f.fixEvidence ?? 'none')}</code>`, esc(f.status), esc(f.confidence)])).join('\n') || '<tr><td colspan="5">No findings.</td></tr>'}
+</tbody></table>
+<h2>Assertions</h2><ul>${a.assertions.map((x) => `<li><strong>${esc(x.status)}</strong>: ${esc(x.text)} <span class="muted">(${x.evidence.length ? x.evidence.map((d) => `<code>${esc(d)}</code>`).join(', ') : 'no evidence cited'}${x.reason ? '; ' + esc(x.reason) : ''})</span></li>`).join('') || '<li>None.</li>'}</ul>
+<h2>Unknowns</h2><ul>${a.unknowns.map((u) => `<li>${esc(u.about)}: ${esc(u.reason)}</li>`).join('') || '<li>None.</li>'}</ul>
+</details></body></html>
+`;
+}

package/src/sast/_comment-strip.js

@@ -1,3 +1,5 @@
+import { createStringMemo } from '../util/string-memo.js';
+
 // Replace comments with same-length whitespace (newlines preserved) so that
 // character indices in the returned string match the original source one-to-one.
 // Required by detectors that emit `line = lineOf(raw, m.index)` after running
@@ -37,7 +39,7 @@
 // and only the comment runs (a small minority of any real file) are rewritten,
 // via a native regex for the newline-preserving cases. Characters are scanned;
 // they are no longer individually concatenated.
-export function blankComments(s, lang) {
+function blankCommentsUncached(s, lang) {
   const parts = [];
   let verbatimFrom = 0;   // start of the run of input not yet emitted as-is
   let inS = null;
@@ -122,3 +124,8 @@ export function blankComments(s, lang) {
   if (verbatimFrom < s.length) parts.push(s.slice(verbatimFrom));
   return parts.join('');
 }
+
+// Every detector that wants a comment-free view of a file asks for it again; the engine alone asks about fifteen times per file. The output depends
+// only on (text, lang), so it is computed once per distinct pair. AGENTIC_SECURITY_NO_STRING_MEMO=1 turns the memo off (used to measure it).
+export const blankComments = createStringMemo((s, lang) => blankCommentsUncached(s, lang === '' ? undefined : lang), { version: 'blankComments@1', disableEnv: 'AGENTIC_SECURITY_NO_STRING_MEMO' });
+export const _blankCommentsUncached = blankCommentsUncached;

package/src/sast/ruby.js

@@ -208,6 +208,28 @@ function _splitArgs(s) {
   return out;
 }
 
+const RB_PATH_METHOD = /(?:^|_)(?:path|file|filename|filepath|dir|folder)s?(?:_for|_of)?\??$|^path_for$/;
+const RB_TAIL_CLOSERS = /^(?:end|else|elsif|rescue|ensure|when|in)\b/;
+/** Is the File.join call at [start, end) the returned value of a method whose name says it resolves a path? */
+function _returnedFromPathResolver(code, start, end) {
+  let name = null; let params = '';
+  for (const dm of code.slice(0, start).matchAll(/^[ \t]*def[ \t]+(?:self\.)?([A-Za-z_][\w]*[?!]?)[ \t]*(?:\(([^)\n]*)\)|([^\n]*))/gm)) { name = dm[1]; params = dm[2] ?? dm[3] ?? ''; }
+  if (!name || !RB_PATH_METHOD.test(name)) return false;
+  // the value the caller controls must come in through the method's own parameters: the last component is a parameter (or the first name bound from one)
+  const paramNames = new Set(params.split(',').map((x) => x.trim().replace(/^[*&]+/, '').replace(/[:=].*$/, '').trim()).filter((x) => /^[A-Za-z_]\w*$/.test(x)));
+  const lastArg = _splitArgs(code.slice(start, end).replace(/^[^(]*\(/, '').replace(/\)$/, '')).pop() || '';
+  const lastName = (lastArg.trim().match(/^[A-Za-z_]\w*/) || [''])[0];
+  if (!paramNames.has(lastName)) return false;
+  const lineStart = code.lastIndexOf('\n', start - 1) + 1;
+  const head = code.slice(lineStart, start);
+  if (!/^[ \t]*(?:return[ \t]+)?$/.test(head)) return false;            // the join begins its own statement
+  const lineEnd = code.indexOf('\n', end) < 0 ? code.length : code.indexOf('\n', end);
+  if (code.slice(end, lineEnd).trim() !== '') return false;               // nothing chained onto it
+  if (/return[ \t]+$/.test(head)) return true;
+  const next = code.slice(lineEnd).split('\n').map((l) => l.trim()).find((l) => l !== '');
+  return next === undefined || RB_TAIL_CLOSERS.test(next);                // last expression of its branch or method
+}
+
 /** File.join(...) whose last component is variable and which reaches the filesystem. */
 export function scanRubyPathJoin(fp, raw) {
   if (!/\.rb$/i.test(fp)) return [];
@@ -250,6 +272,10 @@ export function scanRubyPathJoin(fp, raw) {
         reaches = RB_FS_OP.test(after) && use.test(after);
       }
     }
+    // A path RESOLVER hands its result to a caller (`def path_for(key); File.join(root, tenant, key); end`, the Active Storage disk service shape of
+    // basecamp/activerecord-tenanted, GHSA-pmwx-rm49-xv39). Nothing in the file touches the filesystem with it, because the caller does. It counts as reaching the
+    // filesystem only when BOTH hold: the enclosing method is named for a path, and the join is the value that method returns.
+    if (!reaches && !/(?:^|\/)(?:spec|test|tests)\/|_(?:spec|test)\.rb$/.test(fp) && _returnedFromPathResolver(code, m.index, i)) reaches = true;
     if (!reaches) continue;
 
     // Containment guard anywhere in the enclosing window — that IS the fix.

package/src/sast/zip-slip.js

@@ -38,12 +38,91 @@ import { blankComments } from './_comment-strip.js';
 
 function _lineOf(raw, idx) { return raw.substring(0, idx).split('\n').length; }
 
+// Go (archive/zip, archive/tar). The entry name comes from the archive, so `filepath.Join(dest, f.Name)` is attacker-chosen unless the joined path is checked
+// against `dest`. The check is looked for in the SAME FUNCTION as the use, and it must name the joined path (or the entry name), because a `HasPrefix` on some
+// other value in the same function proves nothing about this one.
+const GO_ARCHIVE_IMPORT_RE = /["`](?:archive\/(?:zip|tar)|github\.com\/(?:klauspost\/compress\/zip|mholt\/archiver(?:\/v\d+)?|mholt\/archives|bodgit\/sevenzip|nwaples\/rardecode(?:\/v\d+)?))["`]/;
+const GO_ZIP_RANGE_RE = /\bfor\s+(?:\w+\s*,\s*)?(\w+)\s*:=\s*range\s+[\w.()]+?\.File\b/g;
+const GO_TAR_NEXT_RE = /\b(\w+)\s*,\s*\w+\s*:?=\s*[\w.]+\.Next\s*\(\s*\)/g;
+const GO_WRITE_SINKS = 'os\\.(?:Create|OpenFile|MkdirAll|Mkdir|WriteFile|Rename|Symlink|Link|Chmod|Remove|RemoveAll)|ioutil\\.WriteFile|afero\\.WriteFile|fs\\.(?:Create|OpenFile|MkdirAll|WriteFile)';
+const GO_GUARD_CALL_RE = /\b(?:strings\.HasPrefix|filepath\.IsLocal|filepath\.Rel|filepath\.IsAbs|securejoin\.SecureJoin|SecureJoin|os\.OpenRoot|OpenInRoot)\s*\(|\bstrings\.Contains\s*\([^)]*[\"`]\.\.[\"`]/;
+
+/** The text of the Go function around `idx`, by brace matching from the nearest preceding `func`. */
+function _goFunctionAround(code, idx) {
+  const start = code.lastIndexOf('\nfunc ', idx);
+  const from = start === -1 ? 0 : start + 1;
+  const open = code.indexOf('{', from);
+  if (open === -1 || open > idx) return code.slice(from, Math.min(code.length, idx + 2000));
+  let depth = 0; let inS = null;
+  for (let i = open; i < code.length; i++) {
+    const c = code[i];
+    if (inS) { if (c === '\\' && inS !== '`') { i++; continue; } if (c === inS) inS = null; continue; }
+    if (c === '"' || c === '`') { inS = c; continue; }
+    if (c === "'") { const e = code.indexOf("'", i + 2); if (e !== -1 && e - i <= 4) { i = e; continue; } }
+    if (c === '{') depth++;
+    else if (c === '}') { depth--; if (depth === 0) return code.slice(from, i + 1); }
+  }
+  return code.slice(from);
+}
+
+function _scanGoArchive(fp, raw, push) {
+  const code = blankComments(raw);
+  if (!GO_ARCHIVE_IMPORT_RE.test(code)) return;
+  // the names that hold an archive entry: `for _, f := range r.File`, `hdr, err := tr.Next()`
+  const entries = new Set();
+  for (const re of [GO_ZIP_RANGE_RE, GO_TAR_NEXT_RE]) { const r = new RegExp(re.source, re.flags); let m; while ((m = r.exec(code))) entries.add(m[1]); }
+  if (!entries.size) return;
+  const ent = `(?:${[...entries].map((e) => e.replace(/[$]/g, '\\$')).join('|')})`;
+  const nameRef = `${ent}\\s*\\.\\s*Name\\b`;
+  // a path built from the entry name: filepath.Join(x, f.Name) / path.Join / dest + "/" + f.Name
+  const builtRe = new RegExp(`(\\w+)\\s*:?=\\s*(?:(?:filepath|path)\\.(?:Join|Clean)\\s*\\([^\\n]*?${nameRef}[^\\n]*\\)|[^\\n]*?\\+\\s*${nameRef}[^\\n]*|[^\\n]*?${nameRef}\\s*\\+[^\\n]*)`, 'g');
+  const sinkRe = new RegExp(`\\b(?:${GO_WRITE_SINKS})\\s*\\(([^\\n]*)`, 'g');
+  const lineOfIdx = (i) => _lineOf(raw, i);
+  const flag = (idx, how) => {
+    const line = lineOfIdx(idx);
+    push({
+      id: `zip-slip:${fp}:${line}:go`, file: fp, line,
+      vuln: `Zip Slip: an archive entry name reaches a file operation (${how}) without a check that the result stays inside the extraction directory`,
+      severity: 'high', cwe: 'CWE-22', stride: 'Tampering',
+      snippet: (raw.split('\n')[line - 1] || '').trim().slice(0, 200),
+      remediation: 'An archive entry may be named `../../x` or be absolute. After joining, clean the path and refuse it unless it is inside the destination: `target := filepath.Join(dest, f.Name); if !strings.HasPrefix(target, filepath.Clean(dest)+string(os.PathSeparator)) { return error }` (or `filepath.IsLocal(f.Name)` on Go 1.20+, or `os.Root` on Go 1.24+).',
+      confidence: 0.8, parser: 'ZIP-SLIP',
+    });
+  };
+  const handled = new Set();
+  // 1) a variable built from the entry name, then used by a write
+  let b;
+  while ((b = builtRe.exec(code))) {
+    const v = b[1];
+    const fn = _goFunctionAround(code, b.index);
+    const fnStart = code.indexOf(fn);
+    // is the variable checked in this function? a guard call must mention it (or the entry name)
+    const mention = new RegExp(`\\b${v}\\b|${nameRef}`);
+    const guarded = fn.split('\n').some((l) => GO_GUARD_CALL_RE.test(l) && mention.test(l));
+    if (guarded) { handled.add(b.index); continue; }
+    const useRe = new RegExp(`\\b(?:${GO_WRITE_SINKS})\\s*\\([^\\n]*\\b${v}\\b`, 'g');
+    useRe.lastIndex = 0;
+    const use = useRe.exec(fn);
+    if (use) { handled.add(b.index); flag(fnStart + use.index, 'built from the entry name'); }
+  }
+  // 2) the entry name used directly in a write
+  let s;
+  while ((s = sinkRe.exec(code))) {
+    if (!new RegExp(nameRef).test(s[1])) continue;
+    const fn = _goFunctionAround(code, s.index);
+    const guarded = fn.split('\n').some((l) => GO_GUARD_CALL_RE.test(l) && new RegExp(nameRef).test(l));
+    if (!guarded) flag(s.index, 'the entry name itself');
+  }
+}
+
 export function scanZipSlip(fp, raw) {
   if (!raw || raw.length > 500_000) return [];
   const findings = [];
   const seen = new Set();
   const push = (f) => { if (!seen.has(f.id)) { seen.add(f.id); findings.push(f); } };
 
+  if (/\.go$/i.test(fp) && !/_test\.go$/i.test(fp)) _scanGoArchive(fp, raw, push);
+
   if (/\.(?:java|kt|kts|scala|groovy)$/i.test(fp)) {
     const code = blankComments(raw);
     // File-wide suppression: canonical path + startsWith pair present

package/src/util/string-memo.js

@@ -0,0 +1,38 @@
+// A small, bounded memo for pure functions of (source text, tag) (E6-03).
+//
+// Profiling a deep scan (see docs/engineering-excellence/PARSE_REUSE.md) showed the same source text being comment-blanked and string-stripped again
+// by every detector that wants a clean view of it: `blankComments` alone was 7% of scan CPU, called about fifteen times per file. The function is
+// pure (same text and language, same output), so the output is computed once per distinct text and reused.
+//
+// BOUNDED: at most `maxEntries` entries and `maxChars` characters of retained output; the least recently used entry is dropped first. A text longer
+// than `maxChars / 4` is not cached at all, so one huge file cannot evict everything else or hold memory.
+// VERSIONED: the cache key includes `version`, so a change to the function that forgets to be reflected in the memo cannot serve stale output
+// after the version is bumped. It is also off when the named environment variable is "1", which is how the measurement compares with and without.
+// CORRECT BY CONSTRUCTION ONLY IF THE FUNCTION IS PURE and its result is never mutated: strings are immutable in JavaScript, and a test checks the
+// memoized output equals the direct output over many inputs.
+export function createStringMemo(fn, { version, maxEntries = 64, maxChars = 24_000_000, disableEnv = null } = {}) {
+  // text -> { size, byTag: Map<tag, output> }; insertion order is recency order (a hit re-inserts)
+  const bySrc = new Map();
+  let chars = 0; let hits = 0; let misses = 0; let skipped = 0;
+  const evict = () => {
+    while (bySrc.size > maxEntries || chars > maxChars) {
+      const oldest = bySrc.keys().next();
+      if (oldest.done) break;
+      chars -= bySrc.get(oldest.value).size; bySrc.delete(oldest.value);
+    }
+  };
+  const memo = function memoized(src, tag = '') {
+    if (typeof src !== 'string' || (disableEnv && process.env[disableEnv] === '1') || src.length > maxChars / 4) { skipped++; return fn(src, tag); }
+    let e = bySrc.get(src);
+    if (e) { bySrc.delete(src); bySrc.set(src, e); if (e.byTag.has(tag)) { hits++; return e.byTag.get(tag); } }
+    misses++;
+    const out = fn(src, tag);
+    if (!e) { e = { size: src.length, byTag: new Map() }; bySrc.set(src, e); chars += src.length; }
+    e.byTag.set(tag, out); e.size += out.length; chars += out.length;
+    evict();
+    return out;
+  };
+  memo.stats = () => ({ version, entries: bySrc.size, chars, hits, misses, skipped });
+  memo.reset = () => { bySrc.clear(); chars = 0; hits = 0; misses = 0; skipped = 0; };
+  return memo;
+}