ossf/allstar

[](https://api.scorecard.dev/projects/github.com/ossf/allstar) # **Allstar** ## 概述 - [什么是 Allstar？](#what-is-allstar) ## Allstar 最新动态 - [whats-new.md](whats-new.md) ## 禁用不需要的 Issue - [救命！我收到了 Allstar 创建的 Issue，但我不想要它们！](#disabling-unwanted-issues-1) ## 新手入门 - [背景](#background) - [组织级选项](#org-level-options) - [安装选项](#installation-options) - [使用公共 Allstar App](#using-the-allstar-app) - [快速入门安装](#quickstart-installation) - [手动安装](#manual-installation) - [自托管 Allstar](#self-hosting-allstar) - [作为 GitHub Action 运行 Allstar](#running-allstar-as-a-github-action) - [作为服务守护进程运行 Allstar](#running-allstar-as-a-service-daemon) ## 策略与操作 - [操作](#actions) - [策略](#policies) ## 进阶 - [配置定义](#configuration-definitions) - [配置示例](#example-config-repository) - [运行您自己的 Allstar 实例](operator.md) ## 概述 ### 什么是 Allstar？ Allstar 是一个 GitHub App，可持续监控 GitHub 组织或 仓库是否遵守安全最佳实践。如果 Allstar 检测到 违反安全策略的情况，它会创建一个 Issue 来提醒仓库或 组织所有者。对于某些安全策略，Allstar 还可以自动 更改导致违规的项目设置，将其恢复为 预期状态。 Allstar 的目标是让您对影响项目安全的文件和设置 拥有精细的控制。您可以选择在组织和仓库级别监控哪些 安全策略，以及如何 处理策略违规。您还可以开发或贡献新的策略。 Allstar 作为 [OpenSSF Scorecard](https://github.com/ossf/scorecard) 项目的一部分进行开发。 ## [Allstar 最新动态](whats-new.md) ## 禁用不需要的 Issue 如果您收到了 Allstar 创建的不需要的 Issue，请按照[这些说明](opt-out.md)选择退出。 ## 新手入门 ### 背景 Allstar 具有高度的可配置性。主要有三个级别的控制： - **组织级**：组织管理员可以选择在以下范围启用 Allstar： - 组织中的所有仓库； - 大多数仓库，排除一些选择退出的仓库； - 仅仅是少数选择加入的仓库。 这些配置在组织的 `.allstar` 仓库中完成。 - **仓库级：** 在使用 Allstar 的组织中，仓库维护者可以 选择让其仓库加入或退出组织级 强制策略。注意：只有当组织级设置中允许“仓库 覆盖”时，这些仓库级控制才会生效。这些配置 在仓库的 `.allstar` 目录中完成。 - **策略级：** 管理员或维护者可以选择在特定仓库上启用哪些策略，以及当策略被违反时 Allstar 采取哪些操作。这些配置在以下位置的策略 yaml 文件中完成： 组织的 `.allstar` 仓库（管理员），或者仓库的 `.allstar` 目录（维护者）。 ### 组织级选项 在组织级别安装 Allstar 之前，您应该大致决定希望 Allstar 在多少个仓库上运行。这将帮助您在选择加入和 选择退出策略之间做出选择。 - “选择加入”策略允许您手动添加希望 Allstar 运行的仓库。如果您不指定任何仓库，即使安装了 Allstar，它也不会 运行。如果您只想在总数较少的仓库上强制执行 策略，或者想在单个仓库上先试用 Allstar，然后再扩展到更多仓库时，请选择“选择加入”策略。自 v4.3 版本发布以来，已支持使用 glob 通配符来轻松添加多个名称相似的 仓库。 - “选择退出”策略（推荐）在所有仓库上启用 Allstar，并允许您手动选择要退出 Allstar 强制执行的仓库。您也可以选择退出所有公共仓库或所有 私有仓库。如果您想在组织中的所有 仓库上运行 Allstar，或者只想退出少数 仓库或特定类型（即公共与私有）的仓库，请选择此选项。 自 v4.3 版本发布以来，已支持使用 glob 通配符来轻松添加多个 名称相似的仓库。

	选择退出 (推荐) optOutStrategy = true	选择加入 optOutStrategy = false
默认行为	所有仓库均已启用	没有仓库被启用
手动添加仓库	手动添加仓库会禁用这些仓库上的 Allstar	手动添加仓库会启用这些仓库上的 Allstar
附加配置	optOutRepos：Allstar 将在列出的仓库上被禁用 optOutPrivateRepos：如果为 true，Allstar 将在所有私有仓库上被禁用 optOutPublicRepos：如果为 true，Allstar 将在所有公共 仓库上被禁用 (optInRepos：此设置将被忽略)	optInRepos：Allstar 将在列出的仓库上被启用 (optOutRepos：此设置将被忽略)
仓库覆盖	如果为 true：仓库可以使用自身仓库文件中的设置退出其组织的 Allstar 强制执行。适用于该仓库的 组织级“选择加入”设置将被忽略。 如果为 false：仓库无法退出组织级别配置的 Allstar 强制执行。	如果为 true：即使未在组织级别为该仓库进行配置，仓库也可以选择加入其组织的 Allstar 强制执行。适用于该仓库的 组织级“选择退出”设置将被忽略。 如果为 false：如果未在组织级别进行配置，仓库无法选择加入 Allstar 强制执行。

### 安装选项 [快速入门](#quickstart-installation)和[手动安装](#manual-installation)选项都涉及将 [Allstar App](https://github.com/apps/allstar-app) 安装到您的 GitHub 组织中。Allstar App 由 [OpenSSF](https://openssf.org/) 运营，对于大多数开源仓库来说是一个不错的选择。您可以查看所请求的权限。该 App 要求对大多数设置和文件内容拥有读取权限，以检测安全合规性。它请求对 Issue 和检查的写入权限，以便它可以创建 Issue 并允许 `block` 操作。 如果您不想使用由 OpenSSF 运营的 Allstar App，您可以[自托管 Allstar](#self-hosting-allstar)，创建您自己的 Allstar App。这提供了对该 App 的直接控制，但代价是需要对其进行配置、保护、监控和维护。 #### 使用 Allstar App 除非您有特定的安全或合规性限制阻止您使用 OpenSSF 托管的 Allstar App，否则建议使用快速入门或手动安装。 ##### 快速入门安装 此安装选项将使用“选择退出”策略在您组织的所有仓库中启用 Allstar。所有当前策略 都将被启用，并且 Allstar 会通过提交 Issue 来提醒您 策略违规。这是开始使用 Allstar 最快、最简单的方法，您以后仍然可以更改任何配置。 工作量：非常简单 步骤： 1. 安装 Allstar App 1. [打开安装 页面](https://github.com/apps/allstar-app) 并点击 Configure 2. 如果您有多个组织，请选择您要 安装 Allstar 的组织 3. 在 Repository Access 下选择“All Repositories”，即使您 计划稍后在某些仓库上禁用 Allstar 2. Fork 示例仓库 1. [打开示例仓库](https://github.com/ossf/dot-allstar-quickstart) 并点击“Use this template”按钮 2. 在 Repository Name 字段中，输入 `.allstar` 3. 点击“Create repository from template” 就是这样！所有当前的 Allstar [策略](#policies)现在都已在您所有的 仓库上启用。如果违反策略，Allstar 将创建一个 Issue。 要更改任何配置，请参阅[手动安装说明](manual-install.md)。 ##### 手动安装 此安装选项将引导您根据“选择加入”或“选择退出”策略创建 配置文件。此 选项从一开始就提供了对配置更精细的控制。 工作量：中等 步骤： 1. 安装 [Allstar App](https://github.com/apps/allstar-app)（在 Repository Access 下选择“All Repositories”，即使您不打算在所有 仓库上使用 Allstar） 2. 按照[手动安装说明](manual-install.md)创建组织级或 仓库级 Allstar 配置文件以及单个策略文件。 #### 自托管 Allstar 只有在必须的情况下才进行自托管！Allstar App 需要配置、安全保障 和持续的维护。当发布新的 Allstar 版本时，您需要 升级您的自托管解决方案。 下面描述了两种自托管方法： - [作为 GitHub Action 运行 Allstar](#running-allstar-as-a-github-action) - 此选项相对轻量，并利用 GitHub Actions 运行 Allstar 检查。 - [作为服务守护进程运行 Allstar](#running-allstar-as-a-service-daemon) - 此选项具有最高的控制级别，并假设您能够在可靠的服务器或容器编排器上运行 持久服务。 ##### 作为 GitHub Action 运行 Allstar 此安装选项使用 GitHub Actions 将 Allstar 作为定时作业运行。 工作量：高 按照 [GitHub Actions 安装说明](github-action-installation.md)进行以下操作： 1. 创建一个新的 GitHub App 以供 Allstar 使用。 2. 创建一个组织级的 `.allstar` 控制仓库，如 [快速入门安装](#quickstart-installation)或 [手动安装](#manual-installation)中所述。（**忽略将 OpenSSF 托管的 Allstar App 安装到您的组织中**的步骤） 3. 在 `.allstar` 中设置一个周期性的 GitHub Action 以批处理模式运行 Allstar。 4. 监控作业活动和结果。 ##### 作为服务守护进程运行 Allstar 此安装选项将 Allstar 作为持久进程运行。 工作量：非常高 有关更多信息，请参阅[操作员说明](#operator-instructions)， 包括创建 Allstar App、管理密钥以及可用的环境 变量。 ## 策略与操作 ## **操作** 每个策略都可以配置一个操作，当 Allstar 检测到 仓库不符合要求时将执行该操作。 - `log`：这是默认操作，实际上对所有 操作都会发生。所有的策略运行结果和详细信息均被记录。目前，日志 仅对 App 操作员可见，公开这些日志的计划正在讨论中。 - `issue`：此操作会创建一个 GitHub Issue。每个 策略仅创建一个 Issue，文本描述了策略违规的详细信息。如果 该 Issue 已经处于打开状态，则每 24 小时会在没有更新的情况下通过评论进行提醒（目前不可由用户配置）。如果策略结果发生变化，将在该 Issue 上 留下新评论并链接到 Issue 正文中。一旦违规问题 得到解决，Allstar 将在 5-10 分钟内自动关闭该 Issue。 - `fix`：此操作特定于策略。该策略将更改 GitHub 设置以纠正策略违规。并非所有策略都能 支持此操作（见下文）。 已提议但尚未实现的操作。未来将添加定义。 - `block`：Allstar 可以设置 [GitHub 状态 检查](https://docs.github.com/en/github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks) ，如果检查失败，则阻止合并仓库中的任何 PR。 - `email`：Allstar 会向仓库管理员发送电子邮件。 - `rpc`：Allstar 会向某些特定于组织的系统发送 rpc。 ### **操作配置** 有两个设置可用于配置 issue 操作： - `issueLabel` 在组织级别和仓库级别可用。进行设置 将覆盖 Allstar 用于标识其 Issue 的默认 `allstar` 标签。 - `issueRepo` 在组织级别可用。进行设置将强制在该组织中创建的所有 Issue 都在指定的仓库中创建。 ## **策略** 与 Allstar App 启用配置类似，所有的策略都是通过位于组织的 `.allstar` 仓库或仓库的 `.allstar` 目录中的 yaml 文件来启用和配置的。与 App 一样，策略默认是选择加入的，而且默认的 `log` 操作不会产生可见结果。一种启用所有策略的简单方法是为每个策略创建一个包含以下内容的 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) 是否根据指定的配置进行了正确的设置。Issue 文本 将描述哪个设置不正确。请参阅 [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` 处拥有安全策略文件，且该文件不为空。创建的 Issue 将包含一个指向 [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/) 上传到每个仓库的 **Security > Code Scanning** 选项卡。这使得组织管理员能够 与其他安全工具（CodeQL、 Dependabot 等）一起查看 Scorecard 的发现结果，而无需为每个仓库设置工作流。 要启用 SARIF 上传，请在您的 `scorecard.yaml` 中添加 `upload` 字段： ``` optConfig: optOutStrategy: true action: issue checks: - Binary-Artifacts - Signed-Releases threshold: 8 upload: sarif: true ``` **要求：** - Allstar GitHub App 必须将 **Code scanning alerts** 仓库 权限设置为 **Read & write**（API 范围：`security_events`）。 自托管操作员需要将此权限添加到其 GitHub App 中。由 OpenSSF 运营的公共 Allstar App 尚未包含此权限。 - SARIF 上传是非阻塞的：如果上传失败（例如，由于缺少 权限），策略检查将继续正常运行。 - 更改检测会比较仓库的 HEAD 提交 SHA，如果自上次上传以来仓库未被推送过，则跳过扫描 和上传。 SARIF 上传适用于两种[自托管部署 模式](operator.md)：作为服务守护进程运行或作为 [GitHub Action](github-action-installation.md) 运行。 ### GitHub Actions 此策略的配置文件名为 `actions.yaml`，[配置 定义在 这里](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/action#OrgConfig)。 此策略检查每个仓库中的 GitHub Actions 工作流配置文件 (`.github/workflows`)（在某些情况下还包括工作流运行），以确保它们符合策略的组织级配置中定义的规则（例如 require、deny）。 ### 仓库管理员 此策略的配置文件名为 `admin.yaml`，[配置 定义在 这里](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/admin#OrgConfig)。 此策略检查默认情况下所有仓库是否必须分配有用户或团队作为管理员。它允许您选择配置是否允许用户（相对于团队）成为管理员。 ### 未来策略 - 确保已启用 dependabot。 - 检查依赖项是否已固定/冻结。 ## **配置示例仓库** 请参阅[此仓库](https://github.com/GoogleContainerTools/.allstar)，查看正在使用的 Allstar 配置示例。 作为组织管理员，请考虑编写一个 README.md，提供有关在您的组织中如何使用 Allstar 的一些信息。 ## 进阶 ### 配置定义 - [组织级启用配置](https://pkg.go.dev/github.com/ossf/allstar/pkg/config#OrgOptConfig) - [仓库覆盖启用配置]( https://pkg.go.dev/github.com/ossf/allstar/pkg/config#RepoOptConfig) ### 组织级辅助配置位置 默认情况下，诸如上述 `allstar.yaml` 文件之类的组织级配置文件，应该位于 `.allstar` 仓库中。如果此仓库不 存在，则使用 `.github` 仓库的 `allstar` 目录作为 次要位置。为了清楚说明，对于 `allstar.yaml`： | 优先级 | 仓库 | 路径 | | - | - | - | | 主要 | `.allstar` | `allstar.yaml` | | 次要 | `.github` | `allstar/allstar.yaml` | 对于下文所述的各个策略的组织级配置文件，情况也是如此。 ### 组织仓库中的仓库策略配置 Allstar 还会在组织的 `.allstar` 仓库中查找仓库级策略配置，位置在与仓库同名的目录下。无论“仓库覆盖”是否被禁用，都会使用此配置。 例如，Allstar 将按以下顺序查找给定仓库 `myapp` 的策略配置： | 仓库 | 路径 | 条件 | | - | - | - | | `myapp` | `.allstar/branch_protection.yaml` | 当允许“仓库覆盖”时。 | | `.allstar` | `myapp/branch_protection.yaml` | 任何情况。 | | `.allstar` | `branch_protection.yaml` | 任何情况。 | | `.github` | `allstar/myapp/branch_protection.yaml` | 如果 `.allstar` 仓库不存在。 | | `.github` | `allstar/branch_protection.yaml` | 如果 `.allstar` 仓库不存在。 | ### 组织级基础与合并配置位置 对于组织级的 Allstar 和策略配置文件，您可以指定 `baseConfig` 字段来指定另一个包含基础 Allstar 配置的仓库。最好用一个例子来解释。 假设您有多个 GitHub 组织，但希望维护一个单一的 Allstar 配置。您的主要组织是“acme”，仓库 `acme/.allstar` 包含 `allstar.yaml`： ``` optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team. ``` 您还有一个名为“acme-sat”的附属 GitHub 组织。您想 重新使用主配置，但在此基础上应用一些更改，在某些仓库上禁用 Allstar。仓库 `acme-sat/.allstar` 包含 `allstar.yaml`： ``` baseConfig: acme/.allstar optConfig: optOutRepos: - acmesat-one - acmesat-two ``` 这将使用 `acme/.allstar` 中的所有配置作为基础配置，然后 在基础配置之上应用当前文件中的任何更改。应用此方法的机制被描述为 [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7396)。`baseConfig` 必须是 一个 GitHub `/`。 ## **贡献** 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)

标签：DevSecOps, EVTX分析, GitHub App, 上游代理, 关系图谱, 基线检查, 安全合规, 开源框架, 持续集成, 日志审计, 网络代理, 请求拦截