mcp-proof 0.3.10 → 0.3.12

package/README.md

@@ -29,7 +29,7 @@ npx mcp-proof --config ~/.config/Claude/claude_desktop_config.json
 npx mcp-proof --skill ~/.claude/skills/example/SKILL.md
 
 # Inspect an exact tools/call payload before execution
-cat call.json | npx mcp-proof --execute --json
+cat call.json | npx mcp-proof --inspect-call --json
 
 # Create a shareable Trust Card for a PR or README
 npx mcp-proof tools.json --markdown > MCP_TRUST.md
@@ -134,7 +134,8 @@ Options:
   --stdio <cmd>      launch a real stdio MCP server, call tools/list, scan returned tools
   --config <path>    scan every stdio server in an MCP client config with mcpServers
   --skill <path>     scan a Claude SKILL.md (educational/warning context aware)
-  --execute [<path>] inspect a tools/call payload before execution
+  --inspect-call [<path>] inspect a tools/call payload before execution
+  --execute [<path>] deprecated alias for --inspect-call
   --markdown         emit a shareable Markdown Trust Card
   --trust-card       alias for --markdown
   --sarif            emit SARIF 2.1.0 for GitHub code scanning
@@ -226,7 +227,7 @@ The npm CLI is local-first: MCP manifests, tool descriptions, tool arguments, cl
 - **Publisher verification is lexical only by default.** npm scope match + Levenshtein typosquat. Pass `--live` to confirm npm packages against `registry.npmjs.org` with one network call. *No GitHub-API lookup, no signature verification.*
 - **No source-tree scan.** The full VyriAI gateway also runs a static scanner over the package source for `child_process`, postinstall scripts, obfuscation. That step needs the source unpacked locally and isn't shipped in this CLI.
 - **No dependency CVE check.** The full gateway wraps `npm audit`; this CLI doesn't shell out.
-- **Limited runtime-payload inspection.** `--execute` scans a supplied `tools/call` name and arguments before execution; it does not execute the call, enforce an authorization policy, verify identity, or observe server runtime behavior.
+- **Limited runtime-payload inspection.** `--inspect-call` scans a supplied `tools/call` name and arguments before execution (`--execute` remains a deprecated alias); it does not execute the call, enforce an authorization policy, verify identity, or observe server runtime behavior.
 - **Stdio discovery only.** `--stdio` / `--config` launches local stdio MCP servers and calls `tools/list`. It does not yet connect to HTTP/SSE MCP servers.
 - **Skill context is keyword-based.** The skill detector looks for warning/example/demonstration framing around sensitive signals. A well-disguised attack without that framing may not downgrade.
 - **Local payload cap.** The CLI refuses inputs over 5 MB by default to avoid accidental memory blowups in CI. Override with `MCP_SCAN_MAX_BYTES=20mb` if you have an unusually large tools manifest.

package/bin/mcp-proof.js

@@ -9,9 +9,9 @@
 //   mcp-proof --self-test
 //
 // Exit codes:
-//   0 — verdict allow
+//   0 — verdict allow (and, with --vetokernel-endpoint, VetoKernel authorized it)
 //   1 — verdict warn
-//   2 — verdict block
+//   2 — verdict block, or VetoKernel denied the action
 //   64 — usage error
 //   65 — input parse error
 //
@@ -24,6 +24,7 @@ const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
 const { evaluate, evaluateCall, scanSkillManifest, verifyPublisherAsync } = require('../engine.js');
+const { authorizeCall } = require('../vetokernel-client.js');
 
 const DEFAULT_MAX_INPUT_BYTES = 5 * 1024 * 1024;
 const DEFAULT_TIMEOUT_MS = 15000;
@@ -43,15 +44,19 @@ Usage:
   mcp-proof --stdio "<command to launch MCP server>"
   mcp-proof --config <claude-or-cursor-config.json>
   mcp-proof --skill <SKILL.md>
-  mcp-proof --execute [<call.json>]        runtime authorization of a tools/call payload
+  mcp-proof --inspect-call [<call.json>]  inspect a tools/call payload before execution
 
-  If <file.json> is omitted and --stdio/--config/--skill/--execute are not used, JSON is read from stdin.
+  If <file.json> is omitted and --stdio/--config/--skill/--inspect-call are not used, JSON is read from stdin.
 
 Options:
   --stdio <cmd>      launch a real stdio MCP server, call tools/list, scan returned tools
   --config <path>    scan every stdio server in an MCP client config with mcpServers
   --skill <path>     scan a Claude SKILL.md (educational/warning context aware)
-  --execute [<path>] inspect a tools/call payload before execution (reads stdin if path omitted)
+  --inspect-call [<path>] inspect a tools/call payload before execution (reads stdin if path omitted)
+  --execute [<path>] deprecated alias for --inspect-call
+  --vetokernel-endpoint <url>  with --inspect-call, ask VetoKernel to authorize the
+                     proposed action before execution and verify the returned receipt
+                     (env: VETOKERNEL_ENDPOINT, VETOKERNEL_API_KEY, VETOKERNEL_TENANT_ID)
   --markdown         emit a shareable Markdown Trust Card
   --trust-card       alias for --markdown
   --sarif            emit SARIF 2.1.0 for GitHub code scanning
@@ -94,9 +99,12 @@ async function main() {
   if (args.selfTest) {
     return runSelfTest(args);
   }
-  const exclusiveModes = [args.stdio, args.config, args.skill, args.execute].filter(Boolean).length;
+  if (args.deprecatedExecute) {
+    process.stderr.write('mcp-proof: --execute is deprecated; use --inspect-call instead.\n');
+  }
+  const exclusiveModes = [args.stdio, args.config, args.skill, args.inspectCall].filter(Boolean).length;
   if (exclusiveModes > 1) {
-    process.stderr.write('mcp-proof: use one of --stdio, --config, --skill, --execute at a time.\n');
+    process.stderr.write('mcp-proof: use one of --stdio, --config, --skill, --inspect-call at a time.\n');
     process.exit(64);
   }
 
@@ -144,16 +152,27 @@ async function main() {
     process.exit(exitCodeForDecision(result.decision));
   }
 
-  if (args.execute) {
+  if (args.inspectCall) {
     let result;
+    let call;
     try {
-      result = runExecute(args);
+      ({ result, call } = runExecute(args));
     } catch (err) {
       process.stderr.write(`mcp-proof: ${err.message}\n`);
       process.exit(err.exitCode || 65);
     }
+    if (args.vetokernelEndpoint) {
+      try {
+        result.authorization = await authorizeInspectedCall(result, call, args);
+      } catch (err) {
+        // Fail closed: if the authorization service is unreachable, the action
+        // is not authorized.
+        process.stderr.write(`mcp-proof: vetokernel authorization failed: ${err.message}\n`);
+        process.exit(2);
+      }
+    }
     emitOutput(result, args);
-    process.exit(exitCodeForDecision(result.decision));
+    process.exit(exitCodeForInspectedCall(result));
   }
 
   let raw;
@@ -207,7 +226,8 @@ function parseArgs(argv) {
   const out = {
     source: '', transport: '', bind: '', json: false, selfTest: false,
     help: false, version: false, file: '', stdio: '', config: '', skill: '',
-    execute: false, format: 'human', live: false, timeoutMs: DEFAULT_TIMEOUT_MS,
+    inspectCall: false, deprecatedExecute: false, format: 'human', live: false, timeoutMs: DEFAULT_TIMEOUT_MS,
+    vetokernelEndpoint: process.env.VETOKERNEL_ENDPOINT || '',
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -224,12 +244,18 @@ function parseArgs(argv) {
       case '--stdio': out.stdio = argv[++i] || ''; break;
       case '--config': out.config = expandHome(argv[++i] || ''); break;
       case '--skill': out.skill = expandHome(argv[++i] || ''); break;
+      case '--inspect-call':
+        out.inspectCall = true;
+        if (argv[i + 1] && !argv[i + 1].startsWith('-')) out.file = argv[++i];
+        break;
       case '--execute':
-        out.execute = true;
+        out.inspectCall = true;
+        out.deprecatedExecute = true;
         if (argv[i + 1] && !argv[i + 1].startsWith('-')) out.file = argv[++i];
         break;
       case '--live': out.live = true; break;
       case '--timeout': out.timeoutMs = parseTimeout(argv[++i] || ''); break;
+      case '--vetokernel-endpoint': out.vetokernelEndpoint = argv[++i] || ''; break;
       default:
         if (a.startsWith('-')) {
           process.stderr.write(`mcp-proof: unknown flag ${a}\n`);
@@ -643,9 +669,42 @@ function runExecute(args) {
     throw e;
   }
   const result = evaluateCall(parsed);
-  result.mode = 'execute';
+  result.mode = 'inspect-call';
   result.name = args.file || 'stdin';
-  return result;
+  return { result, call: parsed };
+}
+
+// authorizeInspectedCall asks VetoKernel to authorize the exact action this
+// call proposes. action_type and target_id come from the call file itself,
+// falling back to the tool name and arguments.target_id, so a call fixture is
+// self-describing and needs no extra flags.
+function authorizeInspectedCall(result, call, args) {
+  const callArgs = call.arguments || (call.params && call.params.arguments) || {};
+  const parametersJSON = JSON.stringify(callArgs);
+  return authorizeCall({
+    endpoint: args.vetokernelEndpoint,
+    apiKey: process.env.VETOKERNEL_API_KEY || '',
+    tenantId: process.env.VETOKERNEL_TENANT_ID || 'default',
+    agentId: call.agent_id || 'mcp-proof',
+    actionId: call.action_id || `mcp-proof-${Date.now()}`,
+    toolName: result.tool,
+    actionType: call.action_type || result.tool,
+    targetId: call.target_id || callArgs.target_id || '',
+    parametersJSON,
+    context: call.context,
+    scanner: {
+      name: 'mcp-proof',
+      decision: result.decision,
+      severity: result.call_scan.severity,
+      reason: result.call_scan.reason,
+    },
+    timeoutMs: args.timeoutMs,
+  });
+}
+
+function exitCodeForInspectedCall(result) {
+  if (result.authorization && result.authorization.decision !== 'allow') return 2;
+  return exitCodeForDecision(result.decision);
 }
 
 function exitCodeForDecision(d) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-proof",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Auditable, privacy-preserving MCP (Model Context Protocol) server verifier with local Trust Cards and SARIF output — test servers before connecting them to an AI system.",
   "main": "engine.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "engine.js",
+    "vetokernel-client.js",
     "bin/mcp-proof.js",
     "README.md",
     "LICENSE"

package/vetokernel-client.js

@@ -0,0 +1,168 @@
+// vetokernel-client.js — post an inspected tools/call to VetoKernel's
+// execution-authorization endpoint and independently verify the receipt.
+//
+// Node stdlib only (http, https, crypto, url) — mcp-proof adds no dependencies.
+
+'use strict';
+
+const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const SCHEMA_VERSION = '1.0';
+
+// goJSONString matches Go's encoding/json string encoding, which HTML-escapes
+// <, > and & by default. Everything else Node's JSON.stringify already agrees on.
+function goJSONString(value) {
+  return JSON.stringify(String(value))
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026');
+}
+
+// canonicalReceiptJSON reproduces, in JavaScript, the exact byte sequence
+// VetoKernel hashes into receipt_hash (Go: backend/auth/execution_authorization.go
+// CanonicalReceiptBytes). It is deliberately an INDEPENDENT re-implementation:
+// agreement between the two is what makes the receipt independently verified
+// rather than merely re-read. Field order and the omitempty set are load-bearing
+// and are pinned by a golden vector in both test suites.
+function canonicalReceiptJSON(receipt) {
+  const fields = [
+    ['schema_version', receipt.schema_version, false],
+    ['decision', receipt.decision, false],
+    ['action_id', receipt.action_id, false],
+    ['action_type', receipt.action_type, false],
+    ['target_id', receipt.target_id, false],
+    ['tool_name', receipt.tool_name, true],
+    ['parameters_hash', receipt.parameters_hash, true],
+    ['tenant_id', receipt.tenant_id, false],
+    ['payload_hash', receipt.payload_hash, false],
+    ['context_hash', receipt.context_hash, false],
+    ['authorized_by_agent_id', receipt.authorized_by_agent_id, true],
+    ['issued_at', receipt.issued_at, false],
+  ];
+  const parts = [];
+  for (const [key, raw, omitempty] of fields) {
+    const value = raw === undefined || raw === null ? '' : raw;
+    if (omitempty && value === '') continue;
+    parts.push(goJSONString(key) + ':' + goJSONString(value));
+  }
+  return '{' + parts.join(',') + '}';
+}
+
+// verifyReceipt re-derives both bindings the receipt claims: that payload_hash
+// is sha256 of the exact parameter bytes we sent, and that receipt_hash is
+// sha256 of the canonical receipt fields.
+function verifyReceipt(receipt, parametersJSON) {
+  if (!receipt || typeof receipt !== 'object') {
+    return { verified: false, problems: ['no receipt returned'], payload_hash: '', receipt_hash: '' };
+  }
+  const problems = [];
+  if (receipt.schema_version !== SCHEMA_VERSION) {
+    problems.push(`unexpected schema_version ${receipt.schema_version}`);
+  }
+  if (receipt.decision !== 'allow') {
+    problems.push(`unexpected receipt decision ${receipt.decision}`);
+  }
+  const payloadHash = crypto.createHash('sha256')
+    .update(Buffer.from(String(parametersJSON), 'utf8')).digest('hex');
+  if (receipt.payload_hash !== payloadHash) {
+    problems.push(`payload_hash does not bind the parameters we sent (recomputed ${payloadHash})`);
+  }
+  const receiptHash = crypto.createHash('sha256')
+    .update(canonicalReceiptJSON(receipt), 'utf8').digest('hex');
+  if (receipt.receipt_hash !== receiptHash) {
+    problems.push(`receipt_hash mismatch (recomputed ${receiptHash})`);
+  }
+  return { verified: problems.length === 0, problems, payload_hash: payloadHash, receipt_hash: receiptHash };
+}
+
+// authorizeCall proposes a consequential action to VetoKernel and returns its
+// decision. It fails closed: an allow whose receipt does not independently
+// verify is downgraded to a deny.
+function authorizeCall(options) {
+  const {
+    endpoint,
+    apiKey = '',
+    tenantId = 'default',
+    agentId = 'mcp-proof',
+    actionId = '',
+    toolName = '',
+    actionType = '',
+    targetId = '',
+    parametersJSON = '{}',
+    context,
+    scanner = { name: 'mcp-proof', decision: 'allow', severity: 'low', reason: 'clean' },
+    timeoutMs = 5000,
+  } = options;
+
+  const body = JSON.stringify({
+    schema_version: SCHEMA_VERSION,
+    action_id: actionId,
+    agent_id: agentId,
+    tool_name: toolName,
+    action_type: actionType,
+    target_id: targetId,
+    parameters_json: parametersJSON,
+    context: context || undefined,
+    scanner,
+  });
+
+  const url = new URL(endpoint);
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request({
+      protocol: url.protocol,
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+        'X-API-Key': apiKey,
+        'X-Tenant-ID': tenantId,
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch (_) {
+          reject(new Error(`vetokernel returned non-JSON (status ${res.statusCode}): ${raw.slice(0, 200)}`));
+          return;
+        }
+        const out = {
+          endpoint,
+          status: res.statusCode,
+          decision: parsed.decision === 'allow' ? 'allow' : 'deny',
+          reason: parsed.reason || '',
+          receipt: parsed.receipt || null,
+          verification: null,
+        };
+        out.verification = out.decision === 'allow'
+          ? verifyReceipt(parsed.receipt, parametersJSON)
+          : { verified: false, problems: ['denied — no receipt issued'], payload_hash: '', receipt_hash: '' };
+        if (out.decision === 'allow' && !out.verification.verified) {
+          out.decision = 'deny';
+          out.reason = `receipt failed independent verification: ${out.verification.problems.join('; ')}`;
+        }
+        resolve(out);
+      });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`vetokernel request timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { authorizeCall, verifyReceipt, canonicalReceiptJSON, SCHEMA_VERSION };