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

package/src/posture/provenance-evidence-bundle.js

@@ -0,0 +1,144 @@
+// Signed provenance evidence bundles (Finding Provenance PRD, M4 §4.1).
+//
+// Sibling to posture/evidence-bundle.js, not a generalization of it — that
+// module's bundle shape (proofTier, taintPath, exploitability...) answers
+// "is this finding real"; this one answers "who/when introduced it, how
+// sure are we." Forcing one shape to cover both would leave half of every
+// bundle null. Same four-function pattern (build/sign/verify + a schema
+// string + a top-level-key allowlist), same Ed25519 key material — reused,
+// not reimplemented.
+//
+// The allowlisted fields mirror provenance/coordinator.js's own
+// computeDigest() material EXACTLY (stableId, findingOrigin.commit,
+// branchIntroduction.commit, evidenceAttribution role:path:line:commit
+// strings, method, confidence.reasons, limitations) plus repo/HEAD identity
+// (not in computeDigest's material, since that digest never leaves the repo
+// it was computed in, but a bundle does). Everything here is copied from
+// what findingProvenance already computed. Nothing is inferred.
+//
+// canonicalJson vs canonicalBytes — resolved before writing this file
+// -------------------------------------------------------------------
+// evidence-bundle.js exports TWO canonicalisation helpers, not one, and they
+// are not interchangeable. `canonicalJson(value)` is a pure, shape-agnostic
+// deterministic serialiser (sorted keys at every level, order-preserving
+// arrays) — safe to reuse for any bundle shape. `canonicalBytes(bundle)`
+// is NOT generic: it hardcodes evidence-bundle.js's own six top-level keys
+// (`schema, finding, evidence, engine, proves, doesNotProve`) when building
+// the object it signs. Reusing `canonicalBytes` here would silently sign a
+// filtered object missing this module's `repo` and `provenance` fields
+// (and would read `bundle.evidence`, which a provenance bundle never has) —
+// exactly the EA-03 failure mode the allowlist check below exists to catch,
+// just introduced from the signing side instead of the verifying side. So
+// this module imports the generic `canonicalJson` (as the brief's Step 1
+// sketch already did) and signs `canonicalJson(bundle)` directly, since
+// `buildProvenanceEvidenceBundle` never puts anything on the unsigned
+// object beyond this module's own allowlisted fields.
+
+import * as crypto from 'node:crypto';
+import { ensureKeyPair, keyPaths, canonicalJson } from './evidence-bundle.js';
+
+export const PROVENANCE_BUNDLE_SCHEMA = 'agentic-security/provenance-evidence@1';
+
+const PROVES = 'This bundle\'s contents are exactly what was signed at attestation time.';
+const DOES_NOT_PROVE = 'This bundle does NOT prove the origin commit is correctly identified — read confidence.level and limitations for that. It proves the RECORD is unmodified, not that the record is right.';
+
+/**
+ * Build an unsigned provenance bundle from one finding's findingProvenance.
+ * Returns null for a finding with no findingProvenance at all (nothing to
+ * attest) — this is a caller error (attest a scan before its provenance
+ * pass ran), not a case to paper over with an empty bundle.
+ */
+export function buildProvenanceEvidenceBundle(finding, { engineVersion, repoIdentity, head } = {}) {
+  if (!finding || typeof finding !== 'object') return null;
+  const fp = finding.findingProvenance;
+  if (!fp || typeof fp !== 'object') return null;
+  return {
+    schema: PROVENANCE_BUNDLE_SCHEMA,
+    finding: {
+      id: finding.id ?? null,
+      stableId: finding.stableId ?? null,
+    },
+    repo: {
+      identity: repoIdentity ?? null,
+      head: head ?? fp.analysisBasis?.head ?? null,
+    },
+    provenance: {
+      status: fp.status ?? null,
+      findingOrigin: fp.findingOrigin
+        ? {
+            commit: fp.findingOrigin.commit ?? null,
+            authorName: fp.findingOrigin.authorName ?? null,
+            authorDate: fp.findingOrigin.authorDate ?? null,
+            summary: fp.findingOrigin.summary ?? null,
+          }
+        : null,
+      branchIntroduction: fp.branchIntroduction
+        ? { commit: fp.branchIntroduction.commit ?? null, branch: fp.branchIntroduction.branch ?? null }
+        : null,
+      evidenceAttribution: (fp.evidenceAttribution || []).map((n) => ({
+        role: n.role ?? null, path: n.path ?? null, line: n.line ?? null, commit: n.commit ?? null,
+      })),
+      method: fp.method ?? null,
+      confidence: fp.confidence
+        ? { level: fp.confidence.level ?? null, score: fp.confidence.score ?? null, reasons: fp.confidence.reasons || [] }
+        : null,
+      limitations: fp.limitations || [],
+      // M4 §4.2 final-review fix: this module was written (Task 1) before
+      // the cross-repo lineage feature existed (Task 5), so a
+      // cross-repo-resolved origin's boundary-crossing marker was dropped
+      // from the signed bundle — a foreign repository's commit SHA and a
+      // real author name, with no MACHINE-READABLE signal that the origin
+      // crossed a repository boundary (only the prose in `limitations`
+      // said so, and a programmatic verifier does not read prose). Nested
+      // under `provenance` alongside the fields above, so it is part of
+      // what gets signed — never a new top-level key.
+      historyCoverage: { crossRepoLineage: fp.historyCoverage?.crossRepoLineage ?? false },
+    },
+    engine: { engineVersion: engineVersion ?? null },
+    proves: PROVES,
+    doesNotProve: DOES_NOT_PROVE,
+  };
+}
+
+export function signProvenanceEvidenceBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, Buffer.from(canonicalJson(bundle), 'utf8'), privateKeyPem);
+  return {
+    ...bundle,
+    signature: { algorithm: 'ed25519', canonicalisation: PROVENANCE_BUNDLE_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+const PROVENANCE_BUNDLE_TOP_LEVEL_KEYS = new Set([
+  'schema', 'finding', 'repo', 'provenance', 'engine', 'proves', 'doesNotProve', 'signature',
+]);
+
+/**
+ * Verify with a PUBLIC key only. Rejects any top-level key outside the
+ * allowlist BEFORE checking the signature — same EA-03 fix evidence-bundle.js
+ * carries: a signature only covers the bytes it was computed over, so an
+ * unknown key stapled on after signing would otherwise verify as authentic.
+ */
+export function verifyProvenanceEvidenceBundle(bundle, publicKeyPem) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  if (bundle.schema !== PROVENANCE_BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  const unknownKeys = Object.keys(bundle).filter((k) => !PROVENANCE_BUNDLE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  const { signature, ...unsigned } = bundle;
+  let ok = false;
+  try {
+    ok = crypto.verify(null, Buffer.from(canonicalJson(unsigned), 'utf8'), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  return ok
+    ? { ok: true, reason: null }
+    : { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+}
+
+export { ensureKeyPair, keyPaths };

package/src/posture/sbom-diff.js

@@ -24,7 +24,8 @@ import * as fs from 'node:fs';
 import { statePath, stateWritesEnabled } from './state-dir.js';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 const HISTORY_DIR = 'sbom-history';
 
@@ -32,9 +33,21 @@ function _historyDir(scanRoot) {
   return statePath(scanRoot, HISTORY_DIR);
 }
 
+// `scanRoot` is the scanned project's repository, not this project's own
+// trusted checkout — hardened per FR-PROV-024 / the second Finding
+// Provenance PRD audit sweep (found missing here by a follow-up review that
+// grepped for `child_process` usage beyond just `execFileSync('git'` call
+// sites). `rev-parse HEAD` was VERIFIED not to itself trigger
+// `core.fsmonitor`/a hook (it touches neither the working tree nor the
+// index), so this is not a second live RCE — but leaving
+// `GIT_CONFIG_NOSYSTEM`/`GIT_TERMINAL_PROMPT`/`core.hooksPath` unset here
+// still violated this module's own "every git call routes through
+// hardenGitArgs/hardenGitEnv" contract, and `execSync` (a shell string) is
+// gratuitous risk this call never needed — `rev-parse HEAD` has no
+// caller-controlled input to interpolate at all.
 function _gitHead(scanRoot) {
   try {
-    return execSync('git rev-parse HEAD', { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return execFileSync('git', hardenGitArgs(['rev-parse', 'HEAD']), { cwd: scanRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() }).trim();
   } catch { return null; }
 }
 

package/src/posture/secret-history.js

@@ -12,6 +12,7 @@
 // needs network and is deferred — see the rollup.
 
 import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 // Pull the post-image (added) lines out of a unified diff: lines starting with
 // a single '+' (not the '+++' file header). Returns reconstructed text.
@@ -62,8 +63,15 @@ export function sweepGitHistory(scanRoot, detectFn, { maxCommits = 50, timeoutMs
   if (!scanRoot || typeof detectFn !== 'function') return [];
   let out;
   try {
-    out = execFileSync('git', ['-C', scanRoot, 'log', '-p', '-n', String(maxCommits), '--no-color', '--no-merges', '--no-textconv'],
-      { encoding: 'utf8', maxBuffer: 96 * 1024 * 1024, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'] });
+    // Second independent Finding Provenance PRD audit (FR-PROV-024): this
+    // scanRoot is a scanned repository, not this project's own trusted
+    // checkout. `--no-textconv` alone (the pre-existing hardening here) closes
+    // the .gitattributes textconv surface but NOT `core.fsmonitor` /
+    // `core.hooksPath` — this `log -p` call renders every historical commit's
+    // diff content, the same shape verified exploitable in
+    // provenance/git-evidence.js, so it gets the full hardening too.
+    out = execFileSync('git', hardenGitArgs(['-C', scanRoot, 'log', '-p', '-n', String(maxCommits), '--no-color', '--no-merges', '--no-textconv']),
+      { encoding: 'utf8', maxBuffer: 96 * 1024 * 1024, timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() });
   } catch { return []; }
   const parts = out.split(/^commit ([0-9a-f]{7,40})/m); // [pre, sha, body, sha, body, ...]
   const findings = [];

package/src/posture/state-dir.js

@@ -130,6 +130,14 @@ export function isSafeStateDir(dir) {
 // per-caller discipline already failed once: its header records a user who
 // uninstalled the plugin after stray state directories broke their build.
 let _stateWritesEnabled = true;
+// Category-scoped override (M2 §2.4 performance fix): when the blanket
+// switch above is OFF, a category listed here still writes. Exists for
+// lsp/server.js, which needs the provenance disk cache live on every
+// keystroke-save while every OTHER state write (dpia.md, lifecycle.json,
+// ...) stays suppressed — see the withStateWritesDisabled call site in
+// lsp/server.js for why the blanket switch alone made every LSP scan pay
+// the FULL uncached provenance-resolution cost on every single save.
+let _enabledCategories = new Set();
 
 /** Turn all state writing off (or back on) for this process. */
 export function setStateWritesEnabled(enabled) {
@@ -148,6 +156,15 @@ export function stateWritesEnabled() {
   return _stateWritesEnabled;
 }
 
+// Category-aware check used by ensureStateDir/safeWriteState below. A
+// caller that never passes `category` behaves EXACTLY as before: it only
+// ever consults the blanket switch.
+function _categoryEnabled(category) {
+  if (process.env.AGENTIC_SECURITY_NO_STATE === '1') return false;
+  if (_stateWritesEnabled) return true;
+  return !!category && _enabledCategories.has(category);
+}
+
 /**
  * Run `fn` with state writes forced off, restoring the PRIOR flag value
  * afterward — for a caller (assurance-hardening PRD FR-704) that must
@@ -157,31 +174,38 @@ export function stateWritesEnabled() {
  * the same process — exactly `apply_fix`'s failure mode this wrapper exists
  * to prevent, via `finally` rather than caller discipline.
  *
- * KNOWN LIMITATION: `_stateWritesEnabled` is process-global, not per-call.
- * Two overlapping calls to this function (or one overlapping a direct
- * setStateWritesEnabled() call) can race and leave the flag in the wrong
- * state for one of them once both finish. mcp/CLAUDE.md already documents
- * an accepted concurrency limitation of the same shape for fix-history.js
- * ("concurrent apply_fix calls can race... today benign... a future
- * stateful tool needs serialization") — this is the same class of risk, not
- * a new one, and this wrapper is still a strict improvement over the
- * alternative it replaces (a caller that writes state UNCONDITIONALLY on
+ * `exceptCategories` lets a caller keep ONE narrow category of write alive
+ * while everything else stays suppressed — see lsp/server.js. Restored via
+ * the same `finally` as the blanket flag, for the same reason.
+ *
+ * KNOWN LIMITATION: `_stateWritesEnabled` and `_enabledCategories` are both
+ * process-global, not per-call. Two overlapping calls to this function (or
+ * one overlapping a direct setStateWritesEnabled() call) can race and leave
+ * the flags in the wrong state for one of them once both finish. mcp/CLAUDE.md
+ * already documents an accepted concurrency limitation of the same shape for
+ * fix-history.js ("concurrent apply_fix calls can race... today benign... a
+ * future stateful tool needs serialization") — this is the same class of
+ * risk, not a new one, and this wrapper is still a strict improvement over
+ * the alternative it replaces (a caller that writes state UNCONDITIONALLY on
  * every call, with no opt-out at all).
  */
-export async function withStateWritesDisabled(fn) {
+export async function withStateWritesDisabled(fn, { exceptCategories = [] } = {}) {
   const prior = _stateWritesEnabled;
+  const priorCategories = new Set(_enabledCategories);
   _stateWritesEnabled = false;
+  for (const c of exceptCategories) _enabledCategories.add(c);
   try {
     return await fn();
   } finally {
     _stateWritesEnabled = prior;
+    _enabledCategories = priorCategories;
   }
 }
 
 // Safe mkdir: only creates .agentic-security/ if the parent has a project marker.
 // Returns the dir on success, null if refused. Logs a warning when refused.
-export function ensureStateDir(scanRoot) {
-  if (!stateWritesEnabled()) return null;
+export function ensureStateDir(scanRoot, { category } = {}) {
+  if (!_categoryEnabled(category)) return null;
   const dir = stateDir(scanRoot);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {
@@ -199,8 +223,8 @@ export function ensureStateDir(scanRoot) {
 
 // Safe write: only writes if isSafeStateDir(parent) returns true.
 // Returns true on success, false if refused or errored.
-export function safeWriteState(filePath, content) {
-  if (!stateWritesEnabled()) return false;
+export function safeWriteState(filePath, content, { category } = {}) {
+  if (!_categoryEnabled(category)) return false;
   const dir = path.dirname(filePath);
   if (!isSafeStateDir(dir)) {
     if (process.env.AGENTIC_SECURITY_DEBUG === '1') {

package/src/posture/vuln-archaeology.js

@@ -34,6 +34,7 @@
 // timeout, degrading to an empty result in a non-repository.
 
 import { execFileSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
 
 const CVE_RE = /\b(?:CVE-\d{4}-\d{4,7}|GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})\b/i;
 
@@ -87,14 +88,19 @@ export function classifyCommit(subject) {
   return { tier: 'mentioned', evidence: `mentions "${noun[0]}" with no fix verb` };
 }
 
+// `scanRoot` is the scanned project's repository, not this project's own
+// trusted checkout — hardened per FR-PROV-024 / the second Finding
+// Provenance PRD audit (same exposure class as
+// provenance/git-evidence.js's `_run`). No `--no-textconv` needed: this
+// invocation has no `-p`/`-L`, so no diff/blob content is rendered.
 function _gitLog(scanRoot, { maxCommits, timeoutMs }) {
   // NUL-delimited records so subjects containing newlines cannot split a
   // record — a commit message is arbitrary user text and must not be able to
   // forge a record boundary.
-  const out = execFileSync('git', [
+  const out = execFileSync('git', hardenGitArgs([
     '-C', scanRoot, 'log', '-n', String(maxCommits), '--no-merges', '--no-color',
     '--name-only', '--format=%x00%H%x1f%aI%x1f%s',
-  ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  ]), { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() });
   const commits = [];
   for (const block of out.split('\0')) {
     if (!block.trim()) continue;

package/src/pr-delta.js

@@ -24,18 +24,27 @@
 // comment) can transform without re-walking IR.
 
 import { spawnSync } from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from './util/git-hardening.js';
 import { runFullScan } from './engine.js';
 
 const FILE_EXT_RE = /\.(?:js|jsx|ts|tsx|mjs|cjs|py|java|cs|kt|go|rb|php|sol|swift|rs|tf|yml|yaml|json|toml|md)$/i;
 const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
 
+// `root` is the PR's repository — a scan target, not this project's own
+// trusted checkout — hardened per FR-PROV-024 / the second Finding
+// Provenance PRD audit (same exposure class as
+// provenance/git-evidence.js's `_run`).
 function _git(root, args) {
-  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync('git', hardenGitArgs(args), { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: hardenGitEnv() });
   return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '' };
 }
 
 function _readFileAtRef(root, ref, file) {
-  const r = _git(root, ['show', `${ref}:${file}`]);
+  // `--no-textconv`: this blob-cat form of `show` (`<ref>:<file>`, not a
+  // diff) was verified NOT reachable via a hostile textconv driver in
+  // current git, same as git-evidence.js's getBlobAtCommit — kept for
+  // defense-in-depth/uniformity.
+  const r = _git(root, ['show', '--no-textconv', `${ref}:${file}`]);
   return r.ok ? r.stdout : null;
 }
 
@@ -56,7 +65,12 @@ async function _scanAtRef(root, ref) {
     const c = _readFileAtRef(root, ref, f);
     if (c != null) fileContents[f] = c;
   }
-  return runFullScan({ fileContents, scanRoot: root }, () => {});
+  // `provenance:false` — a base-ref snapshot, not the current working state.
+  // Beyond the wasted git walks, updateLifecycle marks every open stableId
+  // absent from the finding set it is handed as `remediated`; running the PR
+  // delta gate would silently rewrite the project's lifecycle store from the
+  // base ref's findings.
+  return runFullScan({ fileContents, scanRoot: root, provenance: false }, () => {});
 }
 
 function _summary(findings) {
@@ -71,7 +85,14 @@ function _summary(findings) {
 }
 
 function _changedFiles(root, baseRef, headRef) {
-  const r = _git(root, ['diff', '--name-only', `${baseRef}...${headRef}`]);
+  // `--no-ext-diff`: found during the second-audit-remediation sweep — this
+  // is a `git diff` call site (`--name-only`, no content rendered, so not
+  // itself a verified exploit path today, same as runScan.js's
+  // `changedSince`), but every `diff` invocation in this codebase gets it
+  // uniformly per the live exploit VERIFIED in material-change.js's
+  // classifyGitDiff (external diff drivers fire on `git diff` even with
+  // `--no-textconv`, which is a surface `--no-textconv` alone does not close).
+  const r = _git(root, ['diff', '--name-only', '--no-ext-diff', `${baseRef}...${headRef}`]);
   if (!r.ok) return new Set();
   return new Set(r.stdout.trim().split('\n').filter(Boolean));
 }