@clear-capabilities/agentic-security-scanner 0.139.1 → 0.141.0

package/src/posture/fix-coverage.js

@@ -0,0 +1,113 @@
+// PRD F6.5 — publish the proportion of findings this engine DECLINES to fix.
+//
+// A remediation feature that silently attempts everything is less trustworthy
+// than one that declines 40% and says so. Before this, the only visible number
+// was about fixes that were attempted; a finding for which synthesis was never
+// even tried simply did not appear, so the denominator quietly excluded every
+// hard case.
+//
+// THE BUCKETS
+//
+//   deterministic — a context-independent literal swap exists (md5 -> sha256,
+//                   TLS verify off -> on). Highest confidence: the patch does
+//                   not depend on reading intent.
+//   model         — no deterministic patch, but the finding is a shape a model
+//                   can be asked to fix. Counted as ATTEMPTABLE, not as fixed:
+//                   whether the attempt succeeds is fix-metrics.js's question.
+//   declined      — synthesis refuses, with a reason. Not a failure; a limit
+//                   stated up front.
+//
+// `declined` and `model` are kept apart for the same reason proof-coverage
+// separates `indeterminate` from `unclassified`: "we will not try" and "we will
+// try and might fail" are different promises, and merging them lets the weaker
+// one borrow the stronger one's credibility.
+import { synthesizeDeterministicPatch } from './deterministic-fix.js';
+
+// Families where a patch cannot be synthesised from the finding alone, with the
+// reason. Stated as DATA so a report can print why, rather than leaving a reader
+// to assume the engine simply has not got round to it.
+export const DECLINED_TO_FIX = Object.freeze({
+  'broken-access-control': 'the correct authorisation rule is a product decision — a scanner that invents one is guessing at intent, and a wrong authz patch fails open.',
+  'idor': 'same as broken-access-control: which identity may read which record is not recoverable from the code.',
+  'broken-authz': 'the rule that was checked wrongly is a product decision; patching it from the code alone guesses at which roles may do what, and guessing fails open.',
+  'business-logic': 'by definition the defect is a mismatch with intent, and intent is not in the file.',
+  'concurrency-bug': 'the correct lock discipline depends on the whole call graph; a local patch can deadlock rather than fix.',
+  'license-graph': 'a licence conflict is resolved by a policy or a dependency decision, not by editing code.',
+  'vulnerable-dep': 'resolved by an upgrade, which is apply_sca_upgrade\'s job, not a source patch.',
+});
+
+/** Bucket a finding: 'deterministic' | 'model' | 'declined'. */
+export function fixBucketOf(finding, fileContent) {
+  const fam = (finding && finding.family) || '';
+  for (const key of Object.keys(DECLINED_TO_FIX)) {
+    if (fam === key || fam.startsWith(`${key}-`)) return 'declined';
+  }
+  if (typeof fileContent === 'string' && fileContent) {
+    try {
+      const p = synthesizeDeterministicPatch(finding, fileContent);
+      if (p && p.ok !== false && (p.patch || p.replacement)) return 'deterministic';
+    } catch { /* fall through — an erroring synthesiser is not a fix */ }
+  }
+  return 'model';
+}
+
+/**
+ * Fix coverage over a finding set.
+ *
+ * Every share carries {n, d}. `fileContents` is optional: without it the
+ * deterministic check cannot run, and rather than guessing, those findings fall
+ * to `model` and `deterministicChecked` reports false so a reader knows the
+ * split is a lower bound on deterministic coverage.
+ */
+export function fixCoverage(findings, fileContents = null) {
+  const list = Array.isArray(findings) ? findings.filter(Boolean) : [];
+  const d = list.length;
+  const buckets = { deterministic: [], model: [], declined: [] };
+  for (const f of list) {
+    const src = fileContents && f.file ? fileContents[f.file] : null;
+    buckets[fixBucketOf(f, src)].push(f);
+  }
+
+  const declinedByFamily = {};
+  for (const f of buckets.declined) {
+    const fam = f.family || '(none)';
+    const key = Object.keys(DECLINED_TO_FIX).find(k => fam === k || fam.startsWith(`${k}-`)) || fam;
+    if (!declinedByFamily[key]) declinedByFamily[key] = { n: 0, reason: DECLINED_TO_FIX[key] || 'declined' };
+    declinedByFamily[key].n += 1;
+  }
+
+  return {
+    total: d,
+    deterministic: { n: buckets.deterministic.length, d },
+    model: { n: buckets.model.length, d },
+    declined: { n: buckets.declined.length, d, byFamily: declinedByFamily },
+    deterministicChecked: !!fileContents,
+    meaning: 'deterministic = a context-independent patch exists; model = attemptable by a model, NOT known to succeed; declined = synthesis refuses with a stated reason.',
+  };
+}
+
+/** Markdown for the scorecard. Denominators always attached. */
+export function renderFixCoverage(cov) {
+  if (!cov || !cov.total) return '_No findings to report fix coverage over._\n';
+  const pct = (n) => `${n}/${cov.total} (${Math.round((n / cov.total) * 100)}%)`;
+  const lines = [
+    '| Bucket | Share | Meaning |',
+    '|---|---|---|',
+    `| Deterministic patch | ${pct(cov.deterministic.n)} | context-independent literal swap |`,
+    `| Model-attemptable | ${pct(cov.model.n)} | can be attempted; success not claimed here |`,
+    `| Declined | ${pct(cov.declined.n)} | synthesis refuses — reasons below |`,
+    '',
+  ];
+  if (!cov.deterministicChecked) {
+    lines.push('_Source was not supplied, so the deterministic check could not run: the'
+      + ' deterministic share is a LOWER bound and those findings are counted as'
+      + ' model-attemptable._', '');
+  }
+  const entries = Object.entries(cov.declined.byFamily).sort((a, b) => b[1].n - a[1].n);
+  if (entries.length) {
+    lines.push('**Why each family is declined**', '');
+    for (const [fam, { n, reason }] of entries) lines.push(`- \`${fam}\` (${n}): ${reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/posture/fix-metrics.js

@@ -195,3 +195,79 @@ export function renderFixDurationSummary(sum) {
 }
 
 export const _internals = { _dist, _pct, RELIABLE_N };
+
+
+// ── PRD F6.1 — score fixes on THREE AXES, not one ──────────────────────────
+//
+// The three axes the PRD names:
+//   (a) does the finding disappear      — the rescan leg
+//   (b) does the project's own suite pass — the tests leg
+//   (c) does an independent verifier agree — the PoC re-check leg
+//
+// All three were already computed by verifyFixCore and then collapsed into one
+// boolean, which is the problem: **(a) alone is satisfiable by deleting code.**
+// A patch that removes the vulnerable function passes the rescan, has nothing
+// left to fail, and — on a project with no detectable test suite — reaches
+// ok:true having proven only that the detector went quiet.
+//
+// Reporting the axes separately makes that visible. `aOnly` is the number that
+// matters most and the one nobody was publishing: attempts that satisfied ONLY
+// the disappearance axis. A high aOnly with a high headline is the shape of a
+// remediation feature that is deleting code and calling it a fix.
+export function summarizeFixAxes(attempts) {
+  const list = Array.isArray(attempts) ? attempts.filter(Boolean) : [];
+  const d = list.length;
+
+  const rate = (pred) => ({ n: list.filter(pred).length, d });
+
+  // Each axis is judged INDEPENDENTLY of the overall verdict, so a leg that
+  // passed inside a failed attempt still counts for its own axis. Reading them
+  // off `ok` would make the three axes three copies of the same number.
+  const findingDisappeared = rate((a) => a.rescanOk === true || (a.ok === true && a.rescanOk !== false));
+  const testsStillPass = rate((a) => a.testsRan === true && a.testsOk !== false);
+  const verifierAgrees = rate((a) => a.pocOk === true);
+
+  const satisfiesAll = rate((a) =>
+    (a.rescanOk === true || (a.ok === true && a.rescanOk !== false))
+    && a.testsRan === true && a.testsOk !== false
+    && a.pocOk === true);
+
+  // The honesty number: disappearance WITHOUT either corroborating axis.
+  const aOnly = rate((a) => {
+    const disappeared = a.rescanOk === true || (a.ok === true && a.rescanOk !== false);
+    const corroborated = (a.testsRan === true && a.testsOk !== false) || a.pocOk === true;
+    return disappeared && !corroborated;
+  });
+
+  return {
+    total: d,
+    findingDisappeared,
+    testsStillPass,
+    verifierAgrees,
+    satisfiesAll,
+    aOnly,
+    meaning:
+      'findingDisappeared = the detector went quiet; testsStillPass = the project suite ran AND passed; '
+      + 'verifierAgrees = an independent PoC re-check confirmed the hole is shut. '
+      + 'aOnly counts attempts that satisfied ONLY disappearance — the shape a code-deleting "fix" produces.',
+    caveat: d === 0
+      ? 'no attempts recorded; every rate is 0/0 and means nothing'
+      : 'rates carry {n,d}; a small d is indicative, not settled',
+  };
+}
+
+/** Markdown for a report. Denominators always attached. */
+export function renderFixAxes(sum) {
+  if (!sum || !sum.total) return '_No fix attempts recorded._\n';
+  const row = (label, r, note) => `| ${label} | ${r.n}/${r.d} | ${note} |`;
+  return [
+    '| Axis | Rate | Meaning |',
+    '|---|---|---|',
+    row('(a) finding disappeared', sum.findingDisappeared, 'the detector went quiet'),
+    row('(b) project tests pass', sum.testsStillPass, 'the suite RAN and passed'),
+    row('(c) verifier agrees', sum.verifierAgrees, 'an independent PoC re-check confirmed it'),
+    row('all three', sum.satisfiesAll, 'the only row that means "fixed"'),
+    row('(a) ALONE', sum.aOnly, 'satisfiable by deleting code — watch this number'),
+    '',
+  ].join('\n');
+}

package/src/posture/integrity.js

@@ -39,6 +39,46 @@ function _keyPath() { return path.join(_keyDir(), 'scan-key'); }
 let _keySource = null;
 export function keyProvenance() { return _keySource || 'unresolved'; }
 
+// `writeFileSync(fp, …, {flag:'wx'})` is exclusive-CREATE, not atomic
+// create-with-content: it creates the file and THEN writes it. A concurrent
+// process that opens the path in that window reads an empty or partial file,
+// fails the hex check, and falls through to an ephemeral key — whose signatures
+// verify nowhere, forever, indistinguishable from real tampering. That is the
+// same failure the `wx` flag was added to prevent, just through a narrower
+// window, and CI caught it: 1 of 8 concurrently-generated signatures failed to
+// verify under the install key.
+//
+// Writing the full content to a temp file and hard-LINKING it into place closes
+// the window. link(2) is atomic and fails with EEXIST rather than clobbering, so
+// the destination path only ever appears with complete content, and the
+// first-writer-wins guarantee is preserved. Some filesystems (and Windows in
+// places) refuse hard links, so an unsupported link degrades to the previous
+// exclusive-create behaviour rather than failing the scan.
+function _publishKeyAtomically(fp, contents) {
+  const dir = _keyDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = path.join(dir, `scan-key.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, contents, { mode: 0o600 });
+    try {
+      fs.linkSync(tmp, fp);
+      return 'created';
+    } catch (e) {
+      if (e.code === 'EEXIST') return 'exists';
+      // Hard links unsupported here — fall back, accepting the narrower race.
+      try {
+        fs.writeFileSync(fp, contents, { mode: 0o600, flag: 'wx' });
+        return 'created';
+      } catch (e2) {
+        if (e2.code === 'EEXIST') return 'exists';
+        throw e2;
+      }
+    }
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* best effort */ }
+  }
+}
+
 function _readOrGenerateKey() {
   const fromEnv = process.env.AGENTIC_SECURITY_HMAC_KEY;
   if (fromEnv && /^[0-9a-fA-F]{32,}$/.test(fromEnv.trim())) {
@@ -62,19 +102,30 @@ function _readOrGenerateKey() {
   // forever after, indistinguishable from real tampering.
   const buf = crypto.randomBytes(32);
   try {
-    fs.mkdirSync(_keyDir(), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(fp, buf.toString('hex') + '\n', { mode: 0o600, flag: 'wx' });
-    _keySource = 'per-install-new';
-    return buf;
+    const outcome = _publishKeyAtomically(fp, buf.toString('hex') + '\n');
+    if (outcome === 'created') { _keySource = 'per-install-new'; return buf; }
+    // Another process published first — fall through to the EEXIST path and
+    // adopt ITS key, exactly as before.
+    const e = new Error('key already published'); e.code = 'EEXIST'; throw e;
   } catch (e) {
     if (e.code === 'EEXIST') {
       // Another process won the race and persisted its key first — use
       // THAT key instead of the one we generated, or we'd return a key
       // that matches nothing on disk.
-      try {
-        const hex = fs.readFileSync(fp, 'utf8').trim();
-        if (/^[0-9a-fA-F]{32,}$/.test(hex)) { _keySource = 'per-install'; return Buffer.from(hex, 'hex'); }
-      } catch { /* fall through to ephemeral */ }
+      // Bounded retry, defence-in-depth. With the atomic link publish above the
+      // winner's key is complete the instant the path exists, so one read is
+      // enough. It is NOT enough when the link fell back to exclusive-create
+      // (filesystems without hard links), or when an older version of this file
+      // left a torn key behind — there the content can still be arriving. A few
+      // short retries cost nothing and the alternative is an ephemeral key whose
+      // signatures never verify again.
+      for (let attempt = 0; attempt < 5; attempt++) {
+        try {
+          const hex = fs.readFileSync(fp, 'utf8').trim();
+          if (/^[0-9a-fA-F]{32,}$/.test(hex)) { _keySource = 'per-install'; return Buffer.from(hex, 'hex'); }
+        } catch { /* not readable yet */ }
+        try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2); } catch { /* no sleep available */ }
+      }
     }
     // Could not persist (or the winner's key was unreadable/malformed) —
     // this key lives for this process only, so nothing signed with it will

package/src/posture/mcp-rug-pull.js

@@ -0,0 +1,144 @@
+// PRD F5.2 — rug-pull detection for MCP tool definitions.
+//
+// THE ATTACK
+// ----------
+// A user approves an MCP server by reading what its tools claim to do. The
+// agent then loads those tool DESCRIPTIONS into its context on every session,
+// and acts on them. If a description changes after approval — new instructions
+// appended, the schema widened to accept a path it never took, the stated
+// purpose rewritten — the agent obeys the new text while the human still
+// believes they approved the old one.
+//
+// Nothing in mcp-audit.js could see this. Every rule there judges a definition
+// on its CURRENT content, so a description that is innocuous today and hostile
+// tomorrow passes both times. Rug-pull is a property of the CHANGE, not of any
+// single snapshot, which is why it needs its own mechanism.
+//
+// WHAT IS AND IS NOT A RUG-PULL
+// -----------------------------
+// A NEW tool is not a rug-pull — nobody approved it yet, and mcp-audit judges it
+// on content like any other. A REMOVED tool is not a rug-pull either; it can no
+// longer instruct anything. The finding is specifically: this exact tool name
+// was seen before, and what it says has changed since.
+//
+// The FIRST run records and reports nothing. There is no prior state to compare
+// against, and inventing a finding on first sight would make every new project
+// noisy while teaching people to ignore the rule that matters.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { statePath, stateWritesEnabled, isSafeStateDir } from './state-dir.js';
+
+const BASELINE_FILE = 'mcp-tool-baseline.json';
+
+/**
+ * Fingerprint the parts of a tool definition an agent actually ACTS on.
+ *
+ * Description and input schema, not the name — the name is the identity being
+ * tracked, so folding it in would make every tool its own fingerprint and the
+ * comparison vacuous. Ordering inside the schema is normalised so a formatting
+ * change is not reported as a behavioural one; a reader chasing a false
+ * rug-pull alert stops reading them.
+ */
+export function fingerprintTool(tool) {
+  const payload = JSON.stringify({
+    description: String((tool && tool.description) || ''),
+    inputSchema: _canonical((tool && (tool.inputSchema || tool.input_schema)) || null),
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex').slice(0, 32);
+}
+
+function _canonical(v) {
+  if (Array.isArray(v)) return v.map(_canonical);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = _canonical(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/** { serverName: { toolName: fingerprint } } from an MCP config object. */
+export function fingerprintConfig(config) {
+  const out = {};
+  const servers = (config && (config.mcpServers || config.servers)) || {};
+  for (const [server, def] of Object.entries(servers)) {
+    const tools = (def && def.tools) || [];
+    if (!Array.isArray(tools) || !tools.length) continue;
+    out[server] = {};
+    for (const t of tools) {
+      if (t && t.name) out[server][t.name] = fingerprintTool(t);
+    }
+  }
+  return out;
+}
+
+export function loadBaseline(scanRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(scanRoot, BASELINE_FILE), 'utf8'));
+  } catch { return null; }
+}
+
+export function saveBaseline(scanRoot, fingerprints) {
+  // Same discipline as every other state writer here: decline rather than
+  // create a stray state dir outside a real project.
+  if (!stateWritesEnabled() || !isSafeStateDir(path.dirname(statePath(scanRoot, BASELINE_FILE)))) return false;
+  try {
+    fs.mkdirSync(path.dirname(statePath(scanRoot, BASELINE_FILE)), { recursive: true });
+    fs.writeFileSync(statePath(scanRoot, BASELINE_FILE),
+      JSON.stringify({ schema: 'mcp-tool-baseline/v1', recordedAt: new Date().toISOString(), fingerprints }, null, 1));
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Compare current tool definitions against the recorded baseline.
+ *
+ * Returns { findings, firstRun, changed, added, removed }. `findings` is empty
+ * on a first run by design.
+ */
+export function detectRugPull(scanRoot, config, { file = '.mcp.json' } = {}) {
+  const current = fingerprintConfig(config);
+  const prior = loadBaseline(scanRoot);
+  const findings = [];
+  const changed = [], added = [], removed = [];
+
+  if (!prior || !prior.fingerprints) {
+    return { findings, firstRun: true, changed, added, removed, current };
+  }
+
+  for (const [server, tools] of Object.entries(current)) {
+    const before = prior.fingerprints[server] || {};
+    for (const [name, fp] of Object.entries(tools)) {
+      if (!(name in before)) { added.push(`${server}/${name}`); continue; }
+      if (before[name] === fp) continue;
+      changed.push(`${server}/${name}`);
+      findings.push({
+        id: `mcp-rug-pull:${file}:${server}:${name}`,
+        file,
+        line: 1,
+        vuln: `MCP: tool "${name}" definition CHANGED after approval (rug-pull)`,
+        severity: 'high',
+        cwe: 'CWE-494',
+        family: 'mcp-rug-pull',
+        parser: 'MCP-RUGPULL',
+        confidence: 0.9,
+        description:
+          `The tool "${name}" on server "${server}" was approved with one definition and now has another. `
+          + 'An agent loads tool descriptions into its context and acts on them, so a changed description is a '
+          + 'changed instruction — the human still believes they approved the previous text. This is the '
+          + 'documented rug-pull shape: benign at review time, hostile afterwards.',
+        remediation:
+          `Re-review "${name}" against what it claimed when approved. If the change is legitimate, refresh the `
+          + `baseline at .agentic-security/${BASELINE_FILE}; if it is not, remove the server before the next agent run.`,
+      });
+    }
+  }
+  for (const [server, tools] of Object.entries(prior.fingerprints)) {
+    for (const name of Object.keys(tools)) {
+      if (!current[server] || !(name in current[server])) removed.push(`${server}/${name}`);
+    }
+  }
+
+  return { findings, firstRun: false, changed, added, removed, current };
+}

package/src/posture/poc-generator.js

@@ -23,8 +23,24 @@
 //   - Per-language template variants beyond the primary host language.
 // Those land in P1.2.
 
+import * as crypto from 'node:crypto';
 import { CWE_TO_FAMILY, FAMILY_TO_PRIMARY_CWE } from './poc-cwe-map.js';
 
+// The XSS marker was `Math.random()`, evaluated at GENERATION time, so the
+// same finding produced a different PoC on every scan and `--deterministic`
+// could not make the JSON report byte-identical. (The XXE sentinel further
+// down also calls Math.random(), but that call is literal text inside the
+// EMITTED PoC — it runs when the PoC runs, so the artifact is already stable.
+// Leave it alone.)
+//
+// Derived from the finding instead: still distinct per finding, which is what
+// the marker is for — a token that will not collide with content already in
+// the response — but now reproducible.
+function _stableToken(f, n = 6) {
+  const seed = String((f && (f.stableId || f.id)) || `${f && f.file}:${f && f.line}`);
+  return crypto.createHash('sha256').update(seed).digest('hex').slice(0, n);
+}
+
 // ─── Template selectors ─────────────────────────────────────────────────────
 //
 // Each entry: { cwe, family, vulnContains, lang, render(finding, ctx) → code }
@@ -64,7 +80,7 @@ const TEMPLATES = [
     kind: 'http-payload',
     render: (f, ctx) => _httpPocNode(ctx, {
       header: 'Demonstrates reflected XSS by checking the script payload appears unencoded.',
-      payload: `"><script>__POC_XSS_${Math.random().toString(36).slice(2, 8)}</script>`,
+      payload: `"><script>__POC_XSS_${_stableToken(f)}</script>`,
       expect: 'response body contains the literal <script> payload (proves no HTML encoding)',
     }),
   },