0xRake/mcp-guard

# mcp-guard [](https://github.com/0xRake/mcp-guard/actions/workflows/ci.yml) [](https://github.com/0xRake/mcp-guard/actions/workflows/codeql.yml) [](https://github.com/0xRake/mcp-guard/actions/workflows/osv-scanner.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/0xRake/mcp-guard) [](LICENSE) [](https://www.npmjs.com/package/@mcp-guard/cli) **Find hardcoded secrets, command injection, SSRF, and policy violations in MCP server configs before they ship.** Static scanner + runtime gateway for Model Context Protocol servers. ``` npx @mcp-guard/cli scan ./mcp-config.json ``` 就这样。退出 0 表示干净，退出 1 表示有待处理的工作。 ## 为什么 MCP 服务器以与代理相同的凭据运行。`env` 中的泄露 API 密钥、工具描述中的中毒配置、或数据库服务器上缺失的身份验证检查，在 Claude 调用它们的那一刻就会成为攻击者的立足点。mcp-guard 在你发布之前扫描你的配置，并可以在运行时坐在任何 MCP 服务器前面，对每次调用强制执行策略。 ## 静态扫描器能检测到什么 - **泄露的密钥** — 参数中的 OpenAI 密钥、包含密码的数据库 URL、环境变量中的 GitHub 令牌、私钥、承载令牌。20 多种正则表达式家族，涵盖 AWS、Stripe、Anthropic 等。 - **注入风险** — 命令中的 shell 元字符、提示注入向量、通过误导性描述进行工具中毒、参数中的路径遍历。 - **认证缺口** — 缺少认证的数据库服务器、弱密码、无 PKCE 的 OAuth、本地主机授权服务器。 - **SSRF** — 内部 IP 范围、云元数据端点（169.254.169.254）、危险协议（`gopher://`、`file://`）、URL 参数注入。 - **合规性** — 将发现映射到 GDPR、SOC 2、HIPAA、ISO 27001 和 PCI DSS 控制。 所有内容都在本地运行。没有任何信息离开你的机器。 ## 修复功能 `mcp-guard fix` 交互式加固配置： - **密钥** — 将硬编码的密钥提取到 `${ENV_VAR}` 占位符，并告诉你需要设置哪些环境变量。 - **文件权限** — 检测可被其他用户全局读取的配置文件，并将其 `chmod 600`。会扫描 Claude Desktop、Claude Code、Cursor、VS Code 和 Windsurf 的位置。 - **工具限制** — 在 Claude Code 的 `settings.json` 中写入 `permissions.deny` 规则，以阻止危险的工具模式（如 shell 执行、文件删除等）。 - **Git 安全** — 将包含秘密的任何配置文件添加到 `.gitignore`。 - **配置卫生** — 警告位于被静默忽略路径的配置文件（例如 `~/.claude/mcp.json`，Claude Code 不会加载它）。 - **传输** — 标记已弃用的 SSE 传输并推荐使用 Streamable HTTP。 每个修复都是一个复选框。使用 `--dry-run` 预览，`--auto` 应用全部，`--backup` 先创建快照。 ## 运行时网关能防止什么 `@mcp-guard/gateway` 是一个 stdio 代理，位于 Claude 和任何 MCP 服务器之间，并对每个 JSON-RPC 帧强制执行 YAML 策略。 ``` mcp-guard-gateway run --policy ~/.mcp-guard/policy.yaml --server my-server -- node /path/to/server.js ``` 从那一刻起，每个 `tools/call` 在到达服务器之前都会根据你的策略进行检查，并且每个响应在到达 Claude 之前都会扫描外泄目标。完整的审计日志位于 `~/.mcp-guard/audit.jsonl`。 有关策略语法，请参阅 [`packages/gateway/README.md`](packages/gateway/README.md)。 ## 安装 以下之一： ``` # 快速扫描，无需安装 npx @mcp-guard/cli scan ./mcp-config.json # 全局安装 npm install -g @mcp-guard/cli # 作为开发依赖添加到您自己的项目中 pnpm add -D @mcp-guard/cli # Docker（distroless，非 root，多架构 amd64+arm64） docker run --rm ghcr.io/0xrake/mcp-guard:latest scan /config.json ``` ## 作为 MCP 服务器使用 将 mcp-guard 添加到 MCP 服务器中，以便 Claude / Cursor / VS Code 可以按需扫描配置。配置格式对所有客户端都相同。 ### Claude Desktop 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）： ``` { "mcpServers": { "mcp-guard": { "command": "npx", "args": ["-y", "@mcp-guard/mcp-server"] } } } ``` ### Claude Code 添加到项目根目录的 `.mcp.json`，或添加到 `~/.claude/settings.json`（用户级，所有项目）： ``` { "mcpServers": { "mcp-guard": { "command": "npx", "args": ["-y", "@mcp-guard/mcp-server"] } } } ``` ### Cursor 添加到 `~/.cursor/mcp.json`（用户级）或 `.cursor/mcp.json`（项目级）： ``` { "mcpServers": { "mcp-guard": { "command": "npx", "args": ["-y", "@mcp-guard/mcp-server"] } } } ``` ### VS Code 添加到项目中的 `.vscode/mcp.json`： ``` { "servers": { "mcp-guard": { "type": "stdio", "command": "npx", "args": ["-y", "@mcp-guard/mcp-server"] } } } ``` 这将暴露 `scan_config`、`check_vulnerabilities`、`monitor_traffic` 和 `generate_report` 作为工具，任何 MCP 客户端都可以调用它们。 ## 在 CI 中使用 ``` - name: Scan MCP configs run: npx @mcp-guard/cli scan mcp-config.json --output sarif --file results.sarif - name: Upload to code scanning uses: github/codeql-action/upload-sarif@v3 with: sarif_file: results.sarif ``` 输出格式：`json`、`sarif`、`markdown`、`html`、`csv`、`xml`、`pdf`。 ## 编程式使用 ``` import { MCPGuard } from '@mcp-guard/core'; const guard = new MCPGuard(); const result = await guard.scan({ command: 'node', args: ['server.js', '--api-key', 'sk-live-oops'], env: { DATABASE_URL: 'postgres://admin:pass@localhost/db' }, }); console.log(result.summary.score); // 0 console.log(result.summary.grade); // 'F' console.log(result.vulnerabilities.length); // 9 ``` 适用于单个配置或完整的 Claude Desktop 格式（`{ mcpServers: { ... } }`）。 ## REST API `@mcp-guard/api` 是一个 Fastify 服务器，通过 HTTP 公开扫描器： ``` npx @mcp-guard/api # starts on :3001 ``` ``` POST /api/scan scan a config POST /api/fix apply automated fixes GET /health health check GET /docs Swagger UI ``` ## CLI 参考 ``` mcp-guard scan standard scan mcp-guard scan --depth comprehensive deep scan mcp-guard scan -o sarif -f results.sarif SARIF output for GitHub mcp-guard fix interactive hardening mcp-guard fix --dry-run preview only mcp-guard fix --scan-home include ~/.claude, ~/.cursor, etc. mcp-guard watch -i 30 rescan every 30s on change mcp-guard report --format pdf --output r.pdf PDF report mcp-guard doctor scan known config paths mcp-guard doctor --json machine-readable output mcp-guard dashboard interactive terminal TUI mcp-guard init generate example config mcp-guard list show all scanners ``` 完整标志参考： [`docs/cli.md`](docs/cli.md)。 ## 软件包 | 软件包 | 角色 | | ------ | ---- | | [`@mcp-guard/core`](packages/core) | 扫描引擎、类型和领域扫描器 | | [`@mcp-guard/cli`](packages/cli) | 命令行接口 | | [`@mcp-guard/gateway`](packages/gateway) | stdio 代理 + 策略引擎（运行时网关） | | [`@mcp-guard/mcp-server`](packages/mcp-server) | MCP 服务器，适用于 Claude Desktop、Claude Code、Cursor、VS Code | | [`@mcp-guard/api`](packages/api) | REST API 服务器（Fastify） | | `@mcp-guard/web` | 仪表板（Next.js，内部） | ## 供应链 每一次推送和拉取请求都会运行： - **CodeQL** — JavaScript/TypeScript SAST（安全增强 + 安全与质量） - **OSV-Scanner** — 检查所有清单的 Google OSV 数据库 - **Trivy** — 文件系统和 IaC 扫描（Dockerfile、工作流） - **Semgrep** — 六套规则（security-audit、secrets、typescript、javascript、owasp-top-ten、nodejs） - **gitleaks** — 完整的 Git 历史秘密扫描 - **pnpm audit** — 生产依赖门（中等+ 阻止） - **OSSF Scorecard** — 每周仓库最佳实践评级 - **actionlint** — GitHub Actions 工作流 linter - **CycloneDX SBOM** — 在推送和发布时生成，在标签上证明 - **Self-scan** — mcp-guard 扫描自己的配置，SARIF 上传到代码扫描 发布的软件包使用 **npm provenance**（SLSA 构建证明）。Docker 镜像是 **multi-arch**（amd64、arm64）、**distroless** 基础、**non-root**、**digest-pinned**（通过 Dependabot）。 ## 开发 ``` git clone https://github.com/0xRake/mcp-guard.git cd mcp-guard pnpm install pnpm build pnpm test # 439 tests pnpm typecheck # tsc --noEmit across all packages pnpm lint # eslint pnpm audit --prod --audit-level=moderate ``` 单体仓库：pnpm 工作区 + Turborepo。每个包使用 tsup 构建。 ## 文档 - [CLI 参考](docs/cli.md) - [API 参考](docs/api-reference.md) - [架构](docs/architecture.md) - [网关策略](packages/gateway/README.md) ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](LINK_URL_18/>)。所有 PR 都需要通过供应链检查和 CODEOWNER 审查。`main` 分支受签名提交和线性历史保护。 ## 安全 通过 [GitHub Security Advisories](https://github.com/0xRake/mcp-guard/security/advisories/new) 私下报告漏洞。参见 [SECURITY.md](SECURITY.md)。 ## 许可证 MIT

标签：API 密钥, CI/CD 安全, CI 集成, GitHub Actions, LNA, MCP 安全, MITM代理, NPM 工具, OAuth 安全, SSRF, 前端正则化, 命令注入, 多平台, 安全扫描, 工具中毒, 开发者安全, 开源安全工具, 提示注入, 数据库密码, 数据投毒防御, 时序注入, 模块化设计, 模型上下文协议, 正则匹配, 硬编码密钥, 策略违规, 自动化修复, 自动化攻击, 自动笔记, 请求拦截, 路径遍历, 运行时网关, 逆向工程平台, 集群管理, 静态扫描