Automatiza la integridad de archivos con sha512sum en CI/CD
Usa sha512sum --check --strict checksums.sha512 para comparar archivos con un manifiesto aprobado de sumas de
verificación antes de que tu pipeline los utilice. El comando devuelve un estado de salida distinto
de cero cuando falla la verificación, por lo que un artefacto modificado o ausente puede detener la
tarea. Lo importante es decidir de dónde provienen las sumas de verificación esperadas.
Elige una referencia de confianza
Una suma de verificación SHA-512 describe los bytes de un archivo. Que coincida no te indica, por sí solo, quién creó esos bytes. Si alguien puede sustituir tanto un archivo como su suma de verificación esperada, la verificación puede seguir siendo satisfactoria.
Para tus propios recursos fijos, genera un manifiesto a partir de archivos aprobados y revisa los cambios en ese manifiesto. Para una descarga, obtén la suma de verificación esperada a través de un canal autenticado del publicador; cuando haya sumas de verificación firmadas, sigue primero sus instrucciones de verificación de firmas. La guía de verificación de imágenes de Debian muestra esta distinción entre comprobar los bytes descargados y autenticar su origen.
El siguiente ejemplo registra dos archivos pequeños como referencia y luego reutiliza esa referencia en CI. Generar nuevas sumas de verificación a partir de cualquier contenido que reciba CI anularía el propósito de la comparación.
Flujo de trabajo de verificación de archivos
Usa Bash y GNU coreutils. Estos ejemplos se probaron con Bash 5.1 y coreutils 8.32 en Ubuntu 22.04, y con Bash 5.3 y coreutils 9.12 en macOS. Comprueba la implementación antes de continuar:
sha512sum --version
La primera línea debería identificar GNU coreutils. Un comando con el mismo nombre
puede ser una implementación diferente. En macOS, el
paquete coreutils de Homebrew proporciona herramientas GNU; sigue sus
instrucciones de PATH para gnubin para usar sus nombres sin prefijos.
Ejecuta cada bloque de Bash que aparece a continuación desde el mismo directorio padre. Los
paréntesis mantienen los cambios de directorio dentro de un subshell. Esta preparación crea un nuevo
directorio sha512-demo y rechaza reutilizar uno existente, por lo que volver a
ejecutarla no sobrescribirá tus archivos:
(
set -eC
mkdir sha512-demo
cd sha512-demo
mkdir assets
printf 'release 1\n' > assets/app.txt
printf '{"mode":"production"}\n' > assets/config.json
)
Aquí, set -e detiene el subshell si se produce un fallo, y
-C impide que la redirección de salida sobrescriba un archivo regular
existente. Si falla la preparación, resuelve el error antes de pasar al siguiente bloque; elige otro
directorio padre si necesitas otra demostración.
Genera hashes
Crea el manifiesto una sola vez, mientras ambos archivos contienen los bytes aprobados:
(
set -eC
cd sha512-demo
sha512sum -- assets/app.txt assets/config.json > checksums.sha512
)
Cada línea contiene un resumen SHA-512 hexadecimal de 128 dígitos, un indicador de modo y un nombre de archivo. La lista explícita de archivos hace que una entrada ausente sea un error e impide que el manifiesto calcule su propio hash. Para tus propios archivos, sustituye esa lista y pon entre comillas los nombres de archivo que contengan espacios.
Este comando también rechaza sobrescribir un checksums.sha512 existente. Si falla la
generación, no uses el manifiesto recién creado: puede estar vacío o incompleto. Conserva el
manifiesto aprobado anterior al preparar una actualización intencional y revisa el que lo sustituirá
antes de adoptarlo.
Verifica los archivos
Realiza la comprobación desde el directorio usado para crear los nombres de archivo relativos:
(
cd sha512-demo &&
sha512sum --check --strict checksums.sha512
)
Con los archivos originales, la salida es:
assets/app.txt: OK
assets/config.json: OK
--check lee el manifiesto y compara cada archivo indicado.
--strict también hace que las líneas de sumas de verificación mal formadas
provoquen un fallo, incluso cuando otras entradas coinciden. Un manifiesto vacío también falla. No
añadas --ignore-missing cuando se requieran todos los artefactos enumerados. Estas
opciones se documentan en el
manual de GNU sha512sum incluido en el paquete de Debian.
Para probar el caso de fallo, edita sha512-demo/assets/app.txt y vuelve a ejecutar el bloque de
verificación. Este informa de assets/app.txt: FAILED y termina con un estado distinto de cero.
Restaura los bytes originales aprobados antes de usar los siguientes ejemplos de CI satisfactorios;
deja el manifiesto sin cambios.
Gestión de errores y problemas comunes
Problemas de permisos
El verificador necesita acceso de lectura al manifiesto y a los archivos, además de acceso a través de sus directorios padre. Revisa los permisos y pide al propietario el acceso adecuado si es necesario. No cambies la propiedad de forma generalizada ni hagas públicos archivos sensibles para lograr que una comprobación sea satisfactoria.
Resolución de discrepancias de hash
Una discrepancia significa que los bytes difieren de la referencia. Una descarga truncada, cambios en los finales de línea o una edición intencional pueden causarla. Obtén una nueva copia de confianza o investiga el cambio; regenerar la suma de verificación esperada lo ocultaría.
Un error de archivo ausente también puede significar que ejecutaste el comando desde el directorio equivocado. Las rutas relativas del manifiesto se resuelven desde el directorio de trabajo del proceso, no desde la ubicación del manifiesto. Si hay líneas mal formadas, recupera el manifiesto original en lugar de copiar una tabla de sumas de verificación con formato desde una página web. Conserva tanto la salida estándar como la salida de error estándar en los registros de CI para poder ver la causa.
Integración con CI/CD
Para este ejemplo de recursos fijos, añade sha512-demo/assets/ y el
sha512-demo/checksums.sha512 aprobado a tu repositorio. Los dos flujos de trabajo siguientes verifican
esos archivos obtenidos del repositorio sin regenerar el manifiesto. Revisa los cambios del
manifiesto: una solicitud de incorporación de cambios que modifique tanto los recursos como sus
hashes esperados puede superar esta comprobación.
Coloca la verificación antes del paso que utiliza los archivos y haz que el despliegue dependa de que sea satisfactoria. Si tus artefactos llegan de otra tarea, recupéralos antes de verificarlos y mantén el manifiesto aprobado separado de la salida generada por esa tarea.
Ejemplo de GitHub Actions
Añade lo siguiente como .github/workflows/integrity.yml o integra el paso de verificación en un flujo de
trabajo existente. Usa actions/checkout para obtener el repositorio:
name: Verify file integrity
on: [push, pull_request]
permissions:
contents: read
jobs:
verify:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v7
- name: Verify approved assets
working-directory: sha512-demo
shell: bash
run: sha512sum --check --strict checksums.sha512
El shell bash especificado explícitamente en GitHub propaga al paso el fallo
de un comando; consulta su
documentación sobre los shells de los flujos de trabajo.
Mantén deshabilitada la supresión de fallos para este paso.
Ejemplo de GitLab CI
Para un runner de GitLab con un ejecutor Docker, integra esta tarea en
.gitlab-ci.yml:
verify_integrity:
image: ubuntu:22.04
script:
- cd sha512-demo
- sha512sum --check --strict checksums.sha512
La imagen de Ubuntu proporciona GNU coreutils. GitLab
hace fallar la tarea cuando un comando del script termina con un estado distinto de cero,
lo que incluye un cambio de directorio fallido. Mantén los comandos como entradas separadas del
script y no habilites allow_failure para este control.
Detecta cambios después de una compilación de Docker
Para comprobar artefactos copiados desde una imagen, verifica esos archivos exportados con el manifiesto aprobado antes de distribuirlos. Un manifiesto generado durante la compilación puede detectar cambios posteriores en los bytes solo mientras ese manifiesto siga siendo de confianza. No puede establecer la autenticidad de las entradas de la compilación ni proteger contra alguien que sustituya tanto los archivos como el manifiesto.
Conoce el alcance de una comprobación satisfactoria
La verificación lee todos los archivos enumerados, por lo que los artefactos grandes requieren leer todos sus bytes de nuevo. No comprueba los archivos que no figuran en la lista ni la propiedad, los permisos o las marcas de tiempo de los archivos. Un resultado satisfactorio significa que los bytes enumerados coinciden con la referencia; no demuestra que el directorio contenga únicamente archivos aprobados ni que la compilación sea reproducible.