@clear-capabilities/agentic-security-scanner 0.142.0 → 0.144.0

package/src/posture/privacy-framework.js

@@ -36,6 +36,7 @@
 
 import { loadFramework, evaluateFramework } from './auditor-walkthrough.js';
 import { statePath, safeWriteState } from './state-dir.js';
+import { EVIDENCE_GRADE_DISCLAIMER_SHORT } from './evidence-grade-wording.js';
 
 export const PRIVACY_FRAMEWORK_ID = 'nist-privacy-1-1';
 
@@ -118,6 +119,24 @@ function severityFor(controlId) {
  * Returns `{ frameworkId, controls[], summary, findings[] }`. Never throws:
  * posture modules degrade to a null result rather than failing a scan.
  */
+// FR-405 (assurance-hardening PRD): controls whose ENTIRE mapping depends on
+// privacy-taint's signal — a "clean" (present) result from a NON-IR-backed
+// run (deep mode off, the default path) is not real evidence for these
+// specifically, even when the scan otherwise examined real files and is
+// `assessable` for every other control. Deliberately conservative: a control
+// with an ADDITIONAL, independent mapping (e.g. CT.DP-P1's `family:data-
+// exposure` alongside `family:pii-exposure`) is left alone, because that
+// other signal may still be real and this module cannot attribute which
+// specific mapping produced a "present" verdict. Confirmed by direct
+// execution against this exact framework file that CT.DP-P4/CT.DP-P5 (both
+// codeTestable:'yes', both mapped ONLY to `module:privacy-taint`) currently
+// read `satisfied` from a run with zero real IR-backed analysis — see
+// decisions.md for the reproduction.
+function _isPurelyPrivacyTaintDependent(control) {
+  const mapsTo = Array.isArray(control?.mapsTo) ? control.mapsTo : [];
+  return mapsTo.length > 0 && mapsTo.every(m => m === 'module:privacy-taint' || m === 'family:pii-exposure');
+}
+
 export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
   const fw = loadFramework(scanRoot, PRIVACY_FRAMEWORK_ID);
   if (!fw) return null;
@@ -131,6 +150,9 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
   const assessable = filesScanned > 0
     || (Array.isArray(scan?.findings) && scan.findings.length > 0)
     || (Array.isArray(scan?.components) && scan.components.length > 0);
+  // `null` (never ran) and `false` (ran but degraded) are both "not real
+  // IR-backed evidence" for the gate below; only `true` clears it.
+  const privacyIrBacked = scan?.privacyIrBacked === true;
 
   const controls = [];
   const findings = [];
@@ -138,7 +160,9 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
 
   for (const r of evaluation) {
     const c = r.control || {};
-    const bucket = bucketOf(r, { assessable });
+    const privacyTaintGated = !privacyIrBacked && _isPurelyPrivacyTaintDependent(c);
+    const controlAssessable = assessable && !privacyTaintGated;
+    const bucket = bucketOf(r, { assessable: controlAssessable });
     summary[bucket] += 1;
     summary.total += 1;
 
@@ -153,9 +177,11 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
     };
     if (bucket === 'engine-gap') {
       // Named, not counted as a pass. See the header.
-      row.disclosure = (Array.isArray(c.mapsTo) && c.mapsTo.length && !assessable)
-        ? 'This control is mapped, but the scan examined no files — a clean signal from a run that read nothing is not evidence. NOT assessed.'
-        : `NIST rates this control code-testable (${row.codeTestable}), but this engine has no signal for it. It was NOT assessed.`;
+      row.disclosure = privacyTaintGated
+        ? 'This control depends entirely on privacy-taint\'s signal, which ran without a real IR this scan (deep mode off, or an unsupported language) — a "no findings" result in that mode is not real evidence. NOT assessed.'
+        : (Array.isArray(c.mapsTo) && c.mapsTo.length && !assessable)
+          ? 'This control is mapped, but the scan examined no files — a clean signal from a run that read nothing is not evidence. NOT assessed.'
+          : `NIST rates this control code-testable (${row.codeTestable}), but this engine has no signal for it. It was NOT assessed.`;
     }
     if (bucket === 'manual') {
       row.disclosure = 'NIST rates this control not code-testable — it is a governance, policy, or process control and is outside any scanner\'s reach.';
@@ -228,8 +254,9 @@ function renderPrivacyMarkdown(result) {
   L.push(`| Satisfied | ${result.summary.satisfied} | Mapped, and the signal is clean |`);
   L.push('');
   L.push('> A control in *Not assessed* or *Manual* is not evidence of compliance.');
-  L.push('> This document organizes scanner evidence; it does not certify anything.');
-  L.push('> A licensed assessor is responsible for the attestation.');
+  // FR-507: sourced from evidence-grade-wording.js so this artifact stays in
+  // sync with every other compliance-adjacent disclaimer in the codebase.
+  L.push(`> ${EVIDENCE_GRADE_DISCLAIMER_SHORT}`);
   L.push('');
   for (const bucket of BUCKETS) {
     const rows = result.controls.filter(c => c.bucket === bucket);

package/src/posture/production-feedback.js

@@ -0,0 +1,179 @@
+// FR-907 (assurance-hardening PRD): "Add longitudinal production feedback
+// measurement | Metrics separate user suppression, accepted risk, invalid
+// finding, fixed finding, and verification outcome."
+//
+// Read-only aggregation over 5 ALREADY-BUILT, separate mechanisms — this
+// module invents no new storage of its own, only a unified view:
+//
+//   user-suppression     -> triage-memory.jsonl (decision:'wont-fix'),
+//                            accepted.json (vibecoder soft-accept, dated),
+//                            suppressions.yml (pro exception, undated)
+//   invalid-finding       -> triage-memory.jsonl (decision:'false-positive')
+//   accepted-risk         -> sca-policy.yml's accept-risk[] (undated snapshot
+//                            — the policy file has no per-entry creation
+//                            timestamp, only an optional future `expires`)
+//   fixed-finding          -> fix-history/log.json (dated via `appliedAt`,
+//                            status-tagged: applied/pending/reverted/failed)
+//   verification-outcome  -> fix-metrics.jsonl (dated via `at`, ok-tagged)
+//
+// "Longitudinal" means: every event that HAS a real timestamp is usable in
+// a time-bucketed trend; every event that does NOT (accept-risk entries,
+// pro suppressions — neither schema records when the entry was added) is
+// still counted in its category total but reported separately as
+// "undated" rather than silently smeared across the time window or
+// silently dropped. Same disclosed-gap discipline this codebase already
+// uses elsewhere (privacy-framework.js's engine-gap bucket, accuracy-
+// scorecard.js's excluded-from-denominator entries) — a number without
+// its caveat is not a measurement.
+//
+// Never throws (posture convention): each of the 5 reads is wrapped
+// independently, so a missing or malformed source degrades only that ONE
+// category to empty, never blocks the other four. Every underlying reader
+// (loadSoftAccepted, loadProSuppressions, loadMemory, loadScaPolicy,
+// readLog, loadFixAttempts) already degrades gracefully on its own; the
+// wrapping here is defense in depth against a reader whose contract
+// changes later, not a claim that today's readers can throw.
+
+import { loadSoftAccepted, loadProSuppressions } from './suppressions.js';
+import { loadMemory } from './triage-memory.js';
+import { loadScaPolicy } from './sca-policy.js';
+import { readLog } from './fix-history.js';
+import { loadFixAttempts } from './fix-metrics.js';
+
+const MS_PER_DAY = 86400000;
+
+// The 5 categories named verbatim in FR-907's own acceptance criterion.
+export const CATEGORIES = Object.freeze([
+  'user-suppression', 'accepted-risk', 'invalid-finding', 'fixed-finding', 'verification-outcome',
+]);
+
+function _safe(fn) {
+  try { return fn(); } catch { return []; }
+}
+
+/**
+ * One unified event per underlying record, tagged with which of the 5
+ * PRD-named categories it belongs to. `at` is an ISO timestamp or null
+ * when the source schema has no per-entry creation date. `raw` keeps the
+ * original record for drill-down — never re-derived from the unified
+ * shape, so nothing is lost in translation.
+ */
+export function collectFeedbackEvents(scanRoot) {
+  const events = [];
+
+  for (const e of _safe(() => loadSoftAccepted(scanRoot))) {
+    events.push({
+      category: 'user-suppression', source: 'suppressions.js:accepted.json',
+      at: e.accepted_at || null, findingId: e.id || null, file: e.file || null,
+      line: e.line ?? null, outcome: 'soft-accepted', raw: e,
+    });
+  }
+  for (const e of _safe(() => loadProSuppressions(scanRoot))) {
+    events.push({
+      category: 'user-suppression', source: 'suppressions.js:suppressions.yml',
+      at: null, findingId: e.finding_id || null, file: e.file || null,
+      line: null, outcome: 'pro-exception', raw: e,
+    });
+  }
+  for (const e of _safe(() => loadMemory(scanRoot))) {
+    if (e.decision === 'wont-fix') {
+      events.push({
+        category: 'user-suppression', source: 'triage-memory.js',
+        at: e.at || null, findingId: e.id || null, file: e.file || null,
+        line: e.line ?? null, outcome: 'wont-fix', raw: e,
+      });
+    } else if (e.decision === 'false-positive') {
+      events.push({
+        category: 'invalid-finding', source: 'triage-memory.js',
+        at: e.at || null, findingId: e.id || null, file: e.file || null,
+        line: e.line ?? null, outcome: 'false-positive', raw: e,
+      });
+    }
+  }
+  const scaPolicy = _safe(() => loadScaPolicy(scanRoot));
+  const acceptRisk = scaPolicy && Array.isArray(scaPolicy.acceptRisk) ? scaPolicy.acceptRisk : [];
+  for (const e of acceptRisk) {
+    events.push({
+      category: 'accepted-risk', source: 'sca-policy.js',
+      at: null, findingId: e.cve || e.package || null, file: null,
+      line: null, outcome: 'accept-risk', raw: e,
+    });
+  }
+  for (const e of _safe(() => readLog(scanRoot))) {
+    events.push({
+      category: 'fixed-finding', source: 'fix-history.js',
+      at: e.appliedAt || null, findingId: e.findingId || e.stableId || null,
+      file: e.file || null, line: null, outcome: e.status || 'unknown', raw: e,
+    });
+  }
+  for (const e of _safe(() => loadFixAttempts(scanRoot))) {
+    events.push({
+      category: 'verification-outcome', source: 'fix-metrics.js',
+      at: e.at || null, findingId: e.stableId || null, file: null,
+      line: null, outcome: e.ok ? 'verified' : 'not-verified', raw: e,
+    });
+  }
+
+  return events;
+}
+
+/**
+ * Bucket events by day within a rolling `sinceDays`-day window — the same
+ * cutoff-window shape as posture/triage.js's own trend(). An event with no
+ * timestamp (or an unparseable one) cannot be placed on a time axis: it is
+ * counted once in `undated` per category rather than silently dropped or
+ * silently smeared into the window.
+ */
+export function summarizeFeedbackTrend(events, { sinceDays = 30, now = Date.now() } = {}) {
+  const cutoff = now - sinceDays * MS_PER_DAY;
+  const byCategory = {};
+  for (const cat of CATEGORIES) byCategory[cat] = { total: 0, inWindow: 0, undated: 0 };
+
+  const dayBuckets = new Map(); // 'YYYY-MM-DD' -> { category: count }
+  for (const ev of Array.isArray(events) ? events : []) {
+    if (!ev || !CATEGORIES.includes(ev.category)) continue;
+    byCategory[ev.category].total++;
+    const t = ev.at ? Date.parse(ev.at) : NaN;
+    if (!Number.isFinite(t)) { byCategory[ev.category].undated++; continue; }
+    if (t < cutoff) continue;
+    byCategory[ev.category].inWindow++;
+    const dayKey = new Date(t).toISOString().slice(0, 10);
+    if (!dayBuckets.has(dayKey)) dayBuckets.set(dayKey, {});
+    const bucket = dayBuckets.get(dayKey);
+    bucket[ev.category] = (bucket[ev.category] || 0) + 1;
+  }
+
+  const series = [...dayBuckets.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([day, counts]) => ({ day, counts }));
+  return { sinceDays, byCategory, series };
+}
+
+/**
+ * Convenience wrapper: collect + summarize in one call — same pattern as
+ * fix-metrics.js's fixDurationReport(scanRoot).
+ */
+export function productionFeedbackReport(scanRoot, opts) {
+  const events = collectFeedbackEvents(scanRoot);
+  return { events, ...summarizeFeedbackTrend(events, opts) };
+}
+
+/**
+ * One block of human-readable summary, or null when nothing was measured
+ * at all — same "null when nothing measured" contract as
+ * renderFixDurationSummary, so a caller can skip the section entirely
+ * rather than print an empty header.
+ */
+export function renderProductionFeedbackSummary(report) {
+  if (!report || !Array.isArray(report.events) || !report.events.length) return null;
+  const lines = [`Production feedback (last ${report.sinceDays}d):`];
+  for (const cat of CATEGORIES) {
+    const c = report.byCategory[cat];
+    if (!c || c.total === 0) continue;
+    const undatedNote = c.undated ? `, ${c.undated} undated` : '';
+    lines.push(`  ${cat}: ${c.inWindow} in window / ${c.total} total${undatedNote}`);
+  }
+  return lines.length > 1 ? lines.join('\n') : null;
+}
+
+export const _internals = { MS_PER_DAY };

package/src/posture/retention-policy.js

@@ -0,0 +1,132 @@
+// Retention policy: default and maximum TTL by artifact class (assurance-
+// hardening PRD FR-702).
+//
+// "Enforce default and maximum TTL by artifact class | Expired caches,
+// scans, evidence, tickets, and backups are purged or archived according
+// to policy."
+//
+// TWO NUMBERS PER CLASS, ON PURPOSE
+// --------------------------------------------------------------------------
+// `defaultDays` is what applies when nobody configures anything — a
+// reasonable, disclosed starting point, not a regulatory citation (an
+// operator with a real compliance regime should configure their own via
+// the policy file below). `maxDays` is a CEILING an operator's own
+// configuration cannot exceed: the literal "default AND maximum" wording
+// asks for both a floor-free default and a hard cap, not just a knob. An
+// operator who wants indefinite retention for `evidence` for their own
+// audit reasons should say so in their own retention program — this
+// module will not silently allow a TTL past its built-in ceiling for a
+// class, because "TTL" than can be configured to "never" is not a TTL.
+//
+// PURGE, NOT ARCHIVE
+// --------------------------------------------------------------------------
+// The acceptance criterion allows either. This implements PURGE (delete)
+// only — the simpler, safer, and more directly verifiable of the two.
+// "Archive" implies a defined export format and destination, which is
+// FR-706's own separate scope (manifest-based export); an operator who
+// wants to archive before purging already has the tool for it once FR-706
+// exists, or can back up `.agentic-security/` by their own means before
+// running the enforcement command.
+//
+// WHICH ARTIFACTS THIS APPLIES TO
+// --------------------------------------------------------------------------
+// Only 'generated' artifacts carrying a `retentionClass` in
+// artifact-registry.js — deliberately a SUBSET of all generated artifacts
+// (see that module's own header for which ones were left classless and
+// why). An 'operator-config' artifact is NEVER touched by this module,
+// regardless of age, matching FR-703's own "reset preserves operator-
+// authored configuration" precedent.
+
+import * as fs from 'node:fs';
+import * as yaml from '../util/yaml.js';
+import { statePath, stateDir } from './state-dir.js';
+import { listArtifactsWithRetentionClass } from './artifact-registry.js';
+import { loadLegalHolds, isUnderHold } from './legal-hold.js';
+
+const POLICY_FILE = 'retention-policy.yml';
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// Engineering defaults, not a regulatory claim — see the header above.
+export const RETENTION_DEFAULTS = {
+  cache: { defaultDays: 7, maxDays: 30 },
+  scan: { defaultDays: 90, maxDays: 365 },
+  evidence: { defaultDays: 365, maxDays: 1095 },
+  ticket: { defaultDays: 180, maxDays: 730 },
+  backup: { defaultDays: 30, maxDays: 180 },
+};
+
+/**
+ * Load an operator's `.agentic-security/retention-policy.yml`. Never
+ * throws — a missing or malformed file degrades to "no overrides," the
+ * same no-op-until-configured convention this repo uses for every other
+ * policy surface. Shape:
+ *   cache: { defaultDays: 3 }
+ *   evidence: { defaultDays: 730 }
+ * A class not mentioned, or a file not present at all, uses
+ * RETENTION_DEFAULTS unmodified.
+ */
+export function loadRetentionPolicy(scanRoot) {
+  if (!scanRoot) return null;
+  let fp;
+  try { fp = statePath(scanRoot, POLICY_FILE); } catch { return null; }
+  let raw;
+  try { raw = fs.readFileSync(fp, 'utf8'); } catch { return null; }
+  try {
+    const doc = yaml.load(raw);
+    if (!doc || typeof doc !== 'object') return null;
+    return doc;
+  } catch { return null; }
+}
+
+/**
+ * The TTL (in days) actually in effect for a class, after applying any
+ * operator override and clamping it to the class's own maxDays — an
+ * override CANNOT raise retention past the ceiling, only lower it (or
+ * leave it at the default). An unrecognised class (should not happen —
+ * only artifact-registry.js's own 5 named classes are ever passed in)
+ * degrades to null, meaning "not subject to a TTL."
+ */
+export function effectiveTtlDays(retentionClass, policy) {
+  const bounds = RETENTION_DEFAULTS[retentionClass];
+  if (!bounds) return null;
+  const override = policy?.[retentionClass]?.defaultDays;
+  if (typeof override === 'number' && Number.isFinite(override) && override >= 0) {
+    return Math.min(override, bounds.maxDays);
+  }
+  return bounds.defaultDays;
+}
+
+/**
+ * Which registered, retention-classed artifacts under `scanRoot`'s state
+ * dir are currently past their effective TTL. Never throws — a missing
+ * state dir or an artifact that does not exist on disk is simply absent
+ * from the result, not an error.
+ *
+ * @returns {Array<{name: string, isDir: boolean, retentionClass: string,
+ *   ageDays: number, ttlDays: number}>}
+ */
+export function findExpiredArtifacts(scanRoot, { now = Date.now() } = {}) {
+  const dir = stateDir(scanRoot);
+  let dirExists = true;
+  try { fs.accessSync(dir); } catch { dirExists = false; }
+  if (!dirExists) return [];
+  const policy = loadRetentionPolicy(scanRoot);
+  // FR-707: an artifact under an active legal hold is NEVER reported as
+  // expired, regardless of TTL — checked here (not just in cmdReset) so
+  // any future caller of this function inherits the same guarantee.
+  const holds = loadLegalHolds(scanRoot);
+  const expired = [];
+  for (const artifact of listArtifactsWithRetentionClass()) {
+    const ttlDays = effectiveTtlDays(artifact.retentionClass, policy);
+    if (ttlDays === null) continue;
+    if (isUnderHold(artifact.name, holds, now)) continue;
+    const p = `${dir}/${artifact.name}`;
+    let st;
+    try { st = fs.statSync(p); } catch { continue; } // not present — nothing to expire
+    const ageDays = (now - st.mtimeMs) / MS_PER_DAY;
+    if (ageDays > ttlDays) {
+      expired.push({ name: artifact.name, isDir: st.isDirectory(), retentionClass: artifact.retentionClass, ageDays, ttlDays });
+    }
+  }
+  return expired;
+}