cyvisguard

# CyVisGuard English | [中文](README.zh.md) 一款开源、独立的 **AI 代理安全控制平台**。它位于代理（持有凭证并代表他人调用工具的实体）与代理可以访问的所有内容之间，并对每个操作进行审查：**谁在调用，代表谁，是否仍在允许范围内？** 代理正在成为实际接触生产的关键身份：它们读取票据，查询仓库，调用内部 API，并对未经审核的内容采取行动。感兴趣的控制不再位于模型层面，而是位于 **操作**层面——身份和委托、能力策略、数据流污染和可重放的审计日志。CyVisGuard 通过 **MCP** 强制执行这些控制，因此它们适用于任何使用 MCP 的代理。 编写代理是问题最严重的形式——完整的 filesystem、shell、网络、子代理和不受信任的存储库内容在同一上下文中——因此它们是参考集成。将其指向一个真实的 Claude Code，它会保护每个工具调用，拒绝提示注入的渗透，捕获中毒的 `CLAUDE.md` 或技能，甚至拒绝会删除 guard 本身的设置更改——所有这些都流式传输到实时审计控制台。  * 每行都是一个真实的 `GuardedSession` 调用，每个判决都来自真实的策略引擎——令牌交换、污染跟踪、仲裁、断路器。捕获是 reload-paced 的，不是实时录制。* 单击一行会打开 guard 实际看到的请求和响应：  > **不是 demo-ware。** 真实和脚本的内容都被诚实地标注出来，非确定性遗漏被报告为遗漏。 ## 两种方式 **1 · 查看整个系统运行 - 一条命令，无需 API 密钥，无需网络** ```bash docker compose -f docker/compose.yml up --build ``` 启动仪表板并端到端地运行控制平台：一个真实的 MCP 客户端尝试渗透被阻止，两个员工通过一个网关获得不同的工具视图。打开 **http://localhost:4300/audit** 以查看每个调用落地。使用 `docker compose -f docker/compose.yml run --rm flow` 重放。（可选的 `--profile llm` 将一个真实的弱模型编译到镜像中，以便离线运行实时注入场景。） 没有 Docker？相同的流程在主机上运行： ```bash pnpm install pnpm dev # 仪表板 → http://localhost:4300 pnpm --filter @cyvisguard/demo-flow start # 运行控制平台 ``` **2 · 将其置于您自己的代理前面** - 请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。 ## 它保护什么 四个拦截点，每个点都写入一个实时审计日志。前三个点是与代理无关的；第四个点是当您能够与代理本身集成时可以达到的深度： | 层 | 它保护什么 | 适用于 | |---|---|---| | **MCP 网关** (`apps/mcp-gateway`) | 每个工具调用：身份 → 策略 → 数据流污染 → 审计，然后执行 | 任何 MCP 客户端 | | **聚合 MCP 代理** (`apps/mcp-proxy`) | 一个端点后面的许多下游服务器，每个员工获得一个 **上限过滤的工具视图** | 任何 MCP 客户端，全组织 | | **模型网关** (`apps/model-gateway`) | 工具层无法看到的原始 LLM 请求/响应 | Anthropic API 上的任何代理 | | **Claude Code 钩子** (`apps/cc-hook`) | CC 的**原生**工具（读取/写入/Bash/WebFetch/任务/技能） | Claude Code | 代理连接仅到 CyVisGuard，它位于您的下游 MCP 服务器前面 - 员工无法访问的业务不是被拒绝，而是 **不可见** - 令牌交换意味着下游看到的是真实的员工，而不是代理。 在代理允许您挂钩的地方，guard 还会 **保护其自身的攻击面**。在 Claude Code 上，这意味着（每个都经过文档验证和经验验证）： - **范围被锚定** 到会话的起始目录，不会跟随 `cd`； - **中毒的 `CLAUDE.md`** 被扫描并污染会话； - **中毒的技能** 在调用时被拒绝（指纹白名单 + 内容扫描）； - 设置更改 **删除 guard 的钩子** 被拒绝； - **子代理派生** 产生一个真实的委托子令牌（撤销级联）。 ## 控制平台 强制执行逻辑位于四个可替换的接口后面的小型纯包中： | 包 | 角色 | |---|---| | `@cyvisguard/registry` | 资产注册 + 配置指纹准入 | | `@cyvisguard/identity` | 短寿命 NHI 身份，证明，RFC-8693 样式的令牌交换，带有嵌套委托链，级联撤销 | | `@cyvisguard/gateway` | PEP：策略强制执行 + 数据平面污染标记 | | `@cyvisguard/policy` | 纯 TS 评估器 - **基于能力的**（工具由其 `{egress, scoped, stepup}` 类评估，而非其名称）+ 五级范围仲裁 | | `@cyvisguard/runtime-guard` | 意图对齐评分 + 断路器 | | `@cyvisguard/soc` | 从事件流中重建攻击链 | | `@cyvisguard/audit` | 共享的仅追加审计 / 控制 / 技能状态 | | `@cyvisguard/agent-runtime` | `LLMProvider` + Ollama 提供者 + 用于实时注入模式的 ReAct 环路 | | `@cyvisguard/model-eval` | **学习组件**（如下）的接口，指标和测试 | | `@cyvisguard/shared` | 域类型，事件总线和四个集成 **接口** | 采用者替换的 **接口** 在 `@cyvisguard/shared` 中：`IdentityBackend`、`PolicySource`、`IntentProvider`、`EnforcementAdapter`。演示版使用内存/协作实现。 ## 插入模型 guards 的两个判断位于接口后面，因此您可以将它们与模型支持，而不是内置启发式 - 现有开放权重或我们发布的内容： | 接口 | 问题 | 默认 | |---|---|---| | `ContentClassifier` | 这段文字是注入吗？ | 正则基线 | | `BehaviorJudge` | 给定任务和到目前为止的调用，代理是否仍在执行其工作？ | 基于规则的评分 | 任何本地 Ollama 模型都可以使用。今天就指向上一个并运行测试： ```bash CYVISGUARD_JUDGE_MODEL=gemma4:e2b-it-q4_K_M \ pnpm --filter @cyvisguard/model-eval eval:judge ``` `demo-flow` 行为 4 显示了一个真实案例的差异 - 读取凭证并将它们发布到 C2 地址的代理绕过规则（拒绝次数太少以至于触发断路器），并在附加裁判后被捕获。 **模型只能添加怀疑，而不能移除怀疑。** 规则基线始终运行，结果是单向组合的，因此不存在、错误或被愚弄的模型使 guard 的安全性与没有模型时相同。接口和组合器位于 [`@cyvisguard/shared`](packages/shared/src/model-types.ts)；评估测试及其诚实的警告位于 [`@cyvisguard/model-eval`](packages/model-eval)。 ## 有指导的场景（S0-S4） 仪表板还具有脚本化但真实的场景，这些场景在隔离状态下运行相同的控制平台。打开 **`/docs`** 以获取双语视觉之旅：  - **S0/S1** - 中毒的技能在验证时被拒绝；验证的代理形成一个可追踪的委托链。 - **S2** - 注入污染上下文；渗透被数据流规则阻止（或使用结构分区，出口工具从未存在）。**S2 live** 驱动一个真实的弱模型（`qwen2.5:0.5b`），它确实采取了诱饵 - 并被阻止。 - **S3** - 在任务期间仲裁资源请求：自动批准/人工/拒绝。 - **S4** - 被劫持的代理的对齐度下降，直到断路器跳闸，撤销其令牌，SOC 重建攻击链。 ## 文档 - [INTEGRATIONS.md](INTEGRATIONS.md) - 连接 Claude Code：钩子，MCP 网关/代理，模型网关 - [packages/model-eval](packages/model-eval) - 将模型插入 guard，以及如何评估 - [apps/mcp-proxy](apps/mcp-proxy) - 聚合代理：每个员工的工具视图 - [docker/README.md](docker/README.md) - 在容器中运行整个堆栈 - [AGENTS.md](AGENTS.md) · [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) - [CHANGELOG.md](CHANGELOG.md) - 已发布的内容以及原因 · [docs/TODO.md](docs/TODO.md) - 下一步是什么 ## 自担风险 这是参考实现 - **自担风险**。演示凭证（`user:demo`，字面上的 `demo-secret`）是占位符；在实际运行之前，请提供您自己的密钥和身份后端。实现中的简化在 [SECURITY.md](SECURITY.md) 中记录。 ## 许可证 [Apache-2.0](LICENSE)。