@clear-capabilities/agentic-security-scanner 0.161.0 → 0.163.0

package/src/mcp/invariant-tools.js

@@ -0,0 +1,64 @@
+// invariant-tools.js: the MCP surface for bounded business-logic scenarios (X-407.AC03).
+//
+// One READ-ONLY tool, `invariant_scenario_export`: build the reproducible scenario package for a reviewer-supplied contract and a
+// disposable fixture directory that both live inside the session root. It runs nothing and writes nothing. The same function
+// the CLI calls (`posture/invariants/export.js` `exportFromFiles`) does the work, so the two surfaces cannot disagree.
+//
+// Guarantees, each with a test:
+//   - paths are confined to the session root by the server's own `_confine` (passed in; this file never resolves a path itself);
+//   - the export carries no tenant secret: scenarios holding secret-looking content are withheld, the fixture source is never
+//     included, and the serialized result is checked once more with the server's own secret-shape redactor, which BLOCKS the
+//     result rather than editing it (an edited scenario is a different scenario);
+//   - it never claims exhaustive correctness: every export carries the bounded-sample statement;
+//   - gated behind the `invariant-scenarios` feature (off by default, operator-only): with it off the tool reports it is
+//     disabled and builds nothing.
+// The factory shape (rather than importing `_confine` from tools.js) avoids a cycle between this file and the registry.
+import { exportFromFiles } from '../posture/invariants/export.js';
+import { resolveAssuranceConfig } from '../posture/assurance/config.js';
+import { redactSecretShapes } from './redact.js';
+
+const MAX_RESPONSE_BYTES = 1_500_000;
+
+export function makeInvariantTools({ confine, META }) {
+  const invariant_scenario_export = {
+    name: 'invariant_scenario_export',
+    description: 'Export the bounded stateful scenarios for one executable business-logic invariant as a reproducible package: scenario documents with content digests, the pinned fixture digest, replay manifests (when a commit is given), the bounds applied and the scenario families that could not be built. Read-only: runs nothing. The fixture source and any secret-looking content are never included, and the package states that it is a bounded sample, not a proof of correctness. Requires the invariant-scenarios feature (off by default).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        invariant_file: { type: 'string', minLength: 1, maxLength: 512 },
+        fixture_dir: { type: 'string', minLength: 1, maxLength: 512 },
+        ledger_file: { type: 'string', minLength: 1, maxLength: 512 },
+        commit: { type: 'string', pattern: '^[0-9a-f]{40}([0-9a-f]{24})?$' },
+        seed: { type: 'integer', minimum: 0, maximum: 4294967295 },
+        bounds: {
+          type: 'object', additionalProperties: false,
+          properties: {
+            actors: { type: 'integer', minimum: 1, maximum: 4 }, depth: { type: 'integer', minimum: 1, maximum: 12 }, requests: { type: 'integer', minimum: 1, maximum: 16 },
+            scenarios: { type: 'integer', minimum: 1, maximum: 6 }, timeBudgetMs: { type: 'integer', minimum: 1, maximum: 8000 },
+          },
+        },
+      },
+      required: ['invariant_file', 'fixture_dir'],
+    },
+    async handler(args, ctx) {
+      let invariantPath; let fixturePath; let ledgerPath;
+      try {
+        invariantPath = confine(ctx.sessionRoot, args.invariant_file, 'invariant_file');
+        fixturePath = confine(ctx.sessionRoot, args.fixture_dir, 'fixture_dir');
+        if (args.ledger_file) ledgerPath = confine(ctx.sessionRoot, args.ledger_file, 'ledger_file');
+      } catch (e) {
+        return { _meta: META, ok: false, status: 'rejected', reason: `path refused: ${String(e.message).replace(ctx.sessionRoot, '<root>')}` };
+      }
+      const config = resolveAssuranceConfig({ scanRoot: ctx.sessionRoot, env: process.env });
+      const r = exportFromFiles({ invariantPath, fixturePath, ledgerPath, commit: args.commit, seed: args.seed, bounds: args.bounds, config });
+      if (r.status !== 'ok') return { _meta: META, ok: false, status: r.status, reason: String(r.reason || '').replace(ctx.sessionRoot, '<root>').slice(0, 400), withheld: r.withheld ?? [] };
+      const text = JSON.stringify(r.export);
+      if (redactSecretShapes(text).redactions > 0) return { _meta: META, ok: false, status: 'blocked', reason: 'the export contains secret-shaped content and was not returned; an edited scenario would be a different scenario' };
+      if (text.length > MAX_RESPONSE_BYTES) return { _meta: META, ok: false, status: 'blocked', reason: 'the export is too large for one response; lower the bounds' };
+      return { _meta: META, ok: true, status: 'ok', export: r.export, withheld: r.withheld };
+    },
+  };
+  return { invariant_scenario_export };
+}

package/src/mcp/portfolio-tools.js

@@ -0,0 +1,79 @@
+// portfolio-tools.js: the MCP surface for portfolio progress and review queues (X-707).
+//
+// One READ-ONLY tool, `portfolio_progress`: the coverage-aware progress view of a durable portfolio store that lives inside the session
+// root. It reads the store (verified; a corrupt store is an error, never a reset), the scheduler ledger beside it, and optionally a
+// budgets file and a findings file, and writes nothing. The same function the CLI calls (`posture/portfolio/progress.js`
+// `buildProgressView`) does the work, so the two surfaces cannot disagree.
+//
+// Guarantees, each with a test:
+//   - paths are confined to the session root by the server's own `_confine` (passed in; this file never resolves a path itself);
+//   - the view separates verified, blocked/failed/stale, coverage, budget and pending review, keeps stale workers visible, and never
+//     states that the portfolio passed (a finished controller is reported as finished);
+//   - the serialized result is checked with the server's secret-shape redactor and BLOCKED rather than edited if anything would change;
+//   - gated behind the `portfolio-assurance` feature (off by default): with it off the tool answers `status: 'disabled'` and reads nothing.
+// The factory shape (rather than importing `_confine` from tools.js) avoids a cycle between this file and the registry.
+import * as fs from 'node:fs';
+import { resolveAssuranceConfig, featureStatus } from '../posture/assurance/config.js';
+import { readStore } from '../posture/portfolio/work-units.js';
+import { readLedger } from '../posture/portfolio/scheduler.js';
+import { buildProgressView } from '../posture/portfolio/progress.js';
+import { FEATURE_ID } from '../posture/portfolio/wording.js';
+import { redactSecretShapes } from './redact.js';
+
+const MAX_RESPONSE_BYTES = 1_500_000;
+const MAX_INPUT_BYTES = 8 * 1024 * 1024;
+
+function readJson(file) {
+  const st = fs.lstatSync(file);
+  if (st.isSymbolicLink() || !st.isFile() || st.size > MAX_INPUT_BYTES) throw new Error('not a regular JSON file within the size limit');
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function makePortfolioTools({ confine, META }) {
+  const portfolio_progress = {
+    name: 'portfolio_progress',
+    description: 'Show the progress of a resumable multi-repository portfolio audit as a coverage-aware view: verified units, blocked/failed/stale units, per-repository coverage, remaining budget, pending human review, worker liveness (stale workers stay visible) and, when a findings file is given, aggregate findings deduplicated by stable identity with per-repository/environment evidence and separate affected releases. A finished controller is reported as finished, never as passed. Read-only; paths must be inside the session root. Disabled unless the portfolio-assurance feature is on.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        store_file: { type: 'string', minLength: 1, maxLength: 512 },
+        budgets_file: { type: 'string', minLength: 1, maxLength: 512 },
+        findings_file: { type: 'string', minLength: 1, maxLength: 512 },
+        blocking_severity: { type: 'string', enum: ['info', 'low', 'medium', 'high', 'critical'] },
+        now: { type: 'integer', minimum: 0 },
+      },
+      required: ['store_file'],
+    },
+    async handler(args, ctx) {
+      const config = resolveAssuranceConfig({ scanRoot: ctx.sessionRoot, env: process.env });
+      const gate = featureStatus(config, FEATURE_ID);
+      if (gate.status !== 'ok') return { _meta: META, ok: false, status: gate.status, reason: `portfolio progress is not available: ${gate.reason ?? gate.code}` };
+      let storePath; let budgetsPath; let findingsPath;
+      try {
+        storePath = confine(ctx.sessionRoot, args.store_file, 'store_file');
+        if (args.budgets_file) budgetsPath = confine(ctx.sessionRoot, args.budgets_file, 'budgets_file');
+        if (args.findings_file) findingsPath = confine(ctx.sessionRoot, args.findings_file, 'findings_file');
+      } catch (e) {
+        return { _meta: META, ok: false, status: 'rejected', reason: `path refused: ${String(e.message).replace(ctx.sessionRoot, '<root>')}` };
+      }
+      let store; let ledger; let budgets = null; let findings = null;
+      try {
+        store = readStore(storePath);
+        if (!store) return { _meta: META, ok: false, status: 'rejected', reason: 'no portfolio store at that path' };
+        ledger = readLedger(storePath);
+        if (budgetsPath) budgets = readJson(budgetsPath);
+        if (findingsPath) findings = readJson(findingsPath);
+      } catch (e) {
+        return { _meta: META, ok: false, status: 'blocked', reason: `the store or an input failed verification: ${String(e.code ?? e.message).slice(0, 200)}` };
+      }
+      const r = buildProgressView({ store, ledger, budgets, now: Number.isInteger(args.now) ? args.now : Date.now(), findings, blockingSeverity: args.blocking_severity });
+      if (!r.ok) return { _meta: META, ok: false, status: 'rejected', reason: r.errors.map((e) => e.message).join('; ').slice(0, 400) };
+      const text = JSON.stringify(r.view);
+      if (redactSecretShapes(text).redactions > 0) return { _meta: META, ok: false, status: 'blocked', reason: 'the view contains secret-shaped content and was not returned' };
+      if (text.length > MAX_RESPONSE_BYTES) return { _meta: META, ok: false, status: 'blocked', reason: 'the view is too large for one response' };
+      return { _meta: META, ok: true, status: 'ok', view: r.view };
+    },
+  };
+  return { portfolio_progress };
+}

package/src/mcp/redact.js

@@ -81,6 +81,21 @@ export function redactString(s) {
   return out;
 }
 
+/**
+ * The same provider-shape redaction as `redactString`, without its size caps:
+ * for a caller that must keep the whole payload and only remove secrets from it
+ * (the capability layer's outbound filtering). Returns the text and a count.
+ */
+export function redactSecretShapes(s) {
+  if (typeof s !== 'string' || !s) return { text: typeof s === 'string' ? s : '', redactions: 0 };
+  let out = s;
+  let redactions = 0;
+  for (const [re, kind] of PATTERNS) {
+    out = out.replace(re, () => { redactions++; return `[REDACTED:${kind}]`; });
+  }
+  return { text: out, redactions };
+}
+
 // Deep-redact every string in a finding-like object (mutates returned copy).
 export function redactFinding(f) {
   if (!f || typeof f !== 'object') return f;

package/src/mcp/server.js

@@ -16,6 +16,8 @@ import { fileURLToPath } from 'node:url';
 import { ALL_TOOLS } from './tools.js';
 import { validate } from './validate.js';
 import { auditCall } from './audit.js';
+// X-505: tool calls are checked against the capability policy before a handler runs.
+import { createToolGate } from '../capabilities/tool-gate.js';
 
 const PROTOCOL_VERSION = '2025-03-26';
 const SERVER_NAME = 'agentic-security';
@@ -43,7 +45,7 @@ const TOOLS_BY_NAME = Object.fromEntries(ALL_TOOLS.map(t => [t.name, t]));
 function _codeFingerprint() {
   try {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const files = ['server.js', 'tools.js', 'dataflow-tools.js', 'stdio.js', 'audit.js', 'validate.js', 'redact.js'];
+    const files = ['server.js', 'tools.js', 'dataflow-tools.js', 'invariant-tools.js', 'portfolio-tools.js', 'stdio.js', 'audit.js', 'validate.js', 'redact.js'];
     const h = crypto.createHash('sha256');
     for (const f of files) {
       try { h.update(f); h.update(fs.readFileSync(path.join(here, f))); } catch {}
@@ -63,8 +65,12 @@ function _ok(id, result) {
   return { jsonrpc: '2.0', id, result };
 }
 
-export function createServer({ sessionRoot = process.cwd() } = {}) {
+// `capabilityPolicy` is `{ bound, binding }`, supplied by the operator from the
+// capability manifest facility. Absent, and with the `capability-enforcement`
+// feature off, the gate is inactive and behaviour is unchanged.
+export function createServer({ sessionRoot = process.cwd(), capabilityPolicy = null } = {}) {
   const ctx = { sessionRoot };
+  const gate = createToolGate({ sessionRoot, policy: capabilityPolicy });
 
   async function handleRequest(msg) {
     if (!msg || typeof msg !== 'object') return _err(null, -32600, 'Invalid Request');
@@ -117,6 +123,21 @@ export function createServer({ sessionRoot = process.cwd() } = {}) {
           auditCall({ sessionRoot, tool: name, args, outcome: 'rejected', reason: 'unknown-tool' });
           return _err(id, -32602, `Unknown tool: ${name}`);
         }
+        // X-505: the capability check, for the task identity bound to this server.
+        // An identity named in the request metadata can only be compared with it.
+        const gated = gate.check(name, { claimedTaskId: msg.params?._meta?.taskId });
+        if (!gated.allowed) {
+          auditCall({ sessionRoot, tool: name, args, outcome: 'rejected', reason: `capability-denied: ${gated.code}` });
+          const p = gated.proposal;
+          return _ok(id, {
+            content: [{ type: 'text', text: JSON.stringify({
+              blocked: true, code: gated.code, reason: gated.reason, missing: gated.missing,
+              proposedChange: p && p.proposable ? { review: p.review, change: p.change, nextPolicyVersion: p.nextPolicyVersion, requiresOperatorGrant: true } : null,
+              attemptsRemaining: gated.attemptsRemaining, exhausted: gated.exhausted,
+            }, null, 2) }],
+            isError: true,
+          });
+        }
         try { validate(tool.inputSchema, args); }
         catch (e) {
           auditCall({ sessionRoot, tool: name, args, outcome: 'rejected', reason: `invalid-args: ${e.message}` });
@@ -147,7 +168,7 @@ export function createServer({ sessionRoot = process.cwd() } = {}) {
     }
   }
 
-  return { handleRequest, sessionRoot };
+  return { handleRequest, sessionRoot, capabilityGate: gate };
 }
 
 // NOTE: no default-singleton export. Callers must use createServer({...})

package/src/mcp/tools.js

@@ -26,11 +26,16 @@ import { withStateWritesDisabled } from '../posture/state-dir.js';
 import { analyzeTranscript, formatCacheReport, renderCacheStatusLine } from '../posture/cache-economics.js';
 import { redactString, redactFinding } from './redact.js';
 import { _remediationOf, normalizeFindings } from '../report/index.js';
+// X-206: the one projection of the verification record, shared with the JSON report, the text report and the autopilot response.
+import { verificationFields } from '../posture/verification/projection.js';
+import { boundaryFields } from '../lineage/deployment/projection.js';
 // Git-origin provenance (Finding Provenance M0/M1). Distinct from
 // `finding.provenance` (AI-authorship) and from an SCA entry's `provenance`
 // (Sigstore/SLSA attestation) — see report/index.js's import comment.
 import { redactFindingProvenance } from '../posture/provenance/schema.js';
 import { dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow } from './dataflow-tools.js';
+import { makeInvariantTools } from './invariant-tools.js';
+import { makePortfolioTools } from './portfolio-tools.js';
 
 // Lazy-loaded: these transitively pull in npm packages (@babel/core and
 // friends) that aren't available in the plugin-cache install path
@@ -599,6 +604,14 @@ export const explain_finding = {
       findingProvenance: f.findingProvenance ? redactFindingProvenance(f.findingProvenance, {
         pseudonymize: process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS === '1',
       }) : null,
+      // X-206: the same verification projection the JSON and text reports carry; absent when the finding has no record.
+      ...(f.verificationRecord && typeof f.verificationRecord === 'object'
+        ? { verificationRecord: f.verificationRecord, ...verificationFields(f.verificationRecord, { replay: f.verificationReplay }) }
+        : {}),
+      // X-307: the same boundary projection the JSON and text reports carry; absent when the finding has no context.
+      ...(f.boundaryContext && typeof f.boundaryContext === 'object'
+        ? boundaryFields(f.boundaryContext)
+        : {}),
     };
   },
 };
@@ -875,7 +888,7 @@ export const apply_fix = {
           // default. Normalized to the scan+lint verdict shape used below.
           const { verifyFixWithTests } = await import('../posture/fix-verify-loop.js');
           const t = await verifyFixWithTests({ scanRoot: ctx.sessionRoot, originalFindingStableId: f.stableId, files: _files });
-          verdict = { ok: t.ok, summary: t.summary, rescan: t.legs?.scan?.detail, lint: t.legs?.lint?.detail, tests: t.legs?.tests, testVerdict: t.verdict };
+          verdict = { ok: t.ok, summary: t.summary, rescan: t.legs?.scan?.detail, lint: t.legs?.lint?.detail, tests: t.legs?.tests, testVerdict: t.verdict, verificationRecord: t.verificationRecord ?? null };
         } else {
           const verifyFixCore = await getVerifyFixCore();
           verdict = await verifyFixCore({
@@ -893,6 +906,9 @@ export const apply_fix = {
           _meta: META, applied: false,
           reason: `patch rejected by verifier: ${verdict.summary || verdict.rescan?.reason || 'did not verify'}`,
           verify: { rescan: verdict.rescan, lint: { runner: verdict.lint?.runner, ok: verdict.lint?.ok }, honesty: verdict.honesty || null },
+          // X-201: the same version-1 verification record every surface emits (additive; null when none could be formed).
+          verificationRecord: verdict.verificationRecord ?? null,
+          ...verificationFields(verdict.verificationRecord),
         };
       }
       // FR-307/FR-1002/D-0024: this caller-supplied-patch branch writes via
@@ -913,7 +929,7 @@ export const apply_fix = {
       }
       const materialClassification = classifyFixMaterialRisk(filesForMaterialClassification);
       if (dry_run) {
-        return { _meta: META, applied: false, dryRun: true, verified: true, files: Object.keys(confinedAbs), summary: verdict.summary, materialClassification };
+        return { _meta: META, applied: false, dryRun: true, verified: true, files: Object.keys(confinedAbs), summary: verdict.summary, verificationRecord: verdict.verificationRecord ?? null, ...verificationFields(verdict.verificationRecord), materialClassification };
       }
       const approvalRefusal = _highImpactApprovalRefusal(ctx, materialClassification, fixMeta);
       if (approvalRefusal) return approvalRefusal;
@@ -944,7 +960,7 @@ export const apply_fix = {
       }
       let acceptance = null;
       try { acceptance = fixAcceptanceRate(ctx.sessionRoot); } catch { /* best-effort */ }
-      return { _meta: META, applied: true, verified: true, patched: written, integrity: status, verify: { summary: verdict.summary }, acceptance, materialClassification };
+      return { _meta: META, applied: true, verified: true, patched: written, integrity: status, verify: { summary: verdict.summary, verificationRecord: verdict.verificationRecord ?? null, ...verificationFields(verdict.verificationRecord) }, acceptance, materialClassification };
     }
 
     if (typeof f.fix?.replacement !== 'string') {
@@ -1033,7 +1049,7 @@ export const apply_fix = {
 // proceed with apply_fix.
 export const verify_fix = {
   name: 'verify_fix',
-  description: 'Verify a proposed patch before applying. Re-scans the patched files in memory, runs the project linter, runs the project test suite, checks fix honesty (FULL/MITIGATION/WORKAROUND) when fixMeta is supplied, and re-runs the PoC when one exists. Returns { ok, rescan, lint, tests, honesty, poc, summary }. Does not write to the target project’s own files, but DOES append one record per attempt to .agentic-security/fix-metrics.jsonl for the measured fix-loop.',
+  description: 'Verify a proposed patch before applying. Re-scans the patched files in memory, runs the project linter, runs the project test suite, checks fix honesty (FULL/MITIGATION/WORKAROUND) when fixMeta is supplied, and re-runs the PoC when one exists. Returns { ok, rescan, lint, tests, honesty, poc, summary, verificationRecord } (verificationRecord is the shared version-1 record: outcome is one of not-run, unsupported, inconclusive, error, refuted, confirmed, and a static re-scan alone is never reported as confirmed; verificationView is the shared projection every interface shows for it, with state, scope, evidence ids, replay prerequisites and what was and was not verified). Does not write to the target project’s own files, but DOES append one record per attempt to .agentic-security/fix-metrics.jsonl for the measured fix-loop.',
   inputSchema: {
     type: 'object',
     additionalProperties: false,
@@ -1134,6 +1150,10 @@ export const verify_fix = {
         honesty: r.honesty,
         poc: r.poc ? { ...r.poc, reason: r.poc.reason ? redactString(r.poc.reason) : r.poc.reason } : r.poc,
         summary: r.summary,
+        // X-201: the one version-1 verification record (additive). It states what was actually established, e.g.
+        // `not-run` when no exploit oracle executed against the patch, never a bare pass/fail.
+        verificationRecord: r.verificationRecord ?? null,
+        ...verificationFields(r.verificationRecord),
       };
     } catch (e) {
       return { _meta: META, ok: false, reason: `verify_fix failed: ${e.message}` };
@@ -1699,4 +1719,9 @@ export const apply_sca_upgrade = {
   },
 };
 
-export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry, dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow];
+// X-407: read-only scenario export; the factory takes this file's confinement so the two modules do not import each other.
+const { invariant_scenario_export } = makeInvariantTools({ confine: _confine, META });
+// X-707: read-only portfolio progress view, same factory shape.
+const { portfolio_progress } = makePortfolioTools({ confine: _confine, META });
+
+export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry, dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow, invariant_scenario_export, portfolio_progress];