lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit
GitHub: lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit
一款面向开源仓库治理与 CI/CD 流水线卫生的策略即代码评估工具，支持 GitHub、Azure、AWS 多平台基线检查与结构化报告生成。
Stars: 3 | Forks: 1
# OSS 安全策略即代码入门套件
从本地克隆评估克隆可见的 OSS 仓库治理，以及 GitHub Actions、Azure Pipelines 和 AWS CodeBuild/CodePipeline 信号。仓库外部的平台事实仍需证据或人工审查。
本项目有意保持小型化，并明确界定信任边界。GitHub 支持是目前最成熟的路径；Azure 和 AWS 支持是基于克隆和证据驱动的，而非实时的平台验证。
操作隐私：评估在本地进行，默认为克隆可见。基于 API 的证据收集仅在显式调用时运行，并应限定在正在评估的平台/仓库范围内。
## 快速链接
- [v5.4.0 的新增功能](#whats-new-in-v540)
- [当前发布状态](#current-release-state)
- [推荐的首条命令](#recommended-first-command)
- [快速入门](#quickstart)
- [CI/CD 集成](#cicd-integration)
- [输出](#outputs)
- [文档](#documentation)
- [更新日志 (CHANGELOG.md)](CHANGELOG.md)
- [GitHub 发布](https://github.com/lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit/releases)
- [验证演练](docs/validation-walkthrough.md)
- [CLI 参考](docs/cli-reference.md)
- [结果指南](docs/results-guide.md)
- [捆绑配置文件概览](docs/profiles/overview.md)
- [发布硬性门禁手册](docs/release-playbook-hardgate.md)
- [v5.1.0 迁移指南](docs/v5.1.0-migration-guide.md)
- [v5.0.0 迁移指南](docs/v5.0.0-migration-guide.md)
## 概览
| 领域 | 内容 |
| --- | --- |
| 当前版本 | `v5.4.0` / Python 包 `oss-policy-kit==5.4.0` |
| 输入 | 本地仓库克隆 |
| 输出 | `evaluation-report.json` 和 `evaluation-report.md`（可选 SARIF 2.1.0，通过 `--sarif-output` 生成） |
| 核心范围 | 克隆可见的治理以及 GitHub/Azure/AWS CI/CD 信号 |
| 配置文件 | `github-*`、`azure-*`、`aws-*` 阶梯（`level-1..3`、`release-hardening-*`）—— 使用命令 `python -m oss_policy_kit profiles` 列出；可选的捆绑混合配置 `github-aws-level-2` / `github-azure-level-2` 为**仅供参考；不可用作发布门禁** |
| 例外情况 | 包含所有者、原因和到期时间的豁免注册表 |
| 示例 | 已加固和易受攻击的示例仓库 |
| 保证模型 | 每个控制项均标记为 `deterministic`、`signal` 或 `evidence-backed`；该值流入 `reports/1.0` JSON 和 Markdown 中，以便使用者可以推断证据的强度。参见 [docs/profiles/overview.md](docs/profiles/overview.md)。 |
## 推荐的首条命令
安装后，首先运行已加固的示例：
```
python -m oss_policy_kit evaluate --target ./examples/hardened-repo --profile github-level-1 --output-dir ./out/hardened --summary-only
```
这将验证 CLI、捆绑配置文件数据、示例仓库和报告生成路径，然后再您评估自己的仓库。
### 两行引导 (v5.4.0+)
对于全新的采用者，`init` 将首次运行简化为两个命令：
```
python -m oss_policy_kit init --target . --with-evidence --with-workflow
python -m oss_policy_kit evaluate --target .
```
`init` 写入一个持久化的 `oss-policy-kit.yaml`；当省略 `--profile` 时，`evaluate` 会从中读取配置文件。所有标志请参见 [docs/cli-reference.md](docs/cli-reference.md#project-initialization)。
### 用作 GitHub Action
该套件附带一个复合 GitHub Action，以便采用者可以在每个 Pull Request 上评估捆绑的基线，而无需在其构建镜像中管理 Python：
```
- uses: lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit@v5
with:
profile: github-level-1
fail-on: fail
```
输入与 CLI 标志 1:1 映射。完整参考和 SARIF 转发示例请参见 [docs/github-action.md](docs/github-action.md)。
## 当前发布状态
`v5.4.0` 是当前的公共发布线。它是 `v5.3.0` 之上的增量小版本：JSON 报告契约仍为 `reports/1.0`，旧的 `0.3` 和 `0.2` 报告结构仍可选择，并且现有的配置文件 ID 保持稳定。该版本增加了 `init` 向导，使 `evaluate` 通过 `oss-policy-kit.yaml` 感知配置，发布了官方的 GitHub Marketplace Action (`action.yml`)，引入了首个原生 SAST 集成（`scan-sast` + Semgrep 适配器 + `SAST-SEMGREP-064` 实验性控制），并整合了文档。完整详情请参见 `CHANGELOG.md`。
| 表面 | 当前状态 |
| --- | --- |
| 包 | `oss-policy-kit==5.4.0` |
| GitHub Release | `v5.4.0` 是当前发布目标；`v5.3.0`、`v5.2.0` 和 `v5.1.0` 仍作为前身版本可用 |
| 默认分支 | `master` |
| 许可证 | Apache-2.0 (`LICENSE` + `NOTICE`) |
| 报告契约 | 默认为 `reports/1.0`；`0.3` 和 `0.2` 仍可通过 `--report-json-contract` 选择。`0.1` 已在 v5.0.0 中移除 |
| 安全工作流 | 扫描器在 `Security CI/CD` 中运行；SARIF 上传由 `ENABLE_CODE_SCANNING_UPLOAD=true` 门控，因此当 Code Scanning 上传 API 不可用时，验证不会失败 |
该仓库旨在从干净的克隆中进行复现：安装包、运行内置示例，并比较生成的 JSON/Markdown 报告。
## v5.1.0 的新增功能
仅列出重点 —— 完整细节请参见 [`CHANGELOG.md`](CHANGELOG.md) 以及 [`docs/v5.1.0-migration-guide.md`](docs/v5.1.0-migration-guide.md) 中的增量迁移说明。有关 v4 → v5 的重大过渡，请参见 [`docs/v5.0.0-migration-guide.md`](docs/v5.0.0-migration-guide.md)。
- **审计日志流证据。** 新的实验性控制 `AUDIT-STREAM-060` 检查硬性门禁配置的集中式审计日志流证据，填补了 OWASP CICD-SEC-10 并改善了 AWS/Azure 的可追溯性对齐。
- **签名来源验证。** 新的实验性控制 `PROV-VERIFY-061` 读取可选的 `verification:` 证据，用于签名的构建来源，并将 SLSA Build L2 “Provenance signed” 映射移至 YES。
- **在不破坏契约的情况下扩展了硬性门禁覆盖范围。** 这两个新控制均被接入 6 个 `*-level-3` 和 `*-release-hardening-3` 配置文件中。`reports/1.0`、`0.3` 和 `0.2` 保持稳定。
- **证据模式是增量式的。** 增加了新的审计日志流和 GitHub 来源模式，而 Azure/AWS 来源模式仅增加了可选的验证字段。现有的 `v5.0.0` 证据文件将继续有效。
- **框架对齐已刷新。** 文档现在包括 SLSA v1.2 Source Track 注释、带有明确无认证诚实契约的 EU CRA 映射，以及 NIST SP 800-218A AI 超出范围注释。
- **更友好的 Scorecard 输入错误。** 格式错误的 `--scorecard-json` 文件现在返回 `exit 2` 并带有清晰的解析消息，而不是显示为 `Unexpected error`。
`v5.1.0` 中没有破坏性更改。`--fail-on` 语义、JSON 报告契约、Markdown 报告布局，以及 `evaluate-many` / `recommend-profile` / `scaffold-evidence` / `collect-evidence` / `diff-reports` 的表层均未更改。
## 本套件的功能
该入门套件可帮助您评估仓库是否在本地可观察的文件和工作流中展示了实用的 OSS 基线。它侧重于：
- `SECURITY.md`、`CONTRIBUTING.md`、`LICENSE`、`CODEOWNERS`、变更日志的存在
- 克隆可见的 GitHub Actions、Azure Pipelines 和 AWS 构建/管道结构及卫生信号
- 面向人类和管道的报告生成
- 策略生命周期标记，例如 `stable`、`experimental` 和 `deprecated`
- 增量的本地证据，例如豁免和可选的平台证据文件
它 **不是** 通用的应用程序扫描器、OSPS 认证引擎、合规性保证，也不能替代威胁建模、安全代码审查、渗透测试或 GitHub 设置审查。有关完整的应用范围讨论，请参见 [docs/results-guide.md](docs/results-guide.md)。
## 快速入门
需要 Python 3.12+。
### 安装（官方渠道）
1. **从 PyPI**（推荐给大多数使用者）：
python -m pip install oss-policy-kit
python -m oss_policy_kit --version
2. **从 GitHub Release 产物** —— 当 wheel 或 sdist 产物附加到发布时，从 [Releases](https://github.com/lucashgrifoni/OSS-Security-Policy-as-Code-Starter-Kit/releases) 页面下载 `oss_policy_kit-*.whl` 或 `oss_policy_kit-*.tar.gz`，然后 `pip install /path/to/wheel`。PyPI 仍是主要的安装渠道。
3. **从源码**（贡献者）：
python -m pip install -e ".[dev]"
在 Windows 上首选 `python -m oss_policy_kit` 作为 CLI 入口，这样您就不依赖于 `Scripts\` 是否在 `PATH` 中。
### 运行内置示例
```
python -m oss_policy_kit evaluate --target ./examples/vulnerable-repo --profile github-level-1 --output-dir ./out/vulnerable
python -m oss_policy_kit evaluate --target ./examples/hardened-repo --profile github-level-1 --output-dir ./out/hardened
```
### 成功通常是什么样子
- `examples/hardened-repo` 使用 `github-level-1`：`pass: 14`（配置文件中的所有活动控制）
- `examples/vulnerable-repo` 使用 `github-level-1`：多个 `fail`
- `github-release-hardening-1`：通常为 `pass`，外加一个分支保护结果，根据本地证据，该结果保持为 `manual-review-required` 或 `self-attested`
有关完整的分步演示（CLI 帮助、配置文件发现、夹具比较、控制表、CI 门控），请参见 [docs/validation-walkthrough.md](docs/validation-walkthrough.md)。
## CI/CD 集成
入门工作流位于 [`templates/workflows/`](./templates/workflows/)：
- [`github-oss-policy-check.yml`](./templates/workflows/github-oss-policy-check.yml) —— 针对 `github-level-1` 的基线 `evaluate`，在任何控制为 `fail` 时使作业失败。
- [`github-oss-policy-check-with-waivers.yml`](./templates/workflows/github-oss-policy-check-with-waivers.yml) —— 与上述相同，但传递了 `--waivers ./waivers/waivers.yaml`。
- [`github-oss-policy-check-level-2.yml`](./templates/workflows/github-oss-policy-check-level-2.yml) —— 更严格的 `github-level-2` 配置文件。
- [`pipelines/azure/azure-pipelines.yml`](./pipelines/azure/azure-pipelines.yml) —— Azure Pipelines 示例，用于在 Linux/Ubuntu 代理上进行 Lint、测试、包构建、SBOM 产物生成和自检门控。
典型的 CI 命令：
```
python -m oss_policy_kit evaluate --target . --profile github-level-1 --fail-on fail --output-dir ./oss-policy-reports
```
流水线中的 **退出代码**：`0` 表示评估完成且未违反 `--fail-on` 阈值；`1` 表示触发了门禁；`2` 表示用法或加载错误。使用 `if: always()` 将输出目录保留为产物，以便审查者可以在被阻塞的运行后检查报告。
当附加了 wheel 或 sdist 产物时，GitHub Release 产物是预期的替代安装路径。PyPI 仍是主要的安装渠道，并且发布工作流会生成分发产物和 CycloneDX SBOM 作为工作流产物，以作为发布证据。
## 输出
每次 `evaluate` 运行都会写入：
- `evaluation-report.md` —— 人类可读的报告（摘要、控制表、每项控制的详细信息）
- `evaluation-report.json` —— 机器可读的契约（默认为 `reports/1.0`）
- `evaluation-report.sarif` —— SARIF 2.1.0，仅在传递 `--sarif-output` 时生成
有关 JSON 契约的详细信息，请参见 [docs/reports-contract-v1.0.md](docs/reports-contract-v1.0.md) 和旧版 [docs/reports-contract-v0.3.md](docs/reports-contract-v0.3.md)。有关结果状态（`pass`、`fail`、`manual-review-required`、`self-attested` 等）及其解释方法，请参见 [docs/results-guide.md](docs/results-guide.md)。
## 维护者自检
对本仓库运行此套件：
```
python -m oss_policy_kit evaluate --target . --profile github-level-1 --output-dir ./out/selfcheck
```
将生成的自检报告视为当前修订的权威依据。
[`scripts/`](./scripts/) 下的可选维护者脚本：
- `consumer_smoke.py` —— 将 wheel 安装到干净的 venv 中并端到端地运行 CLI。
- `twine_check_dist` —— 针对 `dist/*.whl` / `dist/*.tar.gz` 运行 `twine check`。
- `check_public_hygiene.py` —— 防止私有令牌泄漏到公共文件中的快速失败保护。
- `demo-video.ps1` —— 用于录制 CLI 演示 GIF/视频的 PowerShell 辅助脚本；不属于 CI 或打包的一部分。
## 文档
- [docs/README.md](docs/README.md) —— 文档中心
- [项目站点](https://lucashgrifoni.github.io/OSS-Security-Policy-as-Code-Starter-Kit/) —— 公共产品站点
- [docs/validation-walkthrough.md](docs/validation-walkthrough.md) —— 包含屏幕截图的完整分步演示
- [docs/cli-reference.md](docs/cli-reference.md) —— 完整的 CLI 参考
- [docs/results-guide.md](docs/results-guide.md) —— 如何解释报告状态
- [docs/profiles/overview.md](docs/profiles/overview.md) —— 捆绑配置文件矩阵、保证词汇表、决策树
- [docs/framework-alignment.md](docs/framework-alignment.md) —— 跨框架映射（Scorecard、OSPS、OWASP CICD Top 10、SLSA v1.0、NIST SSDF、S2C2F、CIS SSCS、AWS Well-Architected、Azure DevOps Security）
- [docs/profiles/github.md](docs/profiles/github.md) / [docs/profiles/aws.md](docs/profiles/aws.md) / [docs/profiles/azure.md](docs/profiles/azure.md) —— 按平台系列划分的操作指南
- [docs/release-playbook-hardgate.md](docs/release-playbook-hardgate.md) —— 带有真实 CLI 命令的发布门禁
- [docs/release-hardening-workflow.md](docs/release-hardening-workflow.md) —— 包含证据路径的端到端 L3 和发布加固工作流
- [docs/adoption-guide.md](docs/adoption-guide.md) —— 基线选择和预期结果
- [docs/recommended-adoption-playbook.md](docs/recommended-adoption-playbook.md) —— 可复制粘贴的采用路径
- [docs/architecture.md](docs/architecture.md) —— 包边界、信任模型和证据语义
- [docs/packaging-and-release.md](docs/packaging-and-release.md) —— 安装、构建和分发指南
- [docs/release-readiness.md](docs/release-readiness.md) —— 发布门禁和公开发布检查
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
参见 [SECURITY.md](SECURITY.md)。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
标签：AWS CodePipeline, Azure DevOps, CI/CD安全, DevOps安全, DevSecOps, GitHub Actions, GitHub安全, Llama, Policy-as-code, SARIF, 上游代理, 仓库安全治理, 代码安全合规, 代码审查, 合规自动化, 安全基线检查, 安全报告, 安全策略即代码, 安全评估自动化, 开源软件治理, 策略即代码, 聊天机器人安全, 自动化安全检查, 自动笔记, 逆向工具