@clear-capabilities/agentic-security-scanner 0.162.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

@@ -28,11 +28,14 @@ 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
@@ -605,6 +608,10 @@ export const explain_finding = {
       ...(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)
+        : {}),
     };
   },
 };
@@ -1712,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];