AccediPrenota un briefing

Capitolo 2.4

Ottenere e verificare una release

Dove si trova ciascuna parte di una release di Nexus, come si scaricano le immagini Enterprise con un pull token e come dimostrare offline, prima di installare qualsiasi cosa, che ogni immagine, chart e file scaricato provenga da Adverant senza modifiche.

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

15 minuti di lettura

Ogni immagine in una release di Nexus è firmata con la chiave di rilascio di Adverant e ogni immagine è identificata dal proprio digest, mai da un tag. Il chart renderizzerà esclusivamente le immagini elencate per digest nel proprio lock delle immagini. Nel complesso, ciò significa che può dimostrare, sulla Sua workstation e senza alcuna connessione verso l'esterno, che ciò che sta per eseguire è esattamente ciò che Adverant ha compilato.

Presso la Harrow Port Authority abbiamo verificato tutto prima della prima installazione. Ci sono voluti circa venti minuti, per la maggior parte impiegati nel ciclo di controllo sulle immagini. Questo capitolo ripercorre lo stesso iter: dove risiede ciascuna parte della release, il pull token per le immagini Enterprise, il lock delle immagini, le verifiche con cosign corredate dai comandi esatti e cosa fare quando un controllo non va a buon fine.

Dove si trova la release

Indirizzo Cosa si scarica da qui
registry.adverant.ai Le immagini della piattaforma, all'indirizzo registry.adverant.ai/nexus/<service>@sha256:<digest>, e il chart Helm, all'indirizzo oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ La chiave pubblica della release e la relativa impronta (fingerprint), i file binari di nexusctl e i bundle offline
https://account.adverant.ai Il Suo account Adverant: le pagine Download, Pull token e comandi di installazione, Deployment e Licenza

Le immagini Community e il chart Community sono pubblici; può scaricarli senza effettuare l'accesso. Le immagini Enterprise si scaricano mediante un pull token generato dal Suo account, mentre il chart e il bundle Enterprise si trovano nella pagina Download dell'account, in base alla Sua licenza.

Download
Download
La sezione Download nell'account Adverant, organizzata per versione e canale. Ogni file è affiancato dal relativo checksum e dalla firma, mentre i componenti non inclusi nella licenza rimangono visibili in grigio, con l'indicazione del motivo.

Leggere le note di rilascio prima di qualsiasi altra cosa

Le note di rilascio sono incluse in ogni bundle come docs/RELEASE-NOTES.md, elencate nel relativo SHA256SUMS, e sono consultabili anche nella pagina della release all'interno del Suo account. Le legga prima di procedere con l'installazione o l'aggiornamento. Per la versione 1.0.0-alpha.1 sono brevi. Trattandosi della prima release, una nuova installazione non presenta nessuno dei punti relativi all'aggiornamento ivi descritti, e l'elenco dei problemi noti indica che nessuno di essi influisce su una nuova installazione eseguita seguendo la procedura documentata. Le release successive elencano ciascun problema noto insieme alla versione che lo risolve.

La pagina della release indica inoltre, in tre righe, cosa garantisce una versione alpha: le funzionalità possono subire modifiche prima della prima versione stabile, un aggiornamento preserva i dati effettuando prima un backup e le correzioni di sicurezza vengono rilasciate entro 7 giorni. A Harrow abbiamo stampato quella pagina e l'abbiamo allegata al registro delle modifiche, poiché rappresenta quanto di più simile a una dichiarazione di supporto il comitato per le modifiche potesse richiedere.

Passaggio 1: ottenere la chiave della release e verificarla tramite un secondo canale

Tutto ciò che segue si fonda su un unico file: la chiave pubblica di rilascio di Adverant. Una chiave proveniente dalla stessa fonte dell'elemento che deve garantire dimostra ben poco; pertanto, ne verifichi l'impronta confrontandola con una copia ricevuta tramite un canale diverso.

  1. Scarichi la chiave dalla cartella della release nella pagina Download.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Ne calcoli l'impronta. L'impronta corrisponde all'hash SHA-256 (Secure Hash Algorithm 256) del file stesso della chiave.

    sha256sum release.pub

    Su macOS, shasum -a 256 release.pub restituisce lo stesso risultato.

  3. La confronti, carattere per carattere, con l'impronta stampata nel Suo contratto con Adverant e nelle note di rilascio. Anche la pagina Download pubblica l'impronta, ma poiché tale copia proviene dallo stesso canale della chiave, non costituisce una verifica valida.

Se anche un solo carattere differisce, si fermi. Non proceda con l'installazione e non cerchi un'altra copia della chiave su Internet. Apra una richiesta di supporto dal Suo account riportando quanto riscontrato.

Passaggio 2: ottenere nexusctl

nexusctl è l'interfaccia a riga di comando (CLI) per l'operatore di Nexus. Viene eseguita sulla Sua workstation e legge il cluster tramite il file kubeconfig. La pagina Download mette a disposizione quattro build:

File Piattaforma
nexusctl-linux-amd64 Linux su Intel o AMD
nexusctl-darwin-arm64 macOS su Apple silicon
nexusctl-darwin-amd64 macOS su Intel
nexusctl-windows-amd64.exe Windows

Accanto a ciascun file si trova il relativo bundle di firma, avente lo stesso nome seguito dal suffisso .sigstore.json. Verifichi il file binario prima di eseguirlo:

curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64.sigstore.json
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle nexusctl-linux-amd64.sigstore.json nexusctl-linux-amd64
Verified OK

Successivamente, lo aggiunga al Suo PATH e ne verifichi la versione:

install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl version

Da questo momento in poi, nexusctl verify può eseguire i controlli sui file al posto Suo. Il Capitolo 2.5, Controlli preliminari (preflight) con nexusctl, ne illustra la funzione principale: il preflight.

Perché il flag riporta la dicitura "insecure"

Ogni comando cosign in questo capitolo include il flag --insecure-ignore-tlog=true. Le release di Nexus sono firmate con la chiave di Adverant e non vengono registrate in alcun registro di trasparenza pubblico, affinché la verifica di una release non richieda mai una connessione verso terzi, incluso Sigstore. Per impostazione predefinita, cosign richiede una voce nel registro; il flag gli indica invece di affidarsi esclusivamente alla chiave. Senza di esso, la verifica fallisce in questo modo:

Error: not enough verified log entries from transparency log: 0 < 1

Quando il flag è impostato, cosign stampa comunque la frase "Existence of the claims in the transparency log was verified offline". Si tratta di un messaggio fisso di cosign; non vi è alcuna voce di registro sottostante. La verifica della firma rispetto alla chiave è invece reale ed è la parte che conta.

Passaggio 3: un pull token, per Enterprise

Le immagini Enterprise sono protette da un pull token. Può generarne uno nel Suo account, nella pagina Pull token e comandi di installazione:

  1. Prema Aggiungi un token.
  2. Indichi a quale cluster è destinato, quali elementi è autorizzato a scaricare e la data di scadenza.
  3. Prema Copia il token e lo incolli immediatamente nel sistema in cui conserva le credenziali, poiché la pagina lo mostra solo questa volta.

Ogni token è limitato agli elementi che può scaricare e ha una data di scadenza. La revoca di un token interrompe immediatamente i nuovi pull, mentre le immagini già scaricate da un cluster continuano a funzionare. A Harrow abbiamo creato un token per ciascun cluster, in modo che la revoca del token del cluster di test non influisca mai sull'ambiente di produzione. Un'installazione Community non richiede alcun token; ne dovrà creare uno solo al momento del passaggio a Enterprise, operazione che potrà effettuare il giorno stesso.

Pull token e comandi di installazione
Pull token e comandi di installazione
I pull token nell'account Adverant. Ogni token mostra cosa è autorizzato a scaricare, chi lo ha creato e quando scade; un nuovo token viene mostrato una sola volta e la sua revoca blocca i nuovi pull senza interrompere ciò che è già in esecuzione.

Il chart non prevede un valore per il pull-secret. Poiché sono i nodi a scaricare le immagini, il token appartiene al container runtime dei nodi stessi. Su k3s, aggiunga il registro al file /etc/rancher/k3s/registries.yaml su ogni nodo e riavvii k3s su ciascuno di essi:

# /etc/rancher/k3s/registries.yaml (on every node)
configs:
  "registry.adverant.ai":
    auth: {username: "<registry-user>", password: "<pull-token>"}

<registry-user> è il nome utente del registro indicato nel Suo invito di Adverant, mentre <pull-token> è il token che ha copiato. Poiché il file contiene una credenziale, si assicuri che i permessi di lettura siano riservati esclusivamente all'utente root.

Su un cluster gestito i cui nodi non leggono tale file, copi le immagini in un registro già attendibile per i Suoi nodi e imposti global.imageRegistry su di esso; ogni nodo deve considerare attendibile il certificato Transport Layer Security (TLS) di tale registro. Il Capitolo 2.11, Varianti: archivi esterni, TLS e ingress, tratta questo scenario, mentre il capitolo 2.10, Installazione air-gapped, illustra la medesima procedura di copia per un sito privo di connessione verso l'esterno.

Passaggio 4: leggere il file di lock delle immagini

Un chart di Nexus non identifica mai un'immagine tramite tag. Ne identifica ciascuna mediante il digest del relativo indice multipiattaforma, prelevato dal lock delle immagini, un file incluso nel chart come files/images.lock.json. Il bundle offline contiene lo stesso file di lock denominato release/images.lock.json.

Scarichi il chart ed estragga il contenuto per leggere il file di lock:

helm pull oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1
tar -xzf nexus-1.0.0-alpha.1.tgz
jq -r '.version, .edition' nexus/files/images.lock.json
1.0.0-alpha.1
community

Il livello principale del file di lock indica a quale release e a quale edizione appartiene. Ogni voce sotto images descrive una singola immagine:

Campo Contenuto
svc Il servizio, ad esempio nexus-auth o nexus-postgres
index Il digest sha256: dell'indice dell'immagine, che copre sia linux/amd64 sia linux/arm64
edition community, enterprise o all per il livello dati
kind service, migrations o data-tier per i cinque archivi dati e OpenBao
verified Il momento in cui la build di rilascio ne ha verificato la firma e le attestazioni

Il chart renderizza ogni immagine nel formato <global.imageRegistry>/nexus/<svc>@<index>. Pertanto, con global.imageRegistry: registry.adverant.ai, il servizio di accesso sarà registry.adverant.ai/nexus/nexus-auth@sha256: seguito da 64 caratteri esadecimali, e nessun componente nel cluster potrà sostituirlo con qualcos'altro avente lo stesso nome.

Il file di lock è specifico per edizione. Un lock Community elenca solo le immagini la cui edizione è community o all. Un lock Enterprise elenca queste ultime più le build Enterprise. Il chart verifica questa corrispondenza a ogni rendering e, anziché procedere per tentativi, rifiuta l'operazione:

Messaggio del chart Perché
edition=enterprise but enterprise.enabled=false: they must agree I due valori relativi all'edizione nel Suo file values non coincidono
files/images.lock.json is the community lock; this install is edition enterprise Sta installando l'edizione Enterprise utilizzando il chart Community, o viceversa
image nexus-auth is not in files/images.lock.json Il chart e il relativo file di lock non corrispondono; scarichi nuovamente il chart
image ... is in the lock but was never verified by build-all La voce nel file di lock è priva del timestamp di verifica; non proceda con l'installazione
NEXUS_EDITION_INVALID edition è vuoto oppure non corrisponde a community o enterprise
RELEASE_VERSION_MISSING Il file di lock non specifica alcuna versione

Elenchi tutte le immagini e i relativi digest in un'unica operazione:

jq -r '.images[] | "\(.svc) \(.index)"' nexus/files/images.lock.json

Passaggio 5: verificare la firma di ogni immagine

Ogni indice di immagine è firmato, così come ogni manifesto di piattaforma al suo interno. Effettui la verifica tramite digest, prelevandolo direttamente dal file di lock, in modo da controllare esattamente ciò che il chart eseguirà:

jq -r '.images[] | "\(.svc)@\(.index)"' nexus/files/images.lock.json |
while read -r ref; do
  cosign verify --key release.pub --insecure-ignore-tlog=true \
    "registry.adverant.ai/nexus/$ref" > /dev/null && echo "OK $ref" || echo "FAILED $ref"
done

Ogni riga dovrebbe iniziare con OK. Sulla nostra connessione il ciclo ha richiesto alcuni minuti, perlopiù trascorsi in attesa di risposta dal registro. Poiché legge solo le firme senza scaricare i layer delle immagini, il controllo è rapido da ripetere dopo ogni aggiornamento. Una riga con FAILED indica che è necessario fermarsi: la sezione successiva spiega il significato di ciascun messaggio.

Per verificare una singola immagine, ometta il reindirizzamento per leggere nel dettaglio cosa ha controllato cosign:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
The following checks were performed on each of these signatures:
  - Existence of the claims in the transparency log was verified offline
  - The signatures were verified against the specified public key

<digest> corrisponde ai 64 caratteri esadecimali riportati nel campo index del file di lock per quell'immagine. Le immagini Enterprise richiedono il Suo pull token per questa verifica, esattamente come per qualsiasi operazione di pull dal registro.

Una sequenza verticale di cinque riquadri collegati da frecce rivolte verso il basso. In alto: "Chiave pubblica di rilascio, impronta verificata rispetto al contratto". Secondo: "Pacchetto chart nexus-1.0.0-alpha.1, firmato". Terzo: "Lock delle immagini all'interno del chart: ogni immagine identificata dal digest dell'indice, una sola edizione". Quarto: "Ogni indice di immagine, firmato, con distinta base del software (SBOM) e attestazioni di provenienza". In basso: "Pod nel namespace nexus, scaricati tramite digest". Una freccia laterale parte dal riquadro superiore e punta al secondo e al quarto riquadro, con l'etichetta "cosign verify, offline".
La catena di attendibilità, dalla chiave che ha verificato fino ai pod in esecuzione.

Entrambe le piattaforme e cosa conservare

Ogni indice di immagine contiene due manifesti di piattaforma, linux/amd64 e linux/arm64, e anch'essi sono firmati singolarmente. cosign verify dà esito positivo sia sul digest dell'indice sia sul digest di ciascuna piattaforma, pertanto un cluster con nodi misti è coperto dalla medesima verifica. Per visualizzare le due piattaforme sottostanti a un indice, richieda al registro l'indice grezzo:

docker buildx imagetools inspect registry.adverant.ai/nexus/nexus-auth@sha256:<digest> --raw

Il relativo elenco manifests riporta una voce amd64 e una voce arm64.

Conservi l'output del ciclo mostrato sopra nel Suo registro delle modifiche, accanto all'impronta che ha verificato. Quando, a distanza di mesi, qualcuno chiederà come può avere la certezza che il cluster stia eseguendo esattamente ciò che Adverant ha rilasciato, quel file e i digest del lock forniranno la risposta. A Harrow il nostro revisore ha posto esattamente questa domanda e per rispondere è bastato un minuto.

Passaggio 6: leggere le attestazioni

Ogni immagine è inoltre corredata da due attestazioni firmate, generate a partire dall'immagine stessa in fase di build: una distinta base del software (SBOM, Software Bill of Materials) e una dichiarazione di provenienza (provenance).

La SBOM è nel formato Software Package Data Exchange (SPDX), una per piattaforma, pertanto un indice ne contiene due. Elenca ogni pacchetto presente nell'immagine con la relativa licenza. Prima del rilascio, tali licenze vengono verificate rispetto a una lista di esclusione (deny list); nessuna immagine Community contiene codice soggetto a licenza GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) o Business Source License (BUSL). La dichiarazione di provenienza segue lo standard Supply-chain Levels for Software Artifacts (SLSA) v1. Specifica il commit sorgente da cui è stata compilata l'immagine, i digest delle immagini di base, nonché gli strumenti di build e le relative versioni, consentendo di ricondurre un'immagine al codice sorgente revisionato senza dover interpellare Adverant.

Entrambe vengono verificate utilizzando la chiave di rilascio già in Suo possesso:

cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type spdxjson registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type slsaprovenance1 registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

La verifica spdxjson stampa due risultati, uno per la SBOM di ciascuna piattaforma. Per visualizzare tutti gli elementi allegati a un'immagine senza eseguirne la verifica, utilizzi cosign tree:

cosign tree registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

Elenca un bundle di firma, due attestazioni spdx.dev/Document e un'attestazione slsa.dev/provenance/v1. La richiesta di un tipo non presente nell'immagine, come --type cyclonedx, restituisce l'errore none of the attestations matched the predicate type: cyclonedx. Tale errore è corretto: la release allega il formato SPDX, non CycloneDX.

Passaggio 7: verificare il chart e i file scaricati

Il chart nel registro è firmato sul proprio digest OCI (OCI sta per Open Container Initiative, il formato per immagini e artefatti utilizzato dai registri). helm pull stampa il digest scaricato; verifichi tale digest nello stesso modo utilizzato per un'immagine:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/charts/nexus@sha256:<chart-digest>

Per un file del chart scaricato localmente, o per il bundle offline, nexusctl verify verifica il file rispetto alla chiave di rilascio di Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Un esito positivo termina indicando la chiave di rilascio di Adverant e la parte iniziale della relativa impronta. Confronti questi gruppi di caratteri con l'impronta verificata al passaggio 1.

Il bundle offline è costituito da un unico file tar non compresso per ciascuna edizione, nexus-alpha-1.0.0-alpha.1-community.tar o nexus-alpha-1.0.0-alpha.1-enterprise.tar, affiancato da un file .sha256. Al suo interno contiene:

Percorso Cos'è
release/images.lock.json Il file di lock delle immagini per quella specifica edizione
release/facts.json I dati della release: versione, edizione, architetture e l'impronta della chiave di rilascio
images/<service>/ Ogni immagine con entrambe le piattaforme, la relativa firma e le attestazioni
charts/nexus-1.0.0-alpha.1.tgz Il chart
sbom/ La SBOM SPDX di ogni immagine, per ciascuna piattaforma
docs/ Le note di rilascio, la guida all'installazione air-gap e i file values di esempio
SHA256SUMS e SHA256SUMS.sigstore.json Il checksum di ogni file e la relativa firma

La chiave pubblica di rilascio non è mai inclusa nel bundle; una chiave fornita insieme all'elemento che deve firmare non dimostra nulla. Verifichi l'intero bundle con due comandi, eseguendoli dall'interno della relativa cartella:

sha256sum -c SHA256SUMS
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS

Ogni riga del primo comando dovrebbe terminare con OK, mentre il secondo dovrebbe stampare Verified OK. Il Capitolo 2.10, Installazione air-gapped, prosegue da questo punto con la gestione del bundle: il caricamento delle immagini nel Suo registro, la nuova verifica di ciascuna di esse al suo interno e il controllo end-to-end integrato nel bundle stesso.

Come verificare un file scaricato
Come verificare un file scaricato
Come verificare un file scaricato, nell'account Adverant. Due controlli offline, un'illustrazione di un esito positivo e di uno negativo, e l'impronta della chiave di rilascio suddivisa in gruppi di quattro caratteri per facilitarne il confronto visivo.

Quando la verifica di una firma non riesce

Si fermi. Non proceda con l'installazione e non modifichi il comando finché non dà esito positivo. Una verifica della firma non riuscita dimostra che il sistema sta funzionando correttamente: significa che il file in Suo possesso non è quello firmato da Adverant, oppure che la chiave che detiene non appartiene ad Adverant.

Cosa si vede Cosa significa Cosa fare
accepted signatures do not match threshold, Found: 0, Expected 1 (uscita 1) L'immagine è firmata, ma non con la chiave specificata Verifichi di aver utilizzato la chiave di rilascio di cui ha controllato l'impronta al passaggio 1
no signatures found (uscita 10) Nessun elemento corrispondente a quel digest risulta firmato Verifichi che il digest provenga dal file di lock; non esegua mai la verifica su un tag
not enough verified log entries from transparency log: 0 < 1 Manca il flag --insecure-ignore-tlog=true Aggiunga il flag; l'immagine non presenta alcun problema
none of the attestations matched the predicate type Ha richiesto un tipo di attestazione che l'immagine non contiene Utilizzi spdxjson o slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Un file scaricato è stato modificato dopo l'apposizione della firma Lo scarichi nuovamente
FAILED da sha256sum -c Un file non corrisponde a quello su cui è stato calcolato il checksum Lo scarichi nuovamente

Se un download fallisce per due volte, apra una richiesta di supporto dal Suo account riportando il nome del file e il messaggio di errore. Conservi il file che ha generato l'errore; il Suo team di sicurezza potrebbe richiederlo.

In un'installazione che carica le release da disco, la console esegue i medesimi controlli e rifiuta una release la cui firma non corrisponde alla chiave installata, restituendo l'errore MEDIA_SIGNATURE_INVALID. Indica cosa ha controllato, in quale ordine, dove si è arrestata e conferma che nulla è stato modificato: nessuna immagine è stata caricata e la versione in esecuzione è rimasta intatta.

Importazione da supporto non riuscita
Importazione da supporto non riuscita
Una release su disco che non ha superato la verifica della firma. Si notino i controlli elencati in ordine fino a quello che ha bloccato il processo, le impronte della chiave attesa e di quella rilevata, e l'indicazione esplicita che nulla è stato caricato o modificato.

Una volta che la chiave, le immagini e il chart hanno superato tutte le verifiche, il passaggio successivo consiste nell'eseguire i controlli preliminari (preflight) sul Suo cluster, come descritto nel capitolo 2.5, Controlli preliminari (preflight) con nexusctl.