oss-hygiene

oss-hygiene

将公开的 GitHub 仓库提升至 GitHub Community Standards 基准和 OpenSSF Scorecard 供应链基准，并为申请 OpenSSF Best Practices Badge 做好准备。

它与 /gh-bootstrap 配合使用，但解决的是另一个问题：gh-bootstrap 锁定合并入口；oss-hygiene 完善面向贡献者和供应链的部分。

此技能的适用场景

关注事项	技能
合并按钮、分支保护、发布说明配置	/gh-bootstrap
社区文件、供应链检查、OSSF 状态	/oss-hygiene（此技能）
跨多个仓库以代码形式管理组织级设置	/safe-settings
按任务处理 PR／议题／CI 运维	/gh

先运行 /gh-bootstrap（锁定 main），再运行 /oss-hygiene（让贡献者了解如何参与，并让供应链检查成为 PR 的合并门槛）。

配置内容

此技能会处理三个相互独立的方面。它会将每个文件与 assets/ 模板进行比较，并在覆盖任何已有文件前征求确认。

方面 1 — GitHub Community Standards

仓库 Insights 下的“Community Standards”选项卡会显示这些文件。缺少文件会导致检查清单不通过。

文件	源资源	用途
README.md	（不提供脚手架 — 仓库有自己的 README）	仅检查是否存在
LICENSE	（不提供脚手架 — 需自行选择许可证）	仅检查是否存在
CODE_OF_CONDUCT.md	assets/CODE_OF_CONDUCT.md	Contributor Covenant 2.1
CONTRIBUTING.md	assets/CONTRIBUTING.md	如何提交议题、发起 PR、运行测试
SECURITY.md	assets/SECURITY.md	漏洞报告（私密安全公告）
.github/ISSUE_TEMPLATE/bug_report.yml	assets/.github/ISSUE_TEMPLATE/bug_report.yml	结构化 Bug 表单
.github/ISSUE_TEMPLATE/feature_request.yml	assets/.github/ISSUE_TEMPLATE/feature_request.yml	结构化功能请求表单
.github/ISSUE_TEMPLATE/config.yml	assets/.github/ISSUE_TEMPLATE/config.yml	禁用空白议题、提供联系链接
.github/PULL_REQUEST_TEMPLATE.md	assets/.github/PULL_REQUEST_TEMPLATE.md	PR 检查清单

如果缺少 LICENSE，不要悄悄创建。选择许可证是一项决策（MIT、Apache-2.0、AGPL-3.0 等）——指出这一缺失，并向用户提供 https://choosealicense.com/ 链接。

如果 README 缺失或内容过少，应提示用户，但不要自动生成。README 的内容体现了项目的声音。

表面 2 — 供应链（Scorecard 检查）

OpenSSF Scorecard 会运行约 18 项自动检查。该技能会配置其中与脚手架相关的检查：

Scorecard 检查	风险	操作
Security-Policy	中	SECURITY.md（表面 1）
License	低	LICENSE（表面 1，仅表面）
Dependency-Update-Tool	高	assets/.github/dependabot.yml
Branch-Protection	高	由 /gh-bootstrap 规则集覆盖
Code-Review	高	由 /gh-bootstrap PR 规则覆盖
CI-Tests	低	仓库现有的 CI
Token-Permissions	高	审核现有工作流中的 permissions: 块；仅报告
Dangerous-Workflow	严重	仅审核 — 对 pull_request_target 与 actions/checkout 检出 head ref 的组合发出警告
SAST	中	assets/.github/workflows/codeql.yml（适用时）
Pinned-Dependencies	中	仅报告 — 依赖固定因生态系统而异，且存在争议
Maintained	高	被动检查 — 随实际活动逐渐体现
Binary-Artifacts	高	扫描目录树中的 .so、.dll、.jar、.exe、.zip、.tgz；发出警告
Vulnerabilities	高	被动检查 — 由 Dependabot 警报处理
Signed-Releases	高	仅报告 — sigstore 配置因项目而异
Fuzzing	中	仅报告 — 因语言而异
Packaging	中	仅报告 — 取决于发布流水线
Contributors	低	被动检查
CII-Best-Practices	低	表面 3

此外，还有不会写入仓库文件的 GitHub 原生代码安全功能：

功能	启用方式	操作
Dependabot 警报	仓库设置 → Advanced Security（公开仓库默认自动启用）	通过 API 验证
Secret scanning 警报（针对用户）	仓库设置 → Advanced Security（公开仓库免费，需主动启用）	通过 API 启用
推送保护（secret scanning）	仓库设置 → Advanced Security	通过 API 启用
依赖关系图	仓库设置 → Security（公开仓库默认自动启用）	通过 API 验证
Dependency Review Action	assets/.github/workflows/dependency-review.yml	配置脚手架
Scorecard 发布	assets/.github/workflows/scorecard.yml	配置脚手架（上传供徽章使用的 SARIF）

表面 3 — OpenSSF Best Practices 徽章

此徽章需在 https://www.bestpractices.dev 上自行申报。该技能不会代为填写 — 项目所有者必须自行完成。该技能会：

1. 检查仓库是否已有徽章（在 README 中查找徽章 URL）。
2. 输出预填仓库 URL 的注册链接。
3. 建议将徽章 Markdown 添加到 README（assets/README-badge-snippet.md）。

该徽章是 Scorecard 的 CII-Best-Practices 检查启用器 — 即使只注册到进行中级别，也是提升该评分最省力的方式。

协议

1. 确认范围并检查当前状态

gh auth status
gh repo view --json nameWithOwner,visibility,isPrivate,licenseInfo,description
gh api "repos/$REPO/community/profile" --jq '{
  health_percentage,
  files: (.files | to_entries | map(select(.value != null)) | from_entries | keys)
}'
gh api "repos/$REPO/vulnerability-alerts" 2>/dev/null && echo "dependabot alerts: ON" || echo "dependabot alerts: OFF"
gh api "repos/$REPO" --jq '{
  secret_scanning: .security_and_analysis.secret_scanning.status,
  push_protection: .security_and_analysis.secret_scanning_push_protection.status
}'

一次性向用户提出一个整合所有决策的单一问题。不要依次提问；用户应能回复“按默认设置”，然后继续执行此技能。问题列表最多包含以下项目（≤5）：

• 可见性 — 此技能面向公开仓库。私有仓库可以使用其中一部分（社区文件可以使用；密钥扫描需要 Advanced Security；要发布 scorecard，徽章需要公开可见性）。
• 许可证 — 如果 licenseInfo 为 null，请说明这一点，并暂停，直到用户选择许可证。
• CodeQL 适用性 — 仓库是否包含 CodeQL 支持的语言代码（actions、c-cpp、csharp、go、java-kotlin、javascript-typescript、python、ruby、swift）？如果没有，请跳过 CodeQL 工作流。如果唯一匹配项是 CI 辅助脚本（例如 .github/scripts/*.py），请提出建议，而不要强行提问 — 这些不是项目代码，默认应跳过，用户可以选择启用。
• FUNDING.yml — 用户是否接受赞助？如果接受，请询问平台和账号名（GitHub Sponsors、Buy Me a Coffee、Ko-fi、OpenCollective 等）。
• CODEOWNERS — 仅在仓库有多位维护者时建议。单人维护时跳过。

2. 创建社区文件

按顺序处理 assets/ 下的每个文件：

CODE_OF_CONDUCT.md
CONTRIBUTING.md
SECURITY.md
.github/ISSUE_TEMPLATE/bug_report.yml
.github/ISSUE_TEMPLATE/feature_request.yml
.github/ISSUE_TEMPLATE/config.yml
.github/PULL_REQUEST_TEMPLATE.md

与现有文件进行差异比较（如果存在）。如果内容不同，请在覆盖前征求同意。替换 {{REPO}}、{{OWNER}}、{{CONTACT_EMAIL}} 占位符。

CONTRIBUTING.md 包含一个通用框架 — 鼓励用户在合并后根据项目进行定制。

3. 创建供应链工作流

资源	目标	跳过条件
assets/.github/dependabot.yml	.github/dependabot.yml	从不（始终有用）
assets/.github/workflows/dependency-review.yml	.github/workflows/dependency-review.yml	未启用 Code Security 的私有仓库
assets/.github/workflows/scorecard.yml	.github/workflows/scorecard.yml	私有仓库（徽章需要公开）
assets/.github/workflows/codeql.yml	.github/workflows/codeql.yml	仓库没有 CodeQL 支持的语言

dependabot.yml 会根据在仓库中检测到的语言包进行配置（查找 package.json、Cargo.toml、pyproject.toml、go.mod、Gemfile、composer.json、pom.xml 等），并添加 github-actions 生态系统条目，以保持工作流操作版本为最新。

清单文件检测范围。 仅统计项目源代码根目录中的清单文件 — 不包括 .github/scripts/、.devcontainer/、tools/ci/ 或其他 CI 辅助路径下的文件。项目根目录下的 pyproject.toml 是有效清单；工作流中的硬编码 pip install foo==1.2.3 行则不是，而且如果没有实际的顶层清单文件，Dependabot 就无法跟踪它。当唯一的语言代码出现在 CI 辅助代码中时，跳过该生态系统，并在生成的 dependabot.yml 中添加一行注释说明原因（例如：“没有顶层 Python 清单文件；Python 代码仅存在于 .github/scripts/ 中”）。这与第 1 步中用于判断 CodeQL 适用性的启发式规则一致。

4. 切换 GitHub 原生安全功能

使用 gh api 启用或验证（幂等 — 重复执行不会产生变化）：

# Automated security fixes / Dependabot security updates
gh api -X PUT "repos/$REPO/automated-security-fixes"

# Vulnerability alerts (Dependabot alerts)
gh api -X PUT "repos/$REPO/vulnerability-alerts"

# Secret scanning alerts for users + push protection
gh api -X PATCH "repos/$REPO" \
  -F security_and_analysis[secret_scanning][status]=enabled \
  -F security_and_analysis[secret_scanning_push_protection][status]=enabled

对于私有仓库，如果没有付费使用 GitHub Code Security，这些操作可能会返回 403 — 请说明情况并跳过，不要失败。

5. 审计现有工作流中的 Token-Permissions 和 Dangerous-Workflow

这是检测，不是修改。此技能会读取每个 .github/workflows/*.yml 文件：

• Token-Permissions： 标记任何缺少顶层 permissions: 块的工作流（或使用 permissions: write-all 的工作流）。建议使用安全的默认设置 permissions: { contents: read }，并且仅为各个作业提升所需权限。
• Dangerous-Workflow： 标记 pull_request_target 与对 head SHA 执行 actions/checkout 这一不安全模式，以及任何将 github.event.* 输入插值到 shell 脚本中的 ${{ ... }} 用法。

打印发现的问题；不要自动编辑。这些改动不易察觉，应由用户审核。

6. 展示 OpenSSF 最佳实践徽章步骤

打印出来，不要应用。项目注册后，替换 <owner>、<repo> 和项目 ID。阅读 assets/README-badge-snippet.md；如果第 3 步跳过了 CodeQL，请删除 和 标记之间的代码块——这些标记的存在，正是为了让该代码片段能够在无歧义的情况下按条件裁剪。

Register at: https://www.bestpractices.dev/en/projects/new
Repo URL:    https://github.com/<owner>/<repo>
Once you have a project ID, paste this into README.md:

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/<owner>/<repo>/badge)](https://scorecard.dev/viewer/?uri=github.com/<owner>/<repo>)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/<id>/badge)](https://www.bestpractices.dev/projects/<id>)

该技能不会代用户注册项目——注册涉及凭据和判断（用户需要对答案作出确认）。

7. 验证并报告

重新阅读社区资料和工作流文件。打印一份简短摘要：

gh api "repos/$REPO/community/profile" --jq '{health_percentage, missing: ([.files | to_entries[] | select(.value == null) | .key])}'
ls .github/workflows/ | sort

摘要应说明：

• 搭建了哪些内容（以及与现有内容的差异，如有）
• 哪些内容原本就正确（未作更改）
• 跳过了哪些内容以及原因（没有 LICENSE、仓库为私有、没有 CodeQL 支持的语言等）
• OSSF 徽章注册链接

幂等性

• 文件：覆盖前先比较差异；如果内容不同，请先询问。
• API 开关：PUT/PATCH 具有幂等性。
• 工作流审查：只读——重新运行只会再次打印相同的发现。
• 绝不删除：如果之前的运行留下了产物（例如名称不同的旧工作流），请指出并由用户决定。

此技能不适用于

• 选择许可证——它会指出缺少许可证，但不会替你选择
• 编写 README——内容应体现项目的风格
• 组织范围的社区文件——请使用 /safe-settings
• 分支保护 / 合并队列——请使用 /gh-bootstrap
• Sigstore 发布签名——与语言和流水线有关，不在范围内
• 填写 OSSF 最佳实践徽章问卷——这是维护者的确认
• 固定依赖项——因生态系统而异，且常有争议
• 设置模糊测试——因语言而异

注意事项

• 默认社区健康文件：如果用户/组织有一个包含这些文件的 .github 仓库，那么所有没有自带副本的仓库都会应用这些文件。在仓库中搭建文件会覆盖组织默认设置；只有在确实需要针对单个仓库覆盖时才这样做。
• Dependency Review Action：公共仓库可免费使用，私有仓库只有在启用了 GitHub Advanced Security 时才能使用。该工作流在私有仓库/免费方案中会直接失败。
• Scorecard 工作流：通过 OIDC 向 scorecard.dev 发布需要 id-token: write；资源文件已配置正确的权限。如果工作流首次运行时因 403 失败，说明用户的组织级 OIDC 限制阻止了该操作。
• CodeQL setup-mode：default 设置需在 GitHub UI 中配置（Settings → Code security → CodeQL → Set up）。资源文件使用 advanced 设置（工作流文件）。两者互斥——如果用户先启用了 default，工作流文件就会产生冲突。
• Token-Permissions 审查：softprops/action-gh-release 等操作以及许多发布操作都需要 contents: write。不要建议用户将每个工作流都设为只读——应指出并解释原因。
• pull_request_target 默认情况下很危险：不要仅仅为了在 fork PR 中访问密钥而使用它。该技能会标记此用法；用户应改用单独的 workflow_run 或带标签的 PR 模式。
• OSSF 徽章由申请者自行确认：徽章通过意味着维护者回答了问卷，而不是项目经过了审计。它是一种信号，并非保证。
• Scorecard 对小型/新建仓库的评分：Maintained 检查要求有 90 天的活动记录；新仓库在积累足够时间前得分会偏低。这是有意的设计，不是缺陷。
• 搭建的工作流会在自身的 Pinned-Dependencies 检查中触发告警：dependency-review.yml、scorecard.yml 和 codeql.yml 使用浮动标签（@v4、@v2、@v3），以匹配 OSSF 参考模板并保持可读性。Scorecard 的 Pinned-Dependencies 检查首次运行时会标记这些标签。这里有意作出了权衡：Dependabot（也由此技能搭建）会自动保持这些标签为最新，而 SHA 固定值会悄无声息地过期。如果你希望 Pinned-Dependencies 得分不受影响，请在首个 Dependabot PR 合并后，将这三个新工作流文件改为固定到提交 SHA；之后 Dependabot 会继续以固定形式维护它们。

参考资料

• references/scorecard-checks.md — 包含全部 18 项 Scorecard 检查的完整表格、检查内容以及修复建议。
• references/badge-criteria.md — OpenSSF 最佳实践徽章的通过标准及其对应的仓库文件。
• references/community-standards.md — GitHub 自带的检查清单，以及各文件的检测方式。
• references/dependabot.md — dependabot.yml 架构参考和各生态系统的示例。
• references/workflow-hardening.md — Token-Permissions 和 Dangerous-Workflow 规则及具体示例。