使用 GitHub 包防火墙保护终端节点

关于 GitHub package firewall

GitHub package firewall 位于你的终结点和包注册表之间。 它会根据最低包期限和恶意软件公告等策略评估包下载，并阻止不符合这些策略的下载。 可以使用它保护 CI 构建、AI 代理会话和本地开发中的依赖项安装。

若要使用防火墙，请配置企业的策略控制，然后将终结点配置为通过防火墙请求包，而不是直接从公共注册表请求包。 还可以通过自定义角色授予管理该策略的权限。

配置策略控制

企业安全经理和企业管理员可以配置策略控制。

1. 导航到您的企业。 例如，从 GitHub.com 上的 公司 页面。
2. 在页面顶部，单击“ 策略”。
3. 在边栏中，单击 Package firewall。
4. 配置以下部分中介绍的策略控制。 这些控制适用于通过防火墙的所有请求。

阻止已知恶意软件

启用后，此控件会检查 GitHub Advisory Database 中的活动恶意软件公告，并阻止包含匹配公告的包。 此控件默认为 On。

屏蔽漏洞公告

此控件检查 GitHub Advisory Database 中影响所请求包版本的漏洞。 选择阻止安装的最低咨询严重性：仅严重级别、高或更高级别、中或更高级别或任何严重级别。 此控件默认为“仅严重”。

阻止认证被降级

此控件将请求的包版本的证明与早期版本的证明进行比较。 如果包以前有 SLSA 证明，但请求的版本没有，防火墙会阻止下载。 缺少认证证明可能表明发布流程已遭破坏。 有关证明材料的详细信息，请参阅 构件认证。 此控件默认为 On。

阻止新引入的安装脚本

此控件检查包最近是否添加了在安装期间运行的脚本，例如 preinstall 或 postinstall 脚本。 这些脚本可以在系统上运行任意命令，并可用于窃取凭据。 此控件默认为 On。

最低程序包存在时间

此控件为新发布的包版本设置冷却期。 防火墙会阻止比配置的最短期限更新的版本，从而在您安装这些版本之前留出时间发现威胁。

将最小年龄设置为介于 1 到 365 天之间的值，或将其设置为 0 以禁用控件。 默认值为 1 天。

配置终结点以使用 Package firewall

将包管理器配置为从防火墙的 URL 而不是默认公共仓库中提取包。

身份验证令牌

注册表 URL 特定于您的企业。 每个请求都必须包含与作为企业成员的用户或机器人帐户关联的身份验证令牌。 令牌不需要超出对公共存储库的只读访问权限之外的任何更高权限。 有关详细信息，请参阅“管理个人访问令牌”。

配置 npm

使用用户级 .npmrc 文件配置 npm。 在示例中，将 ENTERPRISE 替换为你的企业 slug。 将 GITHUB_TOKEN 环境变量设置为可访问您的企业的 GitHub 令牌。 安全地存储令牌，例如在 CI 机密中，不将其提交到存储库。

1. 将以下配置添加到用户级 .npmrc 文件：

   registry=https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE
   //package-firewall.githubapp.com/npm/enterprises/ENTERPRISE/:_authToken=${GITHUB_TOKEN}
   

或者，从命令行配置相同的设置：

npm config set registry \
  https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE
npm config set \
  '//package-firewall.githubapp.com/npm/enterprises/ENTERPRISE/:_authToken=${GITHUB_TOKEN}'

配置 Artifactory

可以将 JFrog Artifactory 配置为通过防火墙检索包。 端点继续使用 Artifactory，这让您可以在将防火墙策略应用于通过防火墙检索的软件包时结合公共和私有软件包。

您必须在 Artifactory 实例中拥有管理员权限。

1. 在 Artifactory 中，单击“ 管理 ”选项卡，然后单击“ 创建存储库”。
2. 选择 Remote 作为存储库类型，然后选择 npm 作为包类型。
3. 在“存储库密钥”字段中，键入一个名称，例如 gh-package-firewall。
4. 在“URL”字段中，键入 https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE，将 ENTERPRISE 替换为您的企业标识符。
5. 在“密码/访问令牌”字段中，粘贴有效的personal access token，然后选择“启用令牌身份验证”。
6. 根据 Artifactory 配置，选择要在其中使用防火墙的阶段。
7. 在“模式”字段中，键入 **/* 以包括所有包路径。
8. 单击“ 保存”。
9. 创建或更新虚拟 npm 存储库，以包含此远程存储库和专用 npm 存储库。 排除直接从公共 npm 注册表提取包的远程源，以便它们无法绕过防火墙。
10. 按照虚拟存储库的 “帮我设置” 说明配置终结点。

细粒度权限

默认情况下，企业管理员和企业安全管理器可以修改防火墙策略。 若要授予其他用户查看和更改策略的权限，请将“编辑企业级包防火墙策略”细粒度权限添加到自定义角色，然后将该角色分配给团队或个人。

管理异常

如果防火墙阻止了所需的软件包，可以申请策略例外。 例如，包含安全修补程序的新包版本可能会被最低包期限策略阻止。

请求例外

当防火墙阻止包时，npm 输出或 CI/CD 日志包含用于申请例外的 URL。 例如：

npm notice testcontainers: 1 version blocked by package-firewall due to security policies (version cooldown). Request an override: https://github.com/enterprises/octocats/security/bypass-requests/package-firewall/new?ecosystem=npm&package=testcontainers

1. 在浏览器中打开 URL。

2. 查看预填充的字段并提供任何缺失的信息：

   • “存储库”：发生阻止的存储库
   • “生态系统”：包生态系统（目前仅支持 npm）
   • “包名称”：包名称，包括 @scope 前缀（如果适用）
   • “版本”：您尝试安装的版本
   • “原因”：为何应解除阻止程序包
   • “添加评论”：供审阅者参考的附加背景信息

3. 提交请求。

查看和批准异常请求

企业管理员和企业安全经理可以查看异常请求。

1. 导航到您的企业。 例如，从 GitHub.com 上的 公司 页面。
2. 在页面顶部，单击 Security and quality。
3. 在边栏中，单击“Package firewall bypass”。
4. 在“软件包防火墙绕过请求”列表中，使用搜索栏查找请求，然后单击该请求。
5. 在“审阅包允许覆盖”对话框中，查看请求的异常。
6. （可选）若要允许包的所有版本，请将“要允许的版本或范围”字段中请求的版本替换为 *。 这扩大了该例外的适用范围，超出了所请求的版本。
7. 添加一条评论，说明您作出此决定的原因，然后单击“批准请求”。

例如，你可能允许企业拥有的软件包的所有版本，而不是在最小软件包期限策略阻止新版本时每次都需要单独设置例外。

管理审批

已批准的绕过请求已添加到防火墙策略。 企业管理员和企业安全经理可以查看和删除过时或不需要的异常，包括手动添加的异常。

1. 导航到您的企业。 例如，从 GitHub.com 上的 公司 页面。
2. 在页面顶部，单击“ 策略”。
3. 在边栏中，单击 Package firewall。
4. 在“覆盖项”下，单击“包覆盖项”。
5. 若要从策略中删除异常，请在该异常旁边单击 。

延伸阅读

• 在企业中创建自定义角色
• 向企业中的人员分配角色
• 在 GitHub Advisory Database 中浏览安全公告