@clear-capabilities/agentic-security-scanner 0.148.0 → 0.148.3

package/CHANGELOG.md

@@ -10,6 +10,156 @@
 
 
 
+## 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
+
+A developer ran the scanner on two of their own applications and sent back a detailed,
+reproducible bug report. All six false positives traced back to the same defect class:
+a loosely-bounded regex matching an identifier or text substring without real syntax
+awareness. None were caught by unit tests, because a fixture an author writes by hand is
+shaped the way the author expects the code to look; these were found by a real user reading
+the lines a real scan cited.
+
+1. SQL injection fired on "Selected"/"selected". Case-insensitive `SELECT` had no word
+   boundary, so it matched the first six letters of "Selected" (an exception message) and
+   "selected" (an ordinary list variable). The rule's own name claimed "assigned to variable"
+   but never checked for an assignment; both fixed (`scanner/src/sast/python-sinks.js`).
+
+2. A Python method literally named `fetch(self, ...)` was reported as a missing-timeout
+   HTTP-DoS finding, at its interface declaration, its implementation, and its call site, with
+   a hardcoded JavaScript remediation. The rule named JS-only APIs (fetch/axios/http.get) but
+   carried no `langScope`, so it matched the raw text "fetch(" in any language. Fixed with a
+   language scope and a declaration-vs-call exclusion (`scanner/src/engine.js`).
+
+3. `HUGGINGFACE_TOKEN = getpass.getpass("Enter your Hugging Face token: ")` was flagged
+   Critical, Hardcoded Secret. The captured-value character class matched newlines, so once
+   the word "token" inside the human-readable PROMPT happened to be followed by `: "`, the
+   "secret" spanned past that string's own closing quote into the next function definition.
+   Excluding newlines from the class confines a match to one physical line
+   (`scanner/src/engine.js`).
+
+4. `bundle.publisher_domain` and `bundle.published_at` were read as a message-queue producer
+   boundary. `(?:kafka|pubsub|sqs|sns)\.produce|\.publish|\.sendMessage` parses as three
+   TOP-LEVEL alternatives; only the first is scoped to a queue library, so `.publish` alone
+   matched the first 8 characters of "publisher"/"published" with no queue library and no
+   method call in sight. The identical defect existed one line above for `queue-consumer`
+   (`.subscribe`/`.receiveMessage`, e.g. an RxJS Observable) and is fixed the same way:
+   the method names moved inside the shared prefix group, and a trailing `(` is now required
+   (`scanner/src/posture/threat-model.js`).
+
+5. `self.session = requests.Session()` was classified as an authenticated user-session asset.
+   The pattern checked only the LHS variable name, never the RHS constructor. A negative
+   lookahead now excludes `requests.Session`/`aiohttp.ClientSession`/`httpx.Client`/
+   `httpx.AsyncClient` (`scanner/src/posture/threat-model.js`).
+
+6. `scanned.lines` was always 0 and a finding's `whyFired.scanner.rulesetVersion` was always
+   `null`, in both cases despite the top-level scan doing the right thing elsewhere. Two dead-
+   wiring bugs, not detector defects: `linesScanned` was read in `report/index.js` but never
+   assigned anywhere in the engine, and `annotateWhyFired(finalFindings, {})` was called with a
+   hardcoded empty context even though the engine already computes the real ruleset version two
+   other places in the same function (`scanner/src/engine.js`).
+
+`scanner/src/posture/threat-model.js` had zero test coverage before this release
+(`scanner/test/threat-model.test.js` is new). Each fix also carries a negative case proving the
+real, intended finding is still reported — a precision fix that silences a genuine positive is
+worse than the false positive it replaced.
+
+Confirmed, by reading the code, NOT a bug: the duplicate `stableId` the report also flagged
+(same id on the interface declaration and the implementation) is documented, intended
+behavior — `stable-id.js` deliberately hashes on normalized code shape rather than file/line,
+specifically so near-identical code keeps one id across refactors. Moot here regardless, since
+fix 2 above means neither finding fires again.
+
+Not fixed, flagged rather than guessed at: the report's "uncertainty inversion" observation,
+where an unproven, low-confidence finding still produced a confident PoC, ATT&CK mapping and
+dollar-impact narrative downstream. `mitigation-composite.js`'s `exposed-in-prod` verdict is
+confirmed to be answering an orthogonal question by design (would a known production control
+block this, defaulting to exposed absent one) and never reads `proof.verdict` or confidence at
+all — so the actual gap, if real, is in a PoC or dollar-estimate consumer not gating on proof
+state, which needs its own dedicated investigation rather than a fix rushed into this release.
 
 ## 0.148.0 - NIST SP 800-171 Rev. 3 (CUI / CMMC basis) as the 10th bundled framework
 

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,62 @@ 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 [topReason, topCount] = ranked[0];
+  const allSameReason = ranked.length === 1;
+  const base = `strict mode requires complete finding provenance; ${badProvenance.length}/${totalFindings} finding(s) have status outside [complete, uncommitted]`;
+
+  if (topReason === 'not a Git repository' || topReason === 'repository state unavailable') {
+    return `${base} — reason: ${allSameReason ? 'all of them are' : `${topCount} of them are`} "${topReason}". ` +
+      `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.`;
+  }
+  // engine.js's own comment on this branch: "unpinned_dep / no_lockfile and
+  // friends... 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.
+  const supplyChainCount = ranked.filter(([r]) => r.startsWith('origin resolution does not apply to a')).reduce((s, [, n]) => s + n, 0);
+  if (supplyChainCount > 0 && supplyChainCount >= badProvenance.length / 2) {
+    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.`;
+  }
+  if (allSameReason) {
+    return `${base} — all ${badProvenance.length} share the same reason: "${topReason}".`;
+  }
+  const breakdown = ranked.slice(0, 5).map(([reason, n]) => `${n}× "${reason}"`).join(', ');
+  return `${base} — breakdown: ${breakdown}${ranked.length > 5 ? ', …' : ''}.`;
+}
+
 /**
  * @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 +213,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 +221,7 @@ function evaluateAssuranceMode(mode, scanHealth, findings = []) {
   return { ok: true, mode: 'strict', reason: null, conditions };
 }
 
-const _internals = { _isValidMode };
+const _internals = { _isValidMode, _provenanceFailureReason };
 
 
 /***/ })