CWNApps/openagentontology

# OpenAgentOntology **Agent 治理的 OpenTelemetry。** 将它指向任何 agent，它会告诉你这个 agent 能做什么——以及哪项治理控制对每个操作负责——涵盖在一个能够同时兼容所有框架的本体中：NIST 800-53、EU AI Act、OWASP LLM Top 10 以及 **MITRE ATT&CK**——每一个操作都带有你的 SOC 已经在追踪的技术（`exec` → T1059，egress → T1048，破坏性更改 → T1485）。 **由 [Cyber Warrior Network](https://cyberwarriornetwork.com) 提供** · 主页：[agent-ontology.cyberwarriornetwork.com](https://agent-ontology.cyberwarriornetwork.com) · 在线演示：[cwnapps.github.io/openagentontology](https://cwnapps.github.io/openagentontology/) ``` SOVEREIGN · score 93 · 3 frameworks · NIST 800-53 AC-5 · EU AI Act Art 14 · OWASP LLM06 ``` _{（这是 `examples/hardened_agent` 的真实输出——可复现）} 你的 agent 可以转移资金、导出记录并发布代码。如今，关于哪种控制治理这些操作的唯一记录存在于幻灯片、电子表格或某个人的脑海中。OpenAgentOntology 读取 agent 自身的源码并将其记录下来——经过类型化、评分、签名，并且每次都保持一致。 这是第一个 **Agent Ontology**——agent 技术栈中缺失的一层。 **[阅读宣言 →](./docs/MANIFESTO.md)** · **[阅读论文（预印本 PDF）→](./docs/OAO_paper_v2.pdf)** ## 证明：它在人们实际运行的 agent 上有效 我们将其指向 GitHub 上 star 数最多的两个自主编程 agent——结果都返回 **UNGOVERNED**，它们带副作用的操作中**零**个被解析为已断言的控制： | 目标 | 带副作用的操作 | 已断言 | 结论 | |---|---|---|---| | [`OpenInterpreter/open-interpreter`](https://github.com/OpenInterpreter/open-interpreter) `@e00f08e` | 21 | **0** | **UNGOVERNED 15/100** | | [`gpt-engineer-org/gpt-engineer`](https://github.com/gpt-engineer-org/gpt-engineer) `@a90fcd5` | 6 | **0** | **UNGOVERNED 15/100** | `exec` ——任意代码执行——映射到**完全没有控制**。扫描结果、签名回执以及三方验证（包括在一个编辑字节上就会失败的篡改测试）均已提交至 **[docs/real-world-scan.md](./docs/real-world-scan.md)** ——可以从上面指定的 commit 中复现。 ## 映射一次，适配所有框架 电汇防护栏不仅仅是一个“Rego 规则”。它是 NIST 800-53 AC-5 *Separation of Duties*、EU AI Act 第 14 条 *Human oversight* 以及 OWASP LLM06 *Excessive Agency*——三者的结合。审计人员、监管机构和你的董事会各自使用其中一种不同的语言。 OpenAgentOntology 将每个 agent 操作**仅映射一次**到共享的本体，并为读者关心的任何框架输出正确的控制 ID。你不再需要将同一个控制重复翻译五次。 它支持摄取： - **Repos** ——包含 agent、工具和策略的源码树 - **MCP servers** ——工具清单 - **LangChain / CrewAI agents** ——声明式 agent 规范 - **OpenAPI** ——agent 调用的 HTTP 接口 - **Rego** ——带有 deny key 且默认拒绝（fail-closed）的策略 - **Workflow YAML** ——多步骤 agent 流程 它将每个 agent 操作映射到： - **Universal Agentic Ontology**（类型化节点：Agent、Capability、Decision、Gate 等） - **NIST SP 800-53r5** · **EU AI Act** · **OWASP LLM Top 10 (2025)** · **NIST AI RMF** · **MITRE ATT&CK** · **OCSF** · **NICE** 然后它会验证本体，对 **Trust Profile** 进行评分，并生成一个可共享的 **SVG 徽章**，以及一个**仅含证书的 Ed25519 回执**，无需服务器和数据库即可验证。 ## 快速开始 无需安装步骤。纯 Python 编写，仅有三个依赖项（`pyyaml`、`cryptography`）。 ``` git clone https://github.com/CWNApps/openagentontology cd openagentontology PYTHONPATH=. python -m openagentontology examples/sample_agent ``` 这会打印出本体的摘要、Trust Profile，并在源码旁边生成徽章和签名回执。通过更改路径，就可以对你自己的 agent 运行它。 ## 输出内容 | 输出 | 它是什么 | |--------|------------| | **Ontology** | 为找到的每个 actor、agent、capability、tool、decision 和 gate 生成的 UAO 类型化节点和边 | | **Cross-walk** | 将每个 capability / decision / gate 映射到其对应的框架控制，并带有置信度标签 | | **Trust Profile** | 0–100 的分数和一个等级：`SOVEREIGN` / `HARDENED` / `DEVELOPING` / `UNGOVERNED` | | **Badge** | 一个可共享的 SVG，显示等级、分数、框架数量和可引用的控制参考 | | **Receipt** | 本体的仅含证书证明，仅凭证书即可验证——始终使用 Ed25519；安装了 `[pq]` 扩展后，还会包含后量子 **ML-DSA-65** (FIPS 204) 和 **SLH-DSA** (FIPS 205) 签名支路 | ## CWN AgentFDE — 一键接入 人类前线部署工程师（Forward Deployed Engineer）会扫描你的 agent，发现未治理的操作，编写策略门控，并证明等级已提升。**AgentFDE 会自主完成这些工作：** ``` PYTHONPATH=. python -m openagentontology.fde your-agent-dir/ ``` 它运行整个闭环——扫描 → 对缺口进行分类 → 生成治理策略 → 重新评分以证明等级跃升 → 公证 → 交接接入报告——并在你的 agent 旁边生成四个产出物： | 文件 | 它是什么 | |------|------------| | `governance.agent.yaml` | 将每个操作绑定到规范原因的声明；扫描结果为 **asserted** | | `governance.rego` | 一个默认拒绝（fail-closed）的策略存根，可接入你的 runtime | | `ONBOARDING.md` | FDE 交接文档：变更前后的等级、自动修复的内容、以及仍需你手动处理的内容 | | `receipt.json` | 投影状态的已签名、可离线验证的回执 | 在 `examples/sample_agent` 上，它将状态从 **UNGOVERNED 41** 提升至 **HARDENED 88**，并且生成的清单是真正的治理策略，而不是存根——它自身的扫描结果为 **SOVEREIGN 96**。AgentFDE 从不执行你的代码，并且它本身也是一个受治理的 agent（[`examples/agent_fde`](./examples/agent_fde/), SOVEREIGN 94）：该工具对执行治理的工具本身进行了治理。 ## 用作 PR 检查 将 [`.github/workflows/agent-governance.yml`](./.github/workflows/agent-governance.yml) 放入任何 repo 中。在每次发起 pull request 时，它会扫描 head 和 base 分支，将 Trust Profile 作为评论发布，标记任何**新出现的未治理高风险操作**以及任何新的 **EU AI Act 第 14 条**（human-oversight）缺口，并且**如果信任等级下降则使检查失败**。门控逻辑位于 [`ci/pr_check.py`](./ci/pr_check.py) 中——采用纯标准库编写，因此易于测试和阅读： ``` PYTHONPATH=. python -m openagentontology . --json --no-receipt > head.scan.json PYTHONPATH=. python -m openagentontology ../base --json --no-receipt > base.scan.json python ci/pr_check.py --head head.scan.json --base base.scan.json --report report.md # exit 0 = 通过，1 = governance regression，2 = usage error ``` ## 用作 MCP server 让你的 agent 治理 agent。该 MCP server 将 pipeline 暴露为四个只读工具，以便任何 MCP 客户端（Claude Desktop、Cursor、Claude Code）都可以扫描 agent、映射操作或内联验证回执——而无需执行它正在扫描的 agent。 ``` git clone https://github.com/CWNApps/openagentontology && cd openagentontology pip install -e ".[mcp]" python -m openagentontology.mcp_server # stdio transport ``` 将其添加到客户端中（Claude Desktop 的 `claude_desktop_config.json`）： ``` { "mcpServers": { "openagentontology": { "command": "python", "args": ["-m", "openagentontology.mcp_server"] } } } ``` 工具：`oao_scan_agent(path)` · `oao_map_action(label, source_reason?)` · `oao_verify_receipt(receipt)` · `oao_explain()`。全部为只读，仅限本地路径（无 clone， 无网络），每个列表都有上限——该 server 无法被用作 SSRF 或 exec 原语。 ## 测试 测试套件可以在**无需安装步骤**的情况下运行（`conftest.py` 会将包加入路径中）： ``` pip install pytest # the only test-time dependency beyond the two runtime deps pytest # 152 tests: crosswalk rigor, ingest safety, e2e, receipt, CI gate, # risk profile, SARIF, golden fixtures, mutation, Proof Lab demo ``` 这些测试在机制上证明了其诚实保证：不包含允许集合之外的框架，不捏造控制 ID，自动检测的映射永远不会是 `asserted`，并且回执的 Python 哈希值可以通过一个**独立的**（JS 风格）规范化器复现，因此浏览器验证器可以做到逐字节验证一致。 ## 构建上的诚实 自动检测的映射绝不会夸大其所知。 - 控制项只有在从固定表中提取出精确且充分验证的匹配项时，才会被标记为 **asserted**。该工具从不构造框架 ID 字符串。 - 所有通过启发式检测到的内容都会被标记为 **inferred**（强、单域动词）或 **ambiguous**（弱、重载动词）——并且徽章只显示已断言的控制。 - 每个节点、边和映射都带有其来源：`EXTRACTED`、`INFERRED` 或 `AMBIGUOUS`。 - 每次运行都会附带以下提示：*“映射为建议性质，并带有置信度标签；请根据已发布的控制文本进行确认。”* 结构损坏或带有捏造数据的本体将**无法通过验证**，并且无法获得徽章。有关完整标准，请参阅 [SPEC.md](./SPEC.md)。 ## 自行验证回执 回执是基于规范 JSON 签名的（`sort_keys`，无空格，ASCII），因此浏览器或任何 Ed25519 工具都可以精确复现 Python 哈希： 1. 对规范的 evidence 重新计算 `sha256` 并与 `evidence_hash` 进行比较。 2. 使用内嵌的公钥验证规范主体的签名。 无需网络。无需信任我们的日志。如果 `cryptography` 不存在，则回执将以未签名形式发出并被明确标记——绝不会伪造签名。 **后量子支路。** 你今天信任的签名在椭圆曲线被攻破时应该依然有效——否则攻击者就可以*现在截获，稍后解密*：存储回执，一旦量子计算机破解了 Ed25519 就对其进行伪造。因此，通过 `pip install "openagentontology[pq]"` 安装后，回执将在同一主体上进行**混合三重签名**：Ed25519 + **ML-DSA-65**（NIST FIPS 204，基于格）+ **SLH-DSA**（NIST FIPS 205，基于哈希——即使在格算法被破解时依然安全）。 每条支路都签署相同的字节，因此只要验证通过任何一条即可证明其真实性，如果验证器检查某条支路时发现其损坏，就会报告篡改。这些支路是附加的：没有 PQ 支路的回执（或不支持 PQ 后端的验证器）仍将像以前一样检查 Ed25519 和哈希。 ## 安全性 pipeline **从不执行摄入的代码**。源码仅被作为文本读取或解析为 AST。核心 pipeline 中**没有网络调用**——回执是在本地签名的。你指向它的任何内容都不会运行。 ## 开源核心模式 这个开源工具完全在**本地**生成所有内容：本体、Trust Profile、徽章和自签名回执——完全离线。 CWN 托管的 **notary and registry** 是一个单独的服务（不在此 repo 中）。它执行跨组织验证并维护公共信任账本，以便一个团队生成的回执可以被另一个团队检查。本地工具可独立运行；而 registry 之上的则是网络效应。 | | OpenAgentOntology (本 repo) | CWN Notary & Registry (托管服务) | |---|---|---| | Ontology + cross-walk | 是 | 是 | | Trust Profile + badge | 是 | 是 | | 自签名回执 | 是 | 是 | | 基于图谱的解析 + 实时威胁信号 | — | 是 | | 验证或弃权门控 (PROCEED / FLAG / ESCALATE) | — | 是 | | 跨组织验证 | — | 是 | | 公共信任账本 | — | 是 | | 持续重新评分 | — | 是 | 托管层通过实时控制图解析每个扫描的操作，并运行确定性的**验证或弃权门控**，将每次解析转化为运行时操作——PROCEED（继续）、PROCEED-FLAGGED（继续并标记），或者在治理依据不足以采取行动时 ESCALATE（升级）交由人工处理。该门控位于签名回执*之上*；它永远不会取代加密证明。已提交的输出示例位于 [docs/scans/open-interpreter/graph_resolutions.json](./docs/scans/open-interpreter/graph_resolutions.json) （open-interpreter 的 21 个操作中有 15 个被升级），并在演示的 Graph Model Preview 中实时呈现。 ## 标准 OpenAgentOntology 定义了 **Agent Ontology** 类别。机器可读的标准—— JSON、规范的 reason 到 control 的 crosswalk、框架、等级和评分权重——位于 [`schema/`](./schema/) 中，由代码生成，因此永远不会发生偏差。文字说明规范位于 [SPEC.md](./SPEC.md)；关于该类别的阐述位于[宣言](./docs/MANIFESTO.md)中。 参考实现 [CWN AgentFDE](./examples/agent_fde/) ——将这一切付诸实践的 agent—— 本身就是根据该标准定义的，并且评级为 SOVEREIGN。该标准是版本化的；当前版本为 `v0.2.0`。 ### 标准文档 该标准背后的诚信契约，每一项都根据代码和测试进行了验证： - **[声明与非声明](./docs/CLAIMS_AND_NON_CLAIMS.md)**：本工具做出的六项声明， 以及刻意未做出的七项声明，以及固定每一项的测试。 - **[威胁模型](./docs/THREAT_MODEL.md)**：受保护的资产、信任边界以及六种 回执篡改场景及其验证后的结果。 - **[Crosswalk 原理](./docs/crosswalk-rationale/)**：每个规范原因（共十个）对应一个文件， 包含与其相邻项的边界、它映射到的实际控制，以及每项的真阳性与假阳性示例。 - **[可复现性](./docs/REPRODUCIBILITY.md)**：重新运行测试套件、 示例扫描，以及从指定的 commit 重新运行两次真实世界扫描的精确命令，并且验证已提交的三重签名回执（包括后量子支路）。 ## 常见问题 **这与 OPA（或任何策略引擎）有何不同？** OPA 在运行时*执行*策略——它是返回 allow/deny 的门。OpenAgentOntology 将你的 agent 操作*映射*到应该治理它们的控制上，并显示哪些操作**完全没有门控**——然后将每一个转化为 NIST 800-53 / EU AI Act / OWASP，以便每个读者都能获得他们熟悉的语言。OPA 是锁；OAO 是找出没有锁的门的审计工具。 它们可以组合使用：OAO 将你的 Rego 作为输入进行摄取，并且在具有规范 deny reason 的 OPA 门之后的操作会获得 **ASSERTED** 评分。OAO 不执行强制控制——它告诉你哪里缺少强制控制。 **这与追踪/可观测性（LangSmith、OpenTelemetry）有何不同？** 追踪告诉你你的 agent 在某次运行中*做*了什么。OAO 会在其运行前，静态地告诉你它*能*做什么，以及哪个控制对每个操作负责。可观测性是飞行记录仪；OAO 是起飞前的检查。 **它会运行我的 agent 的代码吗？** 不会。仅进行 AST 解析 + 文本读取。它从不执行任何内容；核心 pipeline 不发起任何网络调用。你指向它的任何内容都不会运行。 **“INFERRED”听起来像是在猜测——为什么要信任它？** 因为它已被明确标记为一种猜测。动词启发式（`send_*` → egress 控制项）会被标记为 **INFERRED**，需要你进行确认；只有精确、声明的规范原因才会变为 **ASSERTED**。 徽章仅计算已断言的控制项，并且该工具从不捏造框架 ID。 **我可以伪造一个通过的分数吗？** 不能。回执是基于精确本体的哈希进行 Ed25519 签名的。只要修改一个操作来提升等级，验证就会失败（`evidence_hash mismatch`）。你无法在不破坏回执的情况下更改分数——有关篡改测试，请参阅 [docs/real-world-scan.md](./docs/real-world-scan.md)。 ## 许可证 [Apache-2.0](./LICENSE)。由 [Cyber Warrior Network](https://cyberwarriornetwork.com) 构建。 *日志用于解释。回执用于证明。*

标签：AI安全, AI智能体, Chat Copilot, 安全运营, 扫描框架, 本体论, 治理与合规, 结构化提示词, 逆向工具