Mcp Guardian

MCP Guardian

在 AI 助手与其使用的工具之间提供安全防护层。

版本 4.1.8 · 网站 · npm · 安装与故障排除 · 更新日志

4.1.8 新增内容

• 事件策略工作流 — 企业 AI 调查抽屉可根据事件生成、预览、接受或拒绝阻止规则
• 加强 npm 发布安全性 — 按顺序执行发布脚本，在服务上线前检查注册表依赖解析并验证全新安装
• 提高仪表板稳定性 — 修复安全/运行状况面板中的 React Hooks 排序问题，该问题会导致加载时出现错误 #310

4.1.7 新增内容

• 活动规则控制 — “安全 → 策略”现支持列表/搜索、软禁用/启用以及与 YAML 同步的彻底删除操作
• 策略运行时语义 — 所有规则策略均遵循 enabled: false，并保留向后兼容的默认值
• 策略变更 API — 云端和本地仪表板端点现支持列表/切换/删除，并更新了 README 指引

4.1.6 新增内容

• mcp-guardian start — 一条命令即可启动代理和 Web 仪表板，端口为 4000（本地开发默认设置）
• mcp-guardian setup — 为 Git 克隆项目提供一键安装（pnpm install、构建、仪表板 SPA）
• npm 压缩包 — 发布时预先构建仪表板 UI（deploy/dashboard-spa/out/）
• 安装指南 — 扩展了 README 和 docs/INSTALL.md 中的故障排除说明

4.1.5 新增内容

• npm 安装 — 修复了损坏的 @mcp-guardian/[email protected] 注册表清单（workspace: 依赖）。请使用 4.1.5+。

4.1.4 新增内容

• 从全局 npm 运行 mcp-guardian onboard — 解析已安装的软件包根目录（而非 cwd）；在当前目录下写入 guardian-configs/；在 npm 压缩包中附带 scripts/guardian-proxy.sh 和 policy-audit.yaml

4.1.3 新增内容

修复 npm 安装问题 — 注册表清单现与已发布的压缩包一致（使用 ^4.1.3 semver 依赖，而非 workspace:）。请使用 @mcp-guardian/[email protected] 或更高版本。通过 ./scripts/publish-npm-all.sh 发布（server/CLI 从 .tgz 压缩包发布，以确保元数据正确）。

4.1.1 新增内容

规范 npm 安装 — 修复了 4.1.0 中供应链扫描器发现的问题：

• 发布的压缩包不再包含 postinstall 或其他生命周期脚本
• 打包时会将 workspace: 依赖改写为 semver（^4.1.1）
• 通过 ./scripts/publish-npm-all.sh 发布所有软件包（core → plugin-sdk → server → cli）

4.1.0 版本新增内容

行业路线图计划合规性 — 对全部 11 个全舰队模块（A1–C5、B1–B3）进行运行时验证并接入仪表板：

• guardian roadmap audit — CLI + GET /api/agentic/plan-compliance/audit 用于验证所有已交付模块；达到生产就绪状态时退出码为 0
• 仪表板 Agentic AI 面板 — PlanCompliance、Reputation、ZeroTrust、FederatedLearning、Observatory 网格同步、SandboxWizard 捕获流量评分卡、ChainGraph（A1）
• Protection 首页条 — 在主 Protection 选项卡上显示路线图合规性评分，并提供指向 Agentic AI 的链接
• A1 ONNX 图路径 — 通过 GUARDIAN_FLEET_GRAPH_ONNX_MODEL 启用可选的全舰队链路分类器
• B3 MPC-lite 掩码 — 成对掩码的联邦梯度（GUARDIAN_FEDERATED_MPC）
• B2/B1 网格中继 — Observatory 和 Reputation 网格发布/拉取；通过 GUARDIAN_OBSERVATORY_STUB 使用开发存根
• 文档与环境变量 — 已记录 guardian roadmap * 命令；生产环境变量已列入 .env.example

运行 guardian roadmap audit --json，或在仪表板中打开 Agentic AI → Overview，即可确认合规率达到 100%。

4.0.0 版本新增内容

行业标准 MCP 防护 — Guardian 从逐次调用过滤转向全舰队、跨 Agent 安全防护：

• MTX v1 — 开放威胁交换格式（@mcp-guardian/mtx）+ 云端中心
• Guardian Certified MCP — HMAC 证明、持久化注册表、验证 API
• 多步攻击链 — 串谋检测器 + 会话链路图，并实施代理强制执行
• 能力图与意图绑定 — 工具/资源图和会话意图允许列表
• Agent 声誉账本 — 持久化评分，并由代理强制执行
• 动态沙箱等级 — shadow / redact / allow，并支持适配 RL 的持久化
• 协议模糊测试器 — 扩展语料库，支持真实拦截验证和认证门控
• 策略模拟器 — /api/policy/simulate + ab_test_policy MCP 工具
• 事件响应手册与 AI 调查员 — webhook/隔离执行器；与 Threat Lab 关联的调查
• 合规证据运行器 — 实时策略 + 审计已接入 SOC2/HIPAA/PCI/FedRAMP/ISO 映射
• guardian-bench — mcp-guardian bench CLI + 公开排行榜

关于 3.4.1 生产加固（JWKS 刷新、载荷限制、所有拦截路径均接入 SIEM、审计保留），请参阅 CHANGELOG.md。

路线图（已在 4.0 中交付）： 支持审批流程的语义策略转换器、配置溯源链、STRIDE/LINDDUN 威胁建模、行为生物特征、支持 SIEM 导出的跨 MCP 攻击链、数字孪生沙箱、零信任 SPIFFE 评分、去中心化声誉网络、生态系统 Observatory、保险风险量化 + PDF 导出，以及联邦威胁检测 — docs/AGENTIC_ROADMAP.md。

面向 CISO 买家的全舰队要求

Guardian v4 专为全舰队控制平面而设计，而非单一代理过滤器：

• 强制策略溯源 — 每次 YAML 变更都会进行哈希链记录、签名，并可导出给 SIEM/审计人员
• 人在环路中的策略审批 — NL 草案必须通过模拟并获得明确批准后才能应用
• 跨 Agent 攻击链检测 — 会话图跨越多个服务；告警以 CEF 格式导出，供 Splunk/Datadog 使用
• SPIFFE/mTLS 身份 — 零信任综合评分包含来自 SPIFFE SVID 的工作负载身份
• 云端 Observatory + 声誉网格 — 通过 MCP Guardian Cloud 汇总匿名化的全舰队遥测数据和服务声誉共识
• 满足保险要求的风险报告 — ALE 量化，并支持为网络保险工作流导出承保人 PDF

---

这解决了什么问题？

现代 AI 助手（Claude、Cursor、Cline 等）可以连接工具——读取文件、运行命令、查询数据库、向 Slack 发帖等。这些连接通常采用一种名为 MCP（Model Context Protocol）的标准。

这种能力很有用，但也有风险：

• AI 可能会读取它不该查看的文件。
• 它可能会运行 shell 命令，或因失误或恶意提示词而删除数据。
• 秘密信息可能通过工具参数泄露。
• API 费用可能在你没有察觉时飙升。

**MCP Guardian 介于中间。**每个工具请求都会先经过 Guardian。Guardian 会检查你的规则、拦截不当请求、记录发生的情况，还可以显示实时仪表板——在任何请求到达你的实际工具之前。

Your AI assistant
       │
       ▼
  MCP Guardian  ← reads your rules, blocks bad calls, keeps a log
       │
       ▼
  Your real tools (files, GitHub, database, …)

---

工作原理（逐步说明）

1. 安装 Guardian，并将其指向你现有的 MCP 配置（或者运行 mcp-guardian onboard 自动完成）。
2. Guardian 会包装你的工具服务，让 AI 与 Guardian 通信，而不是直接与它们通信。
3. AI 尝试使用工具时，Guardian 会先收到请求。
4. Guardian 会根据你的策略（由你控制的简单规则文件）检查请求。
5. 如果请求获准，Guardian 会将其转发给实际工具，并返回结果。
6. 如果请求违反规则，Guardian 会拦截请求，并告知 AI 请求已被拒绝——实际工具不会运行。
7. 每个放行和拦截事件都会保存到本地数据库，方便你查看历史记录和仪表板图表。

你始终掌握控制权：除非你批准，否则 Guardian 不会悄悄更改规则（例如，在审核 Threat Lab 建议时）。

---

架构

本节介绍 MCP Guardian 的组成方式：各部分在哪里运行、工具调用如何经过治理流程，以及可选的 Pro 流水线如何连接到代理。

本节内容：系统概览 · 工具调用路径 · 传输方式 · Agentic AI · 仪表板 · Pro 流水线 · 学习循环

系统概览

运行 mcp-guardian start 或 pnpm dashboard:proxy 时，通常由一个 Node 进程托管策略代理、仪表板 API，以及（可选的）Agentic 服务。所有组件共用同一个审计数据库（MCP_GUARDIAN_DB_PATH，默认为 ~/.mcp-guardian/history.db）。

flowchart TB
  subgraph clients [AI clients]
    Cursor[Cursor / Cline / Claude]
  end

  subgraph guardian [MCP Guardian process]
    Proxy[Proxy layer\nstdio HTTP SSE WS streamable]
  Policy[PolicyEngine\nYAML + hot reload]
  Agentic[Agentic container\noptional hooks]
  DashboardAPI[Dashboard REST + WebSocket]
  end

  subgraph storage [Persistence]
    SQLite[(history.db)]
    SIEM[SIEM exporters\noptional]
  end

  Upstream[Upstream MCP servers\nfilesystem GitHub etc]

  Cursor --> Proxy
  Proxy --> Policy
  Proxy --> Agentic
  Policy --> Proxy
  Agentic --> Proxy
  Proxy --> Upstream
  Upstream --> Proxy
  Proxy --> SQLite
  Proxy --> SIEM
  DashboardAPI --> SQLite
  clients -.-> DashboardAPI

组件	职责	主要代码
代理层	拦截 JSON-RPC；对每个 tools/call 强制执行策略	src/proxy/
策略引擎	评估 YAML 规则、速率限制、RBAC 和模式	src/policy/
历史数据库	存储放行/拦截审计记录、令牌和费用	src/database/history-db.ts
仪表板	基于同一数据库的本地 UI 和 REST API	deploy/dashboard-spa/、src/utils/dashboard-server.ts
Agentic	智能功能（注入扫描、策略生成、信任等）	src/agentic/

企业部署可以添加 Redis（速率限制、DPoP、断路器同步），并使用 PostgreSQL 替代 SQLite——详见 ENTERPRISE_DEPLOYMENT.md。

工具调用路径（tools/call）

所有危险决策都在实际 MCP 服务运行之前作出。如果 Guardian 阻止了调用，上游工具就不会收到它。

sequenceDiagram
  participant Client as AI client
  participant Transport as Proxy transport
  participant PreGuard as Pre-forward guard
  participant Policy as PolicyEngine
  participant Semantic as Semantic gate
  participant Upstream as Upstream MCP
  participant Audit as Audit queue
  participant SIEM as SIEM log

  Client->>Transport: tools/call JSON-RPC
  Transport->>PreGuard: checkExpandedPayload + agentic hooks
  alt blocked at pre-guard
    PreGuard-->>Client: JSON-RPC error -32001
    PreGuard->>Audit: denied record
    PreGuard->>SIEM: tool_blocked
  else allowed
    PreGuard->>Policy: evaluateAsync context
    alt policy block
      Policy-->>Client: JSON-RPC error
      Policy->>Audit: denied record
      Policy->>SIEM: tool_blocked
    else policy pass
      Policy->>Semantic: sync semantic request gate
      alt semantic block
        Semantic-->>Client: JSON-RPC error
        Semantic->>Audit: denied record
        Semantic->>SIEM: tool_blocked
      else forward
        Semantic->>Upstream: forward request
        Upstream-->>Transport: tool result
        Transport->>Transport: response DLP gate
        Transport-->>Client: JSON-RPC result
        Transport->>Audit: allow record
      end
    end
  end

集成详情：

1. 转发前防护（src/proxy/tool-call-pre-guard.ts）——限制展开后的参数大小，并在所有传输方式上运行 Agent 式前置钩子（提示词注入等）。
2. 策略（src/policy/policy-engine.ts）——你的 YAML 规则；速率限制计数器通过 src/policy/rate-limit-store.ts 在热重载后继续保留。
3. 语义关卡（src/proxy/proxy-post-policy-gates.ts）——转发前对参数进行可选的 LLM/启发式检查。
4. 审计——persistCallRecord → 异步 audit-write-queue → SQLite；拦截操作还会通过 StructuredLogger.logBlocked 向 SIEM 发送日志。

传输方式

Guardian 会在 IDE 可能使用的每种 MCP 传输方式上实现相同的治理堆栈：

传输方式	入口模块	tools/call 治理
stdio	src/proxy/proxy-server.ts	完整流水线（包装配置的默认方式）
HTTP	src/proxy/http-proxy-server.ts	完整流水线 + 转发前防护
SSE	src/proxy/sse-proxy-server.ts	完整流水线 + 转发前防护
WebSocket	src/proxy/websocket-proxy-server.ts	完整流水线 + 转发前防护
可流式 HTTP	src/proxy/streamable-http-proxy-server.ts	完整流水线 + 转发前防护

运行 mcp-guardian onboard，让客户端配置指向由 Guardian 包装的服务。如果 IDE 绕过 Guardian 直接连接 MCP 服务（使用原始 SSE URL 的情况很常见），调用就会无法追踪——指标和日志会显示 sse_untracked。

Agent 式 AI 集成

Agent 式功能是可选模块，会在启动时加载（src/container.ts）。它们不会取代你的 YAML 策略，而是增加观测、评分和建议。

flowchart TB
  subgraph mcp [MCP surface]
    Tools[MCP tools in src/index.ts]
  end

  subgraph container [DI container]
    Core[agentic/core.ts\npipeline scheduler telemetry]
    Features[Feature modules\npolicy gen injection trust mesh]
  end

  subgraph runtime [Runtime integration]
    Hooks[proxy-integration.ts\npre/post call hooks]
    PreGuard[tool-call-pre-guard.ts]
  end

  subgraph ui [Dashboard]
    API[agentic-dashboard-summary.ts]
    Workspace[Agentic AI workspace SPA]
  end

  DB[(agentic tables\nmigration 011)]

  Tools --> Core
  Core --> Features
  PreGuard --> Hooks
  Hooks --> Features
  API --> DB
  Workspace --> API
  Hooks --> DB

集成点	处理方式
每次 tools/call	开启 Agent 式模式时，runAgenticPreForwardHooks 可以拦截或清理参数
MCP 工具	src/index.ts 中注册了约 35 个 Agent 式工具，用于自动化和仪表板操作
模块	src/agentic/ 中有 40 多个 Agent 式模块（预测、策略生成、网格、串谋、信誉等）
仪表板	Agent 式 AI 工作区读取 /api/agentic/* 摘要
数据库	Agent 式状态存储在 011-agentic-tables.sql 中

模块级详情：docs/AGENTIC_ARCHITECTURE.md · 已交付功能：docs/AGENTIC_FEATURES.md · 路线图： docs/AGENTIC_ROADMAP.md。

仪表板与可观测性

flowchart LR
  Proxy[Proxy writes] --> DB[(history.db)]
  DB --> REST[Dashboard REST API]
  REST --> SPA[Next.js SPA\nProtection Activity Agentic]
  REST --> WS[WebSocket push\nGUARDIAN_WS_ENABLED]
  Proxy --> Prom[Prometheus metrics\noptional]
  Proxy --> SIEM[SIEM exporters\nMCP_GUARDIAN_SIEM_ENABLED]

仪表板并非独立数据库，而是读取代理写入的同一份 call_records。运行 pnpm real-life:filesystem 或其他测试时，请统一设置 MCP_GUARDIAN_DB_PATH，以确保图表与代理流量相符。

Pro 流水线架构

这些 Pro 工作流与实时代理并行运行。它们会使用审计数据、群集报告和 LLM 输出来改进检测，而不会进入每次工具调用的热路径。

Security Swarm

自动化红队循环：生成攻击、运行测试框架、检测绕过，并反馈学习结果。

• **功能：**运行脚本化步骤（构建、语料库评估、奇偶校验、测试框架），并在策略允许本应拦截的攻击时记录绕过。
• **连接方式：**在 reports/security-swarm/ 下读写；绕过和提案可为 Threat Lab 和运行时攻击学习提供信息。
• 运行：pnpm security-swarm（生产环境需要 Pro 许可证）。

Threat Lab（LLM 发现）

由人工审核 LLM 提出的新攻击测试样例和策略构想。

• 功能：收集信号（绕过、语义 TP、ThreatIntel），请求本地 LLM 提出新的语料库候选项，验证后写入 threat-lab-candidates.json，供你接受。
• **连接方式：**审核后，输出可供对抗性测试框架和可选的策略应用器使用——不会在静默中应用任何内容。
• 运行：pnpm security-swarm:threat-lab（需要 Ollama）。参见 THREAT_LAB.md。

Auto Threat Research

代理拦截可疑流量时，在后台进行 LLM 研究；写入经过验证的 adv-*.json 测试样例。

• **功能：**对拦截事件进行防抖，分类攻击类型，并在验证通过时写入测试框架测试样例（去重 + 速率上限）。
• **连接方式：**当 GUARDIAN_THREAT_RESEARCH_AUTO 和 SWARM_THREAT_RESEARCH_AUTO 均已启用时，与 Threat Lab 使用同一个自动语料库写入器。
• **运行：**在代理主机上启用环境变量；或从仪表板的 Threat Discovery 触发。

持续改进循环

flowchart LR
  Live[Live proxy blocks] --> Audit[(history.db)]
  Live --> Learn[Attack learning]
  Swarm[Security Swarm] --> Bypasses[bypasses.json]
  Bypasses --> ThreatLab[Threat Lab]
  ThreatLab --> Harness[adversarial harness]
  AutoResearch[Auto Threat Research] --> Fixtures[adv fixtures]
  Fixtures --> Harness
  Harness --> Policy[Policy YAML updates]
  Policy --> Live

深入了解：docs/ARCHITECTURE.md。

---

功能说明

以下以通俗语言介绍各项主要功能。

策略代理（核心）

**是什么：**对每次工具调用进行过滤。

**工作原理：**在 YAML 文件中编写规则（见下文策略文件）。规则可以允许特定工具、拒绝危险工具、限制工具运行频率、限制令牌用量，以及匹配参数中的模式（例如“如果路径包含 ../，则拦截”）。更改文件后，Guardian 可以重新加载规则，无需重启。

**重要性：**这是你的主要防线——快速、可预测，并完全由你掌控。

---

攻击拦截（内置于默认策略）

**是什么：**数百条针对常见滥用行为的预设检查。

**工作原理：**调用到达你的服务前，Guardian 会检查参数中隐藏的 Shell 命令、路径遍历（../etc/passwd）、SQL 注入模式、试图窃取机密的行为、可疑 URL，以及隐藏恶意文本的 Unicode 技巧等。如果匹配到某种模式，就会拦截并记录该调用。

**重要性：**许多现实世界的攻击看起来像普通工具调用；这些检查无需 AI 模型即可捕获其中很大一类攻击。

---

成本跟踪

**是什么：**持续统计工具使用成本。

**工作原理：**Guardian 会估算每次调用的令牌用量和费用（如有模型定价信息，则使用该定价）。你可以设置预算，并在仪表板中查看一段时间内的消耗速率。

**重要性：**失控的 Agent 或循环可能造成高昂费用；你可以及早发现。

---

健康监控

**是什么：**检查每个已连接 MCP 服务的健康状况。

**工作原理：**Guardian 会跟踪成功率、延迟以及服务是否正常响应。如果某个服务持续故障，熔断器可以停止对其反复发送请求。

**重要性：**你可以在用户投诉前发现集成故障或不稳定。

---

实时审计日志

简介： 对允许和拦截的操作进行永久记录。

工作原理： 每项决策都会存储在本地 SQLite 数据库中（默认路径：~/.mcp-guardian/history.db）。仪表板会读取此数据库，以显示表格、图表和筛选器。

重要性： 安全和调试需要清晰的记录——谁在何时尝试了什么，以及为何被拦截。

---

软件包扫描（CVE 和拼写仿冒）

简介： 在信任 MCP 软件包之前对其进行检查。

工作原理： Guardian 可以扫描已安装或已配置的软件包，查找已知安全问题（CVE），以及那些看起来像知名软件包、但拼写略有不同的名称（拼写仿冒）。

重要性： 供应链攻击往往会使用“几乎正确”的软件包名称。

---

对抗性测试框架（离线测试）

简介： 一套大型自动化测试，会向你的策略发送类似攻击的请求，无需运行中的 AI。

工作原理： 在仓库中运行 pnpm harness。它会重放 800 多个测试样例，并报告哪些请求会被拦截或允许。

重要性： 你可以修改规则并立即查看是否误伤了正常使用，或留下了安全漏洞。

---

真实场景（实时测试）

简介： 通过 Guardian，针对真实文件系统 MCP 服务运行一段较短或较长的真实攻击流量测试。

工作原理： pnpm real-life:filesystem 等命令会在代理运行期间，对官方文件系统服务进行路径遍历、注入及类似测试。如果使用相同的数据库路径，测试结果会显示在仪表板中。

重要性： 离线测试速度快；实时测试则能验证完整链路（代理 → 策略 → 日志 → UI）是否正常工作。

---

Agentic AI 功能（版本 4.1）

这些是 Guardian 内置的智能助手，负责监控、评分和提供建议——除非你选择应用某项建议，否则它们不会取代你的策略。

今日已发布

功能	能为你做什么
威胁预测	评估每个 MCP 服务的风险，并在问题发生前建议加固措施。
策略生成	监控常规工具使用情况，然后起草一份精简的“只包含实际所需权限”的策略，供你审核。
提示词注入检测	扫描工具参数，查找旨在劫持其他 AI 的文本（启发式检测 + 可选大模型检测）。
威胁网格（MTX）	可选择参与匿名攻击模式共享；@mcp-guardian/mtx 开放交换格式。
蜜罐	部署虚假诱饵服务；探测行为会触发警报。
供应链检查	发布者验证、依赖混淆检测、仿冒包检测、SBOM 导出。
合规映射	将安全态势映射至 SOC 2、HIPAA、PCI-DSS、FedRAMP、ISO 27001，并提供证据运行器。
漂移检测	发现服务的工具或行为出现意外变化。
红队与协议模糊测试器	使用精选和变异攻击；扩展模糊测试语料库，并设置认证门槛。
信任协议与 Guardian 评分	Agent 间协商及本地信任评分。
串谋与攻击链	跨 Agent/工具检测多步骤模式（会话链图）。
能力图与意图绑定	映射工具/资源关系；设置会话意图允许列表。
Agent 声誉	持久化声誉账本，并通过代理实施策略。
沙箱层级	按工具或服务动态选择影子、脱敏或允许模式。
Guardian 认证 MCP	使用 HMAC 签名的服务证明和验证层级。
策略模拟器	部署前预览策略影响（ab_test_policy、REST 模拟 API）。
事件处理手册与调查器	自动执行处理手册步骤；在仪表板中进行 AI 事件调查。
MCP 生命周期防护	对 tools/list、resources/read、prompts/get 实施会话门控访问。
响应数据防泄漏（DLP）	扫描上游工具响应和流式输出中的机密信息。
强化学习调优	使用上下文老虎机和 Thompson 抽样优化阈值。

仪表板： 在 Web UI 中打开 Agentic AI，查看概览图表、信任评分、审计表和管理工具。参见 Agentic 功能指南。

行业标准路线图（已在 4.0 中交付）

Guardian 的行业标准层提供跨服务、跨 Agent、系统级防护，满足企业 CISO 在整个 Guardian 部署中强制实施的需求。全部十一项能力已在 v4.0 中交付：

层级	功能	主题
1 — 范式	A1 跨 MCP 攻击链检测 · A2 数字孪生与策略沙盒 · A3 Agent 行为生物特征	洞察全局，而非只见树木
2 — 生态系统	B1 去中心化声誉网络 · B2 生态系统健康观测台 · B3 联邦式威胁检测	跨部署的网络效应
3 — 企业	C1 配置溯源链 · C2 以代码形式进行威胁建模（STRIDE/LINDDUN） · C3 零信任持续验证 · C4 保险风险量化 · C5 语义策略转换器	面向合规、CFO 和业务利益相关方

构建顺序（12 个月）： 阶段 1（C5、C1、C2、A3）→ 阶段 2（A1、A2、C3）→ 阶段 3（B1、B2、C4）→ 阶段 4 研究（B3）。

完整详情、已在代码中实现的基础功能，以及差异化理由：docs/AGENTIC_ROADMAP.md。

验证合规性： 运行 guardian roadmap audit（或使用 --json 获取机器可读的输出）。仪表板的 Agentic AI → Overview 标签页会通过 Industry Roadmap Compliance 显示相同的运行时审计结果。其他 CLI 工具：guardian roadmap fleet-graph-train、federated-export|import、observatory-sync、reputation-sync。参见 Agentic 快速入门。

生产环境变量（可选）：舰队攻击链阻断（GUARDIAN_FLEET_CHAIN_BLOCK_CONFIDENCE）、多区域 Redis（GUARDIAN_FLEET_REGION）、观测台中继或开发存根（GUARDIAN_OBSERVATORY_RELAY_URL、GUARDIAN_OBSERVATORY_STUB）、联邦学习（GUARDIAN_FEDERATED_LEARNING、GUARDIAN_FEDERATED_MPC）、ONNX 图模型（GUARDIAN_FLEET_GRAPH_ONNX_MODEL）。完整列表见 .env.example。

---

Web 仪表板

它是什么： 一个本地网站（默认地址为 http://localhost:4000），用于展示 Guardian 的运行情况。

工作原理： 运行 mcp-guardian start（或从 git 克隆的项目中运行 pnpm dashboard:proxy）时，同一个进程会同时提供仪表板和 API。界面会读取历史数据库中的真实数据，而非虚构的演示数据。

主要区域：

区域	可查看内容
Protection	总体状态，以及对当前配置的通俗分析。
Activity	允许和拦截调用的审计日志。
Threats	活跃威胁和隔离操作。
Security	安全评分和趋势。
Operations	流量、错误和成本随时间变化的图表。
Agentic AI	自主功能：信任、威胁、策略、运维、审计和工具。行业路线图面板（A1–C5、B1–B3）位于此处，Overview 中提供计划合规性审计。
Settings	服务、策略和设置清单。

提示： 如果图表显示“此时间范围内没有流量”，请扩大 Time window 下拉菜单中的时间范围（例如 Last 7 days）。较短的时间范围只显示最近的调用。

---

安全蜂群（Pro）

它是什么： 一组自动化测试器，会持续尝试像攻击者一样突破你的策略。

工作原理：

• 一条路径生成并执行攻击、检查是否存在绕过方式，并撰写报告。
• 另一条路径从代理中真实发生的拦截中学习，并随着时间推移改进检测。
• 两条路径相互反馈，因此随着部署接收真实流量，测试也会变得更完善。

重要性： 策略的强度取决于你针对哪些攻击进行过测试；安全蜂群会持续扩大测试范围。

运行：pnpm security-swarm（生产环境需要许可证）。架构图：架构 § Pro 流水线（上文）。

---

Threat Lab（Pro）

简介： 使用本地 AI 模型，根据 Guardian 观察到的内容，提出新的攻击模式和规则构想。

工作原理：

1. 收集近期拦截、CVE 数据和群体发现中的信号。
2. 模型提出新的测试用例和可能的策略条目。
3. 自动检查验证提案。
4. 由你审核并批准——不会自动应用任何内容。

运行：pnpm security-swarm:threat-lab（需要 Ollama 或其他已配置的大模型）。参见 THREAT_LAB.md。

---

Auto Threat Research（Pro）

简介： 在有趣的内容被拦截时开展后台研究。

工作原理： 代理拦截可疑调用时，可以将事件加入队列、分组，并由大模型分析以分类攻击类型，再将其添加到你的研究语料库中。它不会自行更改实时策略——而是为你构建知识，供日后使用。

获得许可后，通过 GUARDIAN_THREAT_RESEARCH_AUTO=true 启用。

---

Guardian Autopilot（Pro）

简介： 一条命令即可完成设置：封装 MCP 配置、启动代理、启用仪表板，以及可选的后台服务（摘要、学习）。

工作原理：

pnpm autopilot:init -- --apply
pnpm autopilot:start

参见 AUTOPILOT.md。

---

免费版与 Pro 版

	免费版（社区版）	Pro
策略代理和 YAML 规则	是	是
攻击拦截、审计日志、成本跟踪	是	是
测试框架和真实场景	是	是
完整企业仪表板	有限 / 开发绕过	是
Security Swarm、Threat Lab、Autopilot	否	是
Fleet、SSO、Kubernetes、PostgreSQL	否	是

本地开发可在运行 pnpm dashboard:proxy 时使用 GUARDIAN_CI_BYPASS_LICENSE=true。生产环境中的 Pro 版需要许可证——PRO_SETUP.md。

---

开始使用——安装、克隆并运行

本节介绍启动 Guardian 的所有方式：日常使用可通过 npm 安装，开发可通过 git clone，运行 mcp-guardian start（或在仓库中运行 pnpm dashboard:proxy）即可在端口 4000 上同时启动代理 + Web 仪表板。

npm 说明： mcp-guardian start、setup 和 onboard --start 已在 GitHub 上的 4.1.6 版本中提供。如果帮助信息中没有 mcp-guardian start，说明你的全局安装版本早于 4.1.6——请使用下方的 git clone + build，或在发布后运行 npm install -g @mcp-guardian/[email protected]。完整修复说明：docs/INSTALL.md。

所需条件

要求	说明
Node.js 18+	@mcp-guardian/server 所需
npm	用于全局安装或运行已发布的 CLI
pnpm	仅在通过 git clone 开发时使用（pnpm install、pnpm build）
Git	仅用于克隆源代码的工作流
Ollama（可选）	用于开发环境中的语义检测、Threat Lab 和 Auto Threat Research 的本地大模型，地址为 http://127.0.0.1:11434

---

从 npm 安装（推荐用户使用）

安装已发布的服务端软件包。请指定 4.1.5+——较早的 4.1.1–4.1.4 版本在 npm 上的 workspace: 元数据存在问题。4.1.6 新增了 start / setup（请查看 GitHub 上的 master 分支，或在 npm 发布后查看）。

# Global CLI (mcp-guardian command on your PATH)
npm install -g @mcp-guardian/server@latest

# Or install in a project directory
npm install @mcp-guardian/server@latest

验证 CLI 和安装状态：

mcp-guardian --version
mcp-guardian doctor

安装内容： 编译后的 dist/、默认策略模板、预构建的仪表板静态文件（4.1.6+ 中位于 deploy/dashboard-spa/out/），以及 mcp-guardian CLI（start、onboard、proxy、analyze、doctor 等）。

安装后的推荐流程：

mcp-guardian onboard --apply
mcp-guardian start

打开 **http://localhost:4000**。也可以使用一条命令完成设置：`mcp-guardian onboard --apply --start`（4.1.6+）。

手动启动代理（高级）——仅当你需要使用自定义环境变量且不使用 start 时：

export DASHBOARD_ENABLED=true
export DASHBOARD_AUTH_DISABLED=true
export GUARDIAN_CI_BYPASS_LICENSE=true
export MCP_GUARDIAN_DB_PATH="$HOME/.mcp-guardian/history.db"
mcp-guardian proxy --config guardian-configs/filesystem.json --policy policy-audit.yaml

---

克隆并设置开发环境

如果你需要完整仓库，包括仪表板 SPA、Agentic 模块、测试、Security Swarm 和 pnpm 脚本，请使用此方式。

git clone https://github.com/rudraneel93/mcp-guardian.git
cd mcp-guardian

# Install workspace dependencies (pnpm is required for the monorepo)
corepack enable
pnpm install

# Copy optional environment overrides
cp .env.example .env
# Edit .env if you need NVD keys, LLM URLs, custom DB path, etc.

# Compile TypeScript + workspace packages + dashboard SPA (first time)
pnpm build
pnpm setup
# setup = pnpm install (if needed) + build + scripts/build-dashboard-spa.sh
# Alternative: pnpm dashboard:build

克隆后运行一条命令（安装并构建全部内容）：

git clone https://github.com/rudraneel93/mcp-guardian.git && cd mcp-guardian && pnpm install && pnpm build && pnpm setup

不进行全局安装，直接从仓库运行：

node dist/cli.js start
# or after linking: npm link && mcp-guardian start

---

配置环境

Guardian 会在启动时读取环境变量。对于本地开发，scripts/start-dashboard-proxy.sh 中的默认值通常已足够。

cp .env.example .env

变量	用途	默认值（开发）
MCP_GUARDIAN_DB_PATH	SQLite 审计/历史数据库	~/.mcp-guardian/history.db
DASHBOARD_ENABLED	REST API + Web UI	使用 mcp-guardian start 或 dashboard:proxy 时为 true
DASHBOARD_PORT	Dashboard URL 端口	4000
DASHBOARD_AUTH_DISABLED	在 localhost 上跳过登录	开发脚本中为 true
GUARDIAN_CI_BYPASS_LICENSE	在本地解锁 Pro Dashboard 功能	开发脚本中为 true
GUARDIAN_LLM_ENABLED	语义/AI 功能	开发脚本中为 true
OLLAMA_BASE_URL	本地大模型端点	http://127.0.0.1:11434
GUARDIAN_WS_ENABLED	实时 WebSocket 指标	true

示例——使用仓库本地数据库，让测试和 Dashboard 共用同一个文件：

export MCP_GUARDIAN_DB_PATH="$PWD/reports/local-history.db"
mkdir -p "$(dirname "$MCP_GUARDIAN_DB_PATH")"

完整参考：.env.example。

---

启动 Dashboard 和代理（推荐）

主要命令（npm 全局安装或 git clone，4.1.6+）：

mcp-guardian start

设置本地默认值（DASHBOARD_ENABLED、MCP_GUARDIAN_DB_PATH=~/.mcp-guardian/history.db、localhost 的许可证绕过），选择单服务器 guardian-configs/*.json（或 onboard configsDir），并运行代理 + API + UI。

自定义配置或策略：

mcp-guardian start --config guardian-configs/filesystem.json --policy default-policy.yaml
mcp-guardian start --build-dashboard   # git clone: build SPA if out/ missing

从仓库启动（开发脚本，同一套组件 + 额外开发环境变量）：

pnpm dashboard:proxy
# or: pnpm dashboard:proxy -- guardian-configs/filesystem.json default-policy.yaml

执行内容：

1. 如果 Dashboard 相关源码有更改，则重新构建 dist/（仅开发脚本）
2. 如果 Dashboard SPA 尚不存在，则构建它（deploy/dashboard-spa/out/）
3. 选择单服务器 MCP 配置，除非你传入 --config
4. 启动一个 Node 进程，运行：
   • MCP 代理（通过 stdio 连接到你的上游 MCP 服务），
   • Dashboard REST API，
   • 位于 http://localhost:4000/ 的静态 Web UI，
   • 可选的 Agentic 调度器和 WebSocket 推送。

预期控制台输出：

[dashboard-proxy] DB: /Users/you/.mcp-guardian/history.db
[dashboard-proxy] Dashboard: http://localhost:4000/
[dashboard-proxy] Config: guardian-configs/filesystem.json  Policy: default-policy.yaml  Mode: block

打开浏览器 → Protection、Activity、Agentic AI 等。如果图表为空，请扩大时间范围（例如 Last 7 days）或生成流量（见下一节）。

**停止：**在终端中按 Ctrl+C。如果端口 4000 卡住：lsof -ti :4000 | xargs kill。

---

Dashboard UI 开发（热重载）

编辑 deploy/dashboard-spa/ 下的 React 面板时，请单独运行 SPA 开发服务器：

# Terminal 1 — proxy + API (backend)
pnpm dashboard:proxy

# Terminal 2 — Next.js dev server for the SPA (frontend hot reload)
pnpm dashboard:dev

对于 SOC 风格的 API + UI 分离方式：pnpm soc:full（API 运行在 4040 端口，SPA 开发服务器——参见 package.json）。

---

最简单的方式：onboard（包装你的 AI 客户端）

npm 全局安装后（4.1.6+），让 Guardian 查找并包装 Cursor、Claude Desktop、Cline 和 Windsurf 的 MCP 配置：

mcp-guardian onboard --apply
mcp-guardian start

--apply 会修补 IDE 正在使用的 MCP JSON（并创建备份）。重启你的 AI 客户端，让流量通过 Guardian。

如果你看到“No MCP config found for client auto”：

• 先安装并配置支持 MCP 的 IDE（Cursor、Cline、Claude Desktop 或 Windsurf），或
• 指定客户端：mcp-guardian onboard --client cursor --apply，或
• 指定配置文件：mcp-guardian onboard --config /path/to/mcp.json --apply，或
• 跳过 onboard，使用仓库示例启动：mcp-guardian start --config guardian-configs/filesystem.json

常见配置路径（macOS）：

客户端	配置文件
Cline	~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Cursor	~/.cursor/mcp.json
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json

从 git clone 安装（构建前/后）：

pnpm build
pnpm onboard -- --client auto --apply
# or: node dist/cli.js onboard --apply

---

不使用 start 运行代理（高级）

建议使用 mcp-guardian start——它会自动设置相同的环境变量。仅当你需要完全控制时，才直接使用 proxy：

export DASHBOARD_ENABLED=true
export DASHBOARD_PORT=4000
export MCP_GUARDIAN_DB_PATH="$HOME/.mcp-guardian/history.db"
mcp-guardian proxy --config guardian-configs/filesystem.json --policy default-policy.yaml --blocking-mode block

从仓库启动：

node dist/cli.js proxy --config guardian-configs/filesystem.json --policy default-policy.yaml

如果没有设置 DASHBOARD_ENABLED，则只会运行代理（没有 Web UI）。日志仍会写入 MCP_GUARDIAN_DB_PATH。

---

生成测试流量并验证

在一个终端中运行 mcp-guardian start 或 pnpm dashboard:proxy：

# Same DB as the proxy (important for dashboard charts)
export MCP_GUARDIAN_DB_PATH="${MCP_GUARDIAN_DB_PATH:-$HOME/.mcp-guardian/history.db}"

# Short live attack smoke test against the official filesystem MCP server
pnpm real-life:filesystem

# Offline policy matrix (no live MCP server required)
pnpm harness

# Plain-English summary of current posture
pnpm analyze

# Industry roadmap module audit (CLI)
node dist/cli.js roadmap audit
# or after global install: mcp-guardian roadmap audit

刷新 http://localhost:4000/ → Activity / Protection 应会显示新事件。

详情：scenarios/real-life/README.md。

---

Guardian Autopilot（一键配置整个集群）

封装配置，启动代理、仪表板和可选的后台任务：

pnpm autopilot:init -- --apply
pnpm autopilot:start
pnpm autopilot:status

有关生产环境许可的信息，请参阅 docs/PRO_SETUP.md（本地开发可在运行 mcp-guardian start 或 pnpm dashboard:proxy 时使用 GUARDIAN_CI_BYPASS_LICENSE=true）。

---

Web 仪表板 — 你将看到的内容

标签页 / 区域	用途
Protection	总体状态、路线图合规性概览（v4.1+）
Activity	tools/call 允许和拦截操作的审计日志
Threats	活跃威胁、隔离区、集群链路图（A1）
Security	评分、趋势和带有 Active Rules 控件的 Policy Studio
Operations	流量、错误、成本图表
Agentic AI	信任、策略生成、观测平台、联邦学习、计划合规审计
Settings	服务、策略、设置检查清单

仪表板读取与代理相同的 SQLite 数据库（MCP_GUARDIAN_DB_PATH）。它使用的不是单独的演示数据集。

现在，你可以在 Security → Policy 中管理规则，无需手动编辑 YAML：

• 带搜索 / 筛选功能的 Active Rules 列表
• 软禁用 / 启用（为规则写入 enabled: false/true）
• 硬删除（从 policy.rules[] 中移除规则）
• 编辑器与结构化操作保持同步，因此 YAML 始终是事实来源

Agentic 功能：docs/AGENTIC_QUICKSTART.md · docs/AGENTIC_FEATURES.md。

---

命令参考

命令	作用
npm install -g @mcp-guardian/server@latest	安装已发布的 CLI
mcp-guardian start	在 :4000 启动代理 + 仪表板（推荐，4.1.6+）
mcp-guardian onboard --apply	自动封装 MCP 客户端配置
mcp-guardian onboard --apply --start	完成接入后启动（4.1.6+）
mcp-guardian setup	开发：pnpm install + 构建 + 仪表板 SPA
mcp-guardian doctor	验证安装、数据库、SPA 和配置
mcp-guardian proxy --policy …	手动启动代理（添加 --config）
pnpm install && pnpm build	开发：安装并编译 monorepo
pnpm setup / pnpm dashboard:build	开发：构建仪表板 SPA
pnpm dashboard:proxy	开发：代理 + API + UI（仓库脚本）
pnpm dashboard:dev	开发：SPA 热重载（需先运行代理）
pnpm real-life:filesystem	实时 MCP 攻击冒烟测试
pnpm harness	离线对抗性策略矩阵
pnpm analyze	通俗易懂的安全摘要
pnpm security-swarm	Pro：持续对抗性测试
pnpm autopilot:init / autopilot:start	Pro：封装并启动完整技术栈
mcp-guardian roadmap audit	验证行业路线图模块（A1–C5）

---

故障排除

症状	修复方法
帮助信息中没有 mcp-guardian start	全局安装版本低于 4.1.6。运行 git pull && pnpm build && node dist/cli.js start，或者等 4.1.6 发布到 npm 后运行 npm install -g @mcp-guardian/server@latest
unknown option --start	同上——升级到 4.1.6，或先运行 onboard --apply，再单独运行 start
InstallError / npm 中出现 workspace:	使用 @mcp-guardian/[email protected]+，不要使用 4.1.1–4.1.4；运行 npm cache clean --force 后重新安装
ETARGET / 找不到与 @mcp-guardian/core 匹配的版本	发布链未完成——维护者运行 ./scripts/publish-npm-all.sh
next: command not found（仪表盘构建）	npm：重新安装软件包（4.1.6 中包含预构建的 out/）。Git：运行 mcp-guardian setup，或运行 cd deploy/dashboard-spa && npm install && npm run build
缺少 benchmark-report.json	运行 git pull——种子文件必须位于 deploy/dashboard-spa/app/data/ 下
找不到 pnpm dashboard:proxy	在仓库根目录运行，或全局使用 mcp-guardian start
找不到 MCP 配置	运行 mcp-guardian onboard --apply，或运行 mcp-guardian start --config guardian-configs/filesystem.json
数据库磁盘 I/O 错误	停止代理；运行 rm -f ~/.mcp-guardian/history.db-wal history.db-shm history.db.pid；再运行 mcp-guardian start
仪表盘图表为空	使用与代理相同的 MCP_GUARDIAN_DB_PATH；扩大时间范围；运行 pnpm real-life:filesystem
端口 4000 已被占用	运行 lsof -ti :4000 | xargs kill，或运行 DASHBOARD_PORT=4001 mcp-guardian start
better-sqlite3 错误（pnpm 10）	运行 pnpm approve-builds → 允许 better-sqlite3 → 运行 pnpm install
启动时出现 Ollama 警告	可选——运行 ollama serve 以使用语义分析 / Threat Lab
Pro 功能已锁定	生产环境：PRO_SETUP.md。开发环境：使用 mcp-guardian start
BundlePhobia / Socket 徽章	服务端软件包仅支持 Node；使用 @mcp-guardian/core 分析大小

分步修复方法： docs/INSTALL.md · SECURITY.md · docs/REAL_WORLD_INTEGRATION.md（多服务代理）。

---

快速开始（摘要）

通过 npm：

npm install -g @mcp-guardian/server@latest
mcp-guardian onboard --apply
mcp-guardian start    # → http://localhost:4000/

通过 git：

git clone https://github.com/rudraneel93/mcp-guardian.git && cd mcp-guardian
pnpm install && pnpm build && pnpm setup
mcp-guardian start

完整的操作流程和故障排除方法，请参阅 入门指南——安装、克隆并运行 和 docs/INSTALL.md。

---

策略文件

规则存储在 default-policy.yaml 中（或你指定的路径中）。示例：

version: '1.0'
policy:
  mode: block
  default_action: block

  rules:
    - name: allow-safe-tools
      description: Only allow read-only tools
      action: block
      tools:
        allow:
          - read_file
          - list_directory
          - search

    - name: block-shell-commands
      description: Never let the AI run shell commands
      action: block
      tools:
        deny:
          - bash
          - execute_command
          - eval

    - name: rate-limit
      description: Max 60 tool calls per minute
      action: block
      maxCallsPerMinute: 60

随附的默认策略已拦截许多常见攻击模式。你可以扩展该策略，也可以从 policy-templates/ 中的模板开始。完整参考：POLICY.md。

---

你可能需要更改的设置

变量	简单说明
MCP_GUARDIAN_POLICY	规则文件的路径
MCP_GUARDIAN_DB_PATH	调用历史的存储位置（代理和测试运行器应共用此路径）
MCP_GUARDIAN_RETENTION_DAYS	审计记录的保留时长（默认 30 天）
MCP_GUARDIAN_MAX_PAYLOAD_BYTES	原始 JSON-RPC 消息的最大大小（默认 10MB）
GUARDIAN_MAX_EXPANDED_PAYLOAD_BYTES	解码后序列化工具参数的最大大小（默认 50MB）
GUARDIAN_JWKS_REFRESH_MS	OIDC JWKS 的刷新频率（默认 5 分钟）
GUARDIAN_STRICT_ALLOWLIST_RBAC	要求对 tools.allow 策略规则实施 RBAC
GUARDIAN_HEALTH_PROBE_INTERVAL_MS	定期进行 MCP 健康探测（0 = 已禁用）
GUARDIAN_SHUTDOWN_GRACE_MS	关闭时等待正在处理的调用（默认 30s）
GUARDIAN_DB_ENCRYPTION_KEY	对静态存储的敏感审计字段进行加密
GUARDIAN_DB_ENCRYPT_AUDIT_ARGS	也对审计中的脱敏参数片段进行加密（设为 true，并配置上面的密钥）
MCP_GUARDIAN_SIEM_ENABLED	将拦截／审计事件导出到 Splunk、Datadog、webhooks 等
DASHBOARD_PORT	仪表板端口（默认 4000）
GUARDIAN_DAILY_BUDGET_USD	每日支出提醒阈值
GUARDIAN_LLM_PROVIDER / OLLAMA_BASE_URL	用于语义检查和 Threat Lab 的本地 AI
GUARDIAN_CI_BYPASS_LICENSE	仅限本地开发：无需 Pro 许可证即可使用仪表板

更多信息：团队、Redis 和多服务部署请参阅 ENTERPRISE_DEPLOYMENT.md。

---

支持的 AI 客户端

Guardian 可自动发现并封装以下客户端的配置：

• Cline（VS Code）
• Claude Desktop
• Cursor
• Windsurf

也可传入任意 MCP 配置：mcp-guardian proxy --config path/to/config.json。

---

文档索引

主题	文档
安装与故障排除	docs/INSTALL.md
Agentic AI（已发布）	docs/AGENTIC_FEATURES.md
Agentic AI 路线图	docs/AGENTIC_ROADMAP.md
Agentic 架构	docs/AGENTIC_ARCHITECTURE.md
MTX 威胁交换	docs/MTX_SPEC.md
MCP 安全参考	docs/MCP_SECURITY_REFERENCE.md
自动驾驶	docs/AUTOPILOT.md
Pro 许可证	docs/PRO_SETUP.md
策略参考	docs/POLICY.md
企业部署	docs/ENTERPRISE_DEPLOYMENT.md
架构	docs/ARCHITECTURE.md
发布历史	CHANGELOG.md

---

许可证

社区功能（代理、策略、扫描、测试框架、真实场景）采用 MIT 许可证——请参阅 LICENSE 和 COMMUNITY_SCOPE.md。

Pro 功能在生产环境中需要许可证：mcp-guardian-cloud.vercel.app。请参阅 LICENSE-PRO。