flankerhqd/cyvisguard

# CyVisGuard English | [中文](README.zh.md) 一个开源、自包含的 **AI agents 安全控制平面**。它位于 agent——任何持有凭证并代表他人调用工具的实体——与它能触及的所有事物之间， 并在每个动作上作出回答：*谁在调用，代表谁，这是否仍在他们被允许的范围内？* Agents 正在成为实际接触生产环境的身份：它们阅读工单， 查询仓库，调用内部 API，并处理无人审查的内容。 有趣的管控不再在于模型，而在于 **action（动作）**——身份与委托， 能力策略，数据流污点，以及您可以重放的审计追踪。 CyVisGuard 通过 **MCP** 执行这些管控，因此它们适用于任何使用该协议的 agent。 编码 agents 是该问题最尖锐的表现形式——完整的文件系统、shell、 网络、子 agents 以及同一上下文中不受信任的仓库内容——因此它们是 参考集成。将其指向真实的 Claude Code，它会保护每一次工具调用， 拒绝提示注入的数据窃取，捕获中毒的 `CLAUDE.md` 或 skill， 甚至拒绝会移除保护程序本身的设置更改——所有这些都流式传输到 实时审计控制台。  *每一行都是一个真实的 `GuardedSession` 调用，每一个判定都来自真实的 策略引擎——token 交换、污点追踪、仲裁、熔断。此捕获是以重放节奏展示的，而非实时录制。* 点击某一行会展开保护程序实际看到的请求和响应：  ## 两种接入方式 **1 · 查看整体运行效果——一条命令，无需 API key，无需网络** ``` docker compose -f docker/compose.yml up --build ``` 启动仪表板并端到端地测试控制平面：一个真实的 MCP client 会使其数据窃取尝试被阻断，两名员工通过同一个网关获得不同的工具视图。 打开 **http://localhost:4300/audit** 观看每一次调用的落地过程。 使用 `docker compose -f docker/compose.yml run --rm flow` 进行重放。 （可选的 `--profile llm` 会将一个真实的弱模型烘焙到镜像中， 以便 live-injection 场景可以离线运行。） 没有 Docker？同样的流程可以直接在主机上运行： ``` pnpm install pnpm dev # dashboard → http://localhost:4300 pnpm --filter @cyvisguard/demo-flow start # exercise the control plane ``` **2 · 将其置于您自己的 agent 之前** — 请参阅 **[INTEGRATIONS.md](INTEGRATIONS.md)**。 ## 保护范围 四个拦截点，每一个都写入同一个实时审计追踪。前三个是 agent 无关的； 第四个展示了当您能与 agent 本身进行集成时，它能深入到何种程度： | 层级 | 保护内容 | 适用范围 | |---|---|---| | **MCP gateway** (`apps/mcp-gateway`) | 每一次工具调用：身份 → 策略 → 数据流污点 → 审计，然后执行 | 任何 MCP client | | **聚合 MCP proxy** (`apps/mcp-proxy`) | 一个 endpoint 后的众多下游服务器，每位员工获得一个 **基于上限过滤的工具视图** | 任何 MCP client，组织范围 | | **Model gateway** (`apps/model-gateway`) | 工具层无法看到的原始 LLM 请求/响应 | Anthropic API 上的任何 agent | | **Claude Code hooks** (`apps/cc-hook`) | CC 的 *原生* 工具 (Read / Write / Bash / WebFetch / Task / Skill) | Claude Code | Proxy 是大多数组织需要的形式：agent 仅连接到 CyVisGuard，由它 代理您下游的 MCP 服务器——员工无法触及的业务不会被拒绝， 而是 **不可见的**——并且 token 交换意味着下游看到的是真实的员工， 而不是 proxy。 当 agent 允许您对其进行 hook 时，保护程序还会 **捍卫其自身的攻击面**。 在 Claude Code 上，这意味着（每一项均已通过文档和经验证实）： - **作用域锚定** 在会话的起始目录，且不随 `cd` 改变； - **中毒的 `CLAUDE.md`** 会被扫描并使会话沾染污点； - **中毒的 skill** 会在调用时被拒绝（指纹白名单 + 内容扫描）； - **移除保护程序自身 hook** 的设置更改会被拒绝； - **子 agent 派生** 会生成真实的委托子 token（撤销可级联）。 ## 控制平面 执行逻辑位于四个可替换的接口背后的微小、纯粹的包中： | 包 | 角色 | |---|---| | `@cyvisguard/registry` | 资产注册 + config-fingerprint 准入 | | `@cyvisguard/identity` | 短生命周期 NHI 身份、证明、带有嵌套委托链的 RFC-8693 式 token 交换、级联撤销 | | `@cyvisguard/gateway` | PEP：策略执行 + 数据平面污点标记 | | `@cyvisguard/policy` | 纯 TS 评估器——**基于能力**（工具由其 `{egress, scoped, stepup}` 类别判定，而非其名称）+ 五级作用域仲裁 | | `@cyvisguard/runtime-guard` | 意图对齐评分 + 断路器 | | `@cyvisguard/soc` | 从事件流中重构攻击链 | | `@cyvisguard/audit` | 共享的只追加审计 / 控制 / skills 状态 | | `@cyvisguard/agent-runtime` | `LLMProvider` + Ollama provider + 用于 live-injection 模式的 ReAct 循环 | | `@cyvisguard/model-eval` | 用于 **学习组件**（见下文）的接口、指标和测试框架 | | `@cyvisguard/shared` | 领域类型、事件总线，以及四个集成 **接口** | 采用者需要替换以将其连接到真实平台的 **接口**，位于 `@cyvisguard/shared`：`IdentityBackend`、`PolicySource`、`IntentProvider`、 `EnforcementAdapter`。演示版本附带了内存中/协作式的实现。 ## 接入模型 保护程序的两个判断位于接口之后，因此您可以用模型 而不是内置的启发式算法来支持它们——可以是现有的开放权重模型， 或者在我们发布后使用我们的模型之一： | 接口 | 问题 | 默认设置 | |---|---|---| | `ContentClassifier` | 这段文本是否为注入？ | regex baseline | | `BehaviorJudge` | 考虑到任务以及迄今为止的调用，这个 agent 是否仍在履行其职责？ | 基于规则的评分 | 目前任何本地 Ollama 模型都可以使用。将其指向一个模型并运行测试框架： ``` CYVISGUARD_JUDGE_MODEL=gemma4:e2b-it-q4_K_M \ pnpm --filter @cyvisguard/model-eval eval:judge ``` `demo-flow` 第 4 幕展示了在真实案例中的差异——一个 agent 读取 凭证并将其发送到 C2 地址，它溜过了规则（拒绝次数太少，不足以 触发熔断器），但在附加了 judge 后被捕获。 **模型永远只能 *增加* 可疑度，绝不能消除它。** 规则 baseline 总是 运行且结果是单向组合的，因此如果模型缺失、错误或被欺骗， 保护程序的强度与没有模型时完全一样。 接口和组合器位于 [`@cyvisguard/shared`](packages/shared/src/model-types.ts)；评估框架及 其客观的注意事项在 [`@cyvisguard/model-eval`](packages/model-eval) 中。 ## 引导场景 (S0–S4) 仪表板还包含脚本化但真实的场景，它们隔离地测试同一个控制平面。 打开 **`/docs`** 查看双语视觉导览：  - **S0/S1** — 中毒的 skill 在证明阶段被拒绝；已验证的 agents 形成可 追溯的委托链。 - **S2** — 注入使上下文沾染污点；数据窃取被数据流规则阻断 （或者，通过结构分区，外发工具根本不存在）。**S2 live** 驱动一个 真实的弱模型 (`qwen2.5:0.5b`)，该模型确实会上当——并被阻断。 - **S3** — 任务中途的资源请求被仲裁：自动批准 / 人工 / 拒绝。 - **S4** — 被劫持的 agent 的对齐度下降，直到熔断器触发， 级联撤销其 token，并且 SOC 重构攻击链。 ## 文档 - [INTEGRATIONS.md](INTEGRATIONS.md) — 连接 Claude Code：hooks、MCP gateway/proxy、model gateway - [packages/model-eval](packages/model-eval) — 将模型接入保护程序，以及它的评估方式 - [apps/mcp-proxy](apps/mcp-proxy) — 聚合 proxy：每位员工的工具视图 - [docker/README.md](docker/README.md) — 在容器中运行整个 stack - [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)。

标签：AI代理, AI风险缓解, DNS 反向解析, Streamlit, 人工智能安全, 合规性, 审计日志, 模型上下文协议, 自动化攻击, 访问控制, 请求拦截