Log indBook en briefing

Kapitel 2.4

Hentning og verificering af en udgivelse

Hvor hver del af en Nexus-udgivelse ligger, hvordan Enterprise-images hentes med et pull-token, og hvordan man beviser, at hvert image, chart og download kom uændret fra Adverant, offline, før du installerer noget.

Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

15 minutters læsetid

Hvert image i en Nexus-udgivelse er signeret med Adverants udgivelsesnøgle, og hvert image navngives med sit digest, aldrig med et tag. Chartet gengiver kun images, der er opført med digest i dets egen images-lås. Tilsammen betyder det, at du på din egen arbejdsstation og uden forbindelse til nogen kan bevise, at det, du skal til at køre, er præcis det, Adverant har bygget.

Hos Harrow Port Authority kontrollerede vi alt før den første installation. Det tog cirka tyve minutter, og det meste af tiden gik med løkken over images. Dette kapitel følger samme spor: hvor hver del af udgivelsen befinder sig, pull-tokenet til Enterprise-images, images-låsen, cosign-kontrollerne med deres præcise kommandoer, og hvad du skal gøre, når en kontrol fejler.

Hvor udgivelsen ligger

Adresse Hvad du henter der
registry.adverant.ai Platforms-images på registry.adverant.ai/nexus/<service>@sha256:<digest> og Helm-chartet på oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ Udgivelsens offentlige nøgle og dens fingeraftryk, de binære nexusctl-filer og offline-pakkerne
https://account.adverant.ai Din Adverant-konto: Downloads, Pull-tokens og installationskommandoer, Udrulninger samt licenssiderne

Community-images og Community-chartet er offentlige; du kan hente dem uden at logge ind. Enterprise-images hentes med et pull-token fra din konto, og Enterprise-chartet og -pakken ligger på kontoens Downloads-side, som følger din licens.

Downloads
Downloads
Downloads på Adverant-kontoen, efter version og kanal. Hver fil har sin kontrolsum og signatur ved siden af sig, og dele uden for licensen forbliver vist med gråt sammen med årsagen.

Læs udgivelsesnoterne før alt andet

Udgivelsesnoterne leveres i hver pakke som docs/RELEASE-NOTES.md, opført i dens SHA256SUMS, og de samme noter findes på udgivelsessiden på din konto. Læs dem, før du installerer eller opgraderer. For 1.0.0-alpha.1 er de korte. Det er den første udgivelse, så en ny installation har ingen af de opgraderingspunkter, de beskriver, og listen over kendte problemer angiver, at intet på den påvirker en ny installation, der følger de dokumenterede trin. Senere udgivelser angiver hvert kendt problem med den version, der løser det.

Udgivelsessiden angiver også på tre linjer, hvad en alfa-udgivelse lover: funktioner kan ændre sig før den første stabile version, en opgradering bevarer dine data og tager en sikkerhedskopi først, og sikkerhedsrettelser kommer inden for 7 dage. Vi udskrev den side og lagde den i ændringsjournalen hos Harrow, fordi det er det tætteste på en supportgaranti, som ændringsudvalget ville bede om.

Trin 1: Hent udgivelsesnøglen, og kontrollér den via en anden vej

Alt nedenfor hviler på én fil: Adverants offentlige udgivelsesnøgle. En nøgle, der kom fra samme sted som det, den står inde for, beviser meget lidt, så kontroller dens fingeraftryk mod en kopi, du har modtaget på en anden måde.

  1. Download nøglen fra udgivelsens mappe under Downloads.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Find dens fingeraftryk. Fingeraftrykket er SHA-256 (Secure Hash Algorithm 256) for selve nøglefilen.

    sha256sum release.pub

    På macOS giver shasum -a 256 release.pub det samme svar.

  3. Sammenlign det, tegn for tegn, med det fingeraftryk, der er trykt i din kontrakt med Adverant og i udgivelsesnoterne. Downloads offentliggør også fingeraftrykket, men den kopi kom ad samme vej som nøglen, så det udgør ikke kontrollen.

Hvis et tegn afviger, skal du stoppe. Installer ikke, og gå ikke ud på internettet for at lede efter en anden kopi af nøglen. Opret en supportanmodning fra din konto, og angiv, hvad du så.

Trin 2: Hent nexusctl

nexusctl er Nexus-operatørens kommandolinjegrænseflade (CLI). Den kører på din arbejdsstation og læser din klynge gennem din kubeconfig. Downloads tilbyder fire builds:

Fil Platform
nexusctl-linux-amd64 Linux på Intel eller AMD
nexusctl-darwin-arm64 macOS på Apple silicon
nexusctl-darwin-amd64 macOS på Intel
nexusctl-windows-amd64.exe Windows

Ved siden af hver fil ligger dens signaturpakke med det samme navn efterfulgt af .sigstore.json. Kontroller den binære fil, før du kører den:

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

Placer den derefter i din søgesti (PATH), og spørg om dens version:

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

Herfra kan nexusctl verify udføre filkontrollerne for dig. Kapitel 2.5, Forhåndskontrol med nexusctl, dækker dens hovedopgave, forhåndskontrol.

Hvorfor flaget siger "insecure"

Hver cosign-kommando i dette kapitel har --insecure-ignore-tlog=true. Nexus-udgivelser signeres med Adverants nøgle og registreres ikke i nogen offentlig transparenslog, så kontrol af en udgivelse aldrig kræver forbindelse til nogen, herunder Sigstore. Som standard insisterer cosign på en logpost; flaget beder den om kun at stole på nøglen. Uden det fejler kontrollen sådan her:

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

Når flaget er sat, udskriver cosign stadig sætningen "Existence of the claims in the transparency log was verified offline". Det er en fast formulering i cosign; der ligger ingen logpost bag den. Signaturkontrollen mod nøglen er reel, og det er den del, der tæller.

Trin 3: Et pull-token til Enterprise

Enterprise-images ligger bag et pull-token. Du opretter et på din konto under Pull-tokens og installationskommandoer:

  1. Tryk på Tilføj et token.
  2. Angiv, hvilken klynge det er til, hvad det må hente, og hvornår det udløber.
  3. Tryk på Kopiér tokenet, og indsæt det direkte der, hvor du opbevarer legitimationsoplysninger, da siden kun viser det denne ene gang.

Hvert token er begrænset til det, det må hente, og har en udløbsdato. Tilbagekaldelse af et token stopper straks nye pulls; images, som en klynge allerede har hentet, fortsætter med at køre. Vi oprettede ét token pr. klynge hos Harrow, så tilbagekaldelse af testklyngens token berører aldrig produktionen. En Community-installation kræver slet ikke noget token; du opretter først et, når du skifter til Enterprise, og du kan oprette det samme dag.

Pull-tokens og installationskommandoer
Pull-tokens og installationskommandoer
Pull-tokens på Adverant-kontoen. Hvert token viser, hvad det må hente, hvem der har oprettet det, og hvornår det udløber; et nyt token vises én gang, og tilbagekaldelse af et token stopper nye pulls uden at stoppe noget, der allerede kører.

Chartet har ingen pull-secret-værdi. Dine noder henter disse images, så tokenet hører til nodernes container-runtime. På k3s skal du føje dette registry til /etc/rancher/k3s/registries.yaml på hver node og genstarte k3s der:

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

<registry-user> er det registry-brugernavn, der står i din Adverant-invitation, og <pull-token> er det token, du kopierede. Filen indeholder en legitimationsoplysning, så sørg for, at den kun kan læses af root.

På en administreret klynge, hvis noder ikke læser den fil, skal du kopiere disse images ind i et registry, som dine noder allerede stoler på, og sætte global.imageRegistry til det; hver node skal stole på det pågældende registrys Transport Layer Security-certifikat (TLS). Kapitel 2.11, Variationer: eksterne lagre, TLS og ingress, dækker dette, og kapitel 2.10, Air-gapped installation, dækker den samme kopiering for et sted uden rute ud.

Trin 4: Læs image-låsefilen

Et Nexus-chart navngiver aldrig et image med tag. Det navngiver hvert enkelt med digestet for dets multi-platformsindeks, hentet fra images-låsen, en fil, som chartet medbringer som files/images.lock.json. Offline-pakken medbringer den samme lås som release/images.lock.json.

Hent chartet, og pak det ud for at læse låsen:

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

Låsens øverste niveau angiver, hvilken udgivelse og hvilken udgave den hører til. Hver post under images beskriver ét image:

Felt Hvad den indeholder
svc Tjenesten, f.eks. nexus-auth eller nexus-postgres
index sha256:-digestet for dette images indeks, som dækker både linux/amd64 og linux/arm64
edition community, enterprise eller all for datalaget
kind service, migrations eller data-tier for de fem datalagre og OpenBao
verified Hvornår udgivelses-buildet verificerede dets signatur og attesteringer

Chartet gengiver hvert image som <global.imageRegistry>/nexus/<svc>@<index>. Så med global.imageRegistry: registry.adverant.ai er login-tjenesten registry.adverant.ai/nexus/nexus-auth@sha256: efterfulgt af 64 hexadecimale tegn, og intet i klyngen kan udskifte det med noget andet med samme navn.

Låsen gælder pr. udgave. En Community-lås viser kun images, hvis udgave er community eller all. En Enterprise-lås viser disse plus Enterprise-builds. Chartet kontrollerer dette, hver gang det gengives, og afviser frem for at gætte:

Hvad chartet siger Hvorfor
edition=enterprise but enterprise.enabled=false: they must agree De to udgaveværdier i din værdifil stemmer ikke overens
files/images.lock.json is the community lock; this install is edition enterprise Du installerer Enterprise fra Community-chartet eller omvendt
image nexus-auth is not in files/images.lock.json Chartet og dets lås hører ikke sammen; hent chartet igen
image ... is in the lock but was never verified by build-all Låseposten har intet verificeringstidspunkt; installer ikke fra den
NEXUS_EDITION_INVALID edition er tom eller ikke en af community og enterprise
RELEASE_VERSION_MISSING Låsen angiver ingen version

Vis hvert image og digest på én gang:

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

Trin 5: Verificér hvert images signatur

Hvert image-indeks er signeret, og det samme gælder hvert platformsmanifest i det. Verificer via digest direkte fra låsen, så du kontrollerer præcis det, chartet vil køre:

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

Hver linje bør starte med OK. På vores forbindelse tog løkken et par minutter, hvoraf det meste af tiden gik med at vente på dette registry. Den læser kun signaturerne og henter ingen image-lag, hvilket gør det nemt at gentage efter hver opgradering. En FAILED-linje betyder stop: næste afsnit forklarer, hvad hver meddelelse betyder.

For et enkelt image alene kan du udelade omdirigeringen og læse, hvad cosign kontrollerede:

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> er de 64 hexadecimale tegn fra låsens index for det pågældende image. Enterprise-images kræver dit pull-token til denne kontrol, ligesom de gør ved ethvert pull fra dette registry.

En lodret kæde af fem bokse forbundet med nedadgående pile. Øverst: "Udgivelsens offentlige nøgle, fingeraftryk kontrolleret mod din kontrakt". Anden: "Chart-pakke nexus-1.0.0-alpha.1, signeret". Tredje: "Images-lås inde i chartet: hvert image efter indeks-digest, én udgave". Fjerde: "Hvert image-indeks, signeret, med software-stykliste (SBOM) og oprindelsesattesteringer". Nederst: "Pods i namespace nexus, hentet via digest". En sidepil fra den øverste boks peger på den anden og fjerde boks med teksten "cosign verify, offline".
Hvad der står inde for hvad, fra den nøgle, du kontrollerede, til de pods, der kører.

Begge platforme, og hvad du skal gemme

Hvert image-indeks indeholder to platformsmanifester, linux/amd64 og linux/arm64, og hvert af dem er også signeret. cosign verify lykkes på indeks-digestet og på begge platforms-digests, så en klynge med blandede noder er dækket af den samme kontrol. For at se de to platforme bag et indeks skal du bede dette registry om det rå indeks:

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

Dets manifests-liste angiver én amd64-post og én arm64-post.

Gem outputtet fra løkken ovenfor sammen med din ændringsjournal ved siden af det fingeraftryk, du kontrollerede. Når nogen måneder senere spørger, hvordan du ved, at klyngen kører det, Adverant har leveret, giver den fil og låsens digests svaret. Vores revisor hos Harrow stillede præcis det spørgsmål, og svaret tog et minut.

Trin 6: Læs attesteringerne

Hvert image medbringer også to signerede attesteringer, der er oprettet ud fra det pågældende image på build-tidspunktet: en software-stykliste (SBOM, software bill of materials) og en oprindelseserklæring (provenance statement).

Denne SBOM er i Software Package Data Exchange-format (SPDX), én pr. platform, så et indeks medbringer to. Den viser hver pakke i det pågældende image med dens licens. Før udgivelsen kontrolleres disse licenser mod en afvisningsliste; intet Community-image indeholder kode under GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) eller Business Source License (BUSL). Oprindelseserklæringen er Supply-chain Levels for Software Artifacts (SLSA) v1. Den angiver det kilde-commit, som det pågældende image blev bygget fra, digests for basis-images samt build-værktøjerne og deres versioner, så et image kan spores tilbage til den gennemgåede kildekode uden at spørge Adverant.

Begge kontrolleres mod den udgivelsesnøgle, du allerede har:

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>

spdxjson-kontrollen udskriver to resultater, ét for hver platforms SBOM. For at se alt, der er knyttet til et image, uden at verificere det, skal du bruge cosign tree:

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

Den viser én signaturpakke, to spdx.dev/Document-attesteringer og én slsa.dev/provenance/v1-attestering. Hvis du beder om en type, som det pågældende image ikke medbringer, f.eks. --type cyclonedx, fejler det med none of the attestations matched the predicate type: cyclonedx. Den fejl er korrekt; udgivelsen vedhæfter SPDX, ikke CycloneDX.

Trin 7: Verificér chartet og dine downloads

Chartet i dette registry er signeret på sit OCI-digest (OCI er Open Container Initiative, det image- og artefaktformat, som registries bruger). helm pull udskriver det digest, den hentede; kontroller det digest på samme måde som et image:

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

For en chart-fil, du har downloadet, eller for offline-pakken, kontrollerer nexusctl verify filen mod Adverants udgivelsesnøgle:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Et godkendt resultat slutter med at angive Adverants udgivelsesnøgle og starten på dens fingeraftryk. Sammenlign disse grupper med det fingeraftryk, du kontrollerede i trin 1.

Offline-pakken er én ukomprimeret tar-fil pr. udgave, nexus-alpha-1.0.0-alpha.1-community.tar eller nexus-alpha-1.0.0-alpha.1-enterprise.tar, med en .sha256-fil ved siden af. Indeni indeholder den:

Sti Hvad det er
release/images.lock.json Images-låsen for den pågældende udgave
release/facts.json Udgivelsesfakta: version, udgave, arkitekturer og udgivelsesnøglens fingeraftryk
images/<service>/ Hvert image med begge platforme, dets signatur og dets attesteringer
charts/nexus-1.0.0-alpha.1.tgz Chartet
sbom/ SPDX SBOM for hvert image, pr. platform
docs/ Udgivelsesnoterne, vejledningen til air-gap-installation og eksempelværdier
SHA256SUMS og SHA256SUMS.sigstore.json Kontrolsummen for hver fil og dens signatur

Udgivelsens offentlige nøgle ligger aldrig inde i pakken; en nøgle, der leveres sammen med det, den signerer, beviser intet. Kontroller hele pakken med to kommandoer inde fra dens mappe:

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

Hver linje i den første bør slutte med OK, og den anden bør udskrive Verified OK. Kapitel 2.10, Air-gapped installation, tager pakken derfra: indlæsning af images i dit eget registry, fornyet verificering af hvert enkelt der samt pakkens egen end-to-end-kontrol.

Sådan kontrollerer du et download
Sådan kontrollerer du et download
Sådan kontrollerer du et download på Adverant-kontoen. To offline-kontroller, et billede af et godkendt og et afvist resultat samt udgivelsesnøglens fingeraftryk i grupper af fire til visuel sammenligning.

Når en signatur ikke kan verificeres

Stop. Installer ikke, og ændr ikke kommandoen, indtil den går igennem. En mislykket signaturkontrol viser, at systemet virker: det betyder, at den fil, du har, ikke er den fil, Adverant signerede, eller at den nøgle, du har, ikke er Adverants.

Hvad du ser Hvad det betyder Hvad du skal gøre
accepted signatures do not match threshold, Found: 0, Expected 1 (exit 1) Dette image er signeret, men ikke med den nøgle, du angav Kontroller, at du brugte den udgivelsesnøgle, hvis fingeraftryk du kontrollerede i trin 1
no signatures found (exit 10) Intet på det digest er signeret Kontroller, at digestet kom fra låsen; verificer aldrig et tag
not enough verified log entries from transparency log: 0 < 1 --insecure-ignore-tlog=true mangler Tilføj flaget; der er intet galt med dette image
none of the attestations matched the predicate type Du bad om en attesteringstype, som dette image ikke medbringer Brug spdxjson eller slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature En downloadet fil blev ændret, efter at den blev signeret Download den igen
FAILED fra sha256sum -c En fil er ikke den fil, der blev beregnet kontrolsum for Download den igen

Hvis et download fejler to gange, skal du oprette en supportanmodning fra din konto og angive filnavnet og meddelelsen. Gem den fejlende fil; dit sikkerhedsteam vil måske se den.

På en installation, der indlæser udgivelser fra disk, kører konsollen de samme kontroller og afviser en udgivelse, hvis signatur ikke matcher den installerede nøgle, med MEDIA_SIGNATURE_INVALID. Den oplyser, hvad den kontrollerede, i hvilken rækkefølge, hvor den stoppede, og at intet blev ændret: intet image indlæst, den kørende version uberørt.

Import fra medie mislykkedes
Import fra medie mislykkedes
En udgivelse på disk, der dumpede i signaturkontrollen. Bemærk kontrollerne i rækkefølge med den, der stoppede den, de forventede og fundne nøglefingeraftryk samt den klare meddelelse om, at intet blev indlæst eller ændret.

Når nøglen, disse images og chartet alle er godkendt, er næste trin forhåndskontrol mod din klynge i kapitel 2.5, Forhåndskontrol med nexusctl.