Allstar

[!IMPORTANT] 由 OpenSSF 托管的 Allstar GitHub App 已退役。 Allstar 作为 OpenSSF Scorecard 子项目，其本身仍在持续维护中——您现在必须自行运行它，可以 作为 GitHub Action 或 作为服务守护进程 运行。

更多详情请参阅 ossf/allstar#881。

如果您的组织一直依赖托管应用，请参阅 从托管应用迁移。

概述

• 什么是 Allstar？

Allstar 的新功能

• whats-new.md

禁用不需要的问题

• 救命！Allstar 创建了我不想要的问题！

入门指南

• 背景
• 组织级选项
• 安装选项
  • 创建您的 GitHub App
  • 创建您的 .allstar 控制仓库
  • 将 Allstar 作为 GitHub Action 运行
  • 将 Allstar 作为服务守护进程运行
• 从托管应用迁移

策略与操作

• 操作
• 策略

高级

• 配置定义
• 示例配置
• 运行您自己的 Allstar 实例

贡献

• 贡献指南

---

---

概述

什么是 Allstar？

Allstar 是一个 GitHub App，持续监控 GitHub 组织或仓库对安全最佳实践的遵守情况。如果 Allstar 检测到安全策略违规，它会创建一个 issue 来提醒仓库或组织所有者。对于某些安全策略，Allstar 还可以自动更改导致违规的项目设置，将其恢复为预期状态。

Allstar 的目标是让您对影响项目安全的文件和设置拥有精细的控制。您可以在组织级别和仓库级别选择要监控的安全策略，以及如何处理策略违规。您还可以开发或贡献新的策略。

Allstar 是作为 OpenSSF Scorecard 项目的一部分开发的。

Allstar 的新功能

禁用不需要的问题

如果您收到 Allstar 创建的不需要的 issue，请按照 这些说明 选择退出。

入门指南

背景

Allstar 具有高度可配置性。主要有三个控制层级：

• 组织级：组织管理员可以选择在以下范围启用 Allstar：
  • 组织中的所有仓库；
  • 大多数仓库，但排除一些已选择退出的仓库；
  • 仅少数已选择加入的仓库。

这些配置在组织的 .allstar 仓库中完成。

• 仓库级：使用 Allstar 的组织中的仓库维护者可以选择将其仓库加入或退出组织级强制执行。注意：这些仓库级控制仅在组织级设置允许“仓库覆盖”时才生效。这些配置在仓库的 .allstar 目录中完成。

• 策略级：管理员或维护者可以选择在特定仓库上启用哪些策略，以及当策略被违反时 Allstar 采取哪些操作。这些配置在组织的 .allstar 仓库（管理员）或仓库的 .allstar 目录（维护者）中的策略 yaml 文件中完成。

组织级选项

在组织级别安装 Allstar 之前，您应该大致决定希望 Allstar 在多少个仓库上运行。这将帮助您在 Opt-In 和 Opt-Out 策略之间做出选择。

• Opt In 策略允许您手动添加希望 Allstar 运行的仓库。如果您未指定任何仓库，即使已安装，Allstar 也不会运行。如果您只想在总仓库中的少数仓库上强制执行策略，或者想在更多仓库上启用之前先在单个仓库上试用 Allstar，请选择 Opt In 策略。自 v4.3 版本起，支持使用 glob 模式轻松添加多个名称相似的仓库。

• Opt Out 策略（推荐） 会在所有仓库上启用 Allstar，并允许您手动选择要退出 Allstar 强制执行的仓库。您还可以选择退出所有公共仓库或所有私有仓库。如果您想在组织的所有仓库上运行 Allstar，或者只想退出少数仓库或特定类型（即公共与私有）的仓库，请选择此选项。自 v4.3 版本起，支持使用 glob 模式轻松添加多个名称相似的仓库。

	Opt Out（推荐） optOutStrategy = true	Opt In optOutStrategy = false
默认行为	所有仓库均已启用	没有仓库被启用
手动添加仓库	手动添加仓库会在这些仓库上禁用 Allstar	手动添加仓库会在这些仓库上启用 Allstar
其他配置	optOutRepos：Allstar 将在列出的仓库上被禁用 optOutPrivateRepos：如果为 true，Allstar 将在所有私有仓库上被禁用 optOutPublicRepos：如果为 true，Allstar 将在所有公共仓库上被禁用 (optInRepos：此设置将被忽略)	optInRepos：Allstar 将在列出的仓库上被启用 (optOutRepos：此设置将被忽略)
仓库覆盖	如果为 true：仓库可以使用其自身仓库文件中的设置退出其组织的 Allstar 强制执行。适用于该仓库的组织级 opt-in 设置将被忽略。 如果为 false：仓库不能退出组织级配置的 Allstar 强制执行。	如果为 true：即使仓库未在组织级配置，也可以加入其组织的 Allstar 强制执行。适用于该仓库的组织级 opt-out 设置将被忽略。 如果为 false：如果仓库未在组织级配置，则不能加入 Allstar 强制执行。

安装选项

Allstar 以 GitHub App 的形式作用于您的组织：您创建应用，然后运行以该应用身份进行身份验证的进程。因此，设置分为两个对所有部署都通用的步骤——创建应用 和 创建控制仓库——然后选择如何运行它：

	GitHub Action	服务守护进程
运行方式	在您的 .allstar 仓库中定时运行的任务	您托管的持久进程
您需要提供	除 GitHub 外无需其他	服务器或容器编排器
运行频率	由您设置的 cron 决定	持续运行，结果在 5-10 分钟内产生
设置工作量	中等	较高
最适合	您想要基础设施开销最低的选项	您想要最大控制权，或已在运行服务

Action 是两者中开销较低的选项，也是大多数组织应该开始使用的方式；您可以稍后迁移到守护进程，而无需更改任何策略配置。

创建您的 GitHub App

App 是一种类似用户的身份，在您的组织中拥有一组权限。Allstar 需要读取大多数设置和文件内容的权限以检测合规性，以及写入 issues 和 checks 的权限以提交 issue 并支持 block 操作。

请遵循 操作员说明 - 创建 GitHub App，并记录 App ID 和私钥。两种运行模式都需要它们。

创建您的 .allstar 控制仓库

Allstar 从您组织中名为 .allstar 的仓库读取其配置。

从示例创建是最快的方式：

1. 打开示例仓库 并点击“Use this template”按钮
2. 在 Repository Name 字段中，输入 .allstar
3. 点击“Create repository from template”

这将在所有仓库上使用 Opt Out 策略启用所有当前的 Allstar 策略，并采用 issue 操作。您之后可以更改其中的任何内容。

如果您想从一开始就进行精细控制——选择 Opt In 或 Opt Out 策略并自行编写各个策略文件——请改用 手动安装说明。

将 Allstar 作为 GitHub Action 运行

此选项使用 GitHub Actions 将 Allstar 作为定时任务运行，因此除了 GitHub 本身之外，无需操作任何基础设施。

请遵循 GitHub Actions 安装说明 在您的 .allstar 仓库中设置一个定期运行的 Action，对其进行加固，并监控其结果。

将 Allstar 作为服务守护进程运行

此选项将 Allstar 作为持久进程运行，持续检测和解决违规问题，而不是按计划运行。

有关运行进程、管理密钥、规模调整以及可用的环境变量，请参阅 操作员说明。

从托管应用迁移

如果您的组织使用了 OpenSSF 托管的应用，您的配置将原样保留。.allstar 控制仓库、allstar.yaml 以及每个策略文件都将继续正常工作，无需更改；您只需替换读取它们的进程。

要迁移：

1. 创建您自己的 GitHub App，并将其安装到您的组织，并授予与托管应用相同的仓库访问权限。
2. 保持您现有的 .allstar 仓库完全不变。
3. 将 Allstar 作为 Action 或 守护进程 运行。
4. 如果 allstar-app 仍出现在您的组织设置 -> GitHub Apps 下，请将其卸载。

托管应用之前提交的 issue 仍保留在您的仓库中。您自己的实例通过相同的 allstar 标签（或您配置的 issueLabel）识别其 issue，因此当违规问题解决后，它会接管并关闭这些 issue，而不是提交重复的 issue。

策略与操作

操作

每个策略都可以配置一个操作，当 Allstar 检测到仓库不合规时，它将采取该操作。

• log：这是默认操作，实际上对所有操作都会执行。所有策略运行结果和详细信息都会被记录。日志目前仅对应用操作员可见，计划将其公开的讨论正在进行中。
• issue：此操作会创建一个 GitHub issue。每个策略只创建一个 issue，文本描述了策略违规的详细信息。如果 issue 已经打开，则每 24 小时（无更新时）会通过评论进行提醒（目前不可由用户配置）。如果策略结果发生变化，将在 issue 上留下新评论，并在 issue 正文中链接。一旦违规问题得到解决，Allstar 将在 5-10 分钟内自动关闭该 issue。
• fix：此操作是策略特定的。该策略将更改 GitHub 设置以纠正策略违规。并非所有策略都能支持此操作（见下文）。

已提议但尚未实现的操作。定义将在未来添加。

• block：Allstar 可以设置 GitHub 状态检查，如果检查失败，则阻止仓库中的任何 PR 被合并。
• email：Allstar 将向仓库管理员发送电子邮件。
• rpc：Allstar 将向某个组织特定的系统发送 rpc。

操作配置

有两个设置可用于配置 issue 操作：

• issueLabel 可在组织级别和仓库级别使用。设置它将覆盖 Allstar 用于识别其 issue 的默认 allstar 标签。

• issueRepo 可在组织级别使用。设置它将强制在组织中创建的所有 issue 都创建到指定的仓库中。

策略

与 Allstar 应用启用配置类似，所有策略都通过组织 .allstar 仓库或仓库 .allstar 目录中的 yaml 文件启用和配置。与应用一样，策略默认是 opt-in 的，同时默认的 log 操作不会产生可见结果。启用所有策略的一个简单方法是为每个策略创建一个 yaml 文件，内容如下：```yaml optConfig: optOutStrategy: true action: issue

每个策略的 `fix` 操作的具体工作方式详见下文。如果下文未提及，则表示该策略不适用 `fix` 操作。

### 分支保护

此策略的配置文件名为 `branch_protection.yaml`，[配置定义见此处](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig)。

分支保护策略会检查 GitHub 的[分支保护设置](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)是否按照指定配置正确设置。问题文本将描述哪个设置不正确。有关修正设置的信息，请参阅 [GitHub 文档](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)。

`fix` 操作将更改分支保护设置，使其符合指定的策略配置。

### 二进制制品

此策略的配置文件名为 `binary_artifacts.yaml`，[配置定义见此处](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig)。