Используйте расширение Gemini CLI Security Extension для проверки запросов на слияние в GitHub.

1. Введение

Расширение Gemini CLI Security Extension — это разработанное Google расширение с открытым исходным кодом для Gemini CLI, которое анализирует код на предмет угроз безопасности и уязвимостей. Вы можете использовать расширение Security с Gemini CLI для выявления проблем безопасности локально, как и с любым другим расширением Gemini CLI. Вы также можете использовать его для просмотра запросов на слияние (Pull Requests) на GitHub. В этом практическом занятии мы рассмотрим, как использовать расширение Security в вашем репозитории GitHub.

Что вы будете делать

• Настройка безопасной аутентификации из GitHub в Google Cloud.
• Создайте рабочий процесс GitHub Actions, который вызывает расширение безопасности Gemini CLI.
• Проведите проверку безопасности нового или существующего запроса на слияние с помощью GitHub Actions.

Что вы узнаете

• Как использовать федерацию идентификации рабочих нагрузок для безопасной аутентификации из GitHub Actions в Google Cloud.
• Узнайте о преимуществах использования пула идентификационных данных рабочей нагрузки и поставщика идентификационных данных рабочей нагрузки вместо ключа API Gemini для аутентификации.
• Как провести проверку безопасности с помощью запросов на слияние (PR)
• Как интерпретировать результаты проверок безопасности, полученные с помощью расширения «Безопасность»

Что вам понадобится

• веб-браузер
• Аккаунт и репозиторий на GitHub
• Проект Google Cloud

Этот практический урок предназначен для разработчиков, знакомых с рабочим процессом CI/CD на GitHub. От вас не требуется знакомства с Gemini CLI или расширениями Gemini CLI. Если вы хотите узнать, как работают расширения, ознакомьтесь с практическим уроком: Начало работы с расширениями Gemini CLI .

В этом практическом занятии вы узнаете, как настроить расширение безопасности Gemini CLI в вашем репозитории GitHub. Мы не будем предлагать вам код для создания запроса на слияние (PR) в вашем репозитории с целью обнаружения уязвимости безопасности.

2. Прежде чем начать

Для использования кредитов Google Cloud: Чтобы начать работу, активируйте свои бесплатные кредиты Google Cloud. Следуйте инструкциям , чтобы активировать кредиты и создать новый проект.

Создать или выбрать проект

1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить выставление счетов .
3. Откройте Cloud Shell — среду командной строки, работающую в Google Cloud. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud.

4. После подключения к Cloud Shell убедитесь, что вы авторизованы и проект настроен на ваш идентификатор проекта, используя следующую команду:

gcloud auth list

5. Выполните следующую команду, чтобы убедиться, что команда gcloud настроена для использования вашего проекта.

gcloud config list project

6. Если ваш проект не задан, используйте следующую команду для его настройки:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

3. Настройте аутентификацию из GitHub в Google Cloud.

Как это работает

Workload Identity Federation — это рекомендуемый способ аутентификации из GitHub Actions в Google Cloud.

1. Для каждого запускаемого задания в GitHub Actions, GitHub, выступая в качестве внешнего поставщика идентификации, выдает подписанный JWT (JSON Web Token). Этот токен содержит «утверждения», такие как repository , workflow и job_workflow_ref , которые действуют как цифровая идентификационная карта для конкретного исполнителя. В этой лабораторной работе вы создадите рабочий процесс GitHub Actions с заданием, использующим действие google-github-actions/run-gemini-cli , которое запросит JWT у GitHub и отправит этот токен в службу токенов безопасности (STS) в Google Cloud.
2. В Google Cloud необходимо настроить пул идентификаторов рабочей нагрузки и поставщика , указав в качестве URL-адреса издателя официальный URL-адрес службы токенов GitHub https://token.actions.githubusercontent.com , а также определив «сопоставления атрибутов», которые обычно включают имена репозиториев и веток. Google Cloud STS проверяет JWT на соответствие правилам пула идентификаторов рабочей нагрузки. Если все, включая сопоставления атрибутов, в порядке, STS обменивает токен GitHub на кратковременный федеративный токен доступа Google Cloud .
3. Теперь действие google-github-actions/run-gemini-cli в вашем рабочем процессе GitHub Actions может использовать кратковременный токен федеративного доступа Google Cloud для «имитации» подключенной учетной записи службы в пуле удостоверений рабочей нагрузки. Подключенная учетная запись службы должна обладать необходимыми ролями и разрешениями IAM для доступа к любым ресурсам и службам Google Cloud.

   GitHub использует прямую федерацию идентификации без имитации учетной записи службы. Однако Gemini CLI требует создания токена учетной записи службы, что поддерживается только при имитации учетной записи службы.

Преимущества использования федерации идентификации рабочих нагрузок вместо ключа API Gemini

Аутентификация вызовов Gemini CLI, инициированных из GitHub Actions, возможна с использованием ключа API Gemini. Для этого необходимо создать новый секрет GitHub Actions с именем GEMINI_API_KEY и соответствующим значением ключа. Однако это не рекомендуется по следующим причинам безопасности:

• Ключи API Gemini могут иметь широкие права доступа, определяемые соответствующими ролями IAM. В случае компрометации они открывают доступ к широкому спектру ресурсов и сервисов Google Cloud. Федерация идентификации рабочих нагрузок использует учетные записи служб и кратковременные токены доступа, что значительно повышает уровень аутентификации.
• Управление ключами API Gemini в масштабе предприятия также представляет собой сложную задачу. Определение того, какие рабочие процессы используют открытый ключ, занимает время. Ручная смена ключей также требует времени. С другой стороны, вы можете легко находить, редактировать и удалять пулы и провайдеры удостоверений рабочих нагрузок, связанные с вашим репозиторием, из облачной консоли.
• При использовании ключей API Gemini необходимо всегда дважды проверять, не раскрываете ли вы их случайно в журналах доступа или отладки. В случае с Workload Identity Federation вы храните не секреты рабочих процессов GitHub Actions, а переменные, которые по своей природе менее конфиденциальны.

Настройка GitHub Actions и Google Cloud

1. В Cloud Shell войдите в свою учетную запись GitHub.

gh auth login

2. Создайте новый файл setup_workload_identity.sh и скопируйте в него скрипт настройки из репозитория google-github-actions/run-gemini-cli .
3. Превратите скрипт в исполняемый файл.

chmod +x setup_workload_identity.sh

4. Запустите скрипт.

./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}

4. Создайте рабочий процесс GitHub Actions.

1. Проверьте репозиторий GitHub, который принадлежит вам.

git clone {YOUR_REPO}
cd {YOUR REPO}

2. Создайте рабочий процесс GitHub Actions, который вызывает команду /security:analyze-github-pr , скопировав пример скрипта yml из репозитория /gemini-cli-extensions/security .

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

3. Отправьте рабочий процесс 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 или оставьте комментарий "@gemini-cli /review" от имени владельца или участника репозитория. Это запустит проверку безопасности запроса на слияние. Расширение безопасности Gemini CLI из рабочего процесса GitHub Actions, которое вы добавили в свой репозиторий, пометит все обнаруженные проблемы безопасности категориями серьезности от "Критическая", "Высокая", "Средняя" до "Низкая".

Вот пример проверки безопасности нового запроса на слияние и пример проверки безопасности существующего запроса на слияние.

6. Дальнейшие исследования

Мы рекомендуем вам ознакомиться с постоянно пополняющимся списком пользовательских команд с новыми возможностями безопасности в расширении Gemini CLI Security и начать использовать его в своих рабочих процессах. Например:

• /security:scan-deps сопоставляет зависимости вашего проекта с OSV.dev .

Ознакомьтесь также с примечаниями к выпуску , чтобы узнать о последних функциях и исправлениях ошибок.

7. Поздравляем!

Поздравляем, вы успешно настроили свой репозиторий GitHub для использования расширения Gemini CLI Security Extension для анализа запросов на слияние (PR) на предмет угроз безопасности и уязвимостей.