mcp-proof 0.3.7 → 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

@@ -51,7 +51,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>] runtime authorization of a tools/call payload (reads stdin if path omitted)
+  --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)
@@ -105,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));
   }
 
@@ -129,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));
   }
 
@@ -145,11 +140,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));
   }
 
@@ -161,11 +152,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, 0, result.tool || 'execute');
-    }
+    emitOutput(result, args);
     process.exit(exitCodeForDecision(result.decision));
   }
 
@@ -211,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);
 }
@@ -224,14 +207,16 @@ function parseArgs(argv) {
   const out = {
     source: '', transport: '', bind: '', json: false, selfTest: false,
     help: false, version: false, file: '', stdio: '', config: '', skill: '',
-    execute: false, 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;
@@ -599,6 +584,51 @@ 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()) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-proof",
-  "version": "0.3.7",
-  "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"