Versione 1.0.0-alpha.1ultima
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

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.
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.
Scarichi la chiave dalla cartella della release nella pagina Download.
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pubNe calcoli l'impronta. L'impronta corrisponde all'hash SHA-256 (Secure Hash Algorithm 256) del file stesso della chiave.
sha256sum release.pubSu macOS,
shasum -a 256 release.pubrestituisce lo stesso risultato.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-amd64Verified OK
Successivamente, lo aggiunga al Suo PATH e ne verifichi la versione:
install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl versionDa 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:
- Prema Aggiungi un token.
- Indichi a quale cluster è destinato, quali elementi è autorizzato a scaricare e la data di scadenza.
- 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.
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.json1.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.jsonPassaggio 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"
doneOgni 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.
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> --rawIl 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.tgzUn 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 SHA256SUMSOgni 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.
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.
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.



