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

package/CHANGELOG.md

@@ -11,6 +11,396 @@
 
 
 
+## 0.147.0 — Documentation overhaul: a cohesive assurance-platform story, verified against the shipped code
+
+The 0.144.0 Assurance Hardening release shipped a real 3-state ship verdict,
+a model-egress policy gate, risk-dollar scenario disclosure, and per-artifact
+retention/encryption — but the docs describing it, and the README's whole
+front-door story, hadn't caught up. This release rewrites both, built
+exclusively from real, re-verified source rather than the original
+documentation brief's assumptions (which turned out to contain several
+fabricated CLI flags and vocabularies — a `scan --assurance` flag that
+doesn't exist, `--assurance` is `ci`-only; a fictional `--explain-health`
+flag; nine invented verify-verdict strings; a fictional unified compliance
+state model where three separate, differently-cased vocabularies actually
+exist).
+
+**README** rewritten around a 5-capability story (Find It / Prove It / Fix
+It Safely / Govern It / Explain It), a corrected 5-minute quickstart, the
+real 3-state ship verdict as a running example, and persona-based
+navigation (Developer / AppSec / Privacy / Compliance / Platform
+Engineering).
+
+**16 new docs**: `docs/walkthroughs/{assurance-modes,scan-health,
+finding-evidence,verified-remediation,privacy-data-flow,model-egress}.md`;
+`docs/architecture/finding-lifecycle.md`; `docs/concepts.md`
+(evidence-before-severity, deterministic-vs-model-assisted);
+`docs/governance/state-and-retention.md`; `docs/guides/risk-dollars.md`;
+`docs/examples/README.md` (a 13-entry gallery); `docs/reference/
+{output-schema,glossary}.md`; `docs/troubleshooting/scan-health.md`; and two
+real, captured Data Flow Explorer browser screenshots at `docs/assets/`.
+
+**A new doc-testing tool**, `scripts/verify-doc-examples.mjs`: parses the
+real CLI dispatch table out of `bin/agentic-security.js` at runtime (so it
+can't drift out of sync with the CLI the way a hand-maintained list would)
+to catch fabricated commands and the specific `<subcommand> --help`
+landmine (passing `--help` to a subcommand silently runs the real command
+instead of printing help — only bare `agentic-security help` is valid),
+plus JSON-block and Mermaid-syntax sanity checks. Deliberately not wired
+into any gate — a standalone `npm run docs:verify-examples`.
+
+**Existing docs corrected**, not just extended: `docs/guides/
+{quickstart,scanning,compliance,ci-setup,finding-provenance}.md`,
+`docs/reference/{cli,configuration}.md`, `docs/ARCHITECTURE.md`,
+`docs/README.md`, and several `commands/`/`skills/` files carried stale
+claims — the most consequential being that `scan` was documented as
+defaulting finding-provenance ON, when it actually defaults OFF (`ci`
+defaults it ON; this asymmetry exists because plain provenance resolution
+cost a measured 4.5s→45s regression on a 207-file tree, the same
+measurement behind this project's own TTFF benchmark).
+
+## 0.146.0 — Data Flow Explorer: trace sensitive data through your architecture, not just through one finding
+
+Every prior release answers "is this line of code dangerous?" This one adds a
+different question: "where does this piece of sensitive data actually go, and
+what protects it along the way?" `agentic-security dataflow` builds a
+`DataFlowGraph` from a real scan — sources, sinks, the data elements that
+flow between them, and a verdict per hop on transit/at-rest/handling
+protection — and a new local, read-only, loopback-only server
+(`agentic-security explore`) serves it to a clickable UI. Six milestones,
+built in dependency order over this release cycle:
+
+**The graph itself (Milestones 0-2).** A stable-ID'd, schema-versioned graph
+contract; an interprocedural field-identity taint engine purpose-built for
+this graph (deliberately separate from the SAST engine's own taint
+analysis — different state shape, different precision goals) with
+context-sensitive summaries and a compact path-provenance DAG that tracks
+*why* a field reached a sink, not just *that* it did; source/sink/
+transformation registries reclassifying this project's existing detection
+catalogs into the graph's own vocabulary; and protection-verdict analyzers
+for transit (TLS presence and validity), at-rest (encryption-before-store),
+and handling (masking/hashing/tokenization — never treated as synonyms).
+
+**A local server and reference UI (Milestone 3).** `agentic-security explore`
+— the first HTTP server anywhere in this codebase (the MCP and LSP servers
+are both stdio) — serves the signed, already-scanned graph read-only,
+loopback-only, to a zero-build-step frontend prototype with architecture,
+privacy-lifecycle, and evidence-trace views.
+
+**Export and decision-intelligence surfaces (Milestone 4).** JSON/CSV/HTML/
+PNG/PDF/SVG export; a Regulatory Obligation Overlay mapping graph facts
+against bundled compliance frameworks (never claiming "compliant" from a
+single mapping); an Executive Risk Story mode ranking flows on nine
+transparent, disclosed factors — never a blended, uncalibrated score; a
+Data-Flow Time Machine (`dataflow diff`) comparing two scans with real
+drift-policy alerting on newly-introduced disclosures; and Third-Party and
+Cross-Border Intelligence, keeping legal/jurisdiction facts honestly
+`unknown` rather than inferred from brand recognition.
+
+**Simulation, corroboration, and cross-repo linkage (Milestone 5).** A
+What-If Architecture Simulator (`dataflow scenario apply`) that clones and
+overrides a graph to test a hypothetical fix, never mutating the real scan,
+with every simulated verdict marked `HYPOTHETICAL` and `assumed`-graded so
+it can never be mistaken for a real one; Blast-Radius Impact Assessment and
+a Remediation Command Center with a hash-chained ledger enforcing that
+closing an item requires either a clean rescan or an explicit, permitted
+manual attestation — and that a later regression reopens it automatically;
+a Runtime-Corroborated Digital Twin (`dataflow observations import`) that
+layers operator-supplied runtime telemetry onto the static graph through a
+closed-world contract that rejects, not merely redacts, any field capable
+of carrying a payload value; per-language coverage-tier disclosure so a
+partially-supported language is labeled as such rather than silently
+under-reported; and `federate declare` — an operator-declared edge between
+two independently-scanned repositories' own graphs, with each graph staying
+its own separate, unmodified artifact.
+
+**New top-level commands:** `explore`, `dataflow`, `governance`,
+`remediation`, `federate` — the latter three write operator-declared
+config through the same reviewable contract (preview, version guard,
+backup, audit event) established for exactly this class of write.
+
+**On rigor, again.** As with 0.145.0's own provenance work, a dedicated
+final-review pass — after every task-level review and a green test
+suite — found real Blocking or Important bugs in nearly every one of
+these sub-projects: a remediation item that could be marked verified from
+a snapshot chronologically *older* than the incident it was supposed to
+fix; a runtime-observation payload-refusal grammar that closed single-value
+smuggling but missed the same payload split across array elements; a
+cross-repo link's own self-consistency digest compared against the wrong
+half of a redacted export, so an untampered file permanently read as
+tampered; and — found only in this release's own post-completion
+re-audit, prompted by checking every named acceptance criterion's text
+against the actual shipped code rather than trusting a summary — one
+acceptance criterion (`AC-26`, on the What-If Simulator) that had never
+been checked against its own literal wording by any prior document, and
+was quietly unmet until this audit closed it. Every one of these was
+found, fixed, and independently re-verified — including personally
+reproducing the bug and its fix live, not just re-reading a diff — before
+this release.
+
+**Disclosed, not built.** Full graph-merge across repositories (only
+declared, single-edge cross-repo links ship); synthetic node/edge
+insertion for the What-If Simulator (every node/edge today derives from a
+real registry decision or call site — inventing one has no precedent yet);
+automatic destination/schema correlation for cross-repo edges (needs
+prerequisite work — schema-derived edges, fuller destination resolution —
+that isn't built); an HTML-table stress-test pass for the largest graphs;
+config-declared (as opposed to runtime-observed) corroboration for the
+Digital Twin, folded into already-scoped backlog rather than duplicated.
+None of these block the acceptance criteria this release's milestones are
+gated on.
+
+## 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-*`)