openguardrails/openguardrails
GitHub: openguardrails/openguardrails
OpenGuardrails 是一套面向 AI agent 安全防护的厂商中立协议与基准排行榜，通过统一接口标准将多供应商集成复杂度从两两对接简化为一次契约集成。
Stars: 8 | Forks: 2
# OpenGuardrails
**面向 AI agent 安全与防护的厂商中立协议 —— 以及为各厂商排名的中立基准测试。**
只需进行一次安全与防护的集成，即可在所有 agent、sandbox 和 LLM 中统一执行 —— 而无需手动将每个供应商连接到每个工具。
Apache-2.0 · [openguardrails.com](https://openguardrails.com)
本 monorepo 是 **OpenGuardrails (OGR) 规范及其参考实现** 的归属地。该规范是每个 adapter、detector 和 sandbox 所遵循的规范性契约；核心 runtime、集成、基准测试、示例、技能和网站也一同置于其中，以便将变更放在一起进行审查和测试。
OGR **不是一款 guardrail 产品**：它负责定义网络传输协议并管理排行榜。各供应商在统一的接口标准下，基于检测质量展开竞争；而用户只需一种方式，即可在他们运行的所有 agent 中配置和组合安全防护措施。
- 我们定义 **网络传输协议（wire）** —— 事件、判定结果、来源、关联和组合。
- 我们为基准测试 **充当裁判**。
- 我们 **不** 构建检测能力 —— 供应商们在契约背后竞争。
```
agent adapters LLM-protocol adapters
(hermes, openclaw, (openai.chat, openai.responses,
claude-code, codex, anthropic.messages)
opencode, kilocode)
│ │
▼ ▼
┌───────────────────────────────────────────┐
│ OGR core contract │
│ GuardEvent · Verdict · Provenance · │
│ guard-context · composition · taxonomy │
└───────────────────────────────────────────┘
▲ ▲
│ │
detector plugins sandbox adapters
(config rules OR (srt, openshell —
model/classifier) runtime PEP + policy compile)
```
## 为什么需要标准
如果没有 OGR，保护 agent 的安全将是一个 `N × M × L × S` 的集成难题：需要将每个 agent、每个 detector 供应商、每个 LLM 协议和每个 sandbox 进行两两对接。
OGR 将其简化为 `N + M + L + S` —— 只需针对契约进行一次集成。
## 六个规范性组件
| 组件 | 定义内容 | OTel 类比 |
|---|---|---|
| [GuardEvent](specification/guard-event.md) | 在拦截点观察到的类型化单元 | span / 日志记录 |
| [Verdict](specification/verdict.md) | detector 对某个事件的决策 | — |
| [Provenance](specification/provenance-and-context.md) | 上下文中每一部分的信任/污染标签 | — |
| [guard-context](specification/provenance-and-context.md#guard-context-propagation) | 跨 gateway / hook / sandbox 的单一逻辑操作关联 | trace context (W3C `traceparent`) |
| [composition](specification/composition.md) | 多个供应商的判定结果如何合并为一个决策 | — |
| [enrollment & receipts](specification/enrollment-and-receipts.md) | PEP 如何向 runtime 验证身份，以及批准如何成为可验证的、与 payload 绑定的工件 | — |
| [attestation](specification/attestation.md) | 身份声明的验证强度有多高 —— 包含主体断言和通道认证的统一阶梯，以及 gateway 多路复用指南 | — |
风险类别位于 [taxonomy](specification/taxonomy.md)（`safety.*` 和 `security.*`）中，支持版本化且可替换 —— 契约引用了类别 ID，但对什么是“不安全的”保持中立。
## 两个领域，一个契约
- **Safety** —— 有害的*内容/行为*（例如毒性、自残、CSAM、品牌、话题）。主要由分类器在内容 I/O 边界进行判定。
- **Security** —— *系统妥协*（例如 prompt injection、数据泄露、恶意命令、SSRF、密钥泄漏、sandbox 逃逸、供应链）。主要依赖策略与来源，可强制执行至 sandbox 内核。
契约是统一的；但 pipeline 和执行点各不相同。请从 [概述](specification/overview.md) 开始了解。
## 一致性与基准测试
- 如果一个 detector 接受 `GuardEvent` 并根据 [JSON Schemas](schema/) 返回有效的 `Verdict`，则它是 **符合 OGR 规范的**。请参阅 [CONFORMANCE.md](CONFORMANCE.md)。
- [基准测试](benchmarks/) 会在共享语料库上评估符合规范的 detector，并发布排行榜。
## Monorepo 布局
| 路径 | 包含内容 |
|---|---|
| [`specification/`](specification/) 和 [`schema/`](schema/) | 规范性协议、schema、taxonomy、一致性和治理。 |
| [`packages/python/`](packages/python/) | `openguardrails` Python 核心 runtime (PyPI)。 |
| [`packages/javascript/`](packages/javascript/) | `@openguardrails/core` JavaScript/TypeScript 核心 runtime (npm)。 |
| [`integrations/`](integrations/) | Agent、gateway、sandbox 和 eBPF 集成类别。 |
| [`benchmarks/`](benchmarks/) | 中立的 detector 基准测试和排行榜。 |
| [`examples/`](examples/) | 可运行示例和集成索引。 |
| [`skills/openguardrails/`](skills/openguardrails/) | 用于起草和执行策略的 Agent 技能。 |
| [`website/`](website/) | [openguardrails.com](https://openguardrails.com) 的源码。 |
各 Package 保持独立版本控制和发布。monorepo 仅集中管理源码、issues、pull requests、CI 以及跨组件的变更。
有关原仓库的映射关系和发布检查清单，请参阅 [MONOREPO.md](MONOREPO.md)；有关 npm/PyPI 发布标签，请参阅 [RELEASING.md](RELEASING.md)。
### 核心 runtime 与集成
Python 和 JavaScript Package 实现了相同的 OGR 核心契约。每种语言的集成都依赖于其对应的核心：
- Python 集成依赖于 `openguardrails`。
- JavaScript/TypeScript 集成依赖于 `@openguardrails/core`。
- 最终用户通常只需安装集成包；pip 或 npm 会自动安装其核心依赖。独立的 marketplace 插件可能会捆绑核心库，以便在没有单独安装步骤的情况下直接运行。
### 集成类别
| 类别 | 目标 | 源码 |
|---|---|---|
| **Agent hook** | Claude Code | [`integrations/agent/claude-code`](integrations/agent/claude-code/) |
| | Codex | [`integrations/agent/codex`](integrations/agent/codex/) |
| | opencode | [`integrations/agent/opencode`](integrations/agent/opencode/) |
| | OpenClaw | [`integrations/agent/openclaw`](integrations/agent/openclaw/) |
| | Hermes | [`integrations/agent/hermes`](integrations/agent/hermes/) |
| | LangGraph | [`integrations/agent/langgraph`](integrations/agent/langgraph/) |
| **Gateway hook** | OpenAI · Anthropic | [`integrations/gateway/openai-anthropic`](integrations/gateway/openai-anthropic/) |
| **Sandbox hook** | Anthropic srt · NVIDIA OpenShell | [`integrations/sandbox`](integrations/sandbox/) — 计划推出独立示例 |
| **eBPF** | OGR 参考传感器 (内核进程 · 文件系统 · 网络事件) | [`integrations/ebpf/sensor`](integrations/ebpf/sensor/) |
## 开发
JavaScript Package 使用 npm workspaces：
```
npm install
npm run build
npm test
```
Python Package 构成了一个 uv workspace，也可以使用 pip 安装：
```
python -m venv .venv
. .venv/bin/activate
python -m pip install pytest
python -m pip install -e packages/python -e integrations/gateway/openai-anthropic \
-e integrations/agent/hermes -e integrations/agent/langgraph \
-e integrations/ebpf/sensor
python -m pytest
```
## 原则
1. **中立。** 协议是开放的，由基金会治理；基准测试是裁判，而不是参赛者。
2. **标准化边界，而不是大脑。** 检测能力保持竞争性。
3. **来源优先。** 最危险的情况通常是不可信的输入引发了特权操作 —— 因此信任标签是一个核心字段，而不是附加功能。
4. **纵深防御。** Gateway、agent hook 和 sandbox 观察同一个操作，并通过 `guard_id` 进行关联。
## 状态
`v0` —— 草案。有关协议版本，请参阅 [CHANGELOG.md](CHANGELOG.md)；有关规范如何演进，请参阅 [GOVERNANCE.md](GOVERNANCE.md)。欢迎贡献 —— [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
Apache-2.0。标签：AI安全, Chat Copilot, DLL 劫持, Docker镜像, 人工智能, 协议规范, 大语言模型, 安全防护, 数据可视化, 用户代理, 用户模式Hook绕过, 评估基准, 逆向工具