@clear-capabilities/agentic-security-scanner 0.148.1 → 0.148.4

package/CHANGELOG.md

@@ -10,6 +10,124 @@
 
 
 
+## 0.148.4 - Adversarial premortem re-run on the 0.148.2/0.148.3 --assurance strict fix: two real defects found and fixed
+
+0.148.2's fix for a confusing `--assurance strict` failure was itself put through an adversarial
+premortem rather than trusted on its own say-so, the same discipline applied to the compliance-
+framework work earlier. It found the message-building logic held up in the common single-reason
+case, but had two real defects when a scan had more than one kind of provenance problem at once —
+which, on a real project, is not an edge case.
+
+1. **Multiple concurrent reasons silently collapsed to one.** A non-git directory with an
+   unpinned dependency produces BOTH a `'not a Git repository'` reason (every SAST/secrets/logic
+   finding) AND a `'origin resolution does not apply to...'` reason (the unpinned-dependency SCA
+   finding) on the very same scan — not hypothetically; `engine.js`'s two SCA populations that get
+   real git-history resolution are filtered to `type === 'vulnerable_dep'` only, so `unpinned_dep`/
+   `no_lockfile` never pass through the git-repo check at all. The message-building code picked
+   whichever reason had the most findings and silently dropped the other, so a user could fix the
+   reported problem (initialize git), rerun, and hit a second wall the tool had full information
+   about on the very first run but never mentioned — a milder recurrence of the exact "the tool
+   knew and didn't tell me" complaint the original fix existed to close. `_provenanceFailureReason`
+   (`scanner/src/pipeline/assurance-mode.js`) now reports every real category present, not just the
+   largest one.
+
+2. **Two structurally different SCA gaps were given the same, wrong advice.** `unpinned_dep`/
+   `no_lockfile` genuinely have no origin commit to resolve (they describe an absent declaration) —
+   correctly labeled a permanent, by-design limitation. But `cdn_no_integrity`/`dynamic_require`
+   both carry a real file:line (a specific `<script src>` tag or `require(...)` call someone wrote)
+   that a future resolver update genuinely could walk; `engine.js`'s provenance-stamping loop
+   previously gave all four types the identical limitation string, so the message-building code told
+   a user with a `cdn_no_integrity` finding to stop investigating a resolvable coverage gap because
+   it looked identical to a truly unresolvable one. `engine.js` now gives the two classes distinct,
+   honest limitation strings.
+
+Both landed with new regression tests (`scanner/test/assurance-mode.test.js`) covering the exact
+multi-reason interaction that exposed the first defect, and the cdn/dynamic-require case for the
+second. No behavior changed for the single-reason case most scans will actually hit.
+
+## 0.148.3 - Dependency currency fix; supersedes 0.148.2, which never published
+
+The `v0.148.2` tag was pushed but its release workflow's dependency-currency gate failed on a
+clean CI runner — `@types/node` (dev-only, scanner and ide/vscode) was one patch behind the
+latest published version, with no advisory and no legitimate reason to hold it. `npm publish`
+never ran for 0.148.2; nothing shipped under that version. Fixed by upgrading `@types/node` to
+`26.5.0` in both trees. No other change from 0.148.2's own content — see that entry below for
+what actually shipped.
+
+## 0.148.2 - A confusing --assurance strict failure made specific and actionable; adversarial premortem re-run on NIST 800-171
+
+A user ran the README's own 5-minute quickstart command and got a confusing, uninformative
+failure — see the last item in this entry for the fix. Separately, 0.148.1's compliance-framework
+fixes were put through a second, independent adversarial pass rather than trusted on their own
+say-so. It found the individual fixes held up, but surfaced two live defects the first pass
+missed entirely, plus six gaps in how the fixes themselves were verified and disclosed.
+
+1. `module:verifier` and `module:sigstore-verify` were referenced by real controls in four
+   bundled frameworks, but nothing ever wrote either artifact — worse than a self-referential
+   mapping (which can at least clear, dishonestly), a mapping that can never clear at all, on
+   any project, permanently. `verifier.js` now writes a real record on every
+   `agentic-security verify` run, closing `module:verifier` for real — proven end-to-end:
+   NIST 800-171 `03.12.01` flips from missing to present after a real `verify` invocation.
+   `module:sigstore-verify` is disclosed as an engine gap instead: its real producer is a
+   fire-and-forget async annotation with no reliable completion point to hang a writer off,
+   a bigger fix than this pass's scope.
+
+2. A new writer-existence test (`scanner/test/module-artifact-liveness.test.js`) checks every
+   `module:` artifact resolves to a real writer or a real repo file, not just a name on a list.
+   Running it once found two more real, previously-unknown defects the manual premortem review
+   missed: a malformed `module:privacy-taint:emitDpiaArtifact` typo in `gdpr.json` (the
+   evaluator parses everything after `module:` as one literal key — no `:`-suffix syntax
+   exists — so this control could never clear), and a dead `module:exploitability-probability`
+   reference in `nist-csf-2.json` (that annotator writes no standalone artifact; removed as
+   redundant with the surviving `module:attack-taxonomy` leg on the same control). Both fixed.
+   The eight structurally self-referential `module:` entries found across this and the prior
+   release are now removed from the vocabulary table itself, not merely left unreferenced, so
+   there is nothing left to copy-paste back into a future mapping.
+
+3. `aibom.json` now auto-persists on every scan. It was only ever reachable through the CLI's
+   `--format aibom` report emitter, which prints to stdout — never to `.agentic-security/` —
+   so `module:aibom` (EU AI Act Art.11, NIST 800-171 `03.04.10`, NIST AI 600-1 `MG-4.1-001`)
+   could never clear on any project unless an operator manually redirected the CLI's output to
+   that exact path.
+
+4. The scoring-threshold provenance caveat added in 0.148.1 (that NIST 800-171's deep-attestation
+   scanner shares AI 600-1's unvalidated weights and thresholds) lived only in a doc and a
+   source docstring — never in the actual generated attestation markdown a customer would
+   submit. It now prints inline in that document whenever the catalog being scored isn't the
+   framework the scoring engine was built for.
+
+5. The held-out anchor set added in 0.148.1 to guard the 97 hand-authored `codeTestable`
+   ratings covered only 3 of the 9 controls that release's own rationale-expansion pass
+   actually touched — the other 6 had no drift protection despite being exactly the work the
+   gate exists to protect. Expanded to cover all 9.
+
+6. `module:why-fired` (EU AI Act Art.13), left an open, undecided question in 0.148.1's own
+   premortem, is now adjudicated: on a full reading of the control text (every other control in
+   the same framework uses "the system" to mean the assessed AI product) and of `why-fired.js`'s
+   actual purpose (explains this scanner's own detection provenance, not the assessed system's),
+   it is the same category error as the other eight — the artifact's content being genuinely
+   target-derived doesn't make the claim it was asked to back correct.
+
+7. `docs/SCORECARD.md` now tracks, per bundled framework, how many controls carry at least one
+   live mapping — not as a gate (a drop is sometimes a correct, honest fix and sometimes a real
+   regression, and only a human reading the diff each release can tell which), but so the
+   cumulative effect of "always subtract a bad mapping, never invent one" is visible instead of
+   assumed fine.
+
+8. The PRD's own implementation record (`NIST-800-171r3-PRD.md`) now documents this pass.
+
+9. `agentic-security ci <path> --assurance strict` on a directory with no git history — the
+   exact result of running the README's own quickstart command against a GitHub "Download ZIP"
+   extraction instead of a `git clone` — used to fail with only a bare count: "1210 finding(s)
+   have status outside [complete, uncommitted]." The scanner already knew and recorded the real
+   reason (`finding.findingProvenance.limitations[0] = 'not a Git repository'`), it just never
+   reached the message a user actually sees. The assurance-gate failure now names the dominant
+   recorded reason and, for the two most common shapes, gives a specific fix: no git history
+   ("run `git init && git add -A && git commit`, or scan a real `git clone`") and an unpinned
+   dependency / missing lockfile ("this is a permanent, by-design limitation — fix the SCA
+   finding or use `--assurance standard`"). `docs/walkthroughs/assurance-modes.md` documents
+   both (`scanner/src/pipeline/assurance-mode.js`).
+
 
 ## 0.148.1 - Six real false-positive fixes from a customer bug report, two report-consistency fixes
 

package/bin/agentic-security.js

@@ -1875,7 +1875,7 @@ async function cmdVerify(args) {
     process.env.AGENTIC_SECURITY_VERIFY_LIVE = '1';
     process.env.AGENTIC_SECURITY_VERIFY_TARGET = targetFlag;
   }
-  const { annotateVerifierVerdicts, verifierCoverageSummary } = await import('../src/posture/verifier.js');
+  const { annotateVerifierVerdicts, verifierCoverageSummary, recordVerifierRun } = await import('../src/posture/verifier.js');
   const filter = args.flags.finding ? findings.filter(f => f.id === args.flags.finding || f.stableId === args.flags.finding) : findings;
   if (!filter.length) {
     console.error(`No matching findings (use --finding <id>).`);
@@ -1901,6 +1901,10 @@ async function cmdVerify(args) {
   const sum = verifierCoverageSummary(filter);
   console.log(`Verified ${filter.length} finding(s):`);
   for (const [k, v] of Object.entries(sum)) console.log(`  ${k}: ${v}`);
+  // Adversarial premortem Q1: a durable record that a security assessment of
+  // findings actually happened, so module:verifier has something real to
+  // point at (see verifier.js's recordVerifierRun header comment).
+  recordVerifierRun(scanRoot, { findingCount: filter.length, live: liveFlag, target: targetFlag || null, summary: sum });
   if (args.flags.verbose || args.flags.finding) {
     for (const f of filter) {
       console.log(`  ${f.file}:${f.line}  ${f.vuln}`);

package/dist/4970.index.js

@@ -65,6 +65,112 @@ function _isValidMode(mode) {
   return ASSURANCE_MODES.includes(mode);
 }
 
+// A real user hit this: `agentic-security ci <a directory downloaded as a
+// GitHub zip, no .git present> --assurance strict` failed with the bare
+// count this function used to produce alone — "1210 finding(s) have status
+// outside [complete, uncommitted]" — with no indication that all 1210
+// findings failed for the exact same, simple, fixable reason
+// (`coordinator.js`'s `annotateGitProvenance` already knows and records it,
+// in `finding.findingProvenance.limitations[0]`, but that reason never
+// reached this message). A user reading "1210 problems" reasonably assumes
+// their CODE has 1210 problems, not that their DIRECTORY isn't a git
+// repository. This surfaces the dominant recorded reason instead of a bare
+// count, and gives the two most common, fully-fixable reasons ("not a Git
+// repository" from a zip download instead of `git clone`; a shallow CI
+// checkout) a one-line, specific remedy — the same specificity the
+// scanHealth branch above already gives for a stale-EPSS-cache failure.
+function _provenanceFailureReason(badProvenance, totalFindings) {
+  const counts = new Map();
+  for (const f of badProvenance) {
+    const reason = f?.findingProvenance?.limitations?.[0] || f?.findingProvenance?.status || 'unknown';
+    counts.set(reason, (counts.get(reason) || 0) + 1);
+  }
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  const base = `strict mode requires complete finding provenance; ${badProvenance.length}/${totalFindings} finding(s) have status outside [complete, uncommitted]`;
+
+  const gitReasons = ranked.filter(([r]) => r === 'not a Git repository' || r === 'repository state unavailable');
+  const gitCount = gitReasons.reduce((s, [, n]) => s + n, 0);
+  // engine.js's own comment on this branch: "unpinned_dep / no_lockfile...
+  // describe the ABSENCE of a declaration, so 'which commit introduced this
+  // version' is not a question that has an answer to defer ... this is a
+  // known, disclosed limitation, not a bug... strict mode WILL fail on
+  // nearly any real project that has a package.json." That disclosure lived
+  // only in a source comment nobody hits this error reads — the README's
+  // own quickstart explicitly invites pointing --assurance strict at "your
+  // own project," where this is the single most likely outcome. Named here
+  // so the person who hits it learns it is expected and permanent, not
+  // something to keep investigating. This prefix is deliberately narrower
+  // than "every non-vulnerable_dep supply-chain entry" — engine.js's
+  // provenance-stamping loop only uses it for unpinned_dep/no_lockfile,
+  // which genuinely have no origin commit; cdn_no_integrity/dynamic_require
+  // carry a real file:line and get a DIFFERENT string precisely so they
+  // never land in this "permanent, give up" bucket (adversarial premortem
+  // R2, 2026-09-07 — conflating the two told a user a resolvable coverage
+  // gap was an unfixable, by-design limitation).
+  const supplyChainReasons = ranked.filter(([r]) => r.startsWith('origin resolution does not apply to a'));
+  const supplyChainCount = supplyChainReasons.reduce((s, [, n]) => s + n, 0);
+  const knownReasonSet = new Set([...gitReasons, ...supplyChainReasons].map(([r]) => r));
+  const otherReasons = ranked.filter(([r]) => !knownReasonSet.has(r));
+  const otherCount = badProvenance.length - gitCount - supplyChainCount;
+  const knownCategoryCount = (gitCount > 0 ? 1 : 0) + (supplyChainCount > 0 ? 1 : 0);
+
+  // Exactly one KNOWN category, and nothing outside it — the shape every
+  // caller before this fix assumed was the only shape, and the one every
+  // existing test was written against. Kept as tight, single-topic prose
+  // rather than the multi-segment form below.
+  if (knownCategoryCount === 0) {
+    if (otherReasons.length === 1) {
+      return `${base} — all ${badProvenance.length} share the same reason: "${otherReasons[0][0]}".`;
+    }
+    const breakdown = otherReasons.slice(0, 5).map(([reason, n]) => `${n}× "${reason}"`).join(', ');
+    return `${base} — breakdown: ${breakdown}${otherReasons.length > 5 ? ', …' : ''}.`;
+  }
+  if (knownCategoryCount === 1 && otherCount === 0) {
+    if (gitCount > 0) {
+      const gitReasonNames = gitReasons.map(([r]) => `"${r}"`).join(' and ');
+      return `${base} — reason: ${gitCount === badProvenance.length ? 'all of them are' : `${gitCount} of them are`} ${gitReasonNames}. ` +
+        `strict mode resolves finding provenance from git history, so it requires a real git repository ` +
+        `(a GitHub "Download ZIP" extracts without one). Run \`git init && git add -A && git commit -m init\` in ` +
+        `the scanned directory, point the scan at a real \`git clone\`, or drop --assurance strict for standard/advisory.`;
+    }
+    return `${base} — ${supplyChainCount} of them describe an ABSENT dependency declaration ` +
+      `(an unpinned version, a missing lockfile) that has no origin commit to resolve, by design. This is a ` +
+      `known, permanent limitation: strict mode cannot pass while any are present, on any real project with ` +
+      `such a dependency. Fix the underlying SCA finding(s) (pin the version / add a lockfile) if you want ` +
+      `strict to pass, or use --assurance standard/advisory for a project you don't control the dependencies of.`;
+  }
+
+  // Two or more independently-blocking categories on the SAME scan — the
+  // defect this closes (adversarial premortem R1, 2026-09-07): the old
+  // code picked whichever category had the most findings and silently
+  // dropped every other one, so a user could "fix" the reported problem,
+  // rerun, and hit a second wall the first run already had full information
+  // about but never mentioned — the same "the tool knew and didn't tell me"
+  // complaint this whole function exists to fix, recurring in a milder form.
+  const segments = [];
+  if (gitCount > 0) {
+    const gitReasonNames = gitReasons.map(([r]) => `"${r}"`).join(' and ');
+    segments.push(`${gitCount} of them are ${gitReasonNames} (strict mode requires a real git repository — ` +
+      `run \`git init && git add -A && git commit\`, or scan a real \`git clone\`)`);
+  }
+  if (supplyChainCount > 0) {
+    segments.push(`${supplyChainCount} of them describe an ABSENT dependency declaration (unpinned version / ` +
+      `missing lockfile) with no origin commit to resolve — a known, permanent limitation, not something a ` +
+      `rerun will fix`);
+  }
+  if (otherCount > 0) {
+    if (otherReasons.length === 1) {
+      segments.push(`${otherCount} share the reason "${otherReasons[0][0]}"`);
+    } else {
+      const breakdown = otherReasons.slice(0, 5).map(([reason, n]) => `${n}× "${reason}"`).join(', ');
+      segments.push(`${otherCount} break down as: ${breakdown}${otherReasons.length > 5 ? ', …' : ''}`);
+    }
+  }
+  return `${base} — MULTIPLE distinct reasons, not just one: ${segments.join('; ')}. Every category above must ` +
+    `be resolved for strict to pass (or drop to --assurance standard/advisory) — fixing only one will surface ` +
+    `the next on your following run.`;
+}
+
 /**
  * @param {string} mode - one of ASSURANCE_MODES; invalid/missing degrades to the default.
  * @param {object|null} scanHealth - the engine's computed scan.scanHealth (FR-206).
@@ -157,7 +263,7 @@ function evaluateAssuranceMode(mode, scanHealth, findings = []) {
     return {
       ok: false,
       mode: 'strict',
-      reason: `strict mode requires complete finding provenance; ${badProvenance.length} finding(s) have status outside [complete, uncommitted]`,
+      reason: _provenanceFailureReason(badProvenance, findings.length),
       conditions,
     };
   }
@@ -165,7 +271,7 @@ function evaluateAssuranceMode(mode, scanHealth, findings = []) {
   return { ok: true, mode: 'strict', reason: null, conditions };
 }
 
-const _internals = { _isValidMode };
+const _internals = { _isValidMode, _provenanceFailureReason };
 
 
 /***/ })