themayursinha/mcp-visor

``` ___ ________ ______ _ _ _____ _____ ___________ | \/ / __ \| ___ \ | | | |_ _/ ___|| _ | ___ \ | . . | / \/| |_/ / | | | | | | \ `--. | | | | |_/ / | |\/| | | | __/ | | | | | | `--. \| | | | / | | | | \__/\| | \ \_/ /_| |_/\__/ /\ \_/ / |\ \ \_| |_/\____/\_| \___/ \___/\____/ \___/\_| \_| ``` MCP 工具执行的运行时策略强制执行与审计控制平面 [](go.mod) [](LICENSE) [](https://github.com/themayursinha/mcp-visor/actions/workflows/ci.yml) [](https://goreportcard.com/report/github.com/themayursinha/mcp-visor) [](https://github.com/themayursinha/mcp-visor/releases) **研究与撰写** | | 链接 | |---|------| | **论文** | [MCP Visor：用于治理工具调用 AI 代理的确定性运行时强制执行](https://www.researchgate.net/publication/407908047_MCP_Visor_Deterministic_Runtime_Enforcement_for_Governing_Tool-Using_AI_Agents)| | **博客** | [AI 代理的运行时策略强制执行](https://themayursinha.com/architecture/2026/05/25/mcp-visor-runtime-policy-enforcement-for-ai-agents/) · [Spec 工程](https://themayursinha.com/architecture/2026/06/27/spec-engineering-the-missing-layer-in-ai-agent-security/) · [三条信任路径](https://themayursinha.com/architecture/2026/06/15/three-trust-paths-for-governing-ai-agent-architectures/) · [MCP 供应链风险](https://themayursinha.com/architecture/2026/05/06/mcp-security-the-new-supply-chain-risk-for-ai-agents/) | ## 快速统计 | 指标 | 数值 | |--------|-------| | **策略评估** | 587 ns | | **链式检测** | 2.9 µs | | **脱敏处理** | 1.8 µs | | **JSON-RPC 解码** | 1 µs | | **二进制文件大小** | ~7 MB | | **依赖项** | 2 (fsnotify + yaml.v3) | | **测试覆盖率** | 15 个包，全部通过 | ## 问题 自治 AI 代理越来越多地被通过 MCP 授予对关键基础设施的执行权限。它们可以修改云状态、执行原始 shell 命令、操纵数据库以及与系统性 API 交互。然而，AI 代理是非确定性的概率引擎，极易受到对抗性胁迫（提示词注入）和执行漂移的影响。 已有发现指出，**约 492 个 MCP 服务器**在零身份验证的情况下暴露在互联网上。工具投毒——即恶意服务器在工具描述中隐藏指令——是排名第一的攻击媒介，这已被 OWASP、NIST 和多篇学术论文记录在案。基于提示词的防护栏被证明是不可靠的——“Prompts Don't Protect”论文展示了其对未授权调用的拦截预防率为 0%。 **MCP Visor** 是一种故障安全（fail-closed）的运行时隔离基元。它直接部署在代理与系统接口之间，在 payload 执行**之前**强制执行数学上确定性的策略。它不使用 LLM 进行决策。它无法通过提示词注入被绕过。 ## 工作原理 ``` AI Agent → mcp-visor proxy → policy decision → allow/deny/approve/redact → MCP server ``` 每个 `tools/call` 都会被拦截并进行评估： 1. **脱敏 (Redact)** — 从参数中剔除机密信息（API key、token、密码） 2. **拦截 (Block)** — 拒绝访问敏感文件（.env、credentials、.ssh） 3. **检查 (Check)** — 根据允许列表、拒绝列表和参数规则进行校验 4. **检测 (Detect)** — 识别危险的工具链（读取 -> 发送） 5. **审批 (Approve)** — 暂扣高风险调用以等待人工确认 6. **记录 (Log)** — 将每个决策记录到经过脱敏处理的结构化审计追踪中 ## 快速开始 ``` # 安装 go install github.com/themayursinha/mcp-visor/cmd/mcp-visor@latest # 使用 demo server 运行（60 秒内首次 enforcement） mcp-visor serve --demo # 或者从 releases 页面下载预构建的 binary： # https://github.com/themayursinha/mcp-visor/releases ``` ## 为什么选择 MCP Visor 及替代方案对比 | | MCP Visor | Runlayer | Microsoft Toolkit | Obot AI | |---|-----------|----------|-------------------|--------| | **强制执行** | 确定性（策略引擎） | LLM 作为裁判 | 确定性（策略） | 基于 LLM 的扫描 | | **感知 MCP** | ✅ 协议原生代理 | ✅ 网关 | ✅ 工具包 | ✅ | | **自托管** | ✅ 单一 Go 二进制文件 | ❌ 仅限 SaaS | ✅ TypeScript | ❌ SaaS | | **开源** | ✅ MIT | ❌ 专有 | ✅ MIT | ❌ 专有 | | **链式检测** | ✅ 滑动窗口 | ❌ | ✅ | ❌ | | **机密脱敏** | ✅ 输入/输出 | ✅ | ❌ | ❌ | | **SIEM 导出** | ✅ Syslog/CEF/JSON | ✅ | ❌ | ❌ | | **Vault/KMS 签名** | ✅ HashiCorp Vault | ❌ | ❌ | ❌ | | **Webhook 审批** | ✅ Slack/Teams/n8n | ✅ | ✅ HITL 法定人数 | ❌ | **独特优势：** 唯一开源、确定性、MCP 原生的强制执行代理，以单一二进制文件发布，支持基于 Vault 的加密签名，并导出至企业级 SIEM——无需 SaaS 订阅。 ## 适用对象 - 负责强化 AI 代理部署的**安全团队**——在代理和工具之间添加强制执行层 - 运行 MCP 基础设施的**平台工程师**——提供工具访问的审计、策略和治理 - 需要代理审计追踪的**合规人员**——带有哈希链完整性及 SIEM 导出的 JSONL 日志 - 希望安全测试其服务器的 **MCP 开发者**——默认拒绝、自动脱敏机密信息的代理 ## 架构 ``` ┌──────────────┐ ┌────────────────────────────────────────────────┐ ┌──────────────┐ │ AI Agent │────▶│ mcp-visor │────▶│ MCP Server │ │ (MCP Client)│ │ │ │ (Tools) │ └──────────────┘ │ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ └──────────────┘ │ │Redaction│ │ Policy │ │ Chain │ │ │ │ Engine │ │ Engine │ │ Detector │ │ │ └─────────┘ └──────────┘ └──────────────┘ │ │ │ │ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ │ │Approval │ │ Audit │ │ Trace │ │ │ │ Engine │ │ Logger │ │ Logger │ │ │ └─────────┘ └──────────┘ └──────────────┘ │ │ │ │ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ │ │Vault │ │ Webhook │ │ SIEM │ │ │ │ Signer │ │ Emitter │ │ Exporter │ │ │ └─────────┘ └──────────┘ └──────────────┘ │ │ │ │ Transport: stdio (local) or HTTP+SSE (remote) │ └────────────────────────────────────────────────┘ ``` ## 策略模型 策略是 YAML 文件，用于精确定义允许哪些工具以及在何种条件下允许。 ``` version: "1.0" default_action: deny # deny everything by default servers: - name: "filesystem" allowed: true tools: - name: "file_read" allowed: true risk: medium rules: - type: deny_path patterns: - "/etc/passwd" - "**/.env" - "**/*.pem" - type: allow_path patterns: - "/home/**" - "/tmp/**" - name: "shell_exec" allowed: true risk: critical approval_required: true rules: - type: deny_command_pattern patterns: - "bash\\s+-i\\s+>&" - "rm\\s+-rf\\s+/" - name: "slack" allowed: true tools: - name: "slack_send_message" allowed: true risk: high approval_required: true # Block read → send chains tool_chains: - name: "prevent_exfiltration" sources: - server: "*" tool_pattern: "file_read" sinks: - server: "*" tool_pattern: "(http_post|slack_send_message)" action: deny within_calls: 3 ``` 查看 [examples/policies/](examples/policies/) 获取更多示例。 ## 功能 ### 策略强制执行 - 带有默认拒绝机制的工具允许列表/拒绝列表 - 16 种参数规则类型：deny_path, allow_path, deny_command_pattern, allow_command_pattern, deny_command_keyword, deny_command_pattern_composite, deny_query_pattern, allow_query_pattern, allowed_repos, deny_recipient_domain, allow_recipient_domain, max_file_size, max_result_rows, max_export_rows, require_approval_always - 风险分类（严重/高/中/低） - 基于代理身份的访问控制 - 基于时间的访问限制（工作时间、拒绝访问的日期） - 使用 fsnotify 监视器进行策略热重载 ### 策略 Linting - `mcp-visor lint` CLI，用于对策略 YAML 进行静态校验 - 检测无效的正则表达式、未知的规则类型、缺失的必填字段 - 按严重性分类的输出（错误/警告/信息） - `--json`, `--strict`, `--no-info`, `--no-warnings` 输出选项 - 复合命令模式校验 ### 链式检测 - 检测危险的工具序列：读取 -> 发送，查询 -> 发布 - 可配置的滑动窗口 - 对匹配的链拒绝执行或要求审批 - 会话级别的跟踪 ### 脱敏处理 - 剔除 API key (`sk-...`)、token (`ghp_...`)、JWT、连接字符串、私钥、内部 IP - 在转发到服务器之前对参数进行脱敏 - 在返回给客户端之前对输出进行脱敏 - 拦截对敏感文件（.env, .ssh, credentials, .pem, .key）的访问 ### 审批工作流 - 基于文件：写入 `req-.json`，审批者创建 `req-.ok` 进行批准 - 基于 CLI：终端上的交互式 yes/no 提示 - 可配置的超时时间，默认采用故障安全（fail-closed）机制 - 针对审批决策的完整审计追踪 ### 持久化审批 (v2) - 带有 ed25519 签名的已签名决策回执 - 带有 nonce 和过期时间的执行 ID，用于防重放保护 - 持久化重试：持久化暂扣中的审批，代理使用已签名的回执进行重试 - 可插拔的签名者接口（内置 ed25519，支持 Vault Transit/KMS） ### Webhook 事件发射器 (v2) - 以异步 HTTP 方式交付审计和审批事件 - 使用 HMAC-SHA256 签名确保 payload 的真实性 - 可配置的带指数退避（exponential backoff）重试机制 ### 审计日志 - 包含已脱敏数据的 JSONL 格式 - 8 种事件类型：tool_call_allowed, tool_call_denied, tool_call_chain_detected, tool_call_approval_required, session_started, session_ended, policy_loaded, policy_reloaded - 哈希链条目 (SHA-256) 提供防篡改证据 - 使用 O_SYNC 写入以确保持久性 ### SIEM 导出 (v2) - RFC 5424 syslog 格式 - 用于 Splunk/Elastic 的 JSON 信封格式 - CEF (通用事件格式) - 可插拔的写入器：file, TCP, UDP ### HTTP/SSE 传输 (v2) - 通过 HTTP 连接到远程 MCP 服务器 - 用于服务器到客户端流式传输的 Server-Sent Events (SSE) - 可配置的 mTLS 支持 - 用于测试的模拟传输 ### n8n 控制平面蓝图 (v2) - 可直接导入的 n8n 工作流，用于 Slack/Teams 审批 - SIEM 转发集成 - 审计数据库存储 (PostgreSQL) ### 追踪日志 (v1.1) - 用于调试和取证的 MCP 消息级别追踪 - 三种输出格式：文本（定向 C->S/S->C），JSONL（机器可读），摘要（计数器） - 可通过 `--trace` 和 `--trace-format` CLI 标志进行配置 - 细粒度控制：握手、决策、脱敏、链式检测 ### Vault Transit 集成 (v1.1) - 由 HashiCorp Vault Transit 密钥引擎支持的加密签名 - 实现可插拔签名者接口的 `TransitSigner` 和 `TransitVerifier` - 可通过 `--vault-addr`, `--vault-token`, `--vault-key-name` CLI 标志进行配置 - 支持 TLS/mTLS，提供 CA 证书和跳过验证选项 - 支持 Vault Enterprise 的命名空间 ### 性能基准测试 (v1.1) - 覆盖 5 个热路径包的 26 项基准测试 - 策略评估：587 ns，链式检测：2.9 us，脱敏处理：1.8 us - JSON-RPC 解码：1 us，编码：180 ns - Ed25519 签名：12.9 us，验证：28.4 us - 提供 `make bench` 目标用于一键运行基准测试 ### 可观测性导出 (v1.2) - 通过实时 `ProxyMetrics` 暴露 Prometheus `/metrics` (`--metrics-addr`) - OTLP gRPC 追踪与工具调用指标 (`--otel-endpoint`)；可与 Grafana LGTM / Tempo / Mimir 搭配使用 - Span 模型：包含 `policy.decision`, `tool.name`, `session.id` 的 `mcp.tools/call`（不包含参数 payload） - 本地实验环境：[`examples/otel-lgtm`](examples/otel-lgtm/README.md) ## 与 mcp-llm-security-evaluator 对比 | | mcp-llm-security-evaluator | mcp-visor | |---|---|---| | 目的 | 评估 LLM 安全性 | 强制执行工具执行 | | 时机 | CI/CD，按需扫描 | 运行时的每一次工具调用 | | 输出 | 报告、评分、发现 | 允许/拒绝/审批，审计日志 | | LLM | 测试 LLM 响应 | 无 LLM 交互 | | MCP | 模拟的 mock 调用 | 真实的 MCP 协议代理 | **Evaluator 告诉你可能出什么错。Visor 在运行时将其拦截。** 查看 [mcp-llm-security-evaluator](https://github.com/themayursinha/mcp-llm-security-evaluator) ## CLI 参考 ``` mcp-visor serve [flags] mcp-visor lint [flags] mcp-visor version Serve flags: -server string MCP server command to proxy (local stdio) -server-name string Logical server name for policy matching -server-arg value Argument for the MCP server command (repeatable) -server-url string Remote MCP server URL (enables HTTP+SSE transport) -sse-path string SSE endpoint path (default: /sse) -insecure-tls Skip TLS certificate verification for remote servers -remote-cert string Client certificate file for remote MCP mTLS -remote-key string Client private key file for remote MCP mTLS -remote-ca string CA certificate file for remote MCP TLS verification -remote-server-name string Expected TLS server name for remote MCP server -policy string Path to policy YAML file (default: built-in deny-all) -audit-log string Path to JSONL audit log file (default: stderr) -webhook-url value Webhook endpoint for audit/approval events (repeatable) -webhook-hmac-secret string HMAC secret used to sign webhook payloads -siem-target value SIEM export target: file path, tcp:host:port, or udp:host:port (repeatable) -siem-format string SIEM export format: json, syslog-rfc5424, cef (default: json) -approval-dir string Directory for file-based approval workflow -approval-cli Use interactive CLI prompt for approval -approval-signing-key string Ed25519 private key PEM file for signing approval receipts (default: ephemeral key) -session-id string Session identifier -client-id string Client identifier -demo Start with built-in mock server and permissive policy -trace Enable MCP message tracing -trace-format string Trace output format: text, jsonl, summary (default: text) -log-level string Log level: debug, info, warn, error (default: info) -vault-addr string Vault server address for Transit signing -vault-token string Vault authentication token -vault-key-name string Vault Transit key name (default: mcp-visor-approval) -vault-namespace string Vault namespace (Enterprise) -vault-ca-cert string Vault CA certificate file -vault-skip-verify Skip Vault TLS verification -metrics-addr string Prometheus /metrics listen address (e.g. 127.0.0.1:9091) -otel-endpoint string OTLP gRPC endpoint (e.g. localhost:4317) -otel-insecure Insecure OTLP gRPC (default true, for local LGTM) -otel-service-name string OpenTelemetry service.name (default mcp-visor) -otel-trace-sample float Trace sampling ratio 0..1 when OTLP enabled (default 1) Lint flags: -json Output in JSON format -strict Treat warnings as errors -no-info Hide info-level findings -no-warnings Hide warning-level findings ``` ## 开发 ``` # 构建 go build ./cmd/mcp-visor/ # 测试 go test ./... # Benchmark make bench # Vet go vet ./... # 运行 demo go run ./examples/demo-runner/ # Lint 一个 policy go run ./cmd/mcp-visor lint examples/policies/developer-medium.yaml ``` ## 路线图 - [x] v1.0：MCP 代理、策略引擎、审计日志、链式检测、脱敏处理、审批 - [x] v1.1：基于身份的策略、基于时间的限制、CLI 审批、策略热重载 - [x] v2.0：签名决策回执、Webhook 审批、哈希链审计日志、mTLS、SIEM 导出、HTTP/SSE 传输、持久化重试审批、n8n 控制平面蓝图 - [ ] v3.0：沙盒化工具执行 (WASI)、eBPF 系统调用遥测、基于 Web 的策略仪表板、OPA/Rego 策略支持 - [ ] v4.0：更深层次的主级强制执行、形式化策略验证、多代理策略联邦 ## 安全模型 - **确定性** — 决策路径中无 LLM - **故障安全 (Fail-closed)** — 默认拒绝未知工具 - **分层防御** — 脱敏 -> 策略 -> 链式 -> 审批 - **可观测** — 每个决策均以哈希链完整性记录 - **最小化 TCB** — 单一 Go 二进制文件，依赖极少 - **防篡改** — 已签名的审批回执，绑定的证据哈希，链式审计哈希 ## 局限性 - 依赖宿主机文件系统的安全性来保障策略文件的完整性 - 审批 Webhook 使用 HMAC；visor 与控制平面之间的完整 mTLS 是可选的 - 会话状态是短暂的（重启时会丢失）；已签名的审批回执会将批准的调用绑定到请求、策略、参数以及链式上下文哈希 - 单代理、单服务器部署模型 - 暂无基于 Web 的审批仪表板（n8n 蓝图提供了 Slack/Teams 路径） ## 贡献 欢迎贡献。请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。需要完善的领域：基于 Web 的审批仪表板、Vault/KMS 实时集成、更多 MCP 服务器集成、WASI 沙盒化。 ## 许可证 MIT — 请查看 [LICENSE](LICENSE)

标签：AI Agent 安全, EVTX分析, Go 语言, MCP 协议, Streamlit, 子域枚举, 审计与治理, 日志审计, 访问控制, 运行时策略执行