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

package/src/posture/provenance/ai-authorship.js

@@ -0,0 +1,68 @@
+// AI-authorship verification hook (Finding Provenance PRD, M4 §4.3).
+//
+// No concrete external signed-commit-metadata standard exists yet to target
+// (the spec's own words) — so this is an extensible REGISTRY a future
+// verifier plugs into, not a hardcoded vendor integration. With nothing
+// registered (today's real state, and likely for some time), every
+// finding's aiAuthorship stays `unknown` — matching the PRD's explicit
+// default: "Unknown unless signed, verifiable generation metadata exists."
+//
+// Scoped to SAST findingOrigin only (see this plan's own scope-correction
+// note) — a transitive/direct SCA origin is a manifest edit, not source
+// authorship in the sense this hook asks about.
+//
+// KNOWN LIMITATION: `commitMeta` (git-evidence.js) is the only shape any
+// verifier registered here ever receives — `{commit, authorName,
+// authorEmail, authorDate, committerDate, summary}`, where `summary` is
+// `%s` (the subject line only), NOT the full commit message body (`%B`).
+// A future verifier that needs to inspect a trailer buried in the body
+// (e.g. a "Co-Authored-By" line that isn't also the subject) cannot see it
+// through this shape today. `commitMeta` is a widely-used shared primitive
+// elsewhere in this directory, so widening it is a bigger, more careful
+// change than this task's budget — deliberately left as a known limitation
+// rather than silently expanding it here.
+
+const _verifiers = new Map();
+
+/**
+ * Register a verifier. `verifyFn(commitMeta) -> {status, verifier} | null`.
+ * A later registration under the SAME name replaces the earlier one (a
+ * re-register, not a stack) — matches this codebase's own precedent
+ * elsewhere (verification-separation.js's "one verifier, one vote per lens,
+ * a re-vote replaces rather than stuffs").
+ */
+export function registerAIAuthorshipVerifier(name, verifyFn) {
+  if (typeof name !== 'string' || !name || typeof verifyFn !== 'function') return false;
+  _verifiers.set(name, verifyFn);
+  return true;
+}
+
+/** Test/reset helper — never called from production code. */
+export function _clearAIAuthorshipVerifiers() {
+  _verifiers.clear();
+}
+
+/**
+ * Consults every registered verifier in registration order; the first one
+ * to return a non-null result wins (first-registered-first-consulted, not
+ * "last wins" — an explicit choice: a more specific verifier should be
+ * registered first if precedence matters, rather than this function
+ * guessing which of several opinions to prefer). Defaults to
+ * {status:'unknown', verifier:null} with nothing registered or every
+ * verifier declining to answer.
+ *
+ * NEVER THROWS: a verifier that throws is treated as "no opinion", exactly
+ * like predicate-replay.js and missing-control-resolver.js already treat a
+ * throwing caller-supplied function elsewhere in this directory.
+ */
+export function resolveAIAuthorship(commitMeta) {
+  if (!commitMeta) return { status: 'unknown', verifier: null };
+  for (const [name, verifyFn] of _verifiers) {
+    let result;
+    try { result = verifyFn(commitMeta); } catch { continue; }
+    if (result && typeof result === 'object' && result.status) {
+      return { status: result.status, verifier: result.verifier || name };
+    }
+  }
+  return { status: 'unknown', verifier: null };
+}

package/src/posture/provenance/branch-entry.js

@@ -0,0 +1,80 @@
+// Branch-introduction resolver (Finding Provenance PRD, Scenario D).
+//
+// Given a finding's already-resolved origin commit, answers "where did this
+// land on the target branch" — either the origin commit itself (it was
+// committed directly on the branch) or the merge commit that brought it in
+// from a feature branch (`git merge --no-ff`). This is a second, distinct
+// question from origin-resolver.js's "which commit introduced this": a
+// commit can be the true origin and still never have existed on the branch
+// people actually deploy from until a later merge folded it in.
+//
+// Same input-validation posture as git-evidence.js, and for the same reason:
+// `originCommit`/`targetRef` are attacker-influenceable-shaped strings
+// (finding data, CLI args) flowing into `execFileSync('git', [...])`. A
+// value like `--output=/tmp/pwned` must never reach argv as a bare token —
+// see git-evidence.js's SHA_RE/SINCE_RE comments for the incident this
+// guards against (a nominally read-only git call gaining write side effects
+// via flag injection).
+
+import * as cp from 'node:child_process';
+import { hardenGitArgs, hardenGitEnv } from '../../util/git-hardening.js';
+
+const GIT_TIMEOUT_MS = 2000;
+
+// Same hostile-repo hardening as git-evidence.js's `_run`, and for the same
+// reason (FR-PROV-024 / second audit) — this module reimplements its own
+// `_run` rather than importing git-evidence.js's, but that must not mean
+// skipping the config/env hardening every other resolver in this directory
+// gets. `--no-textconv` isn't blanket-applied here: this module's own
+// `_run` calls are `rev-parse`/`merge-base`/`log --format=%H` (no diff/blob
+// CONTENT rendered), so there's no textconv surface to close — see
+// git-evidence.js for the calls where `--no-textconv` is load-bearing.
+function _run(scanRoot, args) {
+  try {
+    const stdout = cp.execFileSync('git', hardenGitArgs(args), {
+      cwd: scanRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024,
+      env: hardenGitEnv(),
+    });
+    return { ok: true, stdout };
+  } catch (e) {
+    return { ok: false, stdout: '' };
+  }
+}
+
+// Git SHAs (full or abbreviated) are always lowercase/uppercase hex, 4-40
+// chars. Rejecting anything else closes off flag injection.
+const SHA_RE = /^[0-9a-f]{4,40}$/i;
+function _isSha(sha) {
+  return typeof sha === 'string' && SHA_RE.test(sha);
+}
+
+// `targetRef` is used as a revision (both standalone and as the right side
+// of a `originCommit..targetRef` range), so it must look like a ref/branch/
+// sha — never start with `-` (which git would parse as an option) and
+// contain only characters refs can hold.
+const REF_RE = /^[A-Za-z0-9._/-]+$/;
+function _isSafeRef(ref) {
+  return typeof ref === 'string' && ref.length > 0 && !ref.startsWith('-') && REF_RE.test(ref);
+}
+
+function _currentBranchName(scanRoot, targetRef) {
+  const r = _run(scanRoot, ['rev-parse', '--abbrev-ref', targetRef]);
+  return r.ok ? r.stdout.trim() : targetRef;
+}
+
+export function resolveBranchEntry(scanRoot, originCommit, targetRef = 'HEAD') {
+  if (!_isSha(originCommit)) return null;
+  if (!_isSafeRef(targetRef)) return null;
+
+  const reachable = _run(scanRoot, ['merge-base', '--is-ancestor', originCommit, targetRef]);
+  if (!reachable.ok) return null;
+
+  const branchName = _currentBranchName(scanRoot, targetRef);
+  const r = _run(scanRoot, ['log', '--merges', '--ancestry-path', '--reverse', '--format=%H', `${originCommit}..${targetRef}`]);
+  if (r.ok && r.stdout.trim()) {
+    const firstMerge = r.stdout.trim().split('\n')[0];
+    return { commit: firstMerge, ref: `refs/heads/${branchName}`, relationship: 'merge' };
+  }
+  return { commit: originCommit, ref: `refs/heads/${branchName}`, relationship: 'direct' };
+}

package/src/posture/provenance/cache.js

@@ -0,0 +1,143 @@
+// Content-addressed provenance cache.
+//
+// Paths and writes both go through posture/state-dir.js rather than joining
+// the state directory name by hand. That seam is what enforces the two
+// invariants this module would otherwise each have to remember: it refuses to
+// create state outside a project root, and it honours the read-only scan
+// switch (`--no-state` / AGENTIC_SECURITY_NO_STATE), so scanning somebody
+// else's tree leaves it byte-identical. See test/no-stray-state.test.js — a
+// cache that quietly writes during a read-only scan is exactly the litter that
+// guard exists to prevent.
+//
+// PRIVACY AT REST (second independent Finding Provenance PRD audit): this
+// cache deliberately stores the FULL provenance record — including raw
+// `authorEmail` — not a pre-redacted one. That is a considered choice, not an
+// oversight: `redactFindingProvenance` is applied per output boundary
+// (report/index.js, mcp/tools.js), and different callers in the SAME scan
+// legitimately want different presentations of the SAME cached record — one
+// reader wants the default-redacted view, another passes
+// `--include-author-email`, a third wants `--pseudonymize-authors`. If the
+// cache stored an already-redacted record, whichever policy was in effect at
+// WRITE time would win for every reader forever, silently breaking that
+// per-call flexibility. So redaction stays a read-time/output-time concern,
+// exactly as documented in posture/CLAUDE.md's "Privacy" section, and this
+// cache is accepted as an at-rest store of raw personal data.
+//
+// The mitigation applied here is a permissions floor, not encryption: every
+// write tightens the `provenance-cache/` directory to 0700 and the entry file
+// to 0600 (same posture this project already uses for the per-install HMAC
+// key at integrity.js's `scan-key`, mode 0600 / 0700 parent). That defeats
+// "any local user/process can read this," which is the realistic at-rest
+// threat for a developer machine or CI runner; it does NOT defeat an attacker
+// with root or the operating-system user's own privileges — no local file
+// permission ever does. Encryption-at-rest with a per-install key (the same
+// pattern as `scan-key`) was considered and rejected for this task's scope:
+// unlike the HMAC key, which only ever needs to reproduce a symmetric digest,
+// a cache that must serve back the exact original record on every read would
+// need the plaintext decrypted on every `cacheGet`, which does not raise the
+// bar much over a permissions floor while adding real complexity (key
+// rotation, corrupt-ciphertext handling) for a cache that is disposable and
+// content-addressed to begin with. If that tradeoff is revisited, encrypting
+// only `findingOrigin.authorEmail` (not the whole record) would preserve this
+// module's byte-identical round-trip property, which is asserted by this
+// file's own tests.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { statePath, safeWriteState } from '../state-dir.js';
+import { FINDING_PROVENANCE_SCHEMA_VERSION } from './schema.js';
+
+// Permission floor for the cache directory and every entry inside it — see
+// the module header. Applied on every write, not just at directory creation.
+//
+// Precisely what that does and does not retrofit, because the distinction
+// matters and an earlier version of this comment overstated it: ANY write to
+// this directory retightens the DIRECTORY to 0700, including a write for some
+// unrelated key. An individual ENTRY's own mode is only rewritten when that
+// exact content-addressed key is written again — which a cache hit
+// short-circuits, so in practice a pre-existing 0644 entry keeps that mode.
+// It is still unreachable by another local user, because Unix requires
+// traversal (x) permission on every parent directory to open a file by path,
+// and the 0700 directory denies exactly that. The directory mode is what
+// carries the protection; the file mode is defense in depth.
+const CACHE_DIR_MODE = 0o700;
+const CACHE_FILE_MODE = 0o600;
+
+// Its own top-level `.agentic-security/provenance-cache/` directory, NOT
+// nested under `provenance/` (where it lived through M0-M4) — the artifact
+// registry (posture/artifact-registry.js) can only apply retention per
+// TOP-LEVEL directory name, and this cache (pure HEAD-keyed memo, safely
+// regenerable) needs a TTL that the provenance/ lifecycle ledger (permanent
+// history) must never get. See PRD Section 8 / artifact-registry.js's
+// 'provenance-cache' entry. Single helper so the read and write paths can
+// never drift apart.
+function keyPath(scanRoot, key) {
+  const hash = crypto.createHash('sha256').update(key).digest('hex');
+  return statePath(scanRoot, 'provenance-cache', hash + '.json');
+}
+
+/**
+ * The schema version is part of the key, and is added HERE rather than by the
+ * caller so that no caller can forget it.
+ *
+ * `validate.js` rejects a provenance object stamped with a version this build
+ * does not understand — but a cache hit never reached that check: `cacheGet`
+ * returns the parsed object as-is. With the version outside the key, entries
+ * written by an older schema stayed live key hits after a version bump and
+ * flowed straight through, defeating the exact scenario the version field was
+ * added to guard. Including it means a bump silently misses every stale entry
+ * instead, which is the correct outcome: they are recomputed, not trusted.
+ *
+ * `lineageKey` (M4 §4.2 final-review fix) covers the resolved
+ * `.agentic-security/repo-lineage.json` cross-repo link the same way
+ * `historyBoundary` already covers `--provenance-since`: a cross-repo
+ * `partial` result IS cacheable, so without this the cache key had no field
+ * reflecting which (if any) lineage link produced it. Adding, removing, or
+ * repointing the declaration at the same HEAD would then keep serving a
+ * stale pre-lineage or a stale cross-repo answer. Callers pass the resolved
+ * link's own `${path}@${atCommit}`, or the literal `'none'` when
+ * `loadRepoLineage` returns nothing — never omit it in a way that collapses
+ * both cases to the same empty string the other fields default to.
+ */
+export function makeCacheKey({ repoHead, stableId, detectorVersion, historyBoundary, mode, lineageKey }) {
+  return [
+    FINDING_PROVENANCE_SCHEMA_VERSION,
+    repoHead || '', stableId || '', detectorVersion || '', historyBoundary || '', mode || '', lineageKey || 'none',
+  ].join('|');
+}
+
+export function cacheGet(scanRoot, key) {
+  // Read directly and let the catch handle "missing" — an explicit
+  // existsSync() check first is a check-then-use race for no benefit, since
+  // the catch already covers every failure mode a stale check would too.
+  try {
+    return JSON.parse(fs.readFileSync(keyPath(scanRoot, key), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function cacheSet(scanRoot, key, value) {
+  try {
+    // safeWriteState creates the directory, applies the project-root check and
+    // returns false (never throws) when the read-only switch is on. A refused
+    // write is a cache miss next time, which is correct behaviour, not an error.
+    // category:'provenance-cache' lets lsp/server.js keep THIS write alive
+    // while every other state write stays suppressed on every save — see
+    // state-dir.js's withStateWritesDisabled.
+    const fp = keyPath(scanRoot, key);
+    const wrote = safeWriteState(fp, JSON.stringify(value), { category: 'provenance-cache' });
+    if (wrote) {
+      // Permission floor (see module header) — best-effort, applied AFTER a
+      // successful write so a chmod failure (e.g. an unsupported filesystem)
+      // never turns a real cache write into a reported failure.
+      try {
+        fs.chmodSync(path.dirname(fp), CACHE_DIR_MODE);
+        fs.chmodSync(fp, CACHE_FILE_MODE);
+      } catch { /* best-effort — see above */ }
+    }
+  } catch {
+    // best-effort — cache failures must never fail a scan
+  }
+}

package/src/posture/provenance/confidence.js

@@ -0,0 +1,36 @@
+import { CONFIDENCE_LEVEL } from './schema.js';
+
+// `renameAmbiguous`: the one production caller (coordinator.js, on the
+// `status:'complete'` path) never passes this true today — see the comment
+// there for why a genuine rename-ambiguous case cannot reach `complete`
+// under the current resolver architecture, so `reasons.push('rename_ambiguous')`
+// below is currently unreachable from real scans. Left wired rather than
+// removed: a caller that DOES have a real rename signal (e.g. a future
+// `complete`-status path that resolves via a rename-following replay) can
+// pass `renameAmbiguous: true` without this function changing at all, and
+// `test/posture/provenance-confidence.test.js` exercises the branch directly.
+export function assessConfidence({
+  parentBoundaryVerified = false, historyComplete = false, detectorCompatible = true,
+  renameAmbiguous = false, shallow = false, budgetExhausted = false,
+} = {}) {
+  const reasons = [];
+  if (budgetExhausted) return { level: CONFIDENCE_LEVEL.UNKNOWN, score: 0, reasons: ['budget_exhausted'] };
+
+  if (parentBoundaryVerified && historyComplete && detectorCompatible && !renameAmbiguous) {
+    reasons.push('parent_absence_verified', 'complete_history');
+    return { level: CONFIDENCE_LEVEL.HIGH, score: 0.95, reasons };
+  }
+  if (detectorCompatible && (!historyComplete || !parentBoundaryVerified) && !shallow) {
+    if (!historyComplete) reasons.push('partial_history');
+    if (!parentBoundaryVerified) reasons.push('no_parent_to_test');
+    return { level: CONFIDENCE_LEVEL.MEDIUM, score: 0.65, reasons };
+  }
+  if (shallow || renameAmbiguous || !detectorCompatible) {
+    if (shallow) reasons.push('shallow_history');
+    if (renameAmbiguous) reasons.push('rename_ambiguous');
+    if (!detectorCompatible) reasons.push('detector_incompatible');
+    return { level: CONFIDENCE_LEVEL.LOW, score: 0.35, reasons };
+  }
+  reasons.push('no_defensible_origin');
+  return { level: CONFIDENCE_LEVEL.UNKNOWN, score: 0, reasons };
+}