RafineriaAI/aos-workflow-gate

# aos-workflow-gate 面向 CI、PR、扫描器和 AI-agent 信号的基于证据的工作流门控。 本仓库是围绕 `aos-kernel` 构建的工作流层。其职责是使 pull request 或发布门控变得可解释且可重放：收集工作流信号，应用显式策略，并基于证据生成 `PASS`、`WARN` 或 `BLOCK` 决策。 ## 当前状态 阶段 2：已实现本地 `evaluate` CLI 和咨询性 GitHub Action。阶段 3 已启动：已实现零配置 GitHub check-runs 收集器，因此该 action 无需任何手动编写的输入即可对 pull request 进行门控。门控会将收集到的信号和显式策略转化为确定性、可重放且防篡改的 `PASS`、`WARN` 或 `BLOCK` 决策记录。下一步计划开发更多的信号适配器（如 SARIF、Scorecard 摘要）。 决策记录带有 `UNSIGNED_NOT_OFFICIAL` 验证状态：它们可以进行结构和重放校验，但不是官方的签名裁决。 本仓库目前不作任何关于生产环境、合规性、签名、SLSA 或安全审计的声明。 ## 核心理念 普通的 CI 仪表盘只会告诉你哪些检查通过了。`aos-workflow-gate` 旨在回答一个更严格的问题： 这将门控行为从一堆分散的红绿检查结果转变为可重放的决策记录。 ## 实际用例 维护者希望：当必需的检查缺失时拦截发布候选版本；当非阻塞性扫描器报告已知风险时发出警告；并且只有在具备必需的证据时才予以通过。 在本地运行门控： ``` python -m pip install -e . aos-workflow-gate evaluate \ --input examples/github-pr-signal-bundle.json \ --policy policies/default.yml \ --out examples/gate-decision.json ``` 这将打印出裁决结果并写入完整的决策记录。对于已提交的示例，裁决结果为 `WARN`：必需的检查已通过，但仍存在一个咨询性扫描器警告。该记录保留了主体身份、策略身份及摘要、输入身份及摘要、解释说明以及用于防篡改的自摘要。已提交的副本存放于 [examples/gate-decision.json](examples/gate-decision.json)。 验证决策记录是否被篡改： ``` aos-workflow-gate verify \ --input examples/gate-decision.json \ --bundle examples/github-pr-signal-bundle.json ``` 将记录渲染为 Markdown（即 GitHub Action 发布的摘要）： ``` aos-workflow-gate summarize --input examples/gate-decision.json ``` 将验证过的记录导出为未签名的 in-toto Statement，并使用 您自己的密钥对其进行签名（参见 [docs/DECISION_PREDICATE.md](docs/DECISION_PREDICATE.md)）： ``` aos-workflow-gate export \ --input examples/aos-kernel-gate-decision.json \ --out gate-statement.json cosign sign-blob --yes gate-statement.json \ --output-signature gate-statement.sig ``` 草拟的输入和策略文件分别为 [examples/github-pr-signal-bundle.json](examples/github-pr-signal-bundle.json) 和 [policies/default.yml](policies/default.yml)。 ## GitHub Action 自测模式（零配置）——对您的 pipeline 进行咨询性自测， 无需编写任何 bundle 或策略。该 action 会收集 当前 commit 已完成的 check runs，据此生成显式的咨询性策略， 并向作业页面写入可重放的决策记录和 Markdown 摘要。 这是一个完整的工作流文件——只需将其复制为 `.github/workflows/aos-self-test.yml`。无需 checkout：自测 模式通过 API 读取 check runs，并直接从 action 自身进行安装： ``` name: AOS Self-Test on: pull_request: permissions: contents: read checks: read jobs: self-test: runs-on: ubuntu-latest steps: # Pinned from actions/setup-python@v6 on 2026-07-03. - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 with: python-version: "3.11" - name: AOS self-test (advisory) uses: RafineriaAI/aos-workflow-gate@v0.11.1 with: required-checks: "ci / validate" ``` 需要 `checks: read` 是因为 `permissions:` 块会将所有未列出的 范围设为 `none`，而零配置模式需要通过 workflow token 读取 commit 的 check runs。 公开仓库不配置此项也能正常运行；私有仓库则不行。 `required-checks` 是可选的；被指定的检查将成为必需项（缺失或 失败意味着 `BLOCK`），其他所有收集到的检查均为咨询性检查。设置 `wait-for-checks: "120"` 可轮询等待直到必需的检查完成（仅 等待必需的检查；若等待结束时检查未完成，则执行失败关闭策略 并记录在 bundle 的收集状态中）。生成的 bundle 和策略会被写入 `.aos-gate/` 目录，以确保决策保持可重放性。 若需完全控制，请提供显式的 bundle 和策略。该 action 是 只读的，不需要任何仓库密钥，它会向作业 页面写入 Markdown 摘要，并公开决策记录以便上传为 artifact： ``` permissions: contents: read steps: # Pinned from actions/checkout@v5 on 2026-07-03. - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd with: persist-credentials: false # Pinned from actions/setup-python@v6 on 2026-07-03. - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 with: python-version: "3.11" - name: Run gate (advisory) id: gate uses: RafineriaAI/aos-workflow-gate@v0.11.1 with: input: examples/github-pr-signal-bundle.json # Pinned from actions/upload-artifact@v7.0.1 on 2026-07-04. - name: Upload decision record uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a with: name: gate-decision path: gate-decision.json ``` 咨询模式下绝不会导致作业失败；裁决结果会在步骤摘要 和 `verdict` 输出中报告。设置 `enforce: "true"` 可在出现 `BLOCK` 裁决 时使步骤失败。本仓库在 [.github/workflows/aos-workflow-gate-self.yml](.github/workflows/aos-workflow-gate-self.yml) 中对自身运行了该 action。 ## 试点与设计合作伙伴 自助使用是免费的（Apache-2.0 协议，无功能限制）。正在为您的工作流 评估真实的发布门控？[引导式试点](docs/GUIDED_PILOT.md) 将为您的某个真实工作流设计策略，并交付可衡量的、 可重放的结果——策略的所有权始终归您所有。名额有限的 [设计合作伙伴版本](docs/GUIDED_PILOT.md#design-partner-variant) 允许通过提供结构化反馈来换取范围费用的减免。 **[请求范围评估 →](https://github.com/RafineriaAI/aos-workflow-gate/issues/new?template=guided-pilot-scoping.yml)** （双方均无强制承诺）。体验过该门控？ 只需 [两分钟反馈](https://github.com/RafineriaAI/aos-workflow-gate/issues/new?template=feedback.yml) 即可助力路线图的制定。 ## 平台中立性 门控核心是平台中立的：纯 Python 编写，零运行时依赖， 输入输出均为 JSON。GitHub Enterprise Server 可开箱即用，GitLab CI 或 Jenkins 也可在显式提供的 bundle 上运行相同的评估—— 参见 [docs/CI_INTEGRATIONS.md](docs/CI_INTEGRATIONS.md)。按照设计，只有 check-runs 收集器和 Action 是 GitHub 专用的。 ## 项目定位 - 基于工作流证据的确定性门控。 - 针对 CI、PR、扫描器和 AI-agent 信号的策略与证据层。 - 连接 `aos-kernel` 裁决语义与真实仓库工作流的实用桥梁。 - 一种 GitHub Action 和本地 CLI，在真正拦截任何内容之前以咨询模式运行。 ## 非本项目定位 - 不声明仓库是安全的。 - 不是合规认证系统。 - 不替代代码审查、测试、威胁建模或发布工程。 - 不是工作流系统正确性的运行时证明。 - 不是签名或出处授权机构。 ## 文档导航 - [范围](docs/SCOPE.md) 定义了声明边界和非目标。 - [架构](docs/ARCHITECTURE.md) 定义了各个层级以及每个阶段的实现内容。 - [用例](docs/USE_CASES.md) 提供了首批实际的工作流场景。 - [采用指南](docs/ADOPTION_GUIDE.md) 消除术语和集成障碍。 - [标准兼容性](docs/STANDARDS_COMPATIBILITY.md) 将计划中的集成映射到 SLSA、SPDX、CycloneDX、SARIF、in-toto 和 OpenSSF Scorecard，但不声称合规。 - [决策记录断言](docs/DECISION_PREDICATE.md) 定义了 in-toto Statement 导出和操作员密钥签名方案。 - [CI 集成](docs/CI_INTEGRATIONS.md) 涵盖了 GitHub Enterprise Server、GitLab CI 和通用 shell 用法。 - [信任](docs/TRUST.md) 展示了如何自行验证每一个声明：只读权限、无遥测、零依赖、防篡改证据、离线重放。 - [买家 FAQ](docs/BUYER_FAQ.md) 解答安全审查人员的问题：数据流、权限、免费与付费、供应商风险、平台覆盖范围。 - [安全准备情况](docs/SECURITY_READINESS.md) 记录了私有仓库数据模型和已实施的输入强化，每一项均附带负面测试。 - [用户 FAQ](docs/USER_FAQ.md) 解答首次运行问题，并将每一个故障症状对应到其含义和修复方案。 - [价值](docs/VALUE.md) 阐明了门控的价值，但仅限证据所能达到的范畴。 - [一页纸介绍](docs/ONE_PAGER.md) 是一份可发送的摘要：涵盖问题、产品、证明和参与路径。 - [引导式试点](docs/GUIDED_PILOT.md) 定义了付费辅助路径和设计合作伙伴版本。 - [市场页面](docs/MARKETPLACE_LISTING.md) 包含可直接粘贴的展示文案和状态。 - [真实仓库重放案例研究](docs/case-studies/aos-kernel-release-surface-replay.md) 在指定的 commit 上对真实的工作流信号运行门控，并离线重放已提交的决策。 - [路线图](ROADMAP.md) 定义了分阶段的计划。 - [发布治理](docs/RELEASE_GOVERNANCE.md) 定义了分支、规则集、标签和发布策略。 - [草拟信号 bundle](examples/github-pr-signal-bundle.json) 和 [草拟策略](policies/default.yml) 使首个用例更加具体化。 - [安全策略](SECURITY.md) 定义了负责任的报告边界。 - [贡献](CONTRIBUTING.md) 定义了对贡献的期望。 ## 本地检查 使用以下命令运行本地基础规范检查： ``` python -m ruff check . python -m mypy python -m pytest python tools/check_public_surface.py ``` 或者仅运行公共表面检查： ``` python tools/check_public_surface.py ``` 此检查会验证文档索引、引导声明边界和草拟的示例文件。它不是产品审计。 ## 与 aos-kernel 的关系 `aos-kernel` 仍然是最小的公共内核和形式化表面。`aos-workflow-gate` 是操作层，负责将真实的工作流信号适配为门控决策记录。内核正确性声明不会自动延伸至本仓库。 ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。 该许可证仅涵盖本仓库的源代码。不授予 关于 "AOS"、"AOS Kernel" 或 "RafineriaAI" 名称和标志的任何权利，亦不授予 独立的专有 AOS Core 技术的任何权利。参见 [NOTICE](NOTICE)。

标签：GitHub Action, Homebrew安装, Python, 无后门, 策略引擎, 网络安全挑战, 自动化门禁, 逆向工具