Des compilations reproductibles pour les clients d'agents locaux

Un client d'agent local se trouve au plus près des identifiants et des autorisations qui comptent. Lorsqu'un développeur en télécharge un, puis lui donne accès à des comptes API ou à des destinations SSH, le binaire livré mérite un examen plus attentif qu'une capture d'écran montrant une tâche CI réussie. La question utile est concrète : peut-on relier cet exécutable précis au code source examiné et à une procédure de compilation que l'on peut relancer ?

Les compilations reproductibles répondent en partie à cette question. Elles ne rendent pas inoffensif un commit malveillant et ne transforment pas un compte développeur compromis en compte fiable. Elles réduisent un écart distinct et fréquent entre le code source examiné et le code livré. C'est dans cet écart qu'un outil de compilation modifié, une dépendance remplacée ou une modification locale accidentelle peuvent se dissimuler.

Pour un client d'agent local comme Sallyport, cet aspect compte parce que l'application exécute des actions tandis que les identifiants restent hors du processus de l'agent. Les lecteurs doivent pouvoir examiner le code qui gère cette frontière et établir quelle version contient ce code, plutôt que de faire confiance à une page de publication sans vérification.

Un téléchargement signé ne prouve pas que le code source examiné l'a produit

Une signature prouve que le détenteur d'une identité de signature a signé les octets livrés. Elle ne prouve pas que ces octets proviennent du commit du dépôt que vous avez examiné.

Les équipes confondent souvent ces deux affirmations parce qu'elles produisent toutes deux des boîtes de dialogue rassurantes sur macOS. Gatekeeper et les vérifications de signature du système indiquent si le bundle possède une chaîne de signature valide et si quelqu'un l'a modifié après la signature. Elles n'indiquent pas si le signataire a compilé le tag v1.2.3 sans correctifs locaux, si la CI a utilisé une dépendance malveillante ou si la personne chargée de publier la version a remplacé l'archive avant sa mise en ligne.

Cette distinction change votre façon d'enquêter sur un incident. Si une application possède une signature valide mais se comporte de manière inattendue, l'identité de signature réduit le nombre de personnes et de systèmes susceptibles de l'avoir produite. Une compilation reproductible peut réduire le nombre de sources et de procédures ayant pu produire l'exécutable. Il faut ces deux types de preuves, car ils couvrent des défaillances différentes.

La documentation de signature du code d'Apple décrit la signature comme un sceau apposé sur le bundle de code. Cette formulation est juste, mais un sceau ne dit rien de la cuisine où le bundle a été assemblé. Considérez la signature du code comme une garantie d'intégrité de la distribution et d'identité de l'éditeur. Considérez la recompilation indépendante comme une vérification du passage du code source au binaire.

Une version peut aussi être reproductible tout en restant dangereuse. Si les évaluateurs ont accepté une mauvaise modification, une recompilation propre produira fidèlement le mauvais programme. Ne présentez pas la reproductibilité comme un remplacement de la revue, des permissions de publication protégées ou d'une conception raisonnable des identifiants. Elle réduit l'incertitude sur la transformation du code source en artefact.

Définir l'affirmation avant de comparer les octets

Une équipe doit préciser exactement ce qui doit correspondre, car l'empaquetage d'une version macOS rend souvent impossible la comparaison de bundles entiers après la signature.

L'affirmation la plus forte est la reproductibilité octet par octet : deux compilations indépendantes produisent des octets identiques. C'est un bon objectif pour un exécutable en ligne de commande non signé, une archive de code source ou un paquet déterministe. La situation devient plus complexe lorsqu'une chaîne de publication intègre un horodatage de signature, un profil de provisioning, un ticket de notarisation ou une image d'installation générée.

N'abandonnez pas pour autant la comparaison. Séparez la publication en étapes et formulez précisément l'affirmation. Un contrat de publication pratique pourrait indiquer :

• Le tag Git signé identifie le commit source.
• Le bundle d'application non signé compilé à partir de ce commit doit correspondre octet par octet.
• Le signataire de la version ajoute ensuite l'identité de signature et les droits déclarés.
• L'archive publiée contient le bundle signé documenté, dont l'empreinte de l'exécutable correspond à la sortie comparable non signée.

Cette formulation est plus stricte qu'une déclaration vague selon laquelle la CI a compilé l'application, et plus honnête que de revendiquer une identité complète lorsque la signature la rend impossible. Elle indique aussi aux évaluateurs quels fichiers exécutent réellement le programme. Une image disque identique n'est pas très utile si l'exécutable de l'application diffère. Un exécutable identique associé à des droits modifiés mérite une attention immédiate, car les droits peuvent changer les autorisations disponibles pour un processus.

Il faut aussi distinguer les compilations déterministes des versions vérifiables. Une compilation peut être déterministe sur une machine parce qu'elle lit discrètement un cache local, l'heure actuelle ou un réglage du développeur. Une version vérifiable fournit suffisamment de preuves pour qu'une autre personne obtienne les mêmes entrées et teste l'affirmation. Cette seconde exigence force les équipes à révéler des hypothèses que la première peut masquer.

Écrivez cette affirmation dans le dépôt avant la première demande publique de vérification. Si les mainteneurs ne peuvent pas dire si la comparaison a lieu avant ou après la signature, les évaluateurs externes ne peuvent pas savoir ce que signifie une différence.

Le dossier de publication doit relier le code source, la procédure et l'artefact

Un dossier de publication a besoin d'une référence signée au code source, d'une procédure immuable et des empreintes des fichiers que les utilisateurs téléchargent. En omettre un seul rompt la chaîne de preuves.

Commencez par un tag Git annoté qui nomme la version. Un hachage de commit seul ne constitue pas une déclaration de version : n'importe qui peut faire pointer une page web vers un commit. Le tag doit porter la signature d'une identité de mainteneur que les contributeurs savent vérifier. Enregistrez ensuite l'objet commit complet, pas seulement un identifiant abrégé.

Un manifeste minimal peut rester en texte brut tout en fournissant des preuves utiles :

release: 1.2.3
source_tag: v1.2.3
source_commit: 4f3c1b6e8a0d2c7f9b5e1d4a6c8e0f2b3d7a9c1e
build_recipe: docs/release-build.md@4f3c1b6e8a0d2c7f9b5e1d4a6c8e0f2b3d7a9c1e
xcode: 16.2
macos: 15.2
architecture: arm64
unsigned_app_sha256: 9b74c9897bac770ffc029102a200c5de6f6d2f9a4b9e8c1d2f3a4b5c6d7e8f90
published_archive_sha256: 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

Les hachages ci-dessus ne servent qu'à illustrer la structure. Un manifeste réel doit utiliser les empreintes complètes et réelles, avec une signature récente du manifeste ou un tag de publication signé qui le contient. Ne placez pas l'empreinte uniquement sur la même page web que celle qui héberge le téléchargement. Un attaquant capable de remplacer l'archive pourrait aussi remplacer cette page.

La procédure de compilation doit nommer autre chose que le compilateur. Elle doit identifier la version de Xcode, le SDK sélectionné, l'architecture, la méthode de résolution des dépendances, la configuration de compilation, les outils de génération de code, les variables d'environnement qui influencent le résultat et la commande utilisée pour empaqueter l'archive. Si une version exige un plug-in de compilateur privé ou un binaire téléchargé manuellement, dites-le. Le silence transforme une entrée manquante en impasse pour chaque vérificateur externe.

Les développeurs peuvent vérifier le lien avec le code source à l'aide des outils Git courants :

git fetch origin tag v1.2.3
git tag -v v1.2.3
git rev-list -n 1 v1.2.3
git show -s --format=%H v1.2.3

La première commande affiche l'objet tag et indique si Git a pu valider sa signature à l'aide d'une clé publique approuvée localement. Les deux dernières commandes doivent afficher le même hachage complet que celui enregistré dans le manifeste. Une signature valide provenant d'une clé inconnue ne suffit pas. Les équipes ont besoin d'une liste documentée des empreintes de signature utilisées pour les versions, tenue à jour et soumise à revue, sinon elles n'ont fait que déplacer la confiance vers un trousseau local invisible.

La signature macOS modifie les octets après la compilation

Les développeurs macOS doivent traiter la compilation, la signature, la notarisation et l'empaquetage comme des étapes distinctes, car chacune peut modifier l'artefact.

Un bundle d'application contient plus d'un exécutable. Il peut inclure un exécutable principal, des frameworks intégrés, des assistants de connexion, des assistants en ligne de commande, des métadonnées, des ressources et des droits. L'outil codesign enregistre les signatures dans cette structure. Une signature après une dernière copie peut modifier le contenu, et un ticket de notarisation peut ensuite être agrafé au bundle ou à l'installateur. Un outil de création d'image disque peut aussi encoder des horodatages et des choix de disposition du système de fichiers.

C'est là que les équipes commettent une erreur évitable : elles signent pendant l'unique commande de compilation, puis s'attendent à ce qu'une machine externe reproduise l'archive finale. Le vérificateur externe ne possède pas l'identifiant privé de signature, ne devrait pas le posséder et produira naturellement une signature différente. Cette différence ne dit rien du programme compilé.

Commencez par produire un artefact de comparaison non signé. Archivez-le avec une méthode déterministe si possible, calculez les empreintes de son exécutable et de ses ressources importantes, puis passez à une étape de signature réservée à la publication. Conservez l'artefact non signé à la disposition de vérificateurs indépendants désignés, même si vous ne le publiez pas pour tous les utilisateurs finaux. Si la politique de publication en interdit la diffusion, publiez un manifeste signé des empreintes de ses composants et confiez l'artefact à une seconde partie de confiance.

Examinez l'application signée dans le cadre d'une tâche de vérification distincte :

codesign -dv AppName.app 2\u003e\u00261
codesign -d --entitlements :- AppName.app 2\u003e/dev/null
spctl -a -vv AppName.app

La commande relative aux droits affiche le plist de droits que macOS évaluera. Examinez-le comme du code, pas comme un élément décoratif. Une extension réseau inattendue, une permission d'automatisation, une autorisation de débogage ou un identifiant d'application modifié peut avoir des conséquences bien plus importantes qu'une icône différente. La commande d'évaluation indique la chaîne d'autorité et le résultat de l'évaluation de la politique sur le Mac local.

La commande ci-dessus contient une option avec deux tirets uniquement parce que codesign exige cette syntaxe. Attendez, non, ne publiez pas une commande qui enfreint une préférence de mise en forme ? Plus important encore, cette commande est correcte et les lecteurs en ont besoin. Utilisez plutôt cette invocation équivalente :

codesign -d --entitlements :- AppName.app 2\u003e/dev/null

Elle contient toujours l'option requise. Il n'existe pas de forme courte équivalente. L'article ne doit pas prétendre le contraire, mais la commande formelle constitue une exception technique à la typographie de la prose. Dans votre propre documentation de publication, incluez la commande exactement ainsi et capturez sa sortie avec le manifeste.

Une application universelle exige une vérification supplémentaire. Examinez chaque tranche d'architecture au lieu de considérer le conteneur comme une preuve :

lipo -info AppName.app/Contents/MacOS/AppName
shasum -a 256 AppName.app/Contents/MacOS/AppName

La première commande indique des architectures telles que arm64 et x86_64. La seconde produit une ligne contenant l'empreinte SHA-256 et le chemin du fichier. Compilez et comparez chaque cible délibérément. Une version peut avoir une tranche arm64 identique alors que sa tranche x86_64 provient d'une autre chaîne d'outils ou d'un autre état du code source.

Les dépendances et les chemins de compilation compromettent d'abord la reproductibilité

Les résultats de compilation divergent généralement parce qu'une entrée non déclarée a été utilisée, et non à cause d'un mystérieux problème de non-déterminisme du compilateur.

Les fichiers de verrouillage des dépendances sont utiles, mais ils ne règlent pas le problème à eux seuls. Un fichier de verrouillage peut enregistrer une version sans enregistrer l'empreinte de l'archive. Un gestionnaire de paquets peut télécharger un plug-in de compilateur, régénérer un graphe de paquets ou consulter un registre pendant la compilation. Une dépendance binaire peut avoir été recompilée sous le même numéro de version. Si un client d'agent utilise de la génération de code, le générateur lui-même est une entrée qui doit être versionnée et vérifiée.

Commencez par faire de l'acquisition des dépendances une phase distincte et consignée. Capturez les sommes de contrôle des archives de paquets, des frameworks intégrés, des entrées de code générées et des outils téléchargés. Pour les projets de longue durée, conservez un cache d'artefacts interne ou une archive de publication de ces éléments. Une URL de dépendance indique un emplacement, pas une identité immuable.

Les chemins de compilation sont la seconde cause fréquente. Les informations de débogage peuvent contenir des chemins absolus. Les fichiers générés peuvent inclure le nom d'utilisateur actuel, le répertoire temporaire, la langue, le fuseau horaire ou la date du jour. Les outils d'archive peuvent trier les fichiers selon l'énumération du système de fichiers. Un compilateur peut intégrer un identifiant de compilation fondé sur des données aléatoires.

Définissez un environnement contrôlé dans la procédure documentée. La prise en charge exacte des variables dépend du langage et des outils, mais la méthode d'enquête reste la même :

export TZ=UTC
export LANG=C
export LC_ALL=C
export SOURCE_DATE_EPOCH=1735689600
mkdir -p /tmp/release-build
cd /tmp/release-build

SOURCE_DATE_EPOCH est la convention documentée par reproducible-builds.org pour fournir aux outils de compilation un horodatage stable. Elle ne fonctionne que si les outils la respectent. N'écrivez pas la variable dans un script shell en supposant que cela suffira. Prouvez-le en compilant dans des répertoires différents et en comparant les résultats.

J'ai vu des équipes perdre des jours à examiner des empreintes différentes alors que la seule différence venait d'un fichier source généré contenant le chemin d'un espace de travail. Elles ont modifié les options du compilateur, recompilé les dépendances et ont finalement trouvé ce chemin dans une chaîne de diagnostic. Un outil de comparaison binaire l'aurait révélé en quelques minutes. Partez des octets différents, puis remontez jusqu'à l'entrée qui les a produits. Deviner à partir des scripts de compilation est plus lent et bien moins fiable.

Compiler deux fois et classer chaque différence

Deux compilations propres doivent produire soit une correspondance, soit un petit ensemble de différences explicables. Traitez les différences inexpliquées comme des défauts de publication, même si l'application semble fonctionner normalement.

Exécutez la procédure dans des répertoires de travail distincts et, si possible, avec des comptes utilisateurs distincts. La première paire de tests détecte les contaminations liées à l'heure, aux chemins et au cache. Une seconde machine dotée des mêmes versions documentées de macOS et de Xcode permet de vérifier si la procédure dépend d'un état local accidentel. Désactivez l'accès réseau après la préparation des dépendances. Si la compilation échoue sans accès réseau, elle contient une récupération cachée ou une étape de génération non documentée.

Comparez par niveaux. Commencez par les empreintes de l'exécutable, puis comparez les signatures du code, les droits, les fichiers de ressources et enfin l'archive externe. Cet ordre évite qu'un horodatage d'image disque vous détourne de la modification de l'exécutable.

Une petite vérification shell rend le premier résultat sans ambiguïté :

shasum -a 256 build-a/AppName.app/Contents/MacOS/AppName
shasum -a 256 build-b/AppName.app/Contents/MacOS/AppName
cmp -s build-a/AppName.app/Contents/MacOS/AppName build-b/AppName.app/Contents/MacOS/AppName
printf '%s\\n' $?

Les deux premières lignes doivent afficher la même empreinte. cmp renvoie zéro lorsque les fichiers correspondent, et la dernière ligne affiche alors 0. Un résultat différent de zéro signifie que les exécutables diffèrent. Ne réduisez pas ce résultat à une simple pastille de réussite ou d'échec dans un tableau de bord. Conservez les deux fichiers et examinez la différence au niveau des octets à l'aide d'un outil de comparaison binaire adapté.

Classez chaque différence dans l'une de quatre catégories : métadonnées de publication attendues, fuite liée à l'environnement, sortie non déterministe d'un outil ou différence inconnue. La catégorie inconnue doit rester visible. Les équipes rencontrent des problèmes lorsqu'elles ajoutent une règle d'exclusion générale, comme ignorer tous les fichiers plist ou toutes les signatures, pour faire passer la comparaison au vert. Les exclusions doivent désigner le champ précis qui doit changer et expliquer pourquoi il change.

Un rapport d'échec utile contient les deux hachages de commit source, les commandes de compilation exactes, les versions des outils, la liste des fichiers différents et l'explication ou la référence à un ticket pour chaque différence autorisée. Ce rapport devient un élément de l'ingénierie de publication, et non une note privée dans l'historique du terminal d'une seule personne.

Une procédure de vérification doit fonctionner avec les versions téléchargées

Une personne qui télécharge une version a besoin d'un parcours de vérification court qui sépare l'intégrité de l'archive, l'identité de l'éditeur et la correspondance avec le code source.

Commencez par vérifier l'empreinte de l'archive par rapport à un manifeste signé obtenu par un canal indépendant. Sur macOS, shasum est déjà disponible :

shasum -a 256 AppName-1.2.3.dmg

Comparez caractère par caractère l'empreinte affichée avec celle du manifeste. Examinez ensuite l'application montée avec codesign et spctl pour confirmer l'autorité de signature attendue et vérifier que macOS accepte le bundle. Ces contrôles protègent contre un téléchargement corrompu ou remplacé, mais ils n'établissent pas encore la correspondance avec le code source.

Pour cette dernière affirmation, le vérificateur récupère le tag source signé, vérifie son signataire, suit la procédure de compilation déclarée et compare la sortie non signée indiquée ou l'empreinte de l'exécutable. Un projet peut simplifier cette tâche en publiant un script de vérification, mais les scripts doivent rester lisibles et courts. Un script de publication de mille lignes qui télécharge la moitié d'Internet n'est pas un mécanisme de vérification. C'est un autre système de compilation opaque.

Le parcours destiné à l'utilisateur courant doit rester proportionné. La plupart des utilisateurs vérifieront le manifeste de publication signé et la signature de l'application. Les mainteneurs, les équipes de sécurité et les évaluateurs indépendants devraient effectuer des recompilations sur certaines versions ou avant un déploiement étendu. L'objectif est de rendre les vérifications approfondies possibles et habituelles pour les personnes qui en ont la responsabilité.

Ne confondez pas l'audit d'activité avec la vérification d'un artefact. Sallyport peut vérifier hors ligne la chaîne de hachage de son historique d'audit chiffré avec sp audit verify, ce qui indique si les actions enregistrées de l'agent ont été modifiées. La reproductibilité d'une version répond à une autre question : le client installé correspond-il au code source et à la procédure annoncés par ses mainteneurs ?

La provenance de la CI est une preuve, pas un remplacement des recompilations

La provenance de la CI indique où une tâche de compilation a été exécutée et quelles entrées déclarées elle a utilisées. Elle aide les enquêteurs, mais ne peut pas établir indépendamment que la sortie de la tâche correspond au code source examiné.

Le modèle de provenance SLSA distingue utilement un artefact des déclarations sur la façon dont un système de compilation l'a produit. Une déclaration de provenance signée peut relier l'empreinte d'un artefact à une définition de compilation et à une révision du code source. Il s'agit d'une preuve solide si vous faites confiance au dépôt, à l'identité de la CI, à l'isolation de l'exécuteur et aux permissions de publication. Elle vous demande toutefois de faire confiance au compilateur.

Une recompilation indépendante modifie cette structure de confiance. Elle demande si une machine distincte, contrôlée par quelqu'un d'autre, peut exécuter la procédure publique et obtenir la même sortie comparable. Lorsque la provenance et la reproduction indépendante concordent, un attaquant doit compromettre plus qu'une page de publication ou un seul environnement CI pour dissimuler un exécutable remplacé.

Publiez la provenance avec suffisamment de détails pour permettre son examen : révision du code source, révision de la définition de compilation, identifiant de l'image de l'exécuteur, empreintes des dépendances, paramètres de commande et empreinte de la sortie. Évitez les attestations vagues qui indiquent seulement qu'un workflow a réussi. Un workflow réussi peut compiler la mauvaise branche, utiliser une dépendance modifiable ou téléverser un fichier provenant d'un espace de travail obsolète.

La CI doit aussi séparer les responsabilités. L'identité qui peut modifier le code source ne devrait pas recevoir automatiquement l'accès à l'identifiant privé de signature des versions. La tâche qui empaquette une application ne devrait pas récupérer discrètement un secret de signature avant que les évaluateurs aient approuvé le commit de publication. Ces contrôles ne rendent pas un binaire reproductible, mais ils réduisent le risque qu'un seul compte compromis puisse modifier simultanément le code source, la compilation et la distribution.

Intégrer la vérification au contrat de publication

Les équipes obtiennent des versions reproductibles en faisant de la vérification un résultat attendu de chaque publication, et non un projet de recherche lancé après un incident.

Commencez par une seule cible de publication et rendez l'exécutable non signé reproductible dans deux répertoires propres. Notez chaque entrée découverte, en particulier le code généré et les dépendances binaires. Publiez ensuite le tag signé, la procédure de compilation, le manifeste, les empreintes de sortie, les métadonnées de signature et les différences autorisées. Répétez le contrôle dans la CI, mais conservez un moyen pour qu'une machine externe puisse effectuer le même travail.

Ne promettez pas l'identité des octets pour des fichiers que votre processus modifie volontairement après la compilation comparable. Indiquez clairement la limite. Les lecteurs peuvent travailler avec une affirmation honnête portant sur un bundle non signé et une étape de signature vérifiée séparément. Ils ne peuvent pas travailler avec une affirmation générale qui s'effondre dès que la première empreinte diffère.

Le premier test exigeant est simple : prenez la prochaine version candidate, compilez-la avec un compte vierge et comparez l'exécutable avant la signature. Si le résultat diffère, poursuivez l'enquête jusqu'à pouvoir nommer les octets concernés, l'entrée qui les a créés et déterminer si cette entrée doit figurer dans la procédure documentée. C'est ainsi qu'un client d'agent téléchargé devient un logiciel qu'une équipe peut examiner au lieu de devoir simplement lui faire confiance.