wolfiesch/cihash

## 概览 | | 当前状态 | |---|---| | **产品阶段** | 端到端原型；技术可行性已验证，外部需求尚未证实 | | **核心决策** | 立即接受完全一致的可信证明，否则路由至普通 CI | | **初始用户** | 拥有 agent 生成的更改、确定性 Linux 检查以及明显的 pull request 延迟的团队 | | **支持范围** | 单个代码仓库，单个管理员批准的 profile，同代码仓库的 pull request，精确一致的 head/base/tree，锁定的 Linux 环境 | | **已有验证** | 一次类似的 T4 影子匹配，以及一个涵盖已接受证明、过期证明、缺失证明和回退完成的私有强制沙箱 | | **下一产品关卡** | 一个多团队的经济影子试点，衡量资格、避免的延迟、避免的计算、回退率和运营成本 | | **安全标准** | 在强制执行之前，零误报成功和零无法解释的不匹配 | ## 目录 - [为什么选择 CIHash](#why-cihash) - [工作原理](#how-it-works) - [已验证的内容](#what-has-been-demonstrated) - [信任合约](#trust-contract) - [运行可执行验证](#run-the-executable-evidence) - [仓库架构](#repository-architecture) - [当前范围与局限性](#current-scope-and-limitations) - [项目阶段与下一关卡](#project-stage-and-next-gate) - [文档](#documentation) - [安全](#security) ## 为什么选择 CIHash 编码 agent 在产生变更时越来越多地运行测试。在 push 之后，普通 CI 接着会重复执行同等的工作，这通常处于 pull request 的关键路径上。 仅当完整的信任合约依然匹配时，CIHash 才能让之前的执行变得可复用。仅靠一个 hash 是不够的：证明必须绑定代码仓库、head、base、已测试的 tree、管理员拥有的策略、工作流、环境、架构、完整的作业集、nonce、签名者、时间和结果。 | 现有方法 | 擅长的方面 | CIHash 的边界 | |---|---|---| | 本地 CI runner | push 前的快速反馈 | 将已批准的运行转化为可移植的合并授权 | | 构建与任务缓存 | 复用内容寻址的输出 | 独立于构建图授权一个精确一致的 GitHub check | | 产物证明 | 为生成的产物提供来源证明 | 证明在 push 前已执行所需的测试 | | 托管 runner 供应商 | 让重复的 CI 更快或更便宜 | 在已存在有效证明时，避免同等耗时的 push 后执行 | | CI 证据包 | 记录已完成的运行以供审计 | 做出带有回退编排的在线、fail-closed 决策 | ## 工作原理 ``` flowchart LR A["Coding agent or developer"] --> G["Request server-issued run grant"] G --> R["Trusted runner resolves exact head, base, and merge tree"] R --> W["Untrusted workload runs in pinned isolated environment"] W --> S["Signer validates result outside workload boundary"] S --> E["Signed DSSE / in-toto receipt"] E --> V["Deterministic verifier"] V -->|"Exact valid proof"| C["CIHash App check: success"] V -->|"Missing, stale, invalid, or unsupported"| F["Trusted fallback CI"] F --> C2["Same CIHash App check: final fallback result"] ``` 仓库工作负载永远不会接收到签名密钥、GitHub App 凭据、webhook 密钥、策略管理、回执存储或发布必需 check 的权限。 ### 证明决策流程 ``` flowchart TD P["Pull request event"] --> GH["Resolve current GitHub head, base, and test merge tree"] GH --> L{"Matching submitted proof?"} L -->|No| FB["Queue or observe fallback CI"] L -->|Yes| SIG{"Trusted signature and valid grant lifecycle?"} SIG -->|No| FB SIG -->|Yes| ID{"All identities, timing, jobs, commands, and results match?"} ID -->|No| FB ID -->|Yes| USE["Atomically consume run grant"] USE --> OK["Publish App-owned success"] FB --> DONE["Fallback completes same App-owned check"] ``` 在 **shadow mode** 下，被拒绝的证明复用会产生一个中立的诊断 check，普通 CI 依然具有决定权。在 **强制模式** 下，拒绝会将任务加入回退队列，并且只有 CIHash App 会发布最终必需 check 的结论。在回退任务排队之后验证通过的证明，依然可以对确切授予的修订版本得出相同 check 的结论，在它派发的运行无害完成时取代处于 pending 状态的回退权限。 ## 已验证的内容 一项通过的实验仅确立了指定的合约。它并不暗示已具备生产环境的就绪状态或市场需求。 | 实验 | 状态 | 确立的证据 | 剩余关卡 | |---|---|---|---| | **线上强制回退** | 已在私有 GitHub 沙箱中通过 | 匹配的离机签名证明成功；缺失和过期的证明派发了回退；回退完成更新了相同的 check | 在生产级隔离和真实用户负载下重复测试 | | **T4 影子对比** | 一次类似的匹配 | 对于确定性的离线子集，CIHash 与相应的普通 Actions 作业达成了一致 | 跨越多个 commit 和代码仓库重复测试；暂无性能结论 | | **密钥生命周期与崩溃恢复** | 部分通过 | 计划内的密钥时间窗口、撤销、未知和重复的密钥、原子运行状态、持久化的回退状态以及损坏状态拒绝在本地有效 | 练习实时的轮换、撤销、崩溃、恢复和操作员恢复操作 | | **完整的策略拥有作业集** | 评估器通过 | 不同的必需作业绑定到不同的 argv 命令；缺失、重复、更改、未批准或失败的作业会以稳定的代码拒绝 | 将策略和 runner 调度扩展到当前单一作业之外 | | **外部生产者合规性** | 合约通过 | 严格的无符号结果验证区分了合规的成功、合规的诊断失败以及不完整的证据 | 在构建适配器之前验证维护者的兴趣 | | **Tree 等效的合并队列复用** | 本地沙箱通过 | 仅限元数据的 base 移动可以保持相同的合并 tree；内容或策略更改会被拒绝 | 在仅限 tree 的执行下练习真实的 GitHub 合并队列 | | **独立确认与签名者仲裁** | 实验室通过 | 不同的信任域和签名者阈值无法通过重复项、伪造的 key ID、不同的回执或篡改来满足 | 决定操作复杂性是否因真实的部署而值得 | 有关确切的场景、证据限制和复现命令，请参阅[高杠杆实验里程碑](docs/high-leverage-experiment-milestones.md)。 ## 信任合约 CIHash 的成功意味着受信任的签名者观察到每个必需的作业都在代码仓库管理员批准的确切状态下取得了成功。 | 绑定的声明 | 重要性所在 | |---|---| | **代码仓库、head 和 base** | 防止为不同的代码或已移动的 base 复用证明 | | **已测试的合并 tree** | 绑定呈现给工作负载的确切内容 | | **策略和工作流摘要** | 防止提交的代码削弱命令或必需的作业 | | **环境和架构** | 防止在可变镜像、平台或资源合约之间复用 | | **指定的作业和精确的 argv** | 防止遗漏矩阵条目、替换 wrapper 或更改命令 | | **Nonce、签发和过期** | 防止在服务器授权运行之外进行重放 | | **签名者身份和密钥时间窗口** | 支持信任选择、轮换和撤销 | | **结论、数字退出代码、时间戳和日志摘要** | 绑定完整的结果及其诊断证据 | 签名确定了谁做出了声明。隔离和策略决定了该声明是否值得信任。 ## 运行可执行验证 CIHash 目前从源码运行，并需要 Go 1.25。最安全的引入方式是确定性的实验环境，它不需要 GitHub 凭据或签名密钥。 ``` go test ./... go vet ./... go run ./cmd/cihash lab trust-quorum go run ./cmd/cihash lab applicability go run ./cmd/cihash lab tree-isolation go run ./cmd/cihash lab job-set go run ./cmd/cihash lab tree-reuse go run ./cmd/cihash lab producer-conformance ``` 每个实验都会输出一份机器可读的报告，并在预期的接受或拒绝合约失败时以非零状态退出。 ### 命令界面 | 命令 | 目的 | |---|---| | `cihash policy` | 验证管理员批准的策略，并打印其策略、工作流和环境摘要 | | `cihash run` | 解析精确的本地合并 tree，执行锁定的容器命令，对结果进行签名，并存储回执 | | `cihash hosted-run` | 请求服务器授权，运行确切的工作负载，在本地或通过远程签名者进行签名，并提交证据 | | `cihash verify` | 根据显式预期的输入独立验证一份回执 | | `cihash check` | 将存储的证据评估为 shadow 或强制执行的 check 决策 | | `cihash signer-serve` | 运行独立于工作负载的经过身份验证的签名者边界 | | `cihash serve` | 运行回执摄取、GitHub webhook 验证、check 发布和回退编排 | | `cihash lab` | 执行对抗性产品和信任实验，而不更改托管决策路径 | ## 仓库架构 ``` flowchart TB CLI["cmd/cihash\nCLI and lab surface"] RUN["internal/runner\nExact tree execution and result capture"] GRANT["internal/rungrant\nServer-issued lifecycle and replay protection"] ATTEST["internal/attestation\nDSSE / in-toto schema and Ed25519 signing"] SIGN["internal/remotesigner\nOut-of-workload signer service"] VERIFY["internal/verifier\nDeterministic fail-closed verification"] ACCEPT["internal/acceptance\nTrusted key selection and acceptance engine"] HOST["internal/hosted\nControl plane, GitHub App, persistence, fallback"] LAB["internal/lab + internal/conformance\nExecutable research contracts"] CLI --> RUN CLI --> HOST RUN --> GRANT RUN --> ATTEST SIGN --> ATTEST ATTEST --> VERIFY GRANT --> VERIFY ACCEPT --> VERIFY HOST --> ACCEPT HOST --> GRANT LAB --> VERIFY LAB --> ACCEPT ``` | 区域 | 职责 | |---|---| | `cmd/cihash` | 本地 CLI、托管 runner、签名者、服务器和实验入口点 | | `internal/attestation` | 回执 schema、规范化摘要、DSSE envelope 和签名 | | `internal/runner` | 精确的 Git 解析、无元数据的 tree 实例化、隔离执行和有界日志 | | `internal/rungrant` | 管理员授权的运行身份和单调生命周期 | | `internal/verifier` | 基于显式预期输入的稳定接受和拒绝决策 | | `internal/acceptance` | 密钥时间窗口、撤销、仲裁评估和证明查找 | | `internal/hosted` | GitHub webhook 验证、证明摄取、check 所有权、持久化和回退完成 | | `internal/lab` | 用于尚不属于托管授权一部分的问题的可执行原型 | ## 当前范围与局限性 ### 支持的 v0.1 路径 - 单个代码仓库和单个验证 profile； - 同一代码仓库的 pull request； - 精确一致的 head、base 和 GitHub test-merge tree； - 管理员拥有的命令和策略； - 锁定且禁用网络的 Linux 容器环境； - 有界的 CPU、内存、PID、时间和输出； - 工作负载内部没有特权机密； - 带有普通 CI 回退的 fail-closed 验证。 ### 目前刻意不支持的内容 - fork 的 pull request； - 任意 GitHub Actions 解释； - 携带机密或依赖网络的任务； - 没有被接受摘要的可变外部固定数据； - macOS 和 Windows 工作负载； - 在 base 移动后的生产级合并 tree 复用； - submodules 以及执行依赖于 Git 元数据的代码仓库； - 生产级 runner 集群或多租户控制平面。 工作流摘要绑定了管理员批准的 profile 和命令，而不是任何 GitHub Actions 工作流定义；与代码仓库普通 CI 门禁的等效性是管理员的判断。有关绑定限制的完整列表，请参阅[威胁模型](docs/threat-model.md)。 开发 runner 与其管理程序共享宿主机内核和 Docker 守护进程。生产环境的强制执行需要一个临时的 VM 或强化的容器宿主机，且签名者必须位于工作负载宿主机的边界之外。 ## 项目阶段与下一关卡 ``` flowchart LR A["Receipt and verifier design"] --> B["Local proof round trip"] B --> C["Live shadow comparison"] C --> D["Private enforcement fallback"] D --> E["Economic multi-team shadow pilot"] E -->|"Demand and savings demonstrated"| F["Production isolation and operations"] E -->|"Low eligibility or savings"| G["Narrow or revise the product thesis"] style A fill:#1f6f43,color:#fff style B fill:#1f6f43,color:#fff style C fill:#1f6f43,color:#fff style D fill:#1f6f43,color:#fff style E fill:#9a6700,color:#fff style F fill:#57606a,color:#fff style G fill:#57606a,color:#fff ``` 记录在[产品简报](docs/product-brief.md)中的战略方向是一个**嵌入式证明桥接**：CIHash 集成到那些已经在隔离工作单元中执行编码 agent 最终验证的平台上，因为只有该执行时刻的所有者才能以零边际计算成本将其转化为证据。CIHash 提供回执 schema、确定性验证器和回执驱动的 GitHub App；它并不运行一个竞争性的 runner 集群。 下一个里程碑不是另一个推测性的兼容层。它是一个跨越多个外部团队的经济影子试点，旨在衡量： | 指标 | 它所提供的决策依据 | |---|---| | **证明资格与接受度** | 真实的 agent 工作流是否足够频繁地产生可复用的证据 | | **避免的 p50/p95 关键路径时间** | 证明复用是否实质性地改善了开发者的反馈速度 | | **避免的重复 runner 分钟数** | 节省的计算是否有意义 | | **回退率和拒绝代码** | 哪些工作流假设阻碍了复用 | | **证明决策延迟** | 信任路径是否在运营层面上保持可忽略不计 | | **运营成本和采纳工作量** | 价值是否超过了基础设施和集成成本 | | **误报成功和无法解释的不匹配** | 是否依然禁止强制执行 | ## 文档 | 文档 | 目的 | |---|---| | [产品简报](docs/product-brief.md) | 初始客户、支持的用例、成功标准和继续推进的关卡 | | [威胁模型](docs/threat-model.md) | 信任边界、受保护的资产、威胁和必需的控制 | | [证明0.1](docs/attestation-v0.1.md) | 签名声明和谓词合约 | | [接受策略](docs/acceptance-policy.md) | 管理员所有权、验证顺序、拒绝代码和 check 行为 | | [竞争边界](docs/competitive-boundary.md) | 相邻系统、集成标准和持久的差异化 | | [GitHub App 设置](docs/github-app.md) | App 权限、托管协议、回退合约和推出 | | [T4 影子运行手册](docs/t4-shadow-runbook.md) | 部署的信任边界和第一次类似的影子观察 | | [实验里程碑](docs/high-leverage-experiment-milestones.md) | 已证实的合约、证据限制、剩余关卡和复现 | ## 安全 在更改回执字段、runner 隔离、签名者放置、策略所有权、GitHub check 发布或回退行为之前，请查阅[威胁模型](docs/threat-model.md)。 ## 许可证 CIHash 采用 [Apache License, Version 2.0](LICENSE) 授权。

标签：EVTX分析, 日志审计