bit-nexus-labs/open-agent-runtime-integrity-testbed

# 开放式 Agent 运行时完整性测试平台 一个开源研究原型，用于测试受批准约束的 agent 操作在丢失确认、崩溃、重试和过期恢复的情况下，是否能保持准确、不重复且可恢复。 ## 核心不变量 当前的 `v0.1.0` 技术探针模型模拟了一个合成的 `create_invoice` 操作，并使用了两个独立的持久化数据库： - `runtime.db` — agent 运行时的本地操作账本； - `external.db` — 外部服务的已提交状态。 ## 为什么这很重要 Agent 可能会成功修改外部系统，随后丢失确认信息，从过期的本地状态重启，并重复执行已经提交的操作。对于消息、记录、发票、订单、支付或钱包操作而言，盲目重试可能会导致重复或不匹配的不可逆后果。 该探针重现了以下关键序列： ``` approval issued -> request sent -> external mutation committed -> acknowledgement lost -> runtime crashes before local commit persistence -> restart from durable local state -> retry or reconciliation decision ``` ## 演示结果 | 变体 | 恢复行为 | 匹配的外部修改 | 不变量 | |---|---|---:|---| | `vulnerable` | 使用新请求键进行盲目重试 | 2 | `FAIL` | | `defended` | 持久化歧义处理 + 重试前对账 | 1 | `PASS` | ## 一键演示 需要 Python 3.12+，且无需安装任何项目依赖。 ``` python run_demo.py ``` 预期摘要： ``` { "defended": { "external_mutation_count": 1, "invariant": "PASS", "recovery": "RECONCILED_EXISTING_COMMIT" }, "vulnerable": { "external_mutation_count": 2, "invariant": "FAIL", "recovery": "BLIND_RETRY" } } ``` 生成的证据将写入： ``` artifacts/vulnerable_run/ artifacts/defended_run/ ``` ## 审查者证据套件 面向审查者的套件将六个已实现的控制措施转化为一个确定性证据矩阵： ``` python run_evidence_suite.py ``` 它涵盖： - 易受攻击的提交丢失确认盲目重试； - 受防御的提交丢失确认对账； - 批准后的参数替换； - 不同意图间的批准标识符重用； - 对账不可用时的 fail-closed `INCONCLUSIVE` 行为； - 重复执行已提交操作而无需重新派发。 预期摘要： ``` { "all_expectations_met": true, "case_count": 6, "expectations_met": 6, "suite_id": "reviewer_evidence_suite_v0.1" } ``` 该套件将确定性的 JSON、Markdown 和 SHA-256 清单文件导出至： ``` artifacts/reviewer_evidence_suite/ ``` 此矩阵展示了已实现的控制措施。它并不自诩为广泛的多适配器基准测试或生产级别的 exactly-once 执行。 ## 测试 Windows PowerShell: ``` $env:PYTHONPATH = "src" python -m unittest discover -s tests -v ``` Linux/macOS: ``` PYTHONPATH=src python -m unittest discover -s tests -v ``` GitHub Actions 会在 Python 3.12 和 3.13 上运行编译、离线测试套件、确定性演示、审查者证据套件、参考证据验证以及每个版本的证据导出。 ## 永久参考证据 一个经过净化、校验和固定的语义 fixture（源自一次成功的 CI 运行）存储在： ``` examples/reference_evidence/ ``` 使用以下命令进行验证： ``` python scripts/verify_reference_evidence.py ``` 永久 fixture 省略了动态时间戳和完整的事件日志。全新运行仍会生成 [`docs/EVIDENCE_SCHEMA.md`](docs/EVIDENCE_SCHEMA.md) 中记录的完整证据包。 ## 已实现的控制措施 - 规范的 UTF-8/NFC JSON 意图哈希； - 对主体、操作、资源、参数、过期时间和 `max_uses=1` 的精确批准绑定； - 用于篡改检测的文档化本地 HMAC 测试 fixture； - 持久化的 SQLite 操作账本和仅追加的转换事件； - 显式的 `REQUEST_SENT`、`UNKNOWN`、`RECONCILING`、`COMMITTED`、`FAILED` 和 `BLOCKED` 语义； - 跨重启的稳定幂等性身份； - 外部查找和重试前对账； - 对账不可用时的 fail-closed `INCONCLUSIVE` 行为； - 参数替换和批准重放阻断； - 串行化的本地操作创建； - 机器可读的证据和不变量结果； - 归一化的语义确定性检查。 ## 安全边界与非目标声明 此代码库包含一个本地确定性模拟器。它**不**包含或使用钱包密钥、助记词、交易所凭证、真实的支付 API、生产订单下达、LLM 推理、个人数据或任何项目网络调用。 固定的 HMAC 密钥是测试 fixture，不是生产环境的机密或授权机制。 本项目**不**声称具备： - 生产级别的授权； - 通用的 exactly-once 执行； - 密码学证明系统； - 分布式共识； - 通用的 agent 沙箱； - 主网、交易所或支付安全性。 这些证据是来自受控场景的可重现操作证据。 ## 项目结构 ``` scenarios/ deterministic fault scenarios src/runtime_integrity/ vulnerable and defended reference runtimes tests/ invariant and recovery tests docs/ threat model, evidence schema, extension interface examples/reference_evidence/ permanent sanitized CI-derived fixture scripts/ verification utilities ``` ## 路线图与贡献 - [`docs/ROADMAP.md`](docs/ROADMAP.md) - [`CONTRIBUTING.md`](CONTRIBUTING.md) - [`SECURITY.md`](SECURITY.md) ## 许可证 基于 Apache License, Version 2.0 授权。详见 [`LICENSE`](LICENSE)。 ## 状态 `v0.1.0` 是一个研究原型，也是迈向可复用的运行时完整性红队测试平台的第一步垂直切片。它适用于检查、确定性测试和扩展工作，但不适用于生产部署。

标签：Python, 分布式一致性, 容错与恢复, 幂等性, 无后门, 测试平台, 状态机复制