forwardai-dev/agent-assurance-harness

# Agent Assurance Harness (`aah`) [](https://github.com/forwardai-dev/agent-assurance-harness/actions) [](https://www.python.org/) [](LICENSE) [](tests/) [](#) [](#) [](https://github.com/astral-sh/ruff) [](https://mypy-lang.org/) [](https://github.com/PyCQA/bandit) [](#) **为 Agentic AI 提供可离线验证的证据。** `aah` 每次运行都会生成一个可移植、已签名且 哈希链接的 **Agent Assurance Evidence Object (AAEO)** —— 将正确性 **eval**、对抗性 **security/red-team** 和 **governance** 结合到一个可审计的 记录中 —— 并通过 **确定性策略** 对其进行 CI 门控（在关键路径中不使用 LLM）。 ## 实际运行效果 —— 一条命令，完全离线 ``` $ ./demo.sh # no API keys, no network == Assess a governed subrogation-intake agent (safe) == GATE: PASS verify: OK (integrity=True sig=True decision=True) == Same agent, vulnerable profile == GATE: FAIL (5 open OWASP-Agentic findings: ASI01/02/04/06/07, AIVSS up to 10.0) == Forge it: flip a failing finding to PASS, rewrite the verdict, re-verify offline == integrity : FAIL content hash mismatch: the artifact was mutated after sealing signature : FAIL not signed by the recorded key decision : FAIL recorded=PASS replayed=FAIL VERIFICATION FAILED ``` 伪造的证据对象无法在离线重新验证中存活 —— 通过三种 独立的方式被捕获，且无需信任生产者。这就是其核心主旨。该演示针对 **受监管的代位求偿受理 agent** (`--target arbiter`) 运行，将其作为真实的、具有领域基础的 System-Under-Test。 ## 60秒演示（完全离线，无需 API 密钥） ``` pip install -e . aah run # safe mock agent -> GATE: PASS aah run --vulnerable # vulnerable agent -> GATE: FAIL (with reasons) aah verify out/evidence.json # offline re-verify: integrity + signature + decision replay aah gate out/evidence.json # exit code 0 (PASS) / 1 (FAIL) for CI ``` 伪造证据（翻转一个失败的 finding，将结论重写为 PASS）并重新验证： ``` integrity : FAIL (content hash mismatch: the artifact was mutated after sealing) signature : FAIL (not signed by the recorded key) decision : FAIL (recorded=PASS replayed=FAIL) VERIFICATION FAILED ``` 伪造物会在**离线状态下通过三种独立方式**被捕获。这就是整个核心主旨。 ## 它的独特之处（诚实且可辩护） 1. **可移植、已签名、哈希链接的证据对象 + 离线 `verify`。** 竞争对手生成的是 没有任何完整性的临时 JSON/HTML；GRC 平台生成的是 没有底层确定性测试的人工证明声明。`aah` 生成的是可重新验证的 artifact。 2. **确定性的 policy-as-code 门控 —— 在关键路径中没有 LLM/judge。** 通过/失败的 决定是固定输入的纯函数；重新运行会得到完全相同的结论。 judge 的分数只是策略可能会读取的一个*信号*，而绝不是决策者。 3. **一次运行 → 三个维度 → 一个 Finding schema → 一个门控。** 因为质量回归、**或者** 一个新的安全 finding、**或者**一个损坏的控制导致构建失败，所有这些都绑定在一个对象上。 4. **每个 finding 在构造上均带有 ASI 标签、AIVSS 评分并支持 ATLAS 映射。** 主流的 red-team 工具均不原生输出 AIVSS；它使得合规性交叉映射 变成机械化的，而不是人工认证的。 5. **在该领域尚浅的深度 agentic 原生攻击。** v1 提供了专门构建的 **ASI06 memory/context poisoning**（在运行 N 投毒 → 在运行 N+1 窃取）、**ASI07 inter-agent spoofing** 和 **ASI04 supply-chain secret-exfil** —— 外加攻击者与监控程序的 *联合风险*指标（攻击成功 **且** 监控程序未察觉）。 ## 模块 - `aah.core` —— 规范 JSON、哈希、`Finding` schema、`RunManifest`、AAEO。 - `aah.audit` —— Ed25519 签名 + 哈希链接的仅追加账本（防篡改）。 - `aah.governance` —— policy-as-code + **纯确定性门控** + AIVSS + 交叉映射。 - `aah.target` / `aah.llm` —— 插件式 SUT 和 LLM 接口；默认提供确定性 **mock**（离线）。 - `aah.eval` —— 确定性评分器、`pass^k` + bootstrap CI + McNemar 显著性检验、**leakage linter**。 - `aah.attack` —— OWASP-Agentic red-team 拦截套件 + 独立监控程序 + 密钥扫描器。 - `aah.rerank_eval` —— 检索/重排序优化：nDCG/MRR/MAP/Recall + reranker **sweep**。 - `aah.verify` —— 离线重新验证器（核心差异化所在）。 - `aah.report` —— 自包含的静态 HTML 仪表板。 ## 范围与诚实（这是一项功能） 每个 AAEO 都带有 **强制性的范围 + 残余风险声明**。我们说明了自己 **不**做的事情： - **完整性 ≠ 第三方证明。** 哈希链提供的是防篡改能力，而不是一个受信任的公证。 - **行为测试生成的是证据，而非安全保证。** 它无法验证监管机构所要求的*安全声明*。 - **v1 攻击是一个固定的语料库** —— 针对的是*固定*攻击者的鲁棒性。自适应/反馈引导的攻击是 **v2** 的内容（如果未加标签会产生虚假的舒适感 —— 因此我们明确标注了它）。 - **v1 的门控中没有 LLM judge。** 基于 judge 的 eval 赛道及其偏差/κ 资格测试套件是 **v2** 的内容。 - 控制映射（OWASP-ASI/AIVSS/NIST/EU-AI-Act/ISO-42001/SOC2）属于**信息性映射，而非认证**。 - 不是运行时 guardrail，不是 GRC SaaS，也不是托管服务。它**为** GRC 工具提供数据（OSCAL 导出已在路线图上）；它始终停留在预部署/CI + 审计阶段。 ## v2 路线图（有明确名称，而非虚构） 自适应/黑盒攻击生成 · 带有 κ 资格认证的 LLM-judge 赛道 · 观察框架 差异性（感知 eval vs 未监控） · MCP/依赖项 CVE 扫描 + 完整的供应链环节 · 可插拔的生产者适配器（promptfoo/garak/Inspect） · sigstore/RFC-3161 外部时间戳 · 将 OSCAL 导出到 Credo AI / IBM watsonx.governance。 ## 状态 参考实现。`pytest`：**30 项通过**，完全离线。不作为受监管企业用于合规性背书的 生产级合规门控 —— 它是一个**证据 标准 + 参考实现**。采用 Apache-2.0 许可证。

标签：CI/CD门禁, OWASP Agentic, Python, 人工智能治理, 大语言模型安全, 安全合规, 安全规则引擎, 无后门, 智能体评估, 机密管理, 网络代理, 逆向工具