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

package/CHANGELOG.md

@@ -11,6 +11,257 @@
 
 
 
+## 0.145.0 — Finding Provenance ships, and two audits find what the first one missed
+
+Every finding now carries a `findingProvenance` record answering "when did this
+enter the codebase, and how sure are we?" — resolved from Git history, not
+guessed. It is **opt-in**: pass `--provenance` (or any provenance flag, e.g.
+`--provenance-since`, `--require-provenance`) on a scan of a Git repository.
+
+It is opt-in rather than on-by-default because the release gate measured what
+on-by-default costs: time-to-first-finding over a 207-file tree went 4.5s to
+45s. That is a 7.6x regression on the one metric this product's own benchmark
+calls the binding constraint for its ICP — "how long until the FIRST useful
+result, not aggregate F1" — and resolving commit history for every finding is
+not what a first-time user is waiting on. CI, compliance and triage callers
+that want provenance ask for it explicitly and pay the cost knowingly.
+
+**What it resolves.** For a SAST finding: the commit that introduced it, found
+by replaying the finding's own predicate against historical blobs (`git blame`
+answers "who last touched this line", which is a different and usually wrong
+question) and then confirming the predicate was FALSE in that commit's parent.
+For a direct dependency: the commit that moved the declared version in
+`package.json`/`requirements.txt` into an advisory's vulnerable range. Alongside
+the origin commit: the branch/PR the change entered through, the evidence nodes
+(source/sink/manifest, each as a path:line:commit triple), a confidence level
+with its reasons, and a lifecycle ledger of introduce/remediate/reintroduce
+events at `.agentic-security/provenance/lifecycle.json`.
+
+**Only a complete scan can close a finding.** The ledger's remediation pass turns
+a finding's *absence* into the claim "this was fixed," which is sound only when
+the scan actually looked everywhere it could have found it. A `--changed-since` /
+`--pr` scan, or any caller-supplied file list (the MCP `scan_diff` tool, the LSP's
+on-save scan), therefore records new and reintroduced findings normally but closes
+nothing — the entries it did not look at stay open until a full scan says
+otherwise. For the same reason the ledger is written only when the scan target is
+a real directory: a scan of a path that does not exist resolves its state
+directory by walking up from the current working directory, and would otherwise
+write a verdict about a project it never read.
+
+**It refuses to guess.** Every record carries a terminal `status`, and there is
+no path that leaves the field absent: `complete`, `partial` (history could not
+confirm a parent boundary — a shallow clone, or an advisory with no `introduced`
+bound), `uncommitted` (the finding exists only in the working tree),
+`not_available`, `budget_exhausted`, or `error`. A shallow clone can never reach
+`complete`. Author emails are redacted from every output format unless
+`--include-author-email` is passed.
+
+**New flags** (`agentic-security scan --help` documents all seven):
+`--provenance <standard|deep>`, `--no-provenance`, `--provenance-since <ref>`,
+`--provenance-timeout <ms>`, `--include-author-email`, `--pseudonymize-authors`,
+`--require-provenance`. `deep` mode performs real non-linear DAG analysis (see
+the M3 subsection below) — it is no longer a stub that silently runs `standard`.
+`--require-provenance` reports unresolved provenance as a scan-health condition
+and downgrades `scanHealth.status` to `partial`; it never changes the exit code
+by itself — see the M2 subsection below for the mechanism that does.
+`--verbose --firehose` prints the provenance block per finding in text output.
+See [`docs/guides/finding-provenance.md`](docs/guides/finding-provenance.md)
+for the full user-facing writeup.
+
+### M2: format parity, compliance/MTTR/fix-lifecycle surfacing, and `--assurance strict` can now fail the build
+
+M0+M1 landed provenance resolution and the JSON/text surfaces above. M2 threads
+that data through every other output and, for the first time, gives provenance
+completeness the power to fail a CI build.
+
+- **Format parity.** SARIF, CSV, Markdown, and HTML output now all carry each
+  finding's `findingProvenance`, matching what JSON already had — a consumer no
+  longer has to switch formats to see it.
+- **Compliance evidence.** Auditor-walkthrough and NIST Privacy Framework gap
+  findings now carry `controlRefs` (the finding ids backing a control's gap
+  determination) and `derivedProvenance` (the earliest proven open condition
+  among those findings, with a `confidence` level and stated `limitations`).
+- **MTTR.** `mttr.js` reports `ageBasis` (`finding_origin` | `earliest_observable`
+  | `uncommitted` | `first_observed`) and `provenAgeDays` alongside the existing
+  wall-clock `ageDays`, so age-to-remediate can be read against the commit that
+  actually introduced the finding, not just when the scanner first saw it.
+- **Fix records.** Every fix-history entry now carries a `provenanceAtFix`
+  snapshot — the finding's `findingProvenance` as it stood at the moment the fix
+  was applied — so a later audit can see what was known at fix time, not just
+  what is knowable now.
+- **`--assurance strict` can now fail the build over incomplete provenance.**
+  This is the behavior change that matters most, and it is a genuinely new
+  failure mode, not a rewording of `--require-provenance` above: strict mode
+  (`--assurance strict`) now treats any finding whose `findingProvenance.status`
+  is outside `[complete, uncommitted]` as making the scan incomplete, and fails
+  the same way it already fails on a failed or skipped analyzer. `--require-provenance`
+  is unchanged by this — it still only flags and never fails the exit code.
+  `--assurance strict` is the new, separate mechanism that does fail it. See the
+  `KNOWN INTERACTION` comment in `scanner/src/pipeline/assurance-mode.js` for a
+  known, disclosed consequence: transitive `vulnerable_dep`, `unpinned_dep`, and
+  `no_lockfile` supply-chain findings are stamped `not_available` today (the
+  latter two are a category error — there is no commit that introduced a
+  *missing* lockfile — not merely a deferral), so `--assurance strict` will fail
+  on nearly any real project with a dependency manifest until that gap closes.
+
+### M3: real non-linear history, transitive-dependency provenance, missing-control regressions, PR/CODEOWNERS enrichment
+
+- **`--provenance deep` now does real work.** Instead of the M0–M2 stub that
+  accepted the flag and silently ran `standard`, deep mode walks every parent
+  of a merge commit (not just the first), which resolves origins standard
+  mode's first-parent-only walk cannot see, and detects reverts and
+  cherry-picks — surfaced as `findingOrigin.revertOf` / `.cherryPickOf` — via
+  a real unified-diff inversion.
+- **Transitive-dependency provenance is now live-wired**, not merely
+  modeled: `transitive-sca.js` re-derives lockfile ancestry per historical
+  commit to find the commit that moved a *lockfile-resolved* (not
+  manifest-declared) dependency into an advisory's vulnerable range.
+- **Missing-control regressions** — a previously-observed safeguard (today:
+  `sast/rate-limit.js`'s findings) disappearing — can now resolve a real
+  origin via `missing-control-resolver.js`.
+- **Optional GitHub/GitLab PR-metadata + CODEOWNERS enrichment**
+  (`findingProvenance.providerEnrichment`) is live for `complete`-status
+  findings, configured via `.agentic-security/provenance-providers.yml` /
+  `AGENTIC_SECURITY_GITHUB_TOKEN` / `AGENTIC_SECURITY_GITLAB_TOKEN`, capped
+  per scan.
+
+### M4: signed provenance evidence bundles, cross-repository lineage, an AI-authorship hook
+
+- **`agentic-security attest --provenance`** signs a per-finding provenance
+  record (origin commit, confidence, evidence attribution) with the same
+  Ed25519 key material as the existing finding-evidence bundle mechanism;
+  `verify-attestation` auto-detects and verifies it against a public key
+  alone. Note the flag-shape collision with `scan`: on `attest`, `--provenance`
+  takes an optional *finding id*, not a mode — `attest --provenance deep`
+  looks for a finding literally named `deep`.
+- **Cross-repository lineage.** An operator-declared
+  `.agentic-security/repo-lineage.json` can link a root-commit origin (a
+  finding whose earliest commit has no parent in the current repo) across a
+  prior, local-clone-only fork/split history. Resolution is conservative:
+  content at the linked line must actually match, not merely exist, before
+  an origin is reported, and the record discloses the boundary crossing
+  explicitly.
+- **An extensible AI-authorship verifier registry**
+  (`registerAIAuthorshipVerifier` / `resolveAIAuthorship`) now stamps every
+  SAST `findingOrigin` with an `aiAuthorship` field; no verifier is
+  registered today, so it defaults honestly to `{status:'unknown', verifier:null}`.
+- **Fleet-wide rollups** (`fleet.js`) now surface provenance-proven
+  remediation debt. Fleet MTTR is honestly disclosed rather than fabricated:
+  real remediation-timing data isn't reachable from the production fleet
+  driver without new state, so `rollupFleet` distinguishes "never tracked"
+  from "tracked, zero remediations" instead of reporting a misleading number.
+
+### PRD completion: injection hardening, evidence-digest binding, retention split, and the first real coverage/accuracy measurements
+
+- Author names and commit summaries are now sanitized against terminal
+  control-character and Markdown/HTML injection everywhere they reach a
+  human (FR-PROV-026).
+- The run-attestation digest and provenance cache key are now genuinely
+  bound to the PRD-named inputs they claim to cover, including
+  detector/ruleset version.
+- Symlink-escape protection added to the git evidence layer.
+- **`--pseudonymize-authors`** (new flag, listed above) replaces raw
+  commit-author names with a stable `Contributor-XXXXXXXX` id — for when you
+  need to compare "who introduced what" without a raw name in the output.
+  Honored everywhere `--include-author-email`'s redaction already was,
+  including PR-reviewer logins and CODEOWNERS entries from provider
+  enrichment.
+- The provenance cache now lives in its own top-level, independently-retained
+  state directory (`.agentic-security/provenance-cache/`), split from the
+  permanent lifecycle ledger (`.agentic-security/provenance/lifecycle.json`),
+  so cache eviction can never touch permanent history.
+- **Two PRD success metrics are now genuinely measured and published, not
+  just designed:** known-origin accuracy (12/13 = 92.3% on the labeled
+  corpus, against a ≥98% target) and provenance coverage (311/341 = 91.2% on
+  this repository's own tree, against a ≥95% target — all 30 shortfall
+  findings resolve to `partial`, not `error`/`not_available`, so the gap is
+  reduced confidence rather than pipeline failure).
+- `scan.secrets` and blameable `scan.logicVulns` entries now go through real
+  origin resolution (real stableIds, real git history) instead of a
+  permanent `not_available` placeholder.
+
+### Second-audit remediation: a hostile-repository RCE closed, and further honesty fixes
+
+An independent second audit of the completed Finding Provenance PRD found
+one security-critical gap and several places where a metric or a claim
+wasn't as real as it read. All fixed this release:
+
+- **Security fix (1 of 2).** Git subprocess calls in the provenance pipeline
+  are now hardened against a hostile repository's own `.git/config` (e.g. a
+  malicious `core.fsmonitor`), `.gitattributes` `textconv` drivers, and
+  external `diff` drivers — a repository could previously trigger arbitrary
+  code execution merely by being scanned, provenance on or off. The sweep
+  covers every git invocation in the scanner, not just the provenance
+  module, and a source-level guard now fails the build if a future `git
+  diff` call site omits `--no-ext-diff`. Removing the shell from two
+  remaining `execSync` call sites also closed a command-injection path via
+  attacker-controlled filenames.
+- **Security fix (2 of 2), found while reviewing a performance optimization
+  in this same release.** A change that fused the parent-commit lookup into
+  an existing `git show` placed that field after the author name in a
+  delimiter-separated record. Git preserves a literal `0x1f` inside an
+  author name, so an outside contributor choosing their own author name
+  could shift the parse and select the bytes read as the parent commit.
+  Because a parent whose blobs cannot be fetched is indistinguishable from
+  one that genuinely lacks the finding, this could manufacture a
+  `status: 'complete'` origin with **HIGH confidence** for a boundary that
+  was never verified — a fabricated certainty claim that would then flow
+  into signed evidence bundles. The field now sits behind the commit hash
+  only, with hex validation as defense in depth. Both directions are pinned
+  by a regression test.
+- The provenance cache key and evidence digest are now genuinely bound to
+  the running detector/ruleset version (previously always `null` in
+  practice), so upgrading the scanner correctly invalidates stale cached
+  provenance.
+- `ageBasis` and `provenAgeDays` are now rendered wherever a finding's age is
+  shown, not only written to `last-scan.json`.
+- Provenance coverage is now wired into the real, running scorecard-generation
+  path (see "PRD completion" above for the number) instead of always
+  reporting "unmeasured."
+- **Performance measurement is now honest end-to-end**, and the honest
+  numbers are a real miss against target: real p95 (n=20) over both cold and
+  warm cache arms, and a genuine two-sided memory comparison (not a one-arm
+  heap delta). Measured this release — cold-cache time ~27x wall-clock p95
+  against a ≤1.3x (≤30% overhead) target, warm-cache ~2x; cold-cache memory
+  ~13x against a ≤1.2x target. `bench:provenance-accuracy:check` is now
+  wired into the pre-push gate so the known-origin-accuracy number can no
+  longer silently rot.
+- The PRD's **required compliance-evidence disclaimer** ("Provenance
+  establishes repository history for technical evidence. It does not prove
+  developer intent, control operation outside code, organizational
+  compliance, or certification.") now appears next to every
+  provenance-derived origin the auditor walkthrough renders
+  (`compliance --walkthrough`), and user-facing documentation for the whole
+  feature now exists at
+  [`docs/guides/finding-provenance.md`](docs/guides/finding-provenance.md).
+- **Not fixed, disclosed honestly:** a finding in a file renamed after
+  introduction still degrades to `status: 'partial'` rather than resolving
+  its true pre-rename origin commit. Known and traced, not fixed this round.
+
+### Breaking: SCA finding ids change for manifest-declared dependencies
+
+Direct dependencies declared in `package.json` / `requirements.txt` now carry the
+manifest **line number** where they are declared, and `report/index.js`'s
+`fingerprint()` folds that line into the finding id. This was necessary for
+provenance — an SCA finding had no line, so every `vulnerable_dep` from one
+manifest previously hashed to the SAME id and could not be told apart — but it
+means those ids are **not stable across this upgrade**.
+
+Concretely: any triage verdict, baseline entry, or suppression keyed on the OLD
+id of a `package.json`- or `requirements.txt`-declared dependency finding will no
+longer match and is effectively orphaned. Affected state:
+`.agentic-security/baseline.json`, triage memory, and `disable:`/suppression
+entries naming an SCA finding id. Transitive dependencies (resolved from a
+lockfile, not declared in a manifest) are unaffected, as are all SAST, secrets,
+and business-logic findings.
+
+**There is no automatic migration**, and that is deliberate rather than an
+oversight — id aliasing would have to be carried indefinitely to be safe, and
+the orphaned entries fail open (a finding reappears) rather than closed (a real
+finding stays hidden). Re-triage or re-baseline the affected SCA findings after
+upgrading; `agentic-security scan --set-baseline` regenerates the baseline in one
+step.
+
 ## 0.144.0 — Assurance hardening closes Epic E2, and an independent audit finds what "verified" missed
 
 The assurance-hardening PRD (`docs/implementation/assurance-hardening-*`)

package/bin/agentic-security.js

@@ -8,6 +8,7 @@ import { createRequire } from 'node:module';
 const __require = createRequire(import.meta.url);
 const PKG_VERSION = __require('../package.json').version;
 import { signLastScan as _signLastScan, verifyLastScan as _verifyLastScanShared } from '../src/posture/integrity.js';
+import { isProvenanceHealthy, sanitizeForTerminal } from '../src/posture/provenance/schema.js';
 import { runScan } from '../src/runScan.js';
 
 // Every command is dispatched as `process.exit(await cmdX(args))`, and
@@ -185,9 +186,20 @@ Options:
   --no-epss                    Skip EPSS exploit-prediction enrichment (default: enabled)
   --no-blast-radius            Skip blast-radius / cost framing (default: enabled)
   --verbose                    Include fix bodies + taxonomy in CLI output
+                               (with --firehose, also prints each finding's git-origin provenance)
   --output <file>              Write report to file instead of stdout
   --machine-output             Always write .agentic-security/findings.{sarif,json,csv}
 
+Finding provenance (which commit introduced each finding):
+  --provenance <standard|deep> Resolution depth (default: standard; deep explores non-linear ancestry — merges, reverts, cherry-picks)
+  --no-provenance              Skip git-history provenance entirely (findings report not_available)
+  --provenance-since <ref>     Do not walk history earlier than this git ref/commit
+  --provenance-timeout <ms>    Whole-scan provenance budget in MILLISECONDS (default 60000)
+  --include-author-email       Keep commit author emails in output (redacted by default)
+  --pseudonymize-authors       Replace commit author names with a stable Contributor-XXXXXXXX id
+  --require-provenance         Report unresolved provenance as a scan-health condition
+                               (downgrades scanHealth.status to 'partial'; never changes the exit code)
+
 Exit codes:
   0 = clean   1 = low/medium   2 = high   3 = critical   4 = error`;
 
@@ -393,6 +405,112 @@ function parseArgs(argv) {
   return args;
 }
 
+// The only values `--provenance` accepts. Used both to validate an inline
+// `--provenance=<mode>` and to decide whether a following bare token is this
+// flag's value at all — see the comment inside the parser.
+const PROVENANCE_MODES = new Set(['standard', 'deep']);
+
+// Finding Provenance (M0/M1) — CLI flags that set the env vars engine.js
+// (Task 15) and report/index.js (Task 16) already read:
+// AGENTIC_SECURITY_NO_PROVENANCE, AGENTIC_SECURITY_PROVENANCE_MODE,
+// AGENTIC_SECURITY_PROVENANCE_SINCE, AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS,
+// AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL,
+// AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS. `requireProvenance` is consumed
+// directly by cmdScan (post-scan scanHealth augmentation), not via an env var.
+// Kept as a pure function (argv in, plain object out) so it's unit-testable
+// without invoking the CLI dispatch or touching process.env.
+export function parseProvenanceFlags(argv) {
+  // OPT-IN, not opt-out (0.145.0). Provenance was on by default through M0-M4,
+  // and the release gate caught what that costs: time-to-first-finding on a
+  // 207-file tree went 4.5s -> 45s, a 7.6x regression on the ONE metric
+  // bench/ttff/runner.mjs's own header calls the binding constraint for this
+  // product's vibecoder ICP ("how long until the FIRST useful result, not
+  // aggregate F1"). Resolving history for every finding is simply not what a
+  // first-time user is waiting for. It stays one flag away, and CI/compliance
+  // callers that DO want it pass `--provenance` explicitly.
+  //
+  // `disabled` therefore starts true, and any provenance-shaped flag flips it
+  // off — asking for `--provenance-since` or `--require-provenance` is asking
+  // for provenance, and making the user also pass a bare `--provenance`
+  // alongside it would be a papercut with no upside.
+  const result = { mode: 'standard', since: null, timeoutMs: undefined, includeEmail: false, pseudonymize: false, requireProvenance: false, disabled: true, warning: null };
+  const warnings = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (typeof a !== 'string' || !a.startsWith('--')) continue;
+    // BOTH `--flag value` and `--flag=value`, because parseArgs() above accepts
+    // both for every other flag in this CLI and an operator has no way to know
+    // this one parser is different. Exact-string matching silently ignored
+    // `--provenance=deep` / `--provenance-since=v1.0.0` /
+    // `--provenance-timeout=30000` — no warning, defaults quietly used.
+    //
+    // Split on the FIRST `=` and keep the whole remainder, rather than
+    // parseArgs's `split('=', 2)` which drops everything after a second `=`.
+    // A git ref (`--provenance-since=refs/tags/v1=rc1`) is a legal value and
+    // truncating it would be a worse failure than the one being fixed.
+    const eq = a.indexOf('=');
+    const key = eq === -1 ? a : a.slice(0, eq);
+    const inline = eq === -1 ? undefined : a.slice(eq + 1);
+    // `--flag value` consumes the NEXT argv entry only when there is no inline
+    // value; a value that itself starts with `--` is another flag, not this
+    // one's argument.
+    const takeValue = () => {
+      if (inline !== undefined) return inline;
+      const next = argv[i + 1];
+      if (next !== undefined && !String(next).startsWith('--')) { i++; return next; }
+      return undefined;
+    };
+
+    if (key === '--no-provenance') result.disabled = true;
+    else if (key === '--provenance') {
+      result.disabled = false;
+      // The SPACE form only claims the next token when it actually names a
+      // mode. `--provenance` is legal on its own (provenance is on by default;
+      // the flag is how you say "standard, explicitly"), and this CLI's target
+      // is nearly always a positional — `scan --provenance ./src` must scan
+      // `./src`, not report `unrecognised mode './src'`. parseArgs() does its
+      // own positional collection over the same argv, so consuming here never
+      // steals the path from it, but the warning would still be a lie.
+      //
+      // The INLINE form has no such ambiguity: `--provenance=x` can only ever
+      // be a mode, so an unknown one is a typo worth naming.
+      const v = inline !== undefined
+        ? inline
+        : (PROVENANCE_MODES.has(String(argv[i + 1])) ? argv[++i] : undefined);
+      if (v === 'deep' || v === 'standard' || v === undefined) {
+        result.mode = v || 'standard';
+      } else {
+        warnings.push(`unrecognised --provenance mode '${v}' (expected standard|deep), running standard`);
+      }
+    } else if (key === '--provenance-since') { result.since = takeValue() ?? null; result.disabled = false; }
+    else if (key === '--provenance-timeout') {
+      // MILLISECONDS, and validated as such. `parseInt` alone turned
+      // `--provenance-timeout 30s` into 30 — a 30-MILLISECOND budget that
+      // expires before the first `git blame` returns, so every finding came
+      // back `budget_exhausted` and nothing said why. A missing value produced
+      // NaN, which `if (_provFlags.timeoutMs)` then discarded silently. Both
+      // now warn and fall back to the engine default rather than inventing a
+      // budget the operator did not ask for. The unit is fixed by the env var
+      // this flag feeds, AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS.
+      const raw = takeValue();
+      if (raw === undefined) {
+        warnings.push('--provenance-timeout requires a value in milliseconds; using the default budget');
+      } else if (!/^\d+$/.test(String(raw).trim()) || parseInt(raw, 10) <= 0) {
+        warnings.push(`--provenance-timeout expects a positive integer number of MILLISECONDS, got '${raw}'; using the default budget`);
+      } else {
+        result.timeoutMs = parseInt(raw, 10);
+        result.disabled = false;
+      }
+    }
+    else if (key === '--include-author-email') { result.includeEmail = true; result.disabled = false; }
+    else if (key === '--pseudonymize-authors') { result.pseudonymize = true; result.disabled = false; }
+    else if (key === '--require-provenance') { result.requireProvenance = true; result.disabled = false; }
+  }
+  // One field, so a caller that prints `warning` cannot drop the second one.
+  result.warning = warnings.length ? warnings.join('; ') : null;
+  return result;
+}
+
 async function cmdScan(args) {
   // NON_MUTATING_SCAN_PRD S1 — a scan is an observation; --no-state makes it one.
   if (args.flags['no-state']) {
@@ -488,12 +606,67 @@ async function cmdScan(args) {
     process.stderr.write(`[pr-mode] scanning files changed since: ${changedSince}\n`);
   }
 
+  // Finding Provenance (M0/M1) — translate --provenance/--no-provenance/etc.
+  // into the env vars engine.js already reads. Must run before runScan()
+  // below, same as the --deep/--no-deep wiring above.
+  const _provFlags = parseProvenanceFlags(process.argv.slice(2));
+  if (_provFlags.warning) console.error(`Warning: ${_provFlags.warning}`);
+  if (_provFlags.disabled) process.env.AGENTIC_SECURITY_NO_PROVENANCE = '1';
+  process.env.AGENTIC_SECURITY_PROVENANCE_MODE = _provFlags.mode;
+  if (_provFlags.since) process.env.AGENTIC_SECURITY_PROVENANCE_SINCE = _provFlags.since;
+  if (_provFlags.timeoutMs) process.env.AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS = String(_provFlags.timeoutMs);
+  if (_provFlags.includeEmail) process.env.AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL = '1';
+  if (_provFlags.pseudonymize) process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS = '1';
+
   const { scan, meta } = await runScan(target, {
     changedSince,
     onProgress: (p) => {
       if (process.stderr.isTTY) process.stderr.write(`\r[${p.phase}] ${p.current}/${p.total} ${p.file}     `);
     },
   });
+  // --require-provenance: flag (never fail) any finding whose provenance
+  // isn't resolved, via scanHealth — deliberately independent of the
+  // severity-based exit code computed by exitCodeFor() at the end of this
+  // function. 'uncommitted' is a legitimate terminal status (the finding is
+  // in a file with no git history yet), not an incomplete one.
+  if (_provFlags.requireProvenance) {
+    // ALL FOUR channels (scanner/CLAUDE.md: findings / secrets / supplyChain /
+    // logicVulns). Checking only `scan.findings` made the flag report a clean
+    // bill of provenance health for a scan whose SCA and secrets findings had
+    // none — and report/index.js's normalizeFindings ships all four to the
+    // user as findings, so "every finding" has to mean all four here too.
+    const incomplete = [];
+    for (const [channel, bucket] of [
+      ['findings', scan.findings], ['secrets', scan.secrets],
+      ['supplyChain', scan.supplyChain], ['logicVulns', scan.logicVulns],
+    ]) {
+      for (const f of (bucket || [])) {
+        if (!f || typeof f !== 'object') continue;
+        if (isProvenanceHealthy(f.findingProvenance)) continue;
+        incomplete.push(f.id || f.stableId || `${channel}:${f.name || f.file || f.type || 'entry'}`);
+      }
+    }
+    if (incomplete.length > 0) {
+      // Written the way EVERY other scan-health signal is written — a sentence
+      // in `conditions[]` plus a `complete` -> `partial` status demotion (see
+      // pipeline/scan-health.js's applyFreshness, the same "patch it on from
+      // bin/ after the engine already built scanHealth" pattern). The previous
+      // version set a bespoke `scanHealth.provenanceIncomplete` key that NO
+      // consumer reads: pipeline/assurance-mode.js and
+      // posture/compliance-policy.js both read `status`/`conditions[]` only, so
+      // --require-provenance changed no behaviour anywhere. The array is still
+      // carried, for a consumer that wants the ids, but it is no longer the
+      // only trace.
+      const condition = `--require-provenance: ${incomplete.length} finding(s) have unresolved provenance`;
+      scan.scanHealth = {
+        ...(scan.scanHealth || {}),
+        conditions: [...(Array.isArray(scan.scanHealth?.conditions) ? scan.scanHealth.conditions : []), condition],
+        status: (scan.scanHealth?.status ?? 'complete') === 'complete' ? 'partial' : scan.scanHealth.status,
+        provenanceIncomplete: incomplete,
+      };
+    }
+  }
+
   // The BOM/attestation emitters stamp the producing engine's version into
   // their metadata; carry the real package version so it can never drift.
   if (meta && meta.engineVersion == null) meta.engineVersion = PKG_VERSION;
@@ -745,7 +918,20 @@ async function cmdScan(args) {
   // per-finding list (with inline why-it-matters / how-it-fires / fix depth) so
   // "Show ALL findings" actually shows them. Add --verbose for full narration + code.
   if (args.flags.firehose && (!format || format === 'ship' || format === 'summary')) {
-    body += '\n\n' + toCLI(scan, { verbose });
+    // `provenance` reuses --verbose rather than adding a seventh provenance
+    // flag: --verbose already means "print the extra per-finding narration"
+    // (explainParts's why/how/fix bodies), and the provenance block is exactly
+    // that kind of detail. Before this, explainProvenance()/toCLI's
+    // `{provenance}` option had NO production caller at all — it was reachable
+    // only from its own unit test, so a feature that was built, reviewed and
+    // shipped could never be seen by a user.
+    //
+    // Gated on provenance actually having run, too: with --no-provenance (or
+    // AGENTIC_SECURITY_NO_PROVENANCE=1) every finding carries a `not_available`
+    // record, and printing five lines of "we did not look" per finding is noise
+    // the operator explicitly opted out of.
+    const provenanceOn = !_provFlags.disabled && process.env.AGENTIC_SECURITY_NO_PROVENANCE !== '1';
+    body += '\n\n' + toCLI(scan, { verbose, provenance: verbose && provenanceOn });
   }
 
   // v3 next-gen — supplementary blocks for human-readable formats. These
@@ -1054,7 +1240,7 @@ async function cmdCi(args) {
     console.error(`[ci] --assurance must be one of: ${ASSURANCE_MODES.join('|')} (got '${assuranceMode}')`);
     return 1;
   }
-  const assuranceVerdict = evaluateAssuranceMode(assuranceMode, scan.scanHealth);
+  const assuranceVerdict = evaluateAssuranceMode(assuranceMode, scan.scanHealth, findings);
   if (!assuranceVerdict.ok) {
     console.error(`[ci] assurance gate FAILED (mode=${assuranceMode}): ${assuranceVerdict.reason}`);
     return 1;
@@ -2162,6 +2348,53 @@ async function cmdCompliance(args) {
 
 async function cmdAttest(args) {
   const scanRoot = path.resolve(args.flags.root || '.');
+
+  if (args.flags.provenance) {
+    const {
+      buildProvenanceEvidenceBundle, signProvenanceEvidenceBundle, ensureKeyPair,
+    } = await import('../src/posture/provenance-evidence-bundle.js');
+
+    let scan;
+    try { scan = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8')); }
+    catch { console.error('No .agentic-security/last-scan.json — run a scan first.'); return 2; }
+
+    const findings = scan.findings || [];
+    const wanted = args.flags.provenance === true ? undefined : args.flags.provenance;
+    // `--provenance` alone (boolean flag) attests every finding WITH
+    // findingProvenance present; `--provenance <id>` scopes to one.
+    const subset = (wanted ? findings.filter((f) => f.id === wanted || f.stableId === wanted) : findings)
+      .filter((f) => f.findingProvenance);
+    if (!subset.length) {
+      console.error(wanted ? `No finding matching "${wanted}" with findingProvenance.` : 'No findings with findingProvenance to attest.');
+      return 2;
+    }
+
+    const kp = ensureKeyPair();
+    if (kp.created) console.error(`Generated a new signing key at ${kp.privateKey} (public: ${kp.publicKey}).`);
+
+    const outDir = statePath(scanRoot, 'attestations');
+    fs.mkdirSync(outDir, { recursive: true });
+    // repoIdentity: best-effort, from the same `git remote` lookup other
+    // provenance modules avoid (no such lookup exists yet) — keep it simple,
+    // pass null when unavailable rather than inventing a git-remote reader
+    // here. A future task can enrich this; the field degrades honestly.
+    const meta = { engineVersion: scan.engineVersion || null, repoIdentity: null, head: scan.commit || null };
+
+    let n = 0;
+    for (const f of subset) {
+      const bundle = signProvenanceEvidenceBundle(buildProvenanceEvidenceBundle(f, meta), kp.privateKeyPem);
+      const name = `provenance-${(f.stableId || f.id || `finding-${n}`)}.json`.replace(/[^\w.-]/g, '_');
+      fs.writeFileSync(path.join(outDir, name), JSON.stringify(bundle, null, 2) + '\n');
+      n++;
+    }
+    console.log(`Signed ${n} provenance evidence bundle(s) → ${path.relative(scanRoot, outDir)}/`);
+    console.log(`Public key (share this with whoever verifies): ${kp.publicKey}`);
+    console.log('');
+    console.log('A bundle proves its contents are unmodified since signing. It does NOT');
+    console.log('prove the origin commit is correctly identified — read confidence.level.');
+    return 0;
+  }
+
   const {
     ensureKeyPair, buildEvidenceBundle, signEvidenceBundle,
   } = await import('../src/posture/evidence-bundle.js');
@@ -2302,6 +2535,37 @@ async function cmdVerifyAttestation(args) {
     return 0;
   }
 
+  // Finding Provenance PRD M4 §4.1: a provenance evidence bundle
+  // (schema: agentic-security/provenance-evidence@1) is a fourth distinct
+  // shape this same command can be handed — same auto-detection chain as
+  // the ComplianceEvidence branch above, dispatched by schema marker
+  // rather than a new CLI verb. Must be checked BEFORE the fallback
+  // verifyEvidenceBundle() call below, which assumes evidence-bundle.js's
+  // own shape (`.evidence`, `.finding` with severity/vuln/file/line) and
+  // would misinterpret a provenance bundle.
+  const { verifyProvenanceEvidenceBundle, PROVENANCE_BUNDLE_SCHEMA } = await import('../src/posture/provenance-evidence-bundle.js');
+  if (bundle.schema === PROVENANCE_BUNDLE_SCHEMA) {
+    const pr = verifyProvenanceEvidenceBundle(bundle, publicKeyPem);
+    if (!pr.ok) { console.error(`✗ INVALID — ${pr.reason}`); return 1; }
+    const p = bundle.provenance || {};
+    console.log('✓ VALID — the provenance record is exactly what the signer attested.');
+    console.log('');
+    console.log(`  finding: ${bundle.finding?.stableId || bundle.finding?.id || '?'}`);
+    console.log(`  status: ${p.status || 'n/a'}   method: ${p.method || 'n/a'}`);
+    // FR-PROV-026: findingOrigin.authorName is untrusted git commit metadata
+    // (this bundle's signature only proves the BUNDLE wasn't tampered with —
+    // it says nothing about what the original commit author put in their
+    // name — see the "Signed, portable evidence" section of the root
+    // CLAUDE.md), printed straight to the terminal by `verify-attestation`.
+    if (p.findingOrigin) console.log(`  origin: ${p.findingOrigin.commit || '?'} by ${sanitizeForTerminal(p.findingOrigin.authorName) || '?'} on ${p.findingOrigin.authorDate || '?'}`);
+    console.log(`  confidence: ${p.confidence?.level || 'n/a'} (${p.confidence?.score ?? 'n/a'})`);
+    if ((p.limitations || []).length) console.log(`  limitations: ${p.limitations.join('; ')}`);
+    console.log('');
+    console.log(`  proves:        ${bundle.proves}`);
+    console.log(`  does NOT prove: ${bundle.doesNotProve}`);
+    return 0;
+  }
+
   const r = verifyEvidenceBundle(bundle, publicKeyPem);
   if (!r.ok) {
     console.error(`✗ INVALID — ${r.reason}`);
@@ -2947,4 +3211,31 @@ async function main() {
   }
 }
 
-main();
+// Guard against running as the CLI entry point vs. being `import`ed (e.g. by
+// scanner/test/cli/provenance-flags.test.js, which imports parseProvenanceFlags
+// for a unit test). Without this, any import of this module — for a single
+// named export — re-runs the entire CLI dispatch and calls process.exit(),
+// killing whatever process did the importing.
+//
+// `import.meta.url === file://${process.argv[1]}` looks equivalent but is
+// NOT: when this script is invoked through a symlink (exactly what
+// `npm install -g`, `npx`, and `node_modules/.bin/<name>` all do for a
+// package's `bin` entries — which is the documented `npx
+// @clear-capabilities/agentic-security-scanner` install path), Node
+// resolves `import.meta.url` to the symlink's realpath while
+// `process.argv[1]` stays the symlink path as invoked, so the two never
+// match, the guard is always false, and the CLI silently exits with no
+// output. `import.meta.main` is resolved correctly through a symlink —
+// verified live through an actual symlink, not just read about — see the
+// Task 17 fix report. It was added in Node v24.2.0 (backported to
+// v22.18.0) and is currently Stability 1.0 (early development) per Node's
+// own docs — NOT stable, and NOT available on v20.11 as an earlier
+// version of this comment incorrectly claimed. Concretely: it is
+// `undefined` on Node 24.0.0/24.1.x, which satisfy this repo's declared
+// `engines.node: ">=24.0.0"` floor, so `import.meta.main` alone would
+// reproduce this exact bug (main() silently never runs) on a plain
+// non-symlinked invocation under those two point releases. The `??`
+// fallback below covers that gap without bumping the engines floor.
+if (import.meta.main ?? (import.meta.url === `file://${process.argv[1]}`)) {
+  main();
+}

package/dist/113.index.js

@@ -492,8 +492,8 @@ var external_node_child_process_ = __webpack_require__(1421);
 var external_node_fs_ = __webpack_require__(3024);
 // EXTERNAL MODULE: external "node:path"
 var external_node_path_ = __webpack_require__(6760);
-// EXTERNAL MODULE: ./src/engine.js + 211 modules
-var engine = __webpack_require__(7087);
+// EXTERNAL MODULE: ./src/engine.js + 229 modules
+var engine = __webpack_require__(7691);
 ;// CONCATENATED MODULE: ./src/posture/fix-honesty-gate.js
 // Deterministic honesty gates on fix / finding output (#7).
 //
@@ -904,7 +904,15 @@ async function verifyPatch({
   const fileContents = { ...files };
   let scan;
   try {
-    scan = await (0,engine/* runFullScan */.wW)({ fileContents, depFileContents, scanRoot }, () => {});
+    // `provenance:false` is REQUIRED here, not an optimisation. This scan is
+    // deliberately scoped to just the patched file(s), so its finding set is a
+    // tiny subset of the project's. updateLifecycle marks every open stableId
+    // NOT in the set it is handed as `remediated` — so a single fix
+    // verification (every /fix, apply_fix, and autopilot iteration runs one)
+    // would mass-mark the rest of the project as remediated, then
+    // `reintroduced` on the next real scan. The patched content is also not
+    // committed, so there is no history to resolve provenance against anyway.
+    scan = await (0,engine/* runFullScan */.wW)({ fileContents, depFileContents, scanRoot, provenance: false }, () => {});
   } catch (e) {
     return { ok: false, reason: 'rescan-failed', error: e.message };
   }