1. Introdução
A extensão de segurança da CLI do Gemini é uma extensão de código aberto criada pelo Google que analisa o código em busca de riscos e vulnerabilidades de segurança. É possível usar a extensão de segurança com a CLI do Gemini para identificar problemas de segurança localmente, assim como faria com qualquer outra extensão da CLI do Gemini. Também é possível invocá-la para revisar solicitações de envio no GitHub. Neste codelab, vamos mostrar como usar a extensão de segurança no seu repositório do GitHub.
O que você aprenderá
- Configurar a autenticação segura do GitHub para o Google Cloud
- Criar um fluxo de trabalho do GitHub Actions que chama a extensão de segurança da CLI do Gemini
- Executar uma revisão de segurança em uma solicitação de envio nova ou atual usando o GitHub Actions
O que você aprenderá
- Como usar a federação de identidade da carga de trabalho para autenticação segura do GitHub Actions para o Google Cloud
- Aprender os benefícios de usar um pool de identidade de carga de trabalho e um provedor de identidade de carga de trabalho em vez de uma chave de API Gemini para autenticação
- Como executar uma revisão de segurança com solicitações de envio
- Como interpretar as revisões de segurança retornadas pela extensão de segurança
O que é necessário
- Um navegador da Web
- Uma conta e um repositório do GitHub
- Um projeto na nuvem do Google Cloud
Este codelab foi criado para desenvolvedores familiarizados com o fluxo de trabalho de CI/CD no GitHub. Não é necessário ter familiaridade com a CLI do Gemini ou as extensões dela. Se você quiser aprender como as extensões funcionam, confira o codelab: Como começar a usar as extensões da CLI do Gemini.
Neste codelab, você vai aprender a configurar a extensão de segurança da CLI do Gemini no seu repositório do GitHub. Não vamos sugerir um código para você abrir uma solicitação de envio no seu repositório para acionar uma descoberta de vulnerabilidade de segurança.
2. Antes de começar
Criar ou selecionar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar o faturamento.
- Abra o Cloud Shell, um ambiente de linha de comando em execução no Google Cloud. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
- Depois de se conectar ao Cloud Shell, verifique se você está autenticado e se o projeto está definido como o ID do seu projeto usando o comando a seguir:
gcloud auth list
- Execute o comando a seguir para confirmar se o comando
gcloudestá configurado para usar seu projeto.
gcloud config list project
- Se o projeto não estiver definido, use este comando:
gcloud config set project ${GOOGLE_CLOUD_PROJECT}
3. Configurar a autenticação do GitHub para o Google Cloud
Como funciona
A federação de identidade da carga de trabalho é a maneira recomendada de autenticação do GitHub Actions para o Google Cloud.
- Para cada fluxo de trabalho de execução de job do GitHub Actions, o GitHub como um provedor de identidade externo emite um JWT (JSON Web Token) assinado. Esse token contém "declarações", como
repository,workflow, ejob_workflow_ref, que atuam como um cartão de identidade digital para esse corredor específico. Neste laboratório, você vai criar um fluxo de trabalho do GitHub Actions com um job que usa a açãogoogle-github-actions/run-gemini-cli, que vai solicitar um JWT do GitHub e enviar esse token para o Security Token Service (STS) no Google Cloud. - Você vai configurar um pool de identidade da carga de trabalho e um provedor no Google Cloud definindo o URL do emissor como o URL oficial do serviço de token do GitHub
https://token.actions.githubusercontent.come definindo seus "mapeamentos de atributos", que normalmente incluem nomes de repositórios e ramificações. O STS do Google Cloud valida o JWT nas regras do pool de identidade da carga de trabalho. Se tudo, incluindo os mapeamentos de atributos, for verificado, o STS vai trocar o token do GitHub por um token de acesso federado do Google Cloud de curta duração. - Agora, a ação
google-github-actions/run-gemini-clino fluxo de trabalho do GitHub Actions pode usar o token de acesso federado do Google Cloud de curta duração para "representar" uma conta de serviço conectada ao pool de identidade da carga de trabalho. A conta de serviço conectada precisa ter os papéis e permissões do IAM necessários para acessar recursos e serviços do Google Cloud.
Benefícios de usar a federação de identidade da carga de trabalho em vez da chave da API Gemini
É possível autenticar chamadas da CLI do Gemini originadas do GitHub Actions usando uma chave da API Gemini, que envolve a criação de um novo segredo do GitHub Actions chamado GEMINI_API_KEY com o valor da chave apropriado. No entanto, isso não é recomendado pelos seguintes motivos de segurança:
- As chaves da API Gemini podem ter permissões amplas das respectivas vinculações de papéis do IAM. Quando comprometidas, elas abrem o acesso a uma ampla variedade de recursos e serviços do Google Cloud. A federação de identidade da carga de trabalho usa contas de serviço e tokens de acesso de curta duração, o que aumenta significativamente a autenticação.
- As chaves da API Gemini também são difíceis de gerenciar em escala. Identificar quais fluxos de trabalho estão usando uma chave exposta leva tempo. A rotação manual das chaves também leva tempo. Por outro lado, é possível pesquisar, editar e excluir facilmente pools e provedores de identidade da carga de trabalho associados ao seu repositório no console do Cloud.
- Com as chaves da API Gemini, é necessário verificar sempre se você não as está expondo acidentalmente em registros de acesso ou de depuração. Com a federação de identidade da carga de trabalho, você não armazena nenhum segredo de fluxos de trabalho do GitHub Actions, mas variáveis, que são inerentemente menos sensíveis.
Configurar o GitHub Actions e o Google Cloud
- No Cloud Shell, faça login na sua conta do GitHub.
gh auth login
- Crie um novo arquivo
setup_workload_identity.she copie e cole o script de configuração do repositóriogoogle-github-actions/run-gemini-cli. - Transforme o script em um executável.
chmod +x setup_workload_identity.sh
- Execute o script.
./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}
4. Criar um fluxo de trabalho do GitHub Actions
- Confira um repositório do GitHub que você possui.
git clone {YOUR_REPO}
cd {YOUR REPO}
- Crie um fluxo de trabalho do GitHub Actions que chame o comando de barra
/security:analyze-github-prcopiando um script de fluxo de trabalho de exemploymldo repositório/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
- Envie o fluxo de trabalho do GitHub Actions para sua origem remota no GitHub.
git add .github/workflows/gemini-review.yml
git commit -m "add new gha workflow"
git push --set-upstream origin workflow
5. Executar o fluxo de trabalho de análise de segurança em solicitações de envio novas e atuais
Inicie uma nova solicitação de envio no seu repositório do GitHub ou poste um novo comentário "@gemini-cli /review" como proprietário ou colaborador do repositório. Isso vai iniciar uma revisão de segurança na solicitação de envio. A extensão de segurança da CLI do Gemini do fluxo de trabalho do GitHub Actions que você confirmou no seu repositório vai marcar todos os problemas de segurança encontrados por categorias de gravidade, de "Crítico", "Alto", "Médio" a "Baixo".
Confira um exemplo de revisão de segurança em uma nova solicitação de envio e um exemplo de revisão de segurança em uma solicitação de envio atual.
6. Exploração extra
Recomendamos que você explore uma lista crescente de comandos personalizados com novos recursos de segurança na extensão de segurança da CLI do Gemini e comece a usá-la nos seus fluxos de trabalho. Exemplo:
/security:scan-depsfaz referência cruzada às dependências do seu projeto com OSV.dev.
Confira também as notas da versão para ver os recursos e correções de bugs mais recentes.
7. Parabéns
Parabéns! Você configurou seu repositório do GitHub para usar a extensão de segurança da CLI do Gemini para analisar solicitações de envio em busca de riscos e vulnerabilidades de segurança.