Última actualización: 11 de septiembre

Pipelines de CI/CD seguros con b2sum y la CLI

Tim Koschützki

Cofundador · Berlín, Alemania ·

Garantizar la integridad de los archivos es crucial en el desarrollo de software, sobre todo cuando automatizas los despliegues mediante pipelines de CI/CD. Una herramienta potente para este fin es b2sum, una utilidad de hash basada en el algoritmo BLAKE2. Veamos cómo puedes aprovechar b2sum en tus flujos de trabajo de línea de comandos para mejorar la seguridad y la fiabilidad.

Introducción a b2sum

b2sum es una utilidad de línea de comandos que implementa el algoritmo de hash BLAKE2. Frente a algoritmos de hash tradicionales como MD5 o SHA-1, BLAKE2 ofrece ventajas significativas:

Velocidad: más rápido que MD5, SHA-1, SHA-2 y SHA-3 en plataformas de 64 bits.
Seguridad: ofrece una seguridad similar a la de SHA-3, incluidas la inmunidad frente a ataques de extensión de longitud y la indiferenciabilidad respecto de un oráculo aleatorio.
Versatilidad: admite tanto la variante de 256 bits (BLAKE2s) como la de 512 bits (BLAKE2b).

Variantes de BLAKE2

BLAKE2 se presenta en dos variantes principales, cada una optimizada para casos de uso distintos:

BLAKE2b: optimizada para plataformas de 64 bits, produce valores hash de hasta 512 bits. Es la variante que implementa la utilidad b2sum incluida en GNU coreutils, lo que la hace ideal para entornos de servidor modernos y pipelines de CI/CD.
BLAKE2s: optimizada para plataformas de 32 bits y entornos con recursos limitados, produce valores hash de hasta 256 bits.

Instalación

b2sum viene preinstalado con GNU coreutils en la mayoría de las distribuciones modernas de Linux. Para comprobar si está disponible y ver su versión:

b2sum --version

Si b2sum no está instalado, normalmente puedes instalarlo como parte del paquete coreutils:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install coreutils

CentOS/RHEL:
```
sudo yum install coreutils
```
macOS (con Homebrew):
```
brew install coreutils
```
Nota: en macOS, los comandos de coreutils suelen llevar el prefijo g (por ejemplo, gb2sum) para evitar conflictos con las utilidades nativas de BSD. Es posible que tengas que ajustar tu PATH o usar el comando con prefijo.

Integrar b2sum en pipelines de CI/CD

Integrar b2sum en tu pipeline de CI/CD implica generar hashes de los artefactos de compilación y verificarlos en el momento del despliegue. Este es un enfoque práctico:

Paso 1: generar hashes

Después de compilar tus artefactos (por ejemplo, un binario compilado o un archivo comprimido en zip), genera un hash BLAKE2b y guárdalo en un archivo:

# Example: generate hash for my-app.tar.gz
b2sum my-app.tar.gz > my-app.tar.gz.b2

Este comando calcula el hash BLAKE2b de my-app.tar.gz y redirige la salida (el hash y el nombre del archivo) a my-app.tar.gz.b2. Guarda este archivo .b2 de forma segura junto a tu artefacto, por ejemplo en un repositorio de artefactos o en un almacenamiento seguro.

Paso 2: verificar hashes

Antes de desplegar o usar el artefacto, verifica su integridad con el archivo de hash generado:

# Example: verify the integrity of my-app.tar.gz using its hash file
b2sum -c my-app.tar.gz.b2

La opción -c (o --check) indica a b2sum que lea las sumas hash del archivo especificado y las verifique. Si el archivo my-app.tar.gz coincide con el hash almacenado en my-app.tar.gz.b2, b2sum mostrará:

my-app.tar.gz: OK

Si el archivo ha sido manipulado, está dañado o falta, b2sum informará de un error y saldrá con un código de estado distinto de cero, que puedes usar para detener el pipeline de CI/CD.

Ejemplo de integración con CI/CD

Este es un ejemplo práctico que usa GitHub Actions para integrar b2sum en tu flujo de trabajo:

name: Verify Build Artifacts

on: [push, pull_request]

jobs:
  build_and_verify:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4 # Use the latest major version

      - name: Set up environment
        # Add steps to set up your build environment (e.g., install Node.js, Java, etc.)
        run: echo "Setting up build environment..."

      - name: Build artifact
        run: |
          echo "Building application..."
          # Replace with your actual build commands
          mkdir -p dist
          echo "Build output" > dist/app.txt
          # Create an archive of the build output
          tar -czf artifact.tar.gz ./dist

      - name: Generate hash
        id: generate_hash # Give the step an ID to reference its output
        run: |
          b2sum artifact.tar.gz > artifact.tar.gz.b2
          echo "Generated hash file artifact.tar.gz.b2"
          # Optionally, output the hash value itself for logging
          HASH_VALUE=$(cut -d' ' -f1 artifact.tar.gz.b2)
          echo "hash_value=$HASH_VALUE" >> $GITHUB_OUTPUT

      - name: Verify hash
        run: |
          echo "Verifying hash for artifact.tar.gz..."
          b2sum -c artifact.tar.gz.b2
          echo "Verification successful!"

      - name: Upload artifact and hash
        uses: actions/upload-artifact@v4 # Use the latest major version
        with:
          name: build-artifact
          path: |
            artifact.tar.gz
            artifact.tar.gz.b2
          retention-days: 7 # Optional: Adjust artifact retention period

Este flujo de trabajo:

Hace checkout del código fuente.
Configura el entorno de compilación (marcador de posición).
Compila la aplicación y crea un archivo tar.gz.
Genera un hash BLAKE2 del archivo y lo guarda en un archivo .b2. También muestra el propio valor del hash.
Verifica el hash de inmediato para asegurarse de que el artefacto no se dañó durante el proceso.
Sube tanto el artefacto (artifact.tar.gz) como su archivo de hash (artifact.tar.gz.b2) para usarlos más adelante en las etapas de despliegue.

Automatizar las comprobaciones de integridad

Para escenarios más complejos o para reutilizar la lógica en distintos pipelines, puedes crear un script de shell robusto que se encargue de la verificación de integridad:

#!/bin/bash

# verify-integrity.sh: checks the integrity of a file using its corresponding .b2 hash file.

set -euo pipefail # Exit on error, undefined variable, or pipe failure

ARTIFACT_PATH="${1:-}"
HASH_FILE="${ARTIFACT_PATH}.b2"

# Check if artifact path is provided
if [ -z "$ARTIFACT_PATH" ]; then
  echo "Usage: $0 <path/to/artifact>"
  exit 1
fi

# Check if artifact file exists
if [ ! -f "$ARTIFACT_PATH" ]; then
  echo "Error: Artifact file '$ARTIFACT_PATH' not found."
  exit 1
fi

# Check if hash file exists
if [ ! -f "$HASH_FILE" ]; then
  echo "Error: Hash file '$HASH_FILE' not found."
  exit 1
fi

echo "Verifying integrity of '$ARTIFACT_PATH' using '$HASH_FILE'..."

# Perform the check
if b2sum --quiet -c "$HASH_FILE"; then
  echo "Integrity check PASSED for '$ARTIFACT_PATH'."
  exit 0
else
  echo "Integrity check FAILED for '$ARTIFACT_PATH'!"
  # b2sum already prints detailed error messages when check fails
  exit 1
fi

Guárdalo como verify-integrity.sh, hazlo ejecutable con chmod +x verify-integrity.sh y úsalo en los scripts de tu pipeline:

# Example usage in a CI/CD script after downloading the artifact and hash file
./verify-integrity.sh path/to/downloaded/my-app.tar.gz
# The script will exit with 0 on success, non-zero on failure

Buenas prácticas de gestión de errores

Cuando implementes la verificación de hashes en tu pipeline de CI/CD, ten en cuenta estas buenas prácticas de gestión de errores:

Falla rápido: configura tu pipeline para que se detenga de inmediato si falla una verificación de hash. Así evitas que se desplieguen artefactos potencialmente dañados o manipulados.
Registro detallado: registra el intento de verificación, el hash esperado (si está fácilmente disponible) y el resultado. b2sum -c muestra mensajes de error útiles cuando falla; asegúrate de capturarlos en los logs de tu CI/CD.
Sistema de notificaciones: intégralo con tu sistema de notificaciones (por ejemplo, Slack o email) para avisar de inmediato al equipo correspondiente cuando falle una comprobación de integridad.
Almacenamiento seguro de los hashes: asegúrate de que los archivos de hash .b2 se guarden de forma segura y no puedan manipularse con facilidad. Guardarlos junto a los artefactos en un repositorio que controle versiones o que ofrezca inmutabilidad es una buena práctica. Considera firmar los archivos de hash si necesitas seguridad adicional.
Gestiona los archivos ausentes: asegúrate de que tus scripts manejen con elegancia los casos en los que falte el artefacto o el archivo de hash, mostrando mensajes de error claros.

Solución de problemas comunes

Hash que no coincide: es el modo de fallo principal e indica que el contenido del archivo ha cambiado desde que se generó el hash. Entre las causas están:
- Daño del archivo durante la transferencia o el almacenamiento.
- Modificación intencionada o accidental del artefacto después de calcular el hash.
- Generar el hash sobre una versión del archivo distinta de la que se está verificando.
- Solución: vuelve a descargar o a recuperar el artefacto y el archivo de hash originales. Si el problema persiste, investiga posibles fuentes de corrupción o vuelve a compilar el artefacto desde el código fuente.
b2sum: command not found: la utilidad b2sum no está instalada o no se encuentra en el PATH del sistema dentro del entorno de ejecución de CI/CD.
- Solución: asegúrate de que el paquete coreutils (o equivalente) esté instalado en el entorno de tu runner de CI/CD (por ejemplo, la imagen de Docker o la VM). Consulta la sección Instalación.
Problemas de permisos: puede que el proceso de CI/CD no tenga los permisos de sistema de archivos necesarios para leer el artefacto o el archivo de hash.
- Solución: verifica los permisos y la propiedad de los archivos, así como el contexto de ejecución del comando b2sum.
Diferencias en los finales de línea: en los archivos de texto, las diferencias en los finales de línea (CRLF frente a LF) entre el entorno donde se generó el hash y aquel donde se verifica pueden provocar discrepancias.
- Solución: asegura finales de línea consistentes, normalmente configurando Git (core.autocrlf) o las herramientas de compilación de forma adecuada. Calcular el hash de archivos binarios (como .zip o .tar.gz) suele evitar este problema.
Formato incorrecto del archivo de hash: el archivo .b2 debe contener la salida del hash exactamente como la produce b2sum (el hash seguido del nombre del archivo). Editarlo a mano puede dañar ese formato.
- Solución: vuelve a generar el archivo de hash con el comando b2sum artifact > artifact.b2 estándar.

Integración con Transloadit

El Robot /file/hash de Transloadit admite múltiples algoritmos de hash, incluido BLAKE2b (b2). Puedes integrar el cálculo de hashes directamente en tus flujos de trabajo de procesamiento de archivos. Este es un ejemplo de Assembly que usa BLAKE2:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "hashed": {
      "use": ":original",
      "robot": "/file/hash",
      "algorithm": "b2"
    }
  }
}

Después de que se ejecute la Assembly, el valor del hash BLAKE2b del archivo procesado estará disponible en el JSON de resultados de la Assembly, normalmente dentro del objeto results correspondiente al Step hashed, en el campo file.meta.hash. Así puedes generar hashes como parte de pipelines automatizados de subida y procesamiento.

Conclusión y buenas prácticas

Usar b2sum en tu pipeline de CI/CD mejora notablemente la seguridad y la fiabilidad, ya que aporta garantías sólidas sobre la integridad de los archivos. Al generar y verificar hashes BLAKE2, puedes detectar daños accidentales o manipulaciones maliciosas de tus artefactos de compilación antes de que lleguen a producción.

Entre las buenas prácticas clave están:

Generar los hashes inmediatamente después de crear el artefacto.
Almacenar los archivos de hash de forma segura junto a sus artefactos correspondientes o vinculados a ellos.
Automatizar la verificación de hashes como paso obligatorio antes del despliegue o del consumo del artefacto.
Usar BLAKE2b (b2sum) por sus ventajas de velocidad y seguridad en los sistemas modernos.
Implementar una gestión de errores robusta y notificaciones para los fallos de verificación.
Considerar el uso de hashes firmados o de sumas de verificación almacenadas en manifiestos seguros para aplicaciones críticas.

Al aplicar estas prácticas, construyes un pipeline de despliegue más fiable y seguro.

En Transloadit, aprovechamos algoritmos de hash robustos como BLAKE2 dentro de nuestro ecosistema de Robots como parte de nuestros servicios de procesamiento de archivos, lo que ayuda a garantizar la integridad de los archivos de nuestros usuarios.