mcpids/mcpids

# MCPIDS **MCP 入侵检测与防御系统** — 一个内联安全层，位于 AI 代理与 MCP 服务器之间，实时检查每条 JSON-RPC 消息并执行策略。 ``` AI Agent → [MCPIDS Gateway] → MCP Server ↕ [Control Plane] [Rules Engine] [Diff Engine] [Risk Engine] [Graph Engine] [Semantic Service] [Approvals Workflow] ``` ## 为什么选择 MCPIDS？ MCP 服务器正在迅速成为攻击面。它们可以： - 在工具描述中嵌入**提示注入**指令 - **窃取**工具返回的密钥（API 密钥、令牌、凭证） - 在版本之间**静默更改工具行为**（供应链风险） - 链接工具调用以执行**横向移动**跨系统 MCPIDS 位于您的 AI 代理和每个 MCP 服务器之间，让您无需更改代理或服务器即可对所有 MCP 活动具有可见性、控制力和审计能力。 ## 功能 | 功能 | 描述 | |-----------|-------------| | **内联拦截** | 检查所有 `tools/list`、`tools/call`、`initialize` 和资源请求 | | **规则引擎** | 确定性的短语/正则表达式/密钥模式匹配，内置威胁特征库 | | **语义分类器** | 可插拔分类器；本地开发使用内置 stub，Docker/K8s 通过 HTTP 连接到 `semantic-service`，并有 stub 回退机制 | | **差异引擎** | 检测快照之间的工具添加、描述更改和模式扩展 | | **风险评分** | 来自所有信号源的加权 0.0–1.0 聚合分数 | | **图引擎** | 检测横向移动和可疑调用链，支持可选的 PostgreSQL 持久化图存储 | | **审批工作流** | 暂停并通知人工审查高风险工具调用 | | **密钥脱敏** | 清除响应中的 AWS 密钥、GitHub 令牌、JWT、PEM 块等 | | **会话隔离** | 检测到严重级别活动时冻结整个会话 | | **eBPF 传感器** | 可选的 Linux 内核级进程/网络遥测，来自打包的 tracepoint/ringbuf BPF 程序，备选 `/proc` | | **审计日志** | 每次调用、判定和管理操作的不可变 PostgreSQL 日志 | | **多租户** | 租户范围的策略、规则和会话 | ## 架构 五个组件 — 按需部署： | 组件 | 角色 | |-----------|------| | **Gateway** | 热路径 HTTP 反向代理。拦截所有 MCP 流量（HTTP/SSE + stdio）。 | | **Control Plane** | 策略引擎、审批、事件管理。REST API（`:8080`）+ gRPC（`:9090`）。 | | **Agent** | 端点守护进程。发现本地 MCP 配置，可选包装 stdio 进程。 | | **Semantic Service** | HTTP 分类服务，Docker/K8s 部署使用（`/healthz`、`/classify`）。 | | **eBPF Sensor** | 仅 Linux。内核级进程 + 网络遥测，通过 kprobes。 | 完整数据流请参阅 [`docs/architecture.md`](docs/architecture.md)。 ## 检查管道 每条拦截的消息按顺序经过以下处理： 1. **模式验证** — 根据存储的 JSON Schema 验证工具调用参数 2. **规则拦截器** — Aho-Corasick 短语匹配 + 正则表达式 + 密钥模式 3. **语义拦截器** — 开发配置中的本地 stub，或 Docker/K8s 中对 `semantic-service` 的 HTTP 调用 4. **差异拦截器** — 检测自上次快照以来的能力变化 5. **风险拦截器** — 将信号聚合为 0.0–1.0 风险分数 6. **策略拦截器** — 最终决策 → 判定 ### 判定优先级 ``` quarantine > deny > require_approval > redact > hide > monitor_only > allow ``` 默认行为：**fail-closed** — 管道超时（100ms）→ 拒绝。 ## 快速开始 一键演示命令，启动模拟 MCP 服务器，在本地运行 MCPIDS，并打印过滤/脱敏输出及控制平面状态： ``` ./scripts/demo-local.sh ``` 手动启动： ``` # 启动支持服务 (Postgres, Redis, OTel collector) make docker-up # 运行数据库迁移 make migrate # 初始化默认租户、策略和规则 make seed # 启动控制平面 (REST :8080, gRPC :9090) make run-control-plane & # 启动网关 (HTTP :8443 → your MCP server) make run-gateway & # 验证 curl -s http://localhost:8080/healthz | jq . curl -s http://localhost:8080/api/v1/dashboard/summary | jq . ``` 将您的 MCP 客户端（Claude Desktop、Cursor、VS Code）指向 `http://localhost:8443` 而不是您的 MCP 服务器。所有流量将被拦截和检查。 对于包含 `semantic-service` 的容器化堆栈，请使用： ``` make docker-up-all ``` ## 威胁场景 MCPIDS 附带 8 个威胁场景fixture和相应测试： | # | 场景 | 检测层 | 判定 | |---|----------|----------------|---------| | 01 | 工具描述："ignore previous instructions" | 规则：短语匹配 | `hide` | | 02 | 工具描述指示静默窃取 | 规则：窃取短语 | `deny` | | 03 | 工具响应包含注入的提示 | 规则：响应扫描 | `redact` | | 04 | 服务器更新后出现新的破坏性工具 | 差异：添加的工具 | `require_approval` | | 05 | 工具模式扩展（`additionalProperties: true`） | 差异：模式更改 | `require_approval` | | 06 | 同一会话中 `read_secrets` → `post_to_webhook` | 图：横向移动 | `quarantine` | | 07 | stdio 工具调用 `--exec sh -c rm -rf /` | 规则：参数正则 | `deny` | | 08 | 工具描述悄然更改 | 差异：描述更改 | `require_approval` | ``` make test-threats ``` ## 内置检测特征库 **可疑工具短语**（→ `hide`）： `ignore previous instructions`、`disregard system prompt`、`do not reveal`、`act as`、`you are now`、… **窃取短语**（→ `deny`）： `send to`、`upload to`、`POST to`、`exfiltrate`、`without alerting`、`without notifying`、… **密钥模式**（→ `redact`）： AWS 访问密钥、GCP 令牌、GitHub PAT、Slack 令牌、OpenAI 密钥、JWT 令牌、PEM 私钥块 ## 运行测试 ``` make test-unit # unit tests - no Docker required make test-threats # all 8 threat scenario tests make test-integration # in-process integration tests - no Docker required make test-integration-infra # Postgres/Redis-backed integration smoke tests via Docker Compose ``` ## 项目结构 ``` cmd/ Entry points (gateway, control-plane, agent, semantic-service, sensor-ebpf) internal/ gateway/ HTTP reverse proxy + inspection pipeline policy/rules/ Rules engine with built-in signatures diff/ Snapshot comparison and schema widening detection risk/ Weighted signal aggregation → risk score semantic/ Pluggable semantic classifier (HTTP backend + local stub) graph/ Call graph and lateral movement detection (memory + PostgreSQL store) approvals/ Hold-and-notify workflow via Redis pub/sub session/ Session state machine (Redis-backed) controlplane/ REST API + gRPC service plane agent/ Local MCP discovery + stdio wrapper sensor/ eBPF sensor with ringbuf readers (Linux) + stub (all platforms) storage/ PostgreSQL (pgx/v5) + Redis (go-redis v9) pkg/types/ Exported domain types (Verdict, Decision, MCPServer, …) policies/ YAML policy files (default, strict, examples) tests/ Unit + integration tests + 8 threat scenario fixtures deploy/ Docker Compose + Dockerfiles + Kubernetes manifests docs/ Full documentation ``` ## 文档 | 文档 | 描述 | |-----|-------------| | [`docs/architecture.md`](docs/architecture.md) | 系统概述和数据流 | | [`docs/local-dev.md`](docs/local-dev.md) | 本地开发指南 | | [`docs/deployment.md`](docs/deployment.md) | 生产部署（Docker、Kubernetes、TLS） | | [`docs/policy-model.md`](docs/policy-model.md) | 规则、判定、风险评分、审批 | | [`docs/threat-model.md`](docs/threat-model.md) | 威胁参与者、场景和缓解措施 | | [`docs/api.md`](docs/api.md) | REST API 参考 | | [`docs/limitations.md`](docs/limitations.md) | 已知限制和路线图 | | [`docs/ebpf-support-matrix.md`](docs/ebpf-support-matrix.md) | eBPF 内核/发行版支持矩阵 | ## 贡献与安全 - [贡献指南](CONTRIBUTING.md) - [安全策略](SECURITY.md) - [行为准则](CODE_OF_CONDUCT.md)

标签：AI安全, AMSI绕过, API安全, Chat Copilot, CISA项目, Docker, Docker镜像, EVTX分析, IPS, IP 地址批量处理, JSON-RPC, JSON输出, MCP, Model Context Protocol, PostgreSQL, Python工具, Secret Redaction, XXE攻击, 云计算, 人工审批, 人工智能安全, 入侵检测系统, 入侵防御系统, 合规性, 域名收集, 威胁检测, 威胁检测与响应, 威胁猎捕, 子域名突变, 安全数据湖, 安全防御评估, 密钥泄露防护, 工作流引擎, 工具调用监控, 提示注入防护, 搜索引擎查询, 日志审计, 机器学习安全, 横向移动检测, 流量拦截, 测试用例, 网络安全, 网络安全审计, 规则引擎, 请求拦截, 隐私保护, 零日漏洞检测, 风险评分