1. Introducción
La extensión de seguridad de Gemini CLI es una extensión de código abierto de Gemini CLI creada por Google que analiza el código en busca de riesgos y vulnerabilidades de seguridad. Puedes usar la extensión de seguridad con Gemini CLI para identificar problemas de seguridad de forma local, al igual que con cualquier otra extensión de Gemini CLI. También puedes invocarlo para revisar solicitudes de extracción en GitHub. En este codelab, veremos cómo usar la extensión de seguridad en tu repositorio de GitHub.
Actividades
- Configura la autenticación segura de GitHub a Google Cloud
- Crea un flujo de trabajo de GitHub Actions que llame a la extensión de seguridad de Gemini CLI
- Ejecuta una revisión de seguridad en una solicitud de extracción nueva o existente con las acciones de GitHub
Qué aprenderás
- Cómo usar la federación de identidades para cargas de trabajo para la autenticación segura de acciones de GitHub en Google Cloud
- Conoce los beneficios de usar un grupo de identidades para cargas de trabajo y un proveedor de identidades para cargas de trabajo en lugar de una clave de API de Gemini para la autenticación
- Cómo ejecutar una revisión de seguridad con solicitudes de extracción
- Cómo interpretar las revisiones de seguridad que devuelve la extensión de Seguridad
Requisitos
- Un navegador web
- Una cuenta y un repositorio de GitHub
- Un proyecto de Google Cloud
Este codelab está diseñado para desarrolladores que conocen el flujo de trabajo de CI/CD en GitHub. No es necesario que tengas experiencia con Gemini CLI ni con sus extensiones. Si quieres saber cómo funcionan las extensiones, consulta el codelab Comienza a usar las extensiones de Gemini CLI.
En este codelab, aprenderás a configurar la extensión de seguridad de Gemini CLI en tu repositorio de GitHub. No te sugeriremos código para que abras una PR en tu repositorio y se active la detección de una vulnerabilidad de seguridad.
2. Antes de comenzar
Crea o selecciona un proyecto
- En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
- Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén más información para verificar la facturación.
- Abre Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
- Una vez que te conectes a Cloud Shell, verifica que te autenticaste y que el proyecto se configuró con tu ID del proyecto con el siguiente comando:
gcloud auth list
- Ejecuta el siguiente comando para confirmar que el comando
gcloudesté configurado para usar tu proyecto.
gcloud config list project
- Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:
gcloud config set project ${GOOGLE_CLOUD_PROJECT}
3. Configura la autenticación de GitHub en Google Cloud
Cómo funciona
La federación de identidades para cargas de trabajo es la forma recomendada de autenticarse desde GitHub Actions en Google Cloud.
- Para cada ejecución de flujo de trabajo trabajo de GitHub Actions, GitHub como proveedor de identidad externo emite un JWT (token web JSON) firmado. Este token contiene "reclamaciones", como
repository,workflowyjob_workflow_ref, que actúan como un documento de identidad digital para ese corredor específico. En este lab, crearás un flujo de trabajo de GitHub Actions con un trabajo que usa la accióngoogle-github-actions/run-gemini-cli, que solicitará un JWT a GitHub y enviará este token al Servicio de token de seguridad (STS) en Google Cloud. - Configurarás un grupo de Workload Identity y un proveedor en Google Cloud. Para ello, establecerás la URL del emisor en la URL oficial del servicio de tokens de GitHub
https://token.actions.githubusercontent.comy definirás tus "Asignaciones de atributos", que suelen incluir nombres de repositorios y ramas. El STS de Google Cloud valida el JWT según las reglas del grupo de identidades para cargas de trabajo. Si todo, incluidas las asignaciones de atributos, se verifica correctamente, el STS intercambia el token de GitHub por un token de acceso federado de Google Cloud de corta duración. - Ahora, la acción
google-github-actions/run-gemini-clien tu flujo de trabajo de GitHub Actions puede usar el token de acceso federado de Google Cloud de corta duración para "suplantar" una cuenta de servicio conectada al grupo de identidades para cargas de trabajo. La cuenta de servicio conectada debe tener los roles y permisos de IAM necesarios para acceder a cualquier recurso y servicio de Google Cloud.
Beneficios de usar la federación de identidades para cargas de trabajo en lugar de la clave de la API de Gemini
Es posible autenticar las llamadas a Gemini CLI que se originan en GitHub Actions con una clave de la API de Gemini, lo que implica crear un nuevo secreto de GitHub Actions llamado GEMINI_API_KEY con el valor de clave adecuado. Sin embargo, no se recomienda por los siguientes motivos de seguridad:
- Las claves de la API de Gemini pueden tener permisos amplios a partir de sus respectivas vinculaciones de roles de IAM. Cuando se vulneran, abren el acceso a una amplia variedad de recursos y servicios de Google Cloud. La federación de identidades para cargas de trabajo usa cuentas de servicio y tokens de acceso de corta duración, lo que refuerza significativamente la autenticación.
- Además, las claves de la API de Gemini son difíciles de administrar a gran escala. Identificar qué flujos de trabajo usan una clave expuesta lleva tiempo. Rotar las llaves de forma manual también lleva tiempo. Por otro lado, puedes buscar, editar y borrar fácilmente los grupos y proveedores de Workload Identity asociados con tu repositorio desde la consola de Cloud.
- Con las claves de la API de Gemini, siempre debes verificar que no las expongas accidentalmente en ningún registro de acceso o de depuración. Con la federación de Workload Identity, no almacenas ningún secreto de flujos de trabajo de GitHub Actions, sino variables, que son inherentemente menos sensibles.
Configura GitHub Actions y Google Cloud
- En Cloud Shell, accede a tu cuenta de GitHub.
gh auth login
- Crea un archivo
setup_workload_identity.shnuevo y copia y pega el script de configuración del repositoriogoogle-github-actions/run-gemini-cli. - Haz que la secuencia de comandos sea ejecutable.
chmod +x setup_workload_identity.sh
- Ejecuta la secuencia de comandos.
./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}
4. Crea un flujo de trabajo de GitHub Actions
- Extrae un repositorio de GitHub de tu propiedad.
git clone {YOUR_REPO}
cd {YOUR REPO}
- Crea un flujo de trabajo de GitHub Actions que llame al comando de barra
/security:analyze-github-prcopiando un ejemplo de secuencia de comandos de flujo de trabajoymldel repo/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
- Envía el flujo de trabajo de GitHub Actions a tu origen remoto en GitHub.
git add .github/workflows/gemini-review.yml
git commit -m "add new gha workflow"
git push --set-upstream origin workflow
5. Ejecuta el flujo de trabajo de análisis de seguridad en las PR nuevas y existentes
Inicia una nueva solicitud de extracción en tu repositorio de GitHub o publica un comentario nuevo "@gemini-cli /review" como propietario o colaborador del repositorio. Esto iniciará una revisión de seguridad en la PR. La extensión de seguridad de Gemini CLI del flujo de trabajo de GitHub Actions que confirmaste en tu repo etiquetará cualquier problema de seguridad que encuentre por categorías de gravedad, desde "Crítico", "Alto", "Medio" hasta "Bajo".
Aquí se muestra un ejemplo de una revisión de seguridad en una nueva PR y un ejemplo de una revisión de seguridad en una PR existente.
6. Exploración adicional
Te recomendamos que explores una lista cada vez mayor de comandos personalizados con nuevas capacidades de seguridad en la extensión de seguridad de Gemini CLI y que comiences a usarlos en tus flujos de trabajo. Por ejemplo:
/security:scan-depshace referencias cruzadas de las dependencias de tu proyecto con OSV.dev.
Consulta las notas de la versión para conocer las funciones y correcciones de errores más recientes.
7. Felicitaciones
¡Felicitaciones! Configuraste correctamente tu repositorio de GitHub para usar la extensión de seguridad de Gemini CLI y analizar las PR en busca de riesgos y vulnerabilidades de seguridad.