Cómo verificar que un artefacto de GitHub Actions fue construido por ti, no por un atacante

Los ataques a la cadena de suministro han dejado de ser teoría para convertirse en una dura realidad. Supongamos que un usuario descarga un binario precompilado desde la sección de Releases en GitHub. ¿Cómo puede verificar que el archivo fue realmente construido por el servidor de CI a partir del código fuente de un commit específico, y no subido por un hacker que obtuvo acceso a la cuenta del desarrollador?

Para resolver este problema, GitHub lanzó una acción especial actions/attest-build-provenance. Veamos cómo funciona, por qué se necesitan las firmas de Sigstore y por qué necesitarás una herramienta ligeramente diferente al crear nuevos pipelines.

Dónde vincular la firma

La esencia de la firma de procedencia es bastante simple. Cada archivo terminado necesita un pasaporte digital. Este documento confirma: el artefacto con un hash específico fue construido dentro de un workflow específico, en un repositorio específico y en un commit específico.

La herramienta genera un manifiesto según el estándar in-toto y la especificación SLSA (Supply-chain Levels for Software Artifacts). Luego ocurre la parte más interesante: firmar este manifiesto.

En lugar de obligar a los desarrolladores a generar claves PGP de larga duración y almacenarlas en secretos del repositorio, se utiliza la arquitectura de Sigstore. La acción solicita un token OIDC temporal de GitHub Actions y lo intercambia por un certificado de firma de corta duración.

Para repositorios públicos, la firma se genera a través del servicio público de Sigstore, y los datos sobre ella terminan en el registro transparente de Rekor. Si el repositorio es privado, GitHub utiliza su propia instancia privada de Sigstore (esta característica está disponible en el plan Enterprise Cloud).

Una pequeña sorpresa en la documentación

Si abres el repositorio oficial del proyecto, verás una nota importante justo al principio del README.

A partir de la versión cuatro, actions/attest-build-provenance se convirtió en un simple wrapper sobre la acción base actions/attest. Los desarrolladores de GitHub establecen claramente: si estás manteniendo pipelines antiguas, puedes dejar todo como está. Pero para proyectos nuevos, deberías comenzar directamente con actions/attest.

¿Por qué GitHub añadió una capa extra? Inicialmente, el equipo estaba construyendo una herramienta estrechamente especializada solo para la procedencia de compilación. Después, surgió el deseo de firmar no solo binarios sino también SBOMs (listas de dependencias) o resultados de escaneos de vulnerabilidades. Así es como apareció el actions/attest más universal, y la acción anterior se retiró como sinónimo.

Cómo se veía la configuración

En versiones anteriores de la acción, la lógica en .github/workflows/build.yml se comprimía en un par de líneas después del paso de compilación del artefacto.

Lo importante aquí son los permisos id-token: write y 8. Sin la primera opción, el workflow no podrá obtener un token OIDC para la firma sin contraseña a través de Sigstore, y sin la segunda, no subirá el resultado a la API de Attestations de GitHub.

Cómo verificar la autenticidad del artefacto

Una vez que la atestación se crea y vincula al repositorio, cualquier usuario o script de verificación puede revisar el archivo localmente. Para esto se utiliza la utilidad oficial de GitHub CLI.

El comando de verificación se ve así:

gh attestation verify app.sh --owner my-organization

Si el archivo no ha cambiado y fue construido en la organización especificada, la CLI mostrará información sobre el commit y el certificado de firma. Sin embargo, si el archivo ha sido modificado incluso mínimamente, la verificación fallará con un error.

¿Vale la pena implementarlo?

Si estás desarrollando una biblioteca de código abierto o una herramienta CLI, generar atestationes les da a los usuarios una forma fácil de verificar la seguridad de tus releases.

Por otro lado, si tienes un proyecto interno pequeño sin requisitos estrictos de seguridad en la cadena de suministro, agregar pasos extra a tu CI puede ser innecesario.

Para nuevos workflows, usa actions/attest directamente en lugar de 10. La funcionalidad principal seguirá siendo la misma, pero estarás usando una herramienta actualizada sin wrappers obsoletos.