mcp-proof 0.3.6 → 0.3.8

package/README.md

@@ -28,6 +28,15 @@ npx mcp-proof --config ~/.config/Claude/claude_desktop_config.json
 # Scan a Claude SKILL.md for hidden attack instructions
 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
+
+# Create a shareable Trust Card for a PR or README
+npx mcp-proof tools.json --markdown > MCP_TRUST.md
+
+# Emit SARIF for GitHub code scanning
+npx mcp-proof tools.json --sarif > results.sarif
+
 # Or pipe stdin
 cat tools.json | npx mcp-proof --transport http --bind 0.0.0.0:3001
 
@@ -125,6 +134,10 @@ 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
+  --markdown         emit a shareable Markdown Trust Card
+  --trust-card       alias for --markdown
+  --sarif            emit SARIF 2.1.0 for GitHub code scanning
   --live             confirm npm publisher on registry.npmjs.org (one network call)
   --timeout <ms>     MCP launch/protocol timeout per server (default: 15000)
   --source <s>       npm:@scope/pkg, git+https://..., file://...
@@ -140,9 +153,20 @@ Exit codes:  0 allow · 1 warn · 2 block · 64 usage · 65 parse error
 
 The non-zero exit code on `warn` / `block` makes this drop-in for CI: pin in your `package.json` and any tool poisoning fails the pipeline.
 
+## Trust Cards and GitHub SARIF
+
+Every scan can produce a portable review artifact without uploading server metadata:
+
+```bash
+npx mcp-proof --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" --markdown > MCP_TRUST.md
+npx mcp-proof ./tools.json --sarif > mcp-proof-results.sarif
+```
+
+`MCP_TRUST.md` is suitable for a pull request or repository README. SARIF can be uploaded to GitHub code scanning by a workflow or the included `action.yml`. The output is generated locally from the same verdict and includes the package version and findings; it is not a cryptographic authorization receipt.
+
 ## Real MCP scanning
 
-`0.3.0` can scan a live stdio MCP server, not just a saved JSON manifest. The CLI launches the server locally, performs the MCP `initialize` handshake, calls `tools/list`, and scans the returned tool metadata. It uses a timeout cap so a broken or malicious server cannot hang CI forever.
+`mcp-proof` can scan a live stdio MCP server, not just a saved JSON manifest. The CLI launches the server locally, performs the MCP `initialize` handshake, calls `tools/list`, and scans the returned tool metadata. It uses a timeout cap so a broken or malicious server cannot hang CI forever.
 
 ```bash
 npx mcp-proof --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"
@@ -170,7 +194,7 @@ The scanner only supports stdio MCP servers in this release. HTTP/SSE runtime di
 ## Programmatic API
 
 ```js
-const { evaluate, scanSkillManifest } = require('mcp-proof');
+const { evaluate, evaluateCall, scanSkillManifest } = require('mcp-proof');
 
 const result = evaluate({
   source: 'npm:@modelcontextprotocol/server-filesystem',
@@ -184,6 +208,10 @@ console.log(result.composite);  // 0.0 – 10.0
 console.log(result.reasons);    // human-readable explanations
 console.log(result.toolPoisoning.perTool);  // per-tool findings
 
+// Inspect an exact tool call before execution (does not execute or authorize it)
+const call = evaluateCall({ tool: 'read_file', arguments: { path: './README.md' } });
+console.log(call.decision);
+
 // Scan a Claude SKILL.md
 const skill = scanSkillManifest(fs.readFileSync('./SKILL.md', 'utf8'));
 console.log(skill.decision);
@@ -194,6 +222,7 @@ console.log(skill.decision);
 - **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.
 - **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

@@ -23,7 +23,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
-const { evaluate, scanSkillManifest, verifyPublisherAsync } = require('../engine.js');
+const { evaluate, evaluateCall, scanSkillManifest, verifyPublisherAsync } = require('../engine.js');
 
 const DEFAULT_MAX_INPUT_BYTES = 5 * 1024 * 1024;
 const DEFAULT_TIMEOUT_MS = 15000;
@@ -43,13 +43,18 @@ 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
 
-  If <file.json> is omitted and --stdio/--config/--skill are not used, JSON is read from stdin.
+  If <file.json> is omitted and --stdio/--config/--skill/--execute 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)
+  --markdown         emit a shareable Markdown Trust Card
+  --trust-card       alias for --markdown
+  --sarif            emit SARIF 2.1.0 for GitHub code scanning
   --live             confirm npm publisher against registry.npmjs.org (one network call)
   --timeout <ms>     MCP launch/protocol timeout per server (default: 15000)
   --source <s>       npm:@scope/pkg, git+https://..., or file://...   (drives publisher verification)
@@ -89,9 +94,9 @@ async function main() {
   if (args.selfTest) {
     return runSelfTest(args);
   }
-  const exclusiveModes = [args.stdio, args.config, args.skill].filter(Boolean).length;
+  const exclusiveModes = [args.stdio, args.config, args.skill, args.execute].filter(Boolean).length;
   if (exclusiveModes > 1) {
-    process.stderr.write('mcp-proof: use one of --stdio, --config, --skill at a time.\n');
+    process.stderr.write('mcp-proof: use one of --stdio, --config, --skill, --execute at a time.\n');
     process.exit(64);
   }
 
@@ -103,11 +108,7 @@ async function main() {
       process.stderr.write(`mcp-proof: ${err.message}\n`);
       process.exit(err.exitCode || 65);
     }
-    if (args.json) {
-      process.stdout.write(JSON.stringify(output, null, 2) + '\n');
-    } else {
-      renderMulti(output);
-    }
+    emitOutput(output, args);
     process.exit(exitCodeForDecision(output.decision));
   }
 
@@ -127,11 +128,7 @@ async function main() {
       process.stderr.write(`mcp-proof: ${err.message}\n`);
       process.exit(err.exitCode || 65);
     }
-    if (args.json) {
-      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-    } else {
-      renderHumanReadable(result, result.tool_count || 0, result.name || '');
-    }
+    emitOutput(result, args);
     process.exit(exitCodeForDecision(result.decision));
   }
 
@@ -143,11 +140,19 @@ async function main() {
       process.stderr.write(`mcp-proof: ${err.message}\n`);
       process.exit(err.exitCode || 65);
     }
-    if (args.json) {
-      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-    } else {
-      renderHumanReadable(result, result.tool_count || 0, result.name || '');
+    emitOutput(result, args);
+    process.exit(exitCodeForDecision(result.decision));
+  }
+
+  if (args.execute) {
+    let result;
+    try {
+      result = runExecute(args);
+    } catch (err) {
+      process.stderr.write(`mcp-proof: ${err.message}\n`);
+      process.exit(err.exitCode || 65);
     }
+    emitOutput(result, args);
     process.exit(exitCodeForDecision(result.decision));
   }
 
@@ -193,11 +198,7 @@ async function main() {
   result.source = args.source || (parsed.source || '');
   result.tool_count = tools.length;
 
-  if (args.json) {
-    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-  } else {
-    renderHumanReadable(result, tools.length, result.name);
-  }
+  emitOutput(result, args);
 
   process.exit(result.decision === 'allow' ? 0 : result.decision === 'warn' ? 1 : 2);
 }
@@ -206,14 +207,16 @@ function parseArgs(argv) {
   const out = {
     source: '', transport: '', bind: '', json: false, selfTest: false,
     help: false, version: false, file: '', stdio: '', config: '', skill: '',
-    live: false, timeoutMs: DEFAULT_TIMEOUT_MS,
+    execute: false, format: 'human', live: false, timeoutMs: DEFAULT_TIMEOUT_MS,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     switch (a) {
       case '-h': case '--help': out.help = true; break;
       case '-V': case '--version': out.version = true; break;
-      case '--json': out.json = true; break;
+      case '--json': out.json = true; out.format = 'json'; break;
+      case '--markdown': case '--trust-card': out.format = 'markdown'; break;
+      case '--sarif': out.format = 'sarif'; break;
       case '--self-test': out.selfTest = true; break;
       case '--source': out.source = argv[++i] || ''; break;
       case '--transport': out.transport = argv[++i] || ''; break;
@@ -221,6 +224,10 @@ 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 '--execute':
+        out.execute = 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;
       default:
@@ -577,6 +584,70 @@ function worstDecision(decisions) {
   return 'allow';
 }
 
+function emitOutput(result, args) {
+  if (args.format === 'json') {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else if (args.format === 'sarif') {
+    process.stdout.write(JSON.stringify(toSarif(result), null, 2) + '\n');
+  } else if (args.format === 'markdown') {
+    process.stdout.write(toTrustCard(result) + '\n');
+  } else if (result.results) {
+    renderMulti(result);
+  } else {
+    renderHumanReadable(result, result.tool_count || 0, result.name || result.tool || '');
+  }
+}
+
+function toTrustCard(r) {
+  const verdict = String(r.decision || 'unknown').toUpperCase();
+  const source = r.source || r.name || 'stdin';
+  const findings = r.toolPoisoning && r.toolPoisoning.perTool
+    ? r.toolPoisoning.perTool.flatMap(t => (t.patterns || []).map(p => `- **${p.name}** (${p.severity}) — ${p.reason}`))
+    : r.call_scan && r.call_scan.detected ? [`- **runtime_payload** (${r.call_scan.severity}) — ${r.call_scan.reason}`] : [];
+  const hash = r.manifestHash || r.payloadHash || 'not emitted';
+  return [
+    '# MCP Trust Card', '',
+    `**Verdict: ${verdict}**`, '',
+    '| Field | Value |', '|---|---|',
+    `| Source | ${String(source).replace(/\|/g, '\\|')} |`,
+    `| Tools scanned | ${r.tool_count ?? 'n/a'} |`,
+    `| Trust score | ${r.composite ?? 'n/a'} / 10 |`,
+    `| Findings | ${findings.length} |`,
+    `| Evidence hash | ${hash} |`,
+    `| mcp-proof | ${require('../package.json').version} |`, '',
+    '## Findings', '', findings.length ? findings.join('\n') : '- No actionable findings.', '',
+    '> Reproduce locally with `npx mcp-proof --json`.'
+  ].join('\n');
+}
+
+function toSarif(r) {
+  const results = [];
+  const findings = r.toolPoisoning && r.toolPoisoning.perTool
+    ? r.toolPoisoning.perTool.flatMap(t => (t.patterns || []).map(p => ({ ruleId: p.name, level: p.severity === 'critical' || p.severity === 'high' ? 'error' : 'warning', message: `${p.reason} (tool: ${t.tool})` })))
+    : r.call_scan && r.call_scan.detected ? [{ ruleId: 'runtime_payload', level: r.call_scan.severity === 'critical' ? 'error' : 'warning', message: r.call_scan.reason }] : [];
+  for (const f of findings) results.push({ ruleId: f.ruleId, level: f.level, message: { text: f.message } });
+  return { version: '2.1.0', $schema: 'https://json.schemastore.org/sarif-2.1.0.json', runs: [{ tool: { driver: { name: 'mcp-proof', version: require('../package.json').version, rules: [...new Map(findings.map(f => [f.ruleId, { id: f.ruleId, shortDescription: { text: f.ruleId } }])).values()] } }, results }] };
+}
+
+function runExecute(args) {
+  const raw = args.file ? readFileLimited(args.file) : readStdinLimited();
+  if (!raw.trim()) {
+    throw new Error('empty input. Pipe a tools/call JSON or pass a path.');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const e = new Error(`invalid JSON: ${err.message}`);
+    e.exitCode = 65;
+    throw e;
+  }
+  const result = evaluateCall(parsed);
+  result.mode = 'execute';
+  result.name = args.file || 'stdin';
+  return result;
+}
+
 function exitCodeForDecision(d) {
   return d === 'allow' ? 0 : d === 'warn' ? 1 : 2;
 }

package/engine.js

@@ -634,4 +634,67 @@ function evaluate(req) {
 
 function round1(v) { return Math.round(v * 10) / 10; }
 
-module.exports = { evaluate, scanTools, scanSkillManifest, verifyPublisher, verifyPublisherAsync, validateTransport, levenshtein };
+// ── Runtime tool-call authorization ──────────────────────────────────────────
+//
+// evaluateCall answers the execution-time question: given the exact tool and
+// the exact arguments, is this call still authorized? It applies the same
+// signatures used for static tool manifest scanning to the live payload.
+
+function flattenArgs(args) {
+  const values = [];
+  function walk(v) {
+    if (v == null) return;
+    if (typeof v === 'string') values.push(v);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (typeof v === 'object') Object.values(v).forEach(walk);
+    else values.push(String(v));
+  }
+  walk(args);
+  return values.join('\n');
+}
+
+function scanCall(toolName, args) {
+  const hay = [toolName, flattenArgs(args)].join('\n');
+  for (const sig of SIGNATURES) {
+    if (sig.re.test(hay)) {
+      return { detected: true, severity: sig.sev, reason: sig.reason };
+    }
+  }
+  if (HIDDEN_CHARS.test(hay)) {
+    return { detected: true, severity: 'high', reason: 'arguments contain hidden unicode characters' };
+  }
+  const b64 = hay.match(BASE64_RE);
+  if (b64) {
+    for (const m of b64) {
+      try {
+        const decoded = Buffer.from(m, 'base64').toString('utf8');
+        if (SUSPICIOUS_DECODED.test(decoded)) {
+          return { detected: true, severity: 'high', reason: 'arguments contain base64 with suspicious decoded content' };
+        }
+      } catch (_) { /* ignore */ }
+    }
+  }
+  return { detected: false, severity: 'low', reason: 'clean' };
+}
+
+function evaluateCall(req) {
+  const start = Date.now();
+  const toolName = req.tool || (req.params && req.params.name) || '';
+  const args = req.arguments || (req.params && req.params.arguments) || {};
+  const scan = scanCall(toolName, args);
+  const score = {
+    tool: toolName,
+    call_scan: scan,
+    reasons: [],
+    decision: 'allow',
+  };
+  if (scan.detected) {
+    score.reasons.push(`${scan.severity}: ${scan.reason}`);
+    if (scan.severity === 'critical') score.decision = 'block';
+    else score.decision = 'warn';
+  }
+  score.durationMs = Date.now() - start;
+  return score;
+}
+
+module.exports = { evaluate, evaluateCall, scanTools, scanCall, scanSkillManifest, verifyPublisher, verifyPublisherAsync, validateTransport, levenshtein };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-proof",
-  "version": "0.3.6",
-  "description": "Unbranded, free MCP (Model Context Protocol) server verifier — detects tool poisoning, typosquats, hidden unicode, base64 payloads, exposed transports, and skill-manifest attacks. Same engine as the VyriAI control plane, no account required.",
+  "version": "0.3.8",
+  "description": "Unbranded, free MCP (Model Context Protocol) server verifier with local Markdown Trust Cards and SARIF output — detects tool poisoning, typosquats, hidden unicode, base64 payloads, exposed transports, and skill-manifest attacks.",
   "main": "engine.js",
   "bin": {
     "mcp-proof": "bin/mcp-proof.js"