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 模式轻松添加多个名称相似的仓库。

安装选项

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

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)。

此策略整合了 [scorecard 中的检查](https://github.com/ossf/scorecard/#scorecard-checks)。从仓库中移除二进制制品即可实现合规。由于 scorecard 结果可能较为冗长，您可能需要自行运行 [scorecard](https://github.com/ossf/scorecard) 以查看所有详细信息。

### CODEOWNERS

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

此策略检查您的仓库中是否存在 [`CODEOWNERS` 文件](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)。

### 外部协作者

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

此策略检查是否有任何[外部协作者](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization)拥有仓库的管理员（默认）或推送（可选）访问权限。只有组织成员才应拥有此类访问权限，否则不受信任的成员可以更改管理员级别的设置并提交恶意代码。

### SECURITY.md

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

此策略检查仓库是否在 `SECURITY.md` 中包含安全策略文件，且该文件不为空。创建的问题将包含指向 [GitHub 标签页](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) 的链接，该页面可帮助您向仓库提交安全策略。

### 危险工作流

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

此策略将针对**所有**分支运行，相关理由见[此处](https://github.com/ossf/allstar/issues/569)。

此策略检查 GitHub Actions 工作流配置文件（`.github/workflows`）中是否存在与已知危险行为匹配的模式。有关此检查的更多信息，请参阅 [OpenSSF Scorecard 文档](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)。

### 通用 Scorecard 检查

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

此策略运行 `checks` 配置中列出的任何 scorecard 检查。所有运行的检查得分必须等于或高于 `threshold` 设置。有关每项检查的更多信息，请参阅 [OpenSSF Scorecard 文档](https://github.com/ossf/scorecard/blob/main/docs/checks.md)。

#### SARIF 上传

Scorecard 策略可以选择将结果作为 [SARIF](https://sarifweb.azurewebsites.net/) 上传到每个仓库的 **安全 > 代码扫描** 标签页。这使组织管理员无需在每个仓库中设置工作流，即可与其他安全工具（CodeQL、Dependabot 等）一起查看 Scorecard 的发现结果。

要启用 SARIF 上传，请在您的 `scorecard.yaml` 中添加 `upload` 字段：```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

要求：

• Allstar GitHub 应用必须将 代码扫描警报 仓库权限设置为 读取与写入（API 范围：security_events）。这不在 Allstar 其他情况下所需的权限之列，因此在启用 SARIF 上传之前，请将其添加到你的应用中。
• SARIF 上传是非阻塞的：如果上传失败（例如，由于权限缺失），策略检查仍会正常继续。
• 变更检测会比较仓库 HEAD 提交 SHA，并在自上次上传以来仓库没有新推送时跳过扫描和上传。

SARIF 上传适用于运行 Allstar 的两种方式：作为服务守护进程或作为 GitHub Action。

GitHub Actions

此策略的配置文件名为 actions.yaml，配置定义在此处。

此策略检查每个仓库中的 GitHub Actions 工作流配置文件（.github/workflows）（在某些情况下还包括工作流运行），以确保它们符合组织级策略配置中定义的规则（例如，要求、禁止）。

仓库管理员

此策略的配置文件名为 admin.yaml，配置定义在此处。

此策略默认检查所有仓库是否必须分配一个用户或组作为管理员。它还允许你选择性地配置是否允许用户（而非团队）担任管理员。

未来策略

• 确保已启用 dependabot。
• 检查依赖项是否已固定/冻结。

示例配置仓库

参见此仓库作为 Allstar 配置的使用示例。作为组织管理员，可以考虑添加一个 README.md，其中包含有关你的组织中如何使用 Allstar 的一些信息。

高级

配置定义

• 组织级启用配置
• 仓库覆盖启用配置

次要组织级配置位置

默认情况下，组织级配置文件（例如上面的 allstar.yaml）应位于 .allstar 仓库中。如果该仓库不存在，则使用 .github 仓库的 allstar 目录作为次要位置。为明确起见，对于 allstar.yaml：

对于各个策略的组织级配置文件也是如此，如下所述。

组织仓库中的仓库策略配置

Allstar 还会在组织的 .allstar 仓库中查找仓库级策略配置，位置在与仓库同名的目录下。无论是否禁用“仓库覆盖”，都会使用此配置。

例如，Allstar 将按以下顺序查找给定仓库 myapp 的策略配置：

组织级基础与合并配置位置

对于组织级 Allstar 和策略配置文件，你可以指定 baseConfig 字段来指定包含基础 Allstar 配置的另一个仓库。这最好通过一个示例来说明。

假设你有多个 GitHub 组织，但希望维护单一的 Allstar 配置。你的主组织是“acme”，仓库 acme/.allstar 包含 allstar.yaml：```yaml optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team.

你还有一个名为“acme-sat”的卫星 GitHub 组织。你想复用主配置，但在此基础上应用一些更改，通过在某些仓库上禁用 Allstar 来实现。仓库 `acme-sat/.allstar` 包含 `allstar.yaml`：```yaml
baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

这将使用 acme/.allstar 中的所有配置作为基础配置，但随后会将当前文件中的任何更改应用于基础配置之上。应用此方法的方式被描述为 JSON 合并补丁。baseConfig 必须是 GitHub 的 <组织>/<仓库>。

贡献

参见 CONTRIBUTING.md