MCP Sentinel

Know what your MCP servers can do — before your AI agent does.

## 问题所在 您向 Claude Desktop、Cursor 或您的 agent 框架添加了一个 MCP server。现在该 server 拥有了您的 AI 可以调用的工具——这些工具可能会读取您的文件、运行 shell 命令或删除数据。 **您正在信任未曾审查的代码。** MCP Sentinel 连接到任何 MCP server，向您展示其公开的每一个工具，并允许您定义安全策略以自动阻止危险工具。 ## 快速开始 ``` # 扫描任意 MCP server — 无需安装 npx mcp-sentinel npx @modelcontextprotocol/server-filesystem /tmp ``` 就是这样。您将看到 server 公开的每一个工具，并按风险进行分类： ``` 🔍 MCP Sentinel v0.1.0 📦 Server: secure-filesystem-server v0.2.0 Capabilities: tools 🔧 Tools (14) 11 read · 3 write · 0 admin ✅ read_file Read the complete contents of a file... (3 params) ✅ read_multiple_files Read multiple files simultaneously... (1 params) ✏️ write_file Create a new file or overwrite... [write] (2 params) ✏️ create_directory Create a new directory... [write] (1 params) ✏️ move_file Move or rename files... [write] (2 params) ✅ list_directory Get a detailed listing of all files... (1 params) ✅ search_files Recursively search for files... (3 params) ... Scanned in 1706ms ``` ## 添加安全策略 在您的项目根目录下创建一个 `.mcp-policy.yml`： ``` deny: categories: [admin] # Block dangerous tools (delete, exec, shell) tools: ["write_*", "move_*"] # Block by name pattern require: maxTools: 10 # Limit attack surface allow: tools: ["write_file"] # Exceptions to deny rules ``` 然后执行： ``` npx mcp-sentinel --policy .mcp-policy.yml npx @modelcontextprotocol/server-filesystem /tmp ``` ``` 🛡️ Policy: .mcp-policy.yml ❌ secure-filesystem-server: policy FAILED (2 violations) ✖ [deny.tools] Tool 'move_file' matches denied pattern 'move_*' ✖ [require.maxTools] Server exposes 14 tools, policy allows max 10 ``` 退出代码 `2` = 发现违规。您的 CI 流水线将在此停止。 ## 在 CI/CD 中使用 在您的 GitHub Actions 工作流中添加一行： ``` - run: npx mcp-sentinel --policy .mcp-policy.yml npx ./your-mcp-server ``` 如果 server 违反了您的策略，构建将失败。查看[完整工作流示例](examples/github-action.yml)。

完整 GitHub Actions 示例

``` # .github/workflows/mcp-audit.yml name: MCP Security Audit on: [pull_request] jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: { node-version: 20 } - run: npx mcp-sentinel --policy .mcp-policy.yml npx ./your-mcp-server ```

## 它还能做什么？ ``` # 通过 HTTP 扫描远程服务器 npx mcp-sentinel http://localhost:3000/mcp # 扫描 Claude Desktop、Cursor 或 Windsurf 配置中的所有服务器 npx mcp-sentinel --config # 保存扫描并在稍后检测更改（drift detection） npx mcp-sentinel npx @modelcontextprotocol/server-filesystem /tmp --json > baseline.json npx mcp-sentinel npx @modelcontextprotocol/server-filesystem /tmp --diff baseline.json # 在一条命令中扫描多个服务器 npx mcp-sentinel npx @modelcontextprotocol/server-filesystem /tmp --- npx @modelcontextprotocol/server-github # 导出为 JSON 或 Markdown npx mcp-sentinel --json npx @modelcontextprotocol/server-filesystem /tmp npx mcp-sentinel --markdown report.md npx @modelcontextprotocol/server-filesystem /tmp ``` ## 策略参考 | 规则 | 作用 | 示例 | |------|-------------|---------| | `deny.categories` | 按类别阻止工具 | `[admin]`, `[admin, write]` | | `deny.tools` | 按名称或 glob 匹配阻止 | `["delete_*", "run_command"]` | | `require.maxTools` | 允许的工具最大数量 | `20` | | `require.aguara` | 要求零安全发现 | `clean` | | `allow.tools` | 阻止规则的例外 | `["execute_query"]` | ### 入门策略 从 [`examples/policies/`](examples/policies/) 中选择一个并进行自定义： | 策略 | 最适合 | |--------|----------| | [`permissive.yml`](examples/policies/permissive.yml) | 本地开发 —— 仅阻止破坏性模式 | | [`standard.yml`](examples/policies/standard.yml) | 团队开发 —— 阻止 admin + exec，允许写入 | | [`strict.yml`](examples/policies/strict.yml) | 生产环境 —— 阻止 admin + write，要求安全扫描 | | [`ci-pipeline.yml`](examples/policies/ci-pipeline.yml) | CI/CD —— 阻止 admin + deploy + push | ## 通过 Aguara 进行深度安全分析 MCP Sentinel 可以选择与 [Aguara](https://github.com/garagon/aguara) 集成，这是一个包含 177 条规则的安全扫描器，可检测提示词注入 (prompt injection)、数据渗出、凭据泄露等问题。 ``` # 安装 Aguara（可选） curl -fsSL https://raw.githubusercontent.com/garagon/aguara/main/install.sh | bash ``` 安装后，MCP Sentinel 会自动检测并运行分析。在您的策略中添加 `require.aguara: clean` 以强制执行零发现要求。 ## 所有选项 | 标志 | 描述 | |------|-------------| | `--policy ` | 执行安全策略（自动检测 `.mcp-policy.yml`） | | `--config` | 从 Claude Desktop / Cursor / Windsurf 配置中扫描 server | | `--diff ` | 与上一次扫描结果进行对比 | | `--transport ` | 强制传输方式：`stdio`, `sse`, `streamable-http` | | `--json` | JSON 格式输出 | | `--markdown ` | 导出 Markdown 报告 | | `--fail-on-findings` | 如果 aguara 发现问题则返回退出代码 2 | | `--no-color` | 禁用颜色 | | `--timeout ` | 连接超时（默认：30000） | ## 工作原理 ``` ┌────────────────┐ stdio │ MCP Server │ ┌──────── │ (local) │ │ └────────────────┘ ┌───────────┤ │ mcp- │ HTTP/ ┌────────────────┐ │ sentinel │ SSE │ MCP Server │ │ ├──────── │ (remote) │ │ Scan │ └────────────────┘ │ Enforce │ │ Diff │ ┌──────────────────┐ │ Report │ ──────► │ Aguara (177 │ └───────────┘ │ security rules) │ │ └──────────────────┘ ▼ .mcp-policy.yml (deny / require / allow) ``` ## 生态系统 MCP Sentinel 是 [Aguara](https://github.com/garagon/aguara) 安全生态系统的一部分： | 工具 | 作用 | |------|-------------| | **[Aguara](https://github.com/garagon/aguara)** | 安全扫描器 —— 177 条规则、NLP、toxic-flow 分析 | | **[MCP Aguara](https://github.com/garagon/mcp-aguara)** | MCP server —— 为 AI agent 提供安全扫描工具 | | **MCP Sentinel** | 策略执行 —— 审计、执行和监控 MCP server | | **[Aguara Watch](https://aguarascan.com)** | 云平台 —— 持续监控 MCP 注册表 | ## 贡献 欢迎贡献。请先开 issue 讨论您想要更改的内容。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [Apache 2.0](LICENSE) — Gustavo Aragon ([@oktsec](https://github.com/oktsec))

标签：AI安全, Chat Copilot, Claude Desktop, Cursor, DevSecOps, GNU通用公共许可证, LLM Agent, MCP安全, MITM代理, Node.js, NPM包, OSV-Scalibr, Risky Operations, 上游代理, 云安全监控, 安全策略, 工具扫描, 提示词设计, 文件系统安全, 文档安全, 文档结构分析, 权限管理, 模型上下文协议, 模型越狱, 知识图谱, 自动化攻击, 静态分析