使用 Gemini CLI 安全扩展程序进行 GitHub 拉取请求审核

1. 简介

Gemini CLI Security Extension 是 Google 构建的开源 Gemini CLI 扩展程序，用于分析代码中的安全风险和漏洞。您可以将 Security 扩展程序与 Gemini CLI 搭配使用，以在本地识别安全问题，就像使用任何其他 Gemini CLI 扩展程序一样。您还可以调用它来审核 GitHub 上的拉取请求。在此 Codelab 中，我们将介绍如何在 GitHub 代码库中使用 Security 扩展程序。

实践内容

  • 配置从 GitHub 到 Google Cloud 的安全身份验证
  • 创建调用 Gemini CLI Security Extension 的 GitHub Actions 工作流
  • 使用 GitHub Actions 对新的或现有的 PR 运行安全审核

学习内容

  • 如何使用工作负载身份联合功能通过 GitHub Actions 安全地向 Google Cloud 进行身份验证
  • 了解使用工作负载身份池和工作负载身份提供方而非 Gemini API 密钥进行身份验证的优势
  • 如何使用 PR 运行安全审核
  • 如何解读 Security 扩展程序返回的安全审核结果

所需条件

  • 网络浏览器
  • GitHub 账号和代码库
  • Google Cloud 项目

此 Codelab 专为熟悉 GitHub 上的 CI/CD 工作流的开发者而设计。您无需熟悉 Gemini CLI 或 Gemini CLI 扩展程序。如果您想了解扩展程序的工作原理，请查看 Codelab：Gemini CLI 扩展程序使用入门。

在此 Codelab 中，您将学习如何在 GitHub 代码库中设置 Gemini CLI Security Extension。我们不会建议您打开针对代码库的 PR 以触发安全漏洞发现结果。

2. 准备工作

创建或选择项目

  1. 在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。
  2. 确保您的云项目已启用结算功能。了解如何验证结算功能。
  3. 打开 Cloud Shell，它是在 Google Cloud 中运行的命令行环境。点击 Google Cloud 控制台顶部的激活 Cloud Shell 。

“激活 Cloud Shell”按钮图片

  1. 连接到 Cloud Shell 后，请使用以下命令检查您是否已通过身份验证，以及项目是否已设置为您的项目 ID：
gcloud auth list
  1. 运行以下命令，确认 gcloud 命令已配置为使用您的项目。
gcloud config list project
  1. 如果项目未设置，请使用以下命令进行设置：
gcloud config set project ${GOOGLE_CLOUD_PROJECT}

3. 设置从 GitHub 到 Google Cloud 的身份验证

运作方式

GitHub Actions 工作流

工作负载身份联合功能是建议的通过 GitHub Actions 向 Google Cloud 进行身份验证的方式。

  1. 对于每个 GitHub Actions 工作流 运行 作业，GitHub 作为外部身份提供方 会颁发已签名的 JWT（JSON Web 令牌）。此令牌包含 repository、workflow 和 job_workflow_ref 等“声明”，这些声明充当该特定跑步者的数字身份卡。在此实验中，您将创建一个 GitHub Actions 工作流，其中包含一个使用 google-github-actions/run-gemini-cli 操作的作业，该作业将从 GitHub 请求 JWT 并将此令牌发送到 Google Cloud 中的安全令牌服务 (STS) 。
  2. 您将在 Google Cloud 中配置工作负载身份池 和提供方 ，方法是将颁发者网址设置为官方 GitHub 令牌服务网址 https://token.actions.githubusercontent.com，并定义您的“属性映射”，这些映射通常包括代码库和分支名称。Google Cloud STS 会根据工作负载身份池规则验证 JWT。如果所有内容（包括属性映射）都通过检查，则 STS 会将 GitHub 令牌交换为短期有效的 Google Cloud 联合访问令牌 。
  3. 现在，GitHub Actions 工作流中的 google-github-actions/run-gemini-cli 操作可以使用短期有效的 Google Cloud 联合访问令牌 来“模拟”连接到工作负载身份池的 服务账号 。连接的服务账号需要具有必要的 IAM 角色和权限，才能访问任何 Google Cloud 资源和服务。

使用工作负载身份联合而非 Gemini API 密钥的优势

可以使用 Gemini API 密钥对源自 GitHub Actions 的 Gemini CLI 调用进行身份验证，这需要创建一个名为 GEMINI_API_KEY 的新 GitHub Actions 密钥，并使用适当的密钥值。但是，出于以下安全原因，我们不建议这样做：

  • Gemini API 密钥可以从其各自的 IAM 角色绑定中获得广泛的权限。如果遭到入侵，它们会开放对各种 Google Cloud 资源和服务的访问权限。工作负载身份联合功能使用服务账号和短期有效的访问令牌，这会显著加强身份验证。
  • Gemini API 密钥也很难大规模管理。识别哪些工作流正在使用公开的密钥需要时间。手动轮替密钥也需要时间。另一方面，您可以轻松地从 Cloud 控制台中查找、修改和删除与您的代码库关联的工作负载身份池和提供方。
  • 使用 Gemini API 密钥时，您必须始终仔细检查，确保不会在任何访问或调试日志中意外公开它们。使用工作负载身份联合功能时，您不会存储任何 GitHub Actions 工作流密钥，而是存储变量，这些变量的敏感性本来就较低。

配置 GitHub Actions 和 Google Cloud

  1. 在 Cloud Shell 中，登录您的 GitHub 账号。
gh auth login
  1. 创建一个新文件 setup_workload_identity.sh，然后从 google-github-actions/run-gemini-cli 代码库复制并粘贴设置 脚本。
  2. 将脚本设为可执行文件。
chmod +x setup_workload_identity.sh
  1. 运行脚本。
./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}

4. 创建 GitHub Actions 工作流

  1. 检出您拥有的 GitHub 代码库。
git clone {YOUR_REPO}
cd {YOUR REPO}
  1. 创建一个调用斜杠命令 /security:analyze-github-pr 的 GitHub Actions 工作流，方法是从 /gemini-cli-extensions/security 仓库复制示例工作流 yml 脚本。
git checkout -b workflow
mkdir .github/ && cd .github/
mkdir workflows/ && cd workflows/
curl -L https://raw.githubusercontent.com/gemini-cli-extensions/security/refs/heads/main/.github/workflows/gemini-review.yml -o gemini-review.yml
  1. 将 GitHub Actions 工作流推送到 GitHub 上的远程来源。
git add .github/workflows/gemini-review.yml
git commit -m "add new gha workflow"
git push --set-upstream origin workflow

5. 对新的和现有的 PR 运行安全分析工作流

在 GitHub 代码库中启动新的 PR，或以代码库所有者或贡献者的身份发布新评论 "@gemini-cli /review" 。这将开始对 PR 进行安全审核。您已提交到代码库的 GitHub Actions 工作流中的 Gemini CLI Security Extension 会根据严重程度类别（从“严重”“高”“中”到“低”）标记其发现的任何安全问题。

以下是针对新 PR 的 安全审核示例，以及针对现有 PR 的 安全审核示例。

6. 深入探索

我们建议您探索 Gemini CLI Security Extension 中不断增加的自定义命令列表，这些命令具有新的安全功能，并开始在工作流中使用它们。例如：

  • /security:scan-deps 将项目的依赖项与 OSV.dev 进行交叉引用。

另请查看版本说明，了解最新功能和 bug 修复。

7. 恭喜

恭喜！您已成功配置 GitHub 代码库，以使用 Gemini CLI Security Extension 分析 PR 中的安全风险和漏洞。