Référence CLI
Cette référence suit continuum-attest/src/main.rs en version 0.4.0. Utilisez attest --help et attest <command> --help pour connaître les options exactes du binaire installé. Les options globales sont --verbose et --quiet.
Installation
Continuum Attest 0.4.0 prend en charge Linux et macOS, sur x86-64 et arm64, sous Apache-2.0. Consultez les fichiers de version pour les binaires et les éléments de vérification. Windows n’est pas pris en charge dans cette version.
Installer avec Cargo
Le paquet s’appelle continuum-attest sur
crates.io. Installez-le avec Rust 1.89 ou ultérieur :
cargo install continuum-attest --version 0.4.0 --lockedLa commande installée s’appelle attest. Le paquet nommé attest appartient à
un autre projet.
Premier reçu signé
Depuis le répertoire de votre projet, initialisez Continuum Attest et créez une clé de signature :
attest init
attest keys generate --name releaseAdaptez le fichier attest.yaml généré pour déclarer votre commande de compilation,
ses fichiers d’entrée et ses sorties. Exécutez-le, puis vérifiez le reçu avec votre espace de travail :
attest run --sign
attest verify .attest/receipts/*.yaml --recomputeLa signature est explicite. Gardez les clés privées confidentielles ; le destinataire a besoin du reçu et de clés publiques approuvées indépendamment pour contrôler la signature. Recalculer les empreintes nécessite aussi les fichiers correspondants de l’espace de travail.
La spécification publique Format de reçu décrit les éléments de preuve et les règles de signature. Le Protocole de plugin est un projet de spécification ; la version 0.4.0 n’exécute aucun plugin.
Commandes
| Commande | Fonction |
|---|---|
attest init |
Créer l’espace de travail local et un pipeline initial |
attest run |
Exécuter un pipeline ou envelopper une commande |
attest sign |
Signer un reçu dans un processus qui n’a exécuté aucune commande du projet |
attest timestamp |
Horodater une signature existante sans clé privée |
attest identity sign |
Lier les octets exacts du reçu à un workflow CI avec Cosign 3 |
attest evidence |
Empaqueter les artefacts et preuves, ou les vérifier hors ligne |
attest trust |
Créer, inspecter, importer ou actualiser des bundles de confiance signés |
attest keys |
Générer, lister, exporter, importer ou révoquer des clés |
attest hash |
Calculer les empreintes canoniques des chemins déclarés |
attest capsule |
Initialiser, exécuter ou calculer l’empreinte d’une capsule |
attest verify |
Vérifier des reçus ou une archive hors ligne |
attest export |
Exporter un reçu dans une enveloppe DSSE in-toto |
attest import |
Vérifier une enveloppe DSSE in-toto importée |
attest image |
Signer et vérifier des images |
attest causal |
Consulter l’historique causal, publier un engagement ou récupérer une preuve de comparaison |
Exécuter un pipeline
attest run --pipeline attest.yaml --sign
attest run --sign --key <key-id>
attest run --check-reproducibility
attest run --sign --timestamp--verify sélectionne l’isolation de processus : des limites de ressources, sans contrôle du réseau ni du système de fichiers. Le bloc isolation du reçu détaille les contrôles appliqués, non appliqués ou indisponibles. Cette option ne remplace pas attest verify sur le reçu obtenu. --check-reproducibility exécute deux fois le pipeline dans des espaces de travail neufs et compare les empreintes de sortie. Consultez la référence de configuration pour les champs des étapes.
Envelopper une commande
attest run --wrap --name build --input src/ --output dist/ --report build-report.json -- npm run buildRépétez --input et --output pour plusieurs chemins. --workspace DIR choisit la racine. Le mode wrap fonctionne sans fichier de pipeline ni bac à sable. Ajoutez --sign et une clé provisionnée pour signer. Le rapport JSON nomme le reçu exact et distingue le code de sortie du build du résultat de production des preuves.
Les nouveaux reçus enveloppés enregistrent le vecteur canonique des arguments.
Le destinataire peut recalculer les empreintes des entrées et sorties sans
attest.yaml, en transférant les fichiers déclarés et en utilisant
attest verify --recompute. La vérification n’exécute aucune commande.
Les protections de permissions et le contrôle après le build détectent les
modifications persistantes des entrées ; ils ne constituent pas un bac à sable.
Le guide public d’adoption CI
présente l’action GitHub et le composant GitLab, avec versions fixées. Tous deux
séparent les résultats du build, du reçu, de la signature, de l’horodatage,
de la vérification et de la publication, avec evidence-policy: required ou
optional. Un build en échec conserve son code de sortie ; une preuve obligatoire
manquante après un build réussi fait échouer la CI. Des jobs réels sur GitHub
Actions et GitLab autohébergé ont passé les scénarios d’acceptation et de refus
hors ligne consignés dans
#25.
La signature d’identité GitLab autohébergée nécessite des services reconnaissant
son émetteur et une confiance configurée indépendamment chez le destinataire.
La qualification a utilisé une infrastructure de test temporaire ; elle ne
fournit pas de service de signature de production.
Identité de workflow
attest identity sign receipt.yaml --bundle identity.sigstore.json
attest identity sign receipt.yaml --bundle identity.sigstore.json \
--identity-token-env ATTEST_CI_ID_TOKENLa signature d’identité nécessite un accès réseau, un binaire Cosign 3 fixé et les permissions OIDC ou le jeton du fournisseur CI. Le destinataire fournit une politique fixant l’émetteur, le dépôt, l’identité complète du workflow et la révision source attendue, ainsi qu’une racine Sigstore approuvée séparément. Les variables d’environnement ne suffisent pas à établir cette identité. La signature Ed25519 locale du reçu reste obligatoire. L’identité établit l’origine et l’autorisation, pas l’intégrité du runner.
Preuves de release hors ligne
attest evidence pack receipt.yaml --output release.attest.tar.zst \
--identity-bundle identity.sigstore.json
attest evidence verify release.attest.tar.zst --trust-store /trusted/keys \
--identity-policy /trusted/workflow-policy.json --format json
attest evidence verify release.attest.tar.zst --trust-store /trusted/keys \
--artifact-root /delivery/artifacts --format jsonLe destinataire configure la confiance indépendamment de l’archive.
La vérification exige une signature approuvée, une exécution réussie et des
artefacts conformes. Par défaut, elle exige aussi la complétude des preuves
de capsule et causales référencées ; --identity-policy ajoute l’exigence
d’identité de workflow. --artifact-root contrôle les fichiers livrés séparément,
en conservant leurs chemins relatifs déclarés.
L’empaquetage inclut les événements causaux référencés disponibles. Ajoutez
--capsule-manifest FILE, répétable, pour les capsules référencées. Une preuve
obligatoire manquante ou une preuve altérée empêche l’acceptation.
--require signature,success,artifacts permet explicitement des preuves
facultatives incomplètes ; leurs résultats skipped restent visibles.
Le JSON contient policy.required, policy.unmet, les exigences d’identité,
les déclarations vérifiées et les rôles distincts. La vérification ne télécharge
ni confiance ni preuve manquante.
Compatibilité : la 0.4 produit attest-evidence/v3 lorsqu’un enregistrement de
publication est inclus, et v2 sinon. Mettez les destinataires à jour en 0.4 avant
d’envoyer des preuves de journal ; les anciens vérificateurs refusent v3.
Les paquets v1 et v2 existants restent lisibles. Consultez le
format de preuve.
Ces paquets sont distincts des archives causales acceptées par attest verify --archive.
Publier un engagement et transmettre sa preuve
Glass Ocean ajoute une publication explicite dans un journal externe compatible. Choisissez l’opérateur et configurez sa clé indépendamment chez les destinataires. Attest ne choisit ni n’exploite de journal public. Exécuter un build ne publie jamais d’entrée à lui seul.
attest causal publish --receipt receipt.yaml --log-config producer-log.json \
--output publication.json --publication-policy required --format json
attest evidence pack receipt.yaml --workspace . --publication publication.json \
--output release.attest.tar.zst
attest evidence verify release.attest.tar.zst --trust-store /trusted/keys \
--log-trust recipient-log.json --require signature,success,artifacts,log-inclusion --format jsonSeule une inclusion vérifiée sous un point de contrôle signé et approuvé confirme
la publication. required renvoie 3 si la confirmation manque ; optional
conserve l’enregistrement non confirmé et sa raison avec le code 0. Les erreurs
locales renvoient 2. Conservez publication.json pour reprendre la même soumission.
Le destinataire peut exiger log-inclusion quelle que soit la politique du producteur.
La publication est irréversible. Consultez Publier et vérifier la preuve du journal pour les informations divulguées, la configuration, l’adoption CI et la comparaison de points de contrôle obtenus indépendamment. Inclusion et cohérence relèvent de la vérification des preuves, pas du contrat de vérification des reçus ci-dessous.
Vérifier les reçus
attest verify .attest/receipts/<receipt>.yaml
attest verify --recompute .attest/receipts/<receipt>.yaml
attest verify --trust-store /path/to/trust --format json receipt.yaml
attest verify --archive bundle.attest.tar.zst --offline
attest verify receipt.yaml --recompute --require signature,timestamp,recompute
attest verify --archive bundle.attest.tar.zst --offline --require signature,linkage,trust,successLes codes de sortie sont 0 pour un succès, 1 pour une vérification en échec et 2 pour une erreur opérationnelle. La sortie JSON utilise NDJSON. Le contrôle des signatures est activé par défaut. --check-signatures false autorise explicitement les contrôles d’un reçu non signé et n’établit pas de confiance dans un signataire. Consultez Reçus et confiance.
Un contrôle qui n’a pas eu lieu est marqué skipped et ne satisfait jamais
une exigence --require. Cette option exige un résultat ; elle n’active pas
un contrôle : ajoutez --recompute pour effectuer le recalcul. Les propriétés disponibles sont signature,
timestamp, recompute, linkage (archives), trust (bundle courant) et
success (toutes les étapes terminées avec le code 0). Le résultat distingue
la validité des preuves du succès de la compilation. Le JSON des reçus ajoute
policy, execution et trust_material ; son contrat est publié dans le
schéma de résultat v1.
Les archives sont limitées par défaut à 64 Mio sur disque, 512 Mio décompressées,
10 000 entrées et 64 Mio par entrée. Les reçus et enveloppes DSSE sont limités
à 16 Mio avant analyse. Un dépassement produit le code 2 et le type d’erreur
JSON resource-limit.
Transmettre la confiance
attest trust bundle --output trust.json --key <issuer-key-id>
attest trust show trust.json
attest trust import trust.json --issuer <issuer-key-id>
attest trust refresh trust-2.jsonLe producteur signe les clés approuvées et les révocations datées dans un bundle avec une période de validité et un numéro de séquence. Le destinataire obtient l’identifiant de l’émetteur par un canal de confiance distinct avant le premier import. Une mise à jour antérieure à la séquence acceptée, un bundle altéré ou un émetteur révoqué sont refusés. La rotation d’autorité passe par un successeur désigné dans le bundle signé. L’import et l’actualisation restent explicites et hors ligne. Le verdict indique la fraîcheur du bundle selon l’horloge locale ; il ne connaît pas les révocations publiées après la dernière mise à jour.
Signer après la compilation
attest sign receipt.yaml --key <key-id> --timestamp --output signed-receipt.yaml
attest timestamp signed-receipt.yaml --output timestamped-receipt.yamlattest sign signe dans un processus qui n’a exécuté aucune commande du projet.
ATTEST_KEYS_DIR permet de conserver les clés privées hors de l’espace de travail.
Avec attest run --sign, la clé n’est chargée qu’après la sortie de la dernière
étape. --timestamp et --key sans --sign sont refusés sur attest run.
Les requêtes d’horodatage exigent HTTPS, y compris pour les URL --tsa et les
redirections. L’adresse par défaut est https://timestamp.sectigo.com/rfc3161.
Approuvez l’autorité de certification émettrice par un canal distinct avant
la vérification. attest timestamp ne signe pas à nouveau et ne charge aucune
clé privée.
Clés et empreintes
attest keys generate --name ci
attest keys list
attest keys export <key-id> --output ci.pub
attest keys import ci.pub --name team-ci
attest keys revoke <key-id>
attest keys trust-tsa sectigo-ca.crt --name sectigo
attest hash --input src/ --run 'npm run build'
attest hash --output dist/L’export des clés contient uniquement les données publiques. La gestion des clés détaille le provisionnement en CI et la rotation.
Échange dans un format standard
attest export --receipt receipt.yaml --format in-toto --output statement.json
attest import statement.json --format in-toto --report jsonL’export signe l’enveloppe avec une clé disponible ; --key permet de la choisir. --allow-unsigned autorise explicitement l’export non signé. L’import vérifie l’enveloppe avec le magasin de confiance ; il ne l’envoie pas vers le SaaS.
Les nouvelles projections SLSA conservent le reçu signé original, son signataire,
l’horodatage et le contexte public de confiance. L’import contrôle séparément
le signataire DSSE et l’autorité du reçu original ; une nouvelle signature
n’autorise pas un signataire original inconnu ou révoqué. Les sujets décrivent
les octets des fichiers artefacts : l’export a donc besoin de ces fichiers dans
l’espace de travail. L’identité de workflow du builder est vérifiée avec
--identity-bundle et --identity-policy, ou déclarée non vérifiée.
L’import accepte --identity-policy et --artifact-root pour les contrôles
du destinataire. Les signatures multiples d’enveloppe sont refusées explicitement.
Les anciens imports annoncent leurs garanties plus restreintes. La
spécification versionnée du type de build
définit cette projection ; elle ne revendique aucun niveau de build SLSA.
Autres groupes de commandes
attest capsule --help
attest image --help
attest causal --helpL’initialisation d’une capsule exige une référence OCI fixée par empreinte, plutôt qu’une étiquette. Son exécution nécessite un moteur de conteneurs. Évaluez ces parcours dans votre environnement avant de les adopter. Le guide développeur indique les sources et les tests associés.
Les commandes attest login, attest publish, attest deploy, attest status et attest cache ne sont pas exposées par le binaire actuel.