@clear-capabilities/agentic-security-scanner 0.128.1 → 0.132.0

package/src/posture/suppressions.js

@@ -7,7 +7,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 import { statePath, safeWriteState } from './state-dir.js';
 
 const MS_PER_DAY = 86400000;

package/src/posture/test-runner.js

@@ -0,0 +1,147 @@
+// R5 (partial, roadmap) — the project's own test suite as a verification
+// stage for `verifyFix()` (see `fix-verify.js`). Closes the gap where a
+// "verified" fix only proved a finding's stableId stopped firing — a patch
+// that deletes the feature entirely would satisfy that just as well as a
+// real fix. Running the project's own tests is the cheapest available check
+// that the application still works.
+//
+// Execution-safety note: this spawns the TARGET PROJECT's own test command
+// in the target project's own directory. That is deliberately NOT routed
+// through the R1 confinement sandbox (`../sandbox/`). That sandbox exists to
+// contain untrusted proof-of-concept exploit code the scanner itself
+// synthesizes — code nobody has vetted, being run for the first time. A
+// project's pre-existing test suite is the opposite case: it is the
+// project's own trusted source, already sitting on disk, and running it is
+// exactly what a human developer does by hand before trusting a fix.
+// Wrapping "npm test" / "pytest" / "go test" in the PoC sandbox's
+// syscall/network/filesystem restrictions would break the large majority of
+// real test suites (they bind local ports, spawn child processes, write temp
+// fixtures, etc.) for no corresponding security benefit.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+const NPM_PLACEHOLDER = /Error: no test specified/i;
+
+function _exists(scanRoot, rel) {
+  try { return fs.existsSync(path.join(scanRoot, rel)); } catch { return false; }
+}
+
+function _isDir(scanRoot, rel) {
+  try { return fs.statSync(path.join(scanRoot, rel)).isDirectory(); } catch { return false; }
+}
+
+function _binaryAvailable(cmd) {
+  try {
+    const r = spawnSync(cmd, ['--version'], { timeout: 5_000, stdio: 'ignore' });
+    return !(r.error && r.error.code === 'ENOENT');
+  } catch {
+    return false;
+  }
+}
+
+// Detect the project's test command. Read-only — never spawns the actual
+// test run, only (optionally) a cheap `--version` probe to confirm a tool
+// like `pytest` is actually installed before committing to it. Returns
+// `null` when nothing detectable is found — most scanned repos will hit
+// this path, and that must not be treated as a failure by callers.
+export function detectTestCommand(scanRoot) {
+  if (!scanRoot) return null;
+
+  // JS/TS — package.json with a real (non-placeholder) `scripts.test`.
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(scanRoot, 'package.json'), 'utf8')); } catch { pkg = null; }
+  const testScript = pkg && pkg.scripts && pkg.scripts.test;
+  if (testScript && !NPM_PLACEHOLDER.test(String(testScript))) {
+    if (_exists(scanRoot, 'pnpm-lock.yaml')) return { cmd: 'pnpm', args: ['test'], kind: 'pnpm' };
+    if (_exists(scanRoot, 'yarn.lock')) return { cmd: 'yarn', args: ['test'], kind: 'yarn' };
+    if (_exists(scanRoot, 'bun.lockb') || _exists(scanRoot, 'bun.lock')) return { cmd: 'bun', args: ['test'], kind: 'bun' };
+    return { cmd: 'npm', args: ['test', '--silent'], kind: 'npm' };
+  }
+
+  // Python — pytest.ini / pyproject.toml / tox.ini / a tests/ dir, and the
+  // `pytest` binary actually available. If pytest isn't installed we do NOT
+  // report a python test command — falling through lets a later language
+  // marker (e.g. go.mod in a polyglot repo) still be detected.
+  const pyMarker = _exists(scanRoot, 'pytest.ini') || _exists(scanRoot, 'pyproject.toml') ||
+    _exists(scanRoot, 'tox.ini') || _isDir(scanRoot, 'tests');
+  if (pyMarker && _binaryAvailable('pytest')) {
+    return { cmd: 'pytest', args: ['-q'], kind: 'pytest' };
+  }
+
+  // Go
+  if (_exists(scanRoot, 'go.mod')) {
+    return { cmd: 'go', args: ['test', './...'], kind: 'go' };
+  }
+
+  return null;
+}
+
+// Run the detected test command with a walltime budget. Always returns a
+// result object — never throws. Distinguishes four outcomes:
+//   - no detectable/runnable command  -> status: 'skipped'  (does NOT fail)
+//   - ran and exited 0                -> status: 'passed'
+//   - ran and exited non-zero         -> status: 'failed'
+//   - ran past the timeout budget     -> status: 'failed', timedOut: true
+export function runProjectTests(scanRoot, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const startedAt = Date.now();
+  const command = detectTestCommand(scanRoot);
+  if (!command) {
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: 'no-test-command-detected', exitCode: null, timedOut: false,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  let r;
+  try {
+    r = spawnSync(command.cmd, command.args, {
+      cwd: scanRoot,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      env: { ...process.env, CI: '1' },
+    });
+  } catch (e) {
+    // The spawn call itself threw (rare — e.g. cwd vanished). Treat as
+    // "could not run", not "ran and failed".
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: `spawn-error: ${e.message}`, exitCode: null, timedOut: false,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+  const durationMs = Date.now() - startedAt;
+
+  if (r.error && r.error.code === 'ENOENT') {
+    // The detected tool isn't actually installed on this machine. Not a
+    // test failure — the suite never ran.
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: `${command.kind}-not-installed`, exitCode: null, timedOut: false, durationMs,
+    };
+  }
+
+  if (r.status === null) {
+    // spawnSync sets status:null both on timeout-kill and on being killed by
+    // another signal; either way the run did not complete, which is a
+    // verification failure, never a skip — we asked for a result and the
+    // process was terminated before producing one.
+    return {
+      status: 'failed', passed: false, skipped: false,
+      reason: 'timed-out', exitCode: null, timedOut: true, durationMs,
+    };
+  }
+
+  return {
+    status: r.status === 0 ? 'passed' : 'failed',
+    passed: r.status === 0,
+    skipped: false,
+    reason: r.status === 0 ? null : 'test-failures',
+    exitCode: r.status,
+    timedOut: false,
+    durationMs,
+  };
+}

package/src/posture/verification-separation.js

@@ -0,0 +1,131 @@
+// R7 — adversarial verification with ENFORCED SEPARATION.
+//
+// The falsification pass (`falsification.js`) already tries to DISPROVE a
+// finding. What it could not previously do is *prove* that whoever checked the
+// finding was not whoever produced it. That guarantee is what this module adds,
+// plus a recorded multi-perspective verdict for contested findings.
+//
+// The property that matters: a verifier is structurally unable to rubber-stamp
+// its own finding.
+//   - `recordProducer` stamps who produced the finding, WRITE-ONCE. A later
+//     party cannot re-stamp itself as the producer to manufacture separation.
+//   - `assertSeparation` refuses when the verifier id equals the recorded
+//     producer id, and FAILS CLOSED when no producer was recorded at all
+//     (separation that cannot be established is not separation).
+//   - `recordVerdict` runs that check itself, so there is no code path that
+//     records a verdict without it. One verifier gets one vote per lens: a
+//     re-vote replaces the previous one rather than stuffing the ballot.
+//
+// RECALL-PRESERVING, same precedent as `falsification.js` and
+// `dataflow/proof-gate.js`: nothing here ever removes a finding and nothing
+// here ever touches `severity`. A `refuted` consensus is a triage signal, not
+// a deletion — absence of proof is not proof of absence.
+//
+// NO THROWING (posture/CLAUDE.md convention): every entry point returns a
+// refusal object `{ ok:false, refused:true, reason }` instead of throwing, so
+// an annotator can call it inside the engine's pipeline without a guard.
+
+export const VERIFICATION_VERDICTS = ['upheld', 'refuted', 'undecided'];
+
+// Verifier ids are namespaced so they can never collide with a producer id.
+export const VERIFIER_FALSIFICATION = 'verifier:falsification';
+export const VERIFIER_LLM_REVIEW = 'verifier:llm-review';
+
+function _refuse(reason) { return { ok: false, refused: true, reason }; }
+
+/** Namespaced id for whoever produced a finding — derived from its detector. */
+export function producerIdOf(finding) {
+  const p = finding && finding.parser ? String(finding.parser) : 'unknown';
+  return `detector:${p}`;
+}
+
+/**
+ * Stamp who produced this finding. Write-once: a second call with a different
+ * id is REFUSED (this is what stops a verifier reassigning provenance to
+ * itself). A repeat call with the same id is a no-op success.
+ */
+export function recordProducer(finding, producerId) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  const id = producerId ? String(producerId) : '';
+  if (!id) return _refuse('no producer id');
+  if (!finding.verification || typeof finding.verification !== 'object') {
+    finding.verification = { producer: id, verdicts: [] };
+    return { ok: true, producer: id };
+  }
+  if (!finding.verification.producer) {
+    finding.verification.producer = id;
+    if (!Array.isArray(finding.verification.verdicts)) finding.verification.verdicts = [];
+    return { ok: true, producer: id };
+  }
+  if (finding.verification.producer === id) return { ok: true, producer: id };
+  return _refuse(`producer already recorded as "${finding.verification.producer}" — write-once`);
+}
+
+/**
+ * The separation check. `{ ok:true, producer }` when the verifier is a party
+ * other than the producer; a refusal otherwise. Fails closed when no producer
+ * has been recorded.
+ */
+export function assertSeparation(finding, verifierId) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  const vid = verifierId ? String(verifierId) : '';
+  if (!vid) return _refuse('no verifier id');
+  const producer = finding.verification && finding.verification.producer;
+  if (!producer) {
+    return _refuse('no producer recorded — separation cannot be established');
+  }
+  if (producer === vid) {
+    return _refuse(`verifier "${vid}" is the producer of this finding — separation violated`);
+  }
+  return { ok: true, producer };
+}
+
+/**
+ * Record one verifier's verdict from one perspective (`lens`, e.g.
+ * 'reachability' | 'control-flow' | 'data-shape'). Refuses — recording
+ * nothing — when separation fails or the verdict is not one of
+ * VERIFICATION_VERDICTS. Never touches severity, never removes anything.
+ */
+export function recordVerdict(finding, { verifierId, lens, verdict, reason } = {}) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  if (!lens) return _refuse('no lens');
+  if (!VERIFICATION_VERDICTS.includes(verdict)) {
+    return _refuse(`unknown verdict "${verdict}" — expected one of ${VERIFICATION_VERDICTS.join('|')}`);
+  }
+  const sep = assertSeparation(finding, verifierId);
+  if (!sep.ok) return sep;
+
+  const entry = {
+    verifierId: String(verifierId),
+    lens: String(lens),
+    verdict,
+    ...(reason ? { reason: String(reason) } : {}),
+  };
+  const list = finding.verification.verdicts;
+  const i = list.findIndex(v => v.verifierId === entry.verifierId && v.lens === entry.lens);
+  if (i >= 0) list[i] = entry; else list.push(entry);
+  return { ok: true, recorded: entry };
+}
+
+/**
+ * Majority across every recorded verdict. Ties — including "no verdicts at
+ * all" — are 'undecided'. `lenses` is the sorted set of perspectives that
+ * actually voted, so a caller can see whether a verdict is one-eyed or a panel.
+ */
+export function consensusOf(finding) {
+  const list = (finding && finding.verification && Array.isArray(finding.verification.verdicts))
+    ? finding.verification.verdicts : [];
+  let upheld = 0, refuted = 0, undecided = 0;
+  const lenses = new Set();
+  for (const v of list) {
+    if (!v) continue;
+    if (v.lens) lenses.add(String(v.lens));
+    if (v.verdict === 'upheld') upheld++;
+    else if (v.verdict === 'refuted') refuted++;
+    else if (v.verdict === 'undecided') undecided++;
+  }
+  let verdict = 'undecided';
+  if (upheld > refuted) verdict = 'upheld';
+  else if (refuted > upheld) verdict = 'refuted';
+  return { verdict, upheld, refuted, undecided, lenses: [...lenses].sort() };
+}

package/src/report/index.js

@@ -180,6 +180,11 @@ export function normalizeFindings(scan){
         paramKeyConfidence: f.poc.paramKeyConfidence || null,
         paramKeyInferred: typeof f.poc.paramKeyInferred === 'boolean' ? f.poc.paramKeyInferred : null,
       } : null,
+      // R2: execution-proof tier — copied through only when the annotator
+      // (posture/proof-tier.js) actually attached it. Never synthesised here;
+      // a finding with no proof backing simply omits these fields.
+      ...(f.proofTier !== undefined ? { proofTier: f.proofTier } : {}),
+      ...(f.proofEvidence !== undefined ? { proofEvidence: f.proofEvidence } : {}),
       // Phase-1 next-gen P1.3 (FR-UX-1, FR-UX-2): calibrated probability +
       // 95% Wilson CI + sample size. Null when N < MIN_SAMPLES_FOR_CALIBRATION
       // for this family; `calibration_reason` explains why.
@@ -401,6 +406,12 @@ export function toJSON(scan, meta={}, opts={}){
     // threw and were skipped. The findings still ship; downstream consumers
     // see the gap.
     annotatorErrors: Array.isArray(scan.annotatorErrors) ? scan.annotatorErrors : [],
+    // R4 — run attestation: a stable, order-independent digest over this
+    // finding set bound to the engine/ruleset/bundle that produced it.
+    // Attached by the CLI (posture/attestation.js); null when not computed.
+    // It carries its own `proves` / `doesNotProve` statement — do not quote
+    // the digest as cross-machine reproducibility, which it is not.
+    attestation: scan.attestation || null,
     _scanMeta: scan._scanMeta || null,
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];

package/src/runScan.js

@@ -3,7 +3,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
-import fg from 'fast-glob';
+import { listFiles } from './util/glob.js';
 import { runFullScan, shouldScan } from './engine.js';
 import { appendScanSnapshot } from './posture/security-trend.js';
 import { recover as recoverFixHistory } from './posture/fix-history.js';
@@ -26,11 +26,7 @@ const DEFAULT_IGNORE = [
 ];
 
 export async function readTree(root, { ignore = [] } = {}) {
-  const entries = await fg('**/*', {
-    cwd: root, dot: true, onlyFiles: true,
-    ignore: [...DEFAULT_IGNORE, ...ignore], followSymbolicLinks: false,
-    suppressErrors: true,
-  });
+  const entries = await listFiles(root, { ignore: [...DEFAULT_IGNORE, ...ignore] });
   const fileContents = {};
   const depFileContents = {};
   for (const rel of entries) {
@@ -122,7 +118,9 @@ export async function runScan(rootDir, opts = {}) {
     }
   }
 
-  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root }, opts.onProgress || (()=>{}));
+  // R8: `resume` is opt-in. Left undefined here, runFullScan falls back to the
+  // AGENTIC_SECURITY_RESUME=1 env var, which is off by default.
+  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume }, opts.onProgress || (()=>{}));
   // Premortem 2R4.2: stamp ruleset version + source on the scan result, and
   // notify if the operator pinned a different version than what's installed.
   try { stampScan(root, scan); } catch {}