agent-mcp-guard 0.1.0

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-mcp-guard",
+  "version": "0.1.0",
+  "description": "Open-source CLI scanner for risky MCP server and AI agent tool configuration.",
+  "type": "module",
+  "bin": {
+    "mcp-guard": "bin/mcp-guard.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "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",
+    "publish:npm": "node ./scripts/publish-npm.js",
+    "start": "node ./bin/mcp-guard.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "security",
+    "cli",
+    "scanner",
+    "devsecops"
+  ],
+  "author": "",
+  "license": "Apache-2.0",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "examples"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,156 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { scan } from "./scan.js";
+import { generateJsonReport, generateMarkdownReport, generateTextReport } from "./report.js";
+import { compareSeverity, severityRank } from "./severity.js";
+
+const VERSION = "0.1.0";
+
+export async function runCli(argv, io) {
+  const args = argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    io.stdout.write(helpText());
+    return 0;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    io.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+
+  if (command !== "scan") {
+    io.stderr.write(`Unknown command: ${command}\n\n`);
+    io.stderr.write(helpText());
+    process.exitCode = 1;
+    return 1;
+  }
+
+  if (args.includes("--help") || args.includes("-h")) {
+    io.stdout.write(helpText());
+    return 0;
+  }
+
+  const options = parseScanArgs(args.slice(1), io.cwd);
+  const result = await scan({
+    cwd: options.cwd,
+    env: io.env,
+    configPaths: options.configPaths,
+    includeDefaults: options.includeDefaults,
+    toolVersion: VERSION
+  });
+
+  const report = renderReport(result, options.format);
+  if (options.outputPath) {
+    await fs.mkdir(path.dirname(options.outputPath), { recursive: true });
+    await fs.writeFile(options.outputPath, report, "utf8");
+    io.stdout.write(`Wrote ${options.format} report to ${options.outputPath}\n`);
+    io.stdout.write(generateTextReport(result));
+  } else {
+    io.stdout.write(report);
+  }
+
+  if (options.failOn !== "none" && shouldFail(result, options.failOn)) {
+    process.exitCode = 2;
+    return 2;
+  }
+
+  return 0;
+}
+
+function parseScanArgs(args, defaultCwd) {
+  const options = {
+    cwd: defaultCwd,
+    configPaths: [],
+    includeDefaults: true,
+    outputPath: "",
+    format: "text",
+    failOn: "none"
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--config" || arg === "-c") {
+      options.configPaths.push(resolveInputPath(readValue(args, index, arg), options.cwd));
+      index += 1;
+    } else if (arg === "--output" || arg === "-o") {
+      options.outputPath = resolveInputPath(readValue(args, index, arg), options.cwd);
+      index += 1;
+    } else if (arg === "--format" || arg === "-f") {
+      options.format = readValue(args, index, arg);
+      index += 1;
+      if (!["text", "markdown", "json"].includes(options.format)) {
+        throw new Error("--format must be one of: text, markdown, json");
+      }
+    } else if (arg === "--fail-on") {
+      options.failOn = readValue(args, index, arg);
+      index += 1;
+      if (!["critical", "high", "medium", "low", "none"].includes(options.failOn)) {
+        throw new Error("--fail-on must be one of: critical, high, medium, low, none");
+      }
+    } else if (arg === "--cwd") {
+      options.cwd = path.resolve(readValue(args, index, arg));
+      index += 1;
+    } else if (arg === "--no-defaults") {
+      options.includeDefaults = false;
+    } else {
+      throw new Error(`Unknown scan option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function readValue(args, index, optionName) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${optionName} requires a value`);
+  }
+  return value;
+}
+
+function resolveInputPath(value, cwd) {
+  return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+
+function renderReport(result, format) {
+  if (format === "json") {
+    return `${generateJsonReport(result)}\n`;
+  }
+  if (format === "markdown") {
+    return generateMarkdownReport(result);
+  }
+  return generateTextReport(result);
+}
+
+function shouldFail(result, failOn) {
+  const threshold = severityRank(failOn);
+  return result.findings.some((finding) => compareSeverity(finding.severity, threshold) >= 0);
+}
+
+function helpText() {
+  return `mcp-guard ${VERSION}
+
+Open-source scanner for risky MCP server and AI agent tool configuration.
+
+Usage:
+  mcp-guard scan [options]
+  mcp-guard version
+  mcp-guard help
+
+Scan options:
+  -c, --config <path>       Scan a specific MCP config file. Can be repeated.
+  -o, --output <path>       Write report to a file.
+  -f, --format <format>     text, markdown, or json. Default: text.
+      --fail-on <severity>  Exit 2 when finding severity is at least threshold.
+                            critical, high, medium, low, none. Default: none.
+      --cwd <path>          Working directory for project config discovery.
+      --no-defaults         Only scan paths passed with --config.
+
+Examples:
+  mcp-guard scan
+  mcp-guard scan --format markdown --output mcp-guard-report.md
+  mcp-guard scan --config .mcp.json --fail-on high
+`;
+}

package/src/config.js

@@ -0,0 +1,60 @@
+import fs from "node:fs/promises";
+
+export async function loadConfigFile(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid JSON: ${message}`);
+  }
+}
+
+export function extractServers(config, configPath) {
+  const serversBlock = config?.mcpServers ?? config?.servers;
+  if (!serversBlock || typeof serversBlock !== "object" || Array.isArray(serversBlock)) {
+    return [];
+  }
+
+  return Object.entries(serversBlock).map(([name, raw]) => normalizeServer(name, raw, configPath));
+}
+
+function normalizeServer(name, raw, configPath) {
+  const server = raw && typeof raw === "object" ? raw : {};
+  return {
+    name,
+    configPath,
+    command: normalizeString(server.command),
+    args: normalizeArgs(server.args),
+    env: normalizeEnv(server.env),
+    cwd: normalizeString(server.cwd),
+    url: normalizeString(server.url),
+    headers: normalizeEnv(server.headers),
+    raw: server
+  };
+}
+
+function normalizeString(value) {
+  return typeof value === "string" ? value : "";
+}
+
+function normalizeArgs(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item));
+  }
+  if (typeof value === "string") {
+    return [value];
+  }
+  return [];
+}
+
+function normalizeEnv(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [key, item == null ? "" : String(item)])
+  );
+}
+

package/src/discovery.js

@@ -0,0 +1,39 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export async function discoverConfigFiles({ cwd, env }) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const candidates = uniquePaths([
+    path.join(cwd, ".mcp.json"),
+    path.join(cwd, "mcp.json"),
+    path.join(cwd, ".cursor", "mcp.json"),
+    path.join(home, ".cursor", "mcp.json"),
+    path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"),
+    path.join(home, "AppData", "Roaming", "Claude", "claude_desktop_config.json"),
+    path.join(home, ".config", "Claude", "claude_desktop_config.json"),
+    path.join(home, ".config", "claude", "claude_desktop_config.json")
+  ]);
+
+  const found = [];
+  for (const candidate of candidates) {
+    if (await isReadableFile(candidate)) {
+      found.push(candidate);
+    }
+  }
+  return found;
+}
+
+async function isReadableFile(filePath) {
+  try {
+    const stat = await fs.stat(filePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function uniquePaths(paths) {
+  return [...new Set(paths.map((item) => path.resolve(item)))];
+}
+

package/src/redact.js

@@ -0,0 +1,28 @@
+const SECRET_NAME_PATTERN = /(api[_-]?key|token|secret|password|passwd|private[_-]?key|client[_-]?secret|access[_-]?key|auth|credential|session|jwt|bearer|oauth)/i;
+
+export function isSecretLikeName(name) {
+  return SECRET_NAME_PATTERN.test(name);
+}
+
+export function redactValue(value) {
+  if (!value) return "<empty>";
+  const text = String(value);
+  if (looksLikeVariableReference(text)) {
+    return text;
+  }
+  if (text.length <= 8) {
+    return "<redacted>";
+  }
+  return `${text.slice(0, 3)}...${text.slice(-3)} (${text.length} chars)`;
+}
+
+export function redactEnv(env) {
+  return Object.fromEntries(
+    Object.entries(env).map(([key, value]) => [key, isSecretLikeName(key) ? redactValue(value) : "<set>"])
+  );
+}
+
+function looksLikeVariableReference(value) {
+  return /^\$\{?[A-Z0-9_]+\}?$/i.test(value);
+}
+

package/src/report.js

@@ -0,0 +1,136 @@
+import { redactEnv } from "./redact.js";
+
+export function generateTextReport(result) {
+  const lines = [];
+  lines.push("mcp-guard scan report");
+  lines.push(`Generated: ${result.metadata.generatedAt}`);
+  lines.push(`Scanned files: ${result.summary.scannedFileCount}`);
+  lines.push(`MCP servers: ${result.summary.serverCount}`);
+  lines.push(`Findings: ${result.summary.findingCount}`);
+  lines.push(`Risk score: ${result.summary.riskScore}`);
+  lines.push(`Critical: ${result.summary.counts.critical}  High: ${result.summary.counts.high}  Medium: ${result.summary.counts.medium}  Low: ${result.summary.counts.low}`);
+  lines.push("");
+
+  if (result.scannedFiles.length > 0) {
+    lines.push("Scanned config files:");
+    for (const file of result.scannedFiles) {
+      lines.push(`- ${displayPath(file, result.metadata.cwd)}`);
+    }
+    lines.push("");
+  }
+
+  if (result.findings.length === 0) {
+    lines.push("No findings.");
+    return `${lines.join("\n")}\n`;
+  }
+
+  lines.push("Findings:");
+  for (const finding of result.findings) {
+    lines.push(`- [${finding.severity.toUpperCase()}] ${finding.id} ${finding.title}`);
+    lines.push(`  Server: ${finding.serverName}`);
+    lines.push(`  Evidence: ${finding.evidence}`);
+    lines.push(`  Fix: ${finding.recommendation}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function generateMarkdownReport(result) {
+  const lines = [];
+  lines.push("# mcp-guard Scan Report");
+  lines.push("");
+  lines.push(`Generated: ${result.metadata.generatedAt}`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`- Scanned files: ${result.summary.scannedFileCount}`);
+  lines.push(`- MCP servers: ${result.summary.serverCount}`);
+  lines.push(`- Findings: ${result.summary.findingCount}`);
+  lines.push(`- Risk score: ${result.summary.riskScore}`);
+  lines.push(`- Critical: ${result.summary.counts.critical}`);
+  lines.push(`- High: ${result.summary.counts.high}`);
+  lines.push(`- Medium: ${result.summary.counts.medium}`);
+  lines.push(`- Low: ${result.summary.counts.low}`);
+  lines.push("");
+
+  lines.push("## Scanned Files");
+  lines.push("");
+  if (result.scannedFiles.length === 0) {
+    lines.push("- None found");
+  } else {
+    for (const file of result.scannedFiles) {
+      lines.push(`- \`${displayPath(file, result.metadata.cwd)}\``);
+    }
+  }
+  lines.push("");
+
+  lines.push("## MCP Server Inventory");
+  lines.push("");
+  if (result.servers.length === 0) {
+    lines.push("- No MCP servers found.");
+  } else {
+    lines.push("| Server | Command | Args | CWD | URL | Env |");
+    lines.push("| --- | --- | --- | --- | --- | --- |");
+    for (const server of result.servers) {
+      const env = Object.entries(redactEnv(server.env)).map(([key, value]) => `${key}=${value}`).join("<br>");
+      lines.push(`| ${cell(server.name)} | ${cell(server.command || "-")} | ${cell(server.args.join(" ") || "-")} | ${cell(server.cwd || "-")} | ${cell(server.url || "-")} | ${cell(env || "-")} |`);
+    }
+  }
+  lines.push("");
+
+  lines.push("## Findings");
+  lines.push("");
+  if (result.findings.length === 0) {
+    lines.push("No findings.");
+  } else {
+    lines.push("| Severity | Rule | Server | Finding | Evidence | Recommendation |");
+    lines.push("| --- | --- | --- | --- | --- | --- |");
+    for (const finding of result.findings) {
+      lines.push(`| ${cell(finding.severity)} | ${cell(finding.id)} | ${cell(finding.serverName)} | ${cell(finding.title)} | ${cell(finding.evidence)} | ${cell(finding.recommendation)} |`);
+    }
+  }
+  lines.push("");
+
+  lines.push("## Notes");
+  lines.push("");
+  lines.push("- This report is an assistive security review, not a guarantee that all issues were found.");
+  lines.push("- Secret-like values are redacted by default.");
+  lines.push("- Review each MCP server before granting access to files, shells, SaaS accounts, or production systems.");
+  lines.push("");
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function generateJsonReport(result) {
+  return JSON.stringify(sanitizeResult(result), null, 2);
+}
+
+function cell(value) {
+  return String(value).replaceAll("|", "\\|").replaceAll("\n", "<br>");
+}
+
+function displayPath(filePath, cwd) {
+  if (!filePath || !cwd) return filePath;
+  if (filePath === cwd) return ".";
+  if (filePath.startsWith(`${cwd}/`)) return filePath.slice(cwd.length + 1);
+  return filePath;
+}
+
+function sanitizeResult(result) {
+  return {
+    metadata: result.metadata,
+    scannedFiles: result.scannedFiles,
+    servers: result.servers.map((server) => ({
+      name: server.name,
+      configPath: server.configPath,
+      command: server.command,
+      args: server.args,
+      env: redactEnv(server.env),
+      cwd: server.cwd,
+      url: server.url,
+      headers: redactEnv(server.headers)
+    })),
+    findings: result.findings,
+    summary: result.summary
+  };
+}