Automatiser l’intégrité des fichiers avec sha512sum en CI/CD

Kevin van Zonneveld

Cofondateur · Amsterdam, Pays-Bas · Afficher la bio

Utilisez sha512sum --check --strict checksums.sha512 pour comparer des fichiers à un manifeste de sommes de contrôle approuvé avant que votre pipeline ne les utilise. La commande renvoie un code de sortie non nul en cas d’échec de la vérification, si bien qu’un artefact modifié ou manquant peut arrêter la tâche. Le plus utile est de décider d’où proviennent les sommes de contrôle attendues.

Choisir une référence de confiance

Une somme de contrôle SHA-512 décrit les octets d’un fichier. Une somme de contrôle correspondante ne vous indique pas, à elle seule, qui a créé ces octets. Si quelqu’un peut remplacer à la fois un fichier et sa somme de contrôle attendue, la vérification peut quand même réussir.

Pour vos propres ressources fixes, générez un manifeste à partir des fichiers approuvés et relisez les modifications apportées à ce manifeste. Pour un téléchargement, obtenez la somme de contrôle attendue par un canal authentifié de l’éditeur ; lorsque des sommes de contrôle signées sont disponibles, suivez d’abord les instructions de vérification de signature de l’éditeur. Le guide de vérification des images de Debian⁠ illustre cette distinction entre la vérification des octets téléchargés et l’authentification de leur source.

L’exemple ci-dessous enregistre deux petits fichiers comme référence, puis réutilise cette référence dans la CI. Générer de nouvelles sommes de contrôle à partir de ce que reçoit la CI annulerait l’intérêt de la comparaison.

Processus de vérification des fichiers

Utilisez Bash et les GNU coreutils. Ces exemples ont été testés avec Bash 5.1 et coreutils 8.32 sous Ubuntu 22.04, ainsi qu’avec Bash 5.3 et coreutils 9.12 sous macOS. Vérifiez l’implémentation avant de continuer :

sha512sum --version

La première ligne doit identifier GNU coreutils. Une commande portant le même nom peut être une implémentation différente. Sous macOS, le paquet coreutils de Homebrew⁠ fournit les outils GNU ; suivez ses instructions de PATH pour gnubin afin d’utiliser leurs noms sans préfixe.

Exécutez chaque bloc Bash ci-dessous depuis le même répertoire parent. Les parenthèses confinent les changements de répertoire à un sous-shell. Cette configuration crée un nouveau répertoire sha512-demo et refuse d’en réutiliser un existant ; la relancer n’écrasera donc pas vos fichiers :

(
  set -eC
  mkdir sha512-demo
  cd sha512-demo
  mkdir assets
  printf 'release 1\n' > assets/app.txt
  printf '{"mode":"production"}\n' > assets/config.json
)

Ici, set -e arrête le sous-shell en cas d’échec, et -C empêche la redirection de sortie d’écraser un fichier ordinaire existant. Si la configuration échoue, résolvez l’erreur avant de passer au bloc suivant ; choisissez un autre répertoire parent si vous avez besoin d’une autre démo.

Génération des empreintes

Créez le manifeste une seule fois, tant que les deux fichiers contiennent les octets approuvés :

(
  set -eC
  cd sha512-demo
  sha512sum -- assets/app.txt assets/config.json > checksums.sha512
)

Chaque ligne contient un condensé SHA-512 hexadécimal de 128 chiffres, un indicateur de mode et un nom de fichier. La liste explicite de fichiers fait d’une entrée manquante une erreur et empêche le manifeste de se hacher lui-même. Pour vos propres fichiers, remplacez cette liste et mettez entre guillemets les noms de fichiers contenant des espaces.

Cette commande refuse également d’écraser un checksums.sha512 existant. Si la génération échoue, n’utilisez pas le manifeste nouvellement créé : il peut être vide ou incomplet. Conservez le manifeste approuvé précédent lorsque vous préparez une mise à jour intentionnelle, et relisez son remplaçant avant de l’adopter.

Vérification des fichiers

Lancez la vérification depuis le répertoire utilisé pour créer les noms de fichiers relatifs :

(
  cd sha512-demo &&
  sha512sum --check --strict checksums.sha512
)

Avec les fichiers d’origine, la sortie est :

assets/app.txt: OK
assets/config.json: OK

--check lit le manifeste et compare chaque fichier nommé. --strict fait aussi échouer la vérification en présence de lignes de somme de contrôle mal formées, même lorsque d’autres entrées correspondent. Un manifeste vide échoue également. N’ajoutez pas --ignore-missing lorsque chaque artefact listé est requis. Ces options sont documentées dans le manuel GNU de sha512sum empaqueté par Debian⁠.

Pour tester le cas d’échec, modifiez sha512-demo/assets/app.txt et exécutez à nouveau le bloc de vérification. Il signale assets/app.txt: FAILED et se termine avec un code non nul. Restaurez les octets approuvés d’origine avant d’utiliser les exemples de CI réussis ci-dessous ; laissez le manifeste inchangé.

Gestion des erreurs et problèmes courants

Problèmes de permissions

Le vérificateur a besoin d’un accès en lecture au manifeste et aux fichiers, ainsi que d’un accès via leurs répertoires parents. Examinez les permissions et demandez au propriétaire un accès approprié si nécessaire. Ne modifiez pas largement la propriété des fichiers et ne rendez pas publics des fichiers sensibles simplement pour faire réussir une vérification.

Dépannage des empreintes non concordantes

Une non-concordance signifie que les octets diffèrent de la référence. Un téléchargement tronqué, des fins de ligne modifiées ou une modification intentionnelle peuvent en être la cause. Récupérez une nouvelle copie de confiance ou examinez la modification ; régénérer la somme de contrôle attendue la masquerait.

Une erreur de fichier manquant peut aussi signifier que vous avez exécuté la commande depuis le mauvais répertoire. Les chemins relatifs contenus dans le manifeste sont résolus à partir du répertoire de travail du processus, et non de l’emplacement du manifeste. En cas de lignes mal formées, récupérez le manifeste d’origine plutôt que de copier un tableau de sommes de contrôle mis en forme depuis une page web. Conservez à la fois la sortie standard et la sortie d’erreur standard dans les journaux de CI afin de pouvoir en identifier la cause.

Intégration CI/CD

Pour cet exemple de ressources fixes, ajoutez sha512-demo/assets/ et le sha512-demo/checksums.sha512 approuvé à votre dépôt. Les deux flux de travail ci-dessous vérifient ces fichiers extraits sans régénérer le manifeste. Relisez les modifications du manifeste : une pull request qui modifie à la fois les ressources et leurs empreintes attendues peut passer cette vérification.

Placez la vérification avant l’étape qui consomme les fichiers, et faites dépendre le déploiement de sa réussite. Si vos artefacts proviennent d’une autre tâche, récupérez-les avant la vérification et gardez le manifeste approuvé séparé de la sortie générée par cette tâche.

Exemple GitHub Actions

Ajoutez ceci en tant que .github/workflows/integrity.yml, ou fusionnez l’étape de vérification dans un flux de travail existant. Il utilise actions/checkout⁠ pour récupérer le dépôt :

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

Le shell explicite bash de GitHub propage l’échec d’une commande à l’étape ; consultez sa documentation sur les shells de flux de travail⁠. Laissez la suppression des échecs désactivée pour cette étape.

Exemple GitLab CI

Pour un runner GitLab doté d’un exécuteur Docker, fusionnez cette tâche dans .gitlab-ci.yml :

verify_integrity:
  image: ubuntu:22.04
  script:
    - cd sha512-demo
    - sha512sum --check --strict checksums.sha512

L’image Ubuntu fournit les GNU coreutils. GitLab fait échouer la tâche lorsqu’une commande de script se termine avec un code non nul⁠, y compris en cas d’échec d’un changement de répertoire. Conservez les commandes sous forme d’entrées de script distinctes et n’activez pas allow_failure pour ce contrôle.

Détecter les modifications après la construction d’une image Docker

Pour contrôler des artefacts copiés depuis une image, vérifiez ces fichiers exportés par rapport au manifeste approuvé avant de les distribuer. Un manifeste généré pendant la construction ne peut détecter des modifications ultérieures des octets que tant que ce manifeste reste digne de confiance. Il ne peut ni établir l’authenticité des entrées de la construction, ni protéger contre une personne qui remplacerait à la fois les fichiers et le manifeste.

Savoir ce que couvre une vérification réussie

La vérification lit chaque fichier listé ; les artefacts volumineux nécessitent donc de relire tous leurs octets. Elle ne contrôle ni les fichiers non listés, ni leur propriétaire, leurs permissions ou leurs horodatages. Un résultat positif signifie que les octets listés correspondent à la référence ; il ne prouve pas que le répertoire ne contient que des fichiers approuvés, ni que la construction est reproductible.