Logg innBestill en gjennomgang

Kapittel 2.4

Hente og verifisere en utgivelse

Hvor hver del av en Nexus-utgivelse ligger, hvordan Enterprise-avbildninger hentes med et pull-token, og hvordan du beviser at hver avbildning, hvert chart og hver nedlasting kom uendret fra Adverant, frakoblet, før du installerer noe.

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

15 minutter å lese

Hvert avbild (image) i en Nexus-utgivelse er signert med Adverants utgivelsesnøkkel, og hvert avbild er navngitt etter sjekksummen (digest) sin, aldri etter en tagg. Chartet vil kun gjengi avbilder som er oppført med sjekksum i sin egen avbildslås (images lock). Samlet sett betyr dette at du på din egen arbeidsstasjon, og helt uten nettforbindelse til noen, kan bevise at det du er i ferd med å kjøre, er nøyaktig det Adverant har bygget.

Hos Harrow Port Authority kontrollerte vi alt før den første installasjonen. Det tok omtrent tjue minutter, og mesteparten av tiden gikk med til løkken gjennom avbildene. Dette kapittelet følger den samme ruten: hvor hver del av utgivelsen befinner seg, hentetokenet (pull token) for Enterprise-avbilder, avbildslåsen, cosign-kontrollene med de nøyaktige kommandoene deres, og hva du skal gjøre når en kontroll feiler.

Hvor utgivelsen ligger

Adresse Hva du henter der
registry.adverant.ai Plattformavbildene, 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/ Den offentlige utgivelsesnøkkelen og fingeravtrykket dens, nexusctl-binærfilene og de frakoblede pakkene (offline bundles)
https://account.adverant.ai Adverant-kontoen din: Nedlastinger, Hentetokener og installasjonskommandoer, Utrullinger og lisenssidene

Community-avbilder og Community-chartet er offentlige; du kan hente dem uten å logge inn. Enterprise-avbilder hentes med et hentetoken fra kontoen din, og Enterprise-chartet og -pakken ligger på kontoens Nedlastinger-side, som følger lisensen din.

Nedlastinger
Nedlastinger
Nedlastinger i Adverant-kontoen, etter versjon og kanal. Hver fil har sin egen kontrollsum og signatur ved siden av seg, og deler som ligger utenfor lisensen, blir stående i listen, nedtonet i grått, med begrunnelsen.

Les utgivelsesnotatene før alt annet

Utgivelsesnotatene følger med i hver pakke som docs/RELEASE-NOTES.md, oppført i dens SHA256SUMS, og de samme notatene finnes på utgivelsessiden i kontoen din. Les dem før du installerer eller oppgraderer. For 1.0.0-alpha.1 er de korte. Det er den første utgivelsen, så en ny installasjon har ingen av oppgraderingspunktene de beskriver, og listen over kjente feil sier at ingenting i den påvirker en ny installasjon som følger de dokumenterte trinnene. Senere utgivelser fører opp hver kjente feil sammen med versjonen som retter den.

Utgivelsessiden sier også, på tre linjer, hva en alfautgivelse lover: funksjoner kan endre seg før den første stabile versjonen, en oppgradering beholder dataene dine og tar en sikkerhetskopi først, og sikkerhetsoppdateringer kommer innen 7 dager. Vi skrev ut den siden og la den i endringsloggen hos Harrow, fordi det er det nærmeste en støtteerklæring endringsutvalget ville be om.

Trinn 1: hent utgivelsesnøkkelen, og kontroller den via en annen vei

Alt nedenfor hviler på én fil: Adverants offentlige utgivelsesnøkkel. En nøkkel som kommer fra samme sted som det den går god for, beviser svært lite, så kontroller fingeravtrykket mot en kopi du har mottatt på en annen måte.

  1. Last ned nøkkelen fra utgivelsens mappe under Nedlastinger.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Beregn fingeravtrykket dens. Fingeravtrykket er SHA-256 (Secure Hash Algorithm 256) av selve nøkkelfilen.

    sha256sum release.pub

    På macOS gir shasum -a 256 release.pub det samme svaret.

  3. Sammenlign det, tegn for tegn, med fingeravtrykket som er trykt i kontrakten din med Adverant og i utgivelsesnotatene. Nedlastinger publiserer også fingeravtrykket, men den kopien kom samme vei som nøkkelen, så det teller ikke som en kontroll.

Hvis et eneste tegn avviker, må du stoppe. Ikke installer, og ikke let etter en annen kopi av nøkkelen på internett. Opprett en støttehenvendelse fra kontoen din og oppgi hva du så.

Trinn 2: hent nexusctl

nexusctl er kommandolinjegrensesnittet (CLI) for Nexus-operatøren. Det kjører på arbeidsstasjonen din og leser klyngen din gjennom din kubeconfig. Nedlastinger tilbyr fire bygg:

Fil Plattform
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 av hver fil ligger signaturpakken dens, med samme navn og .sigstore.json til slutt. Kontroller binærfilen før du kjø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

Legg den deretter i søkestien (path) din og spør etter versjonen:

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

Herfra og ut kan nexusctl verify utføre filkontrollene for deg. Kapittel 2.5, Forhåndskontroll med nexusctl, dekker hovedoppgaven dens, forhåndskontroll (preflight).

Hvorfor flagget sier «insecure»

Hver cosign-kommando i dette kapittelet har med --insecure-ignore-tlog=true. Nexus-utgivelser er signert med Adverants nøkkel og registreres ikke i noen offentlig åpenhetslogg (transparency log), slik at kontroll av en utgivelse aldri krever forbindelse til noen, inkludert Sigstore. Som standard krever cosign en loggoppføring; flagget forteller den at den kun skal stole på nøkkelen. Uten flagget feiler kontrollen slik:

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

Når flagget er satt, skriver cosign likevel ut setningen «Existence of the claims in the transparency log was verified offline». Dette er en fast formulering i cosign; det ligger ingen loggoppføring bak. Signaturkontrollen mot nøkkelen er reell, og det er den delen som betyr noe.

Trinn 3: et pull-token, for Enterprise

Enterprise-avbilder ligger bak et hentetoken. Du oppretter et i kontoen din, under Hentetokener og installasjonskommandoer:

  1. Trykk på Legg til et token.
  2. Angi hvilken klynge det gjelder for, hva det har lov til å hente, og når det utløper.
  3. Trykk på Kopier tokenet og lim det rett inn der du oppbevarer påloggingsinformasjon, for siden viser det kun denne ene gangen.

Hvert token er begrenset til hva det kan hente, og har en utløpsdato. Hvis du trekker tilbake et token, stoppes nye hentinger umiddelbart; avbilder som en klynge allerede har hentet, fortsetter å kjøre. Vi opprettet ett token per klynge hos Harrow, slik at det å trekke tilbake testklyngens token aldri berører produksjonsmiljøet. En Community-installasjon trenger ikke noe token i det hele tatt; du oppretter kun et når du går over til Enterprise, og du kan opprette det samme dag.

Hentetokener og installasjonskommandoer
Hentetokener og installasjonskommandoer
Hentetokener i Adverant-kontoen. Hvert token viser hva det kan hente, hvem som opprettet det og når det utløper; et nytt token vises én gang, og hvis du trekker tilbake et token, stoppes nye hentinger uten å stoppe noe som allerede kjører.

Chartet har ingen verdi for pull-secret. Det er nodene dine som henter avbildene, så tokenet hører hjemme i nodenes kjøremiljø for containere (container runtime). På k3s legger du til registeret i /etc/rancher/k3s/registries.yaml på hver node og starter k3s på nytt der:

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

<registry-user> er brukernavnet for registeret i Adverant-invitasjonen din, og <pull-token> er tokenet du kopierte. Filen inneholder påloggingsinformasjon, så sørg for at den kun kan leses av root.

På en administrert klynge der nodene ikke leser den filen, kopierer du avbildene inn i et register som nodene dine allerede stoler på, og setter global.imageRegistry til dette; hver node må stole på dette registerets TLS-sertifikat (Transport Layer Security). Kapittel 2.11, Variasjoner: eksterne lagre, TLS og ingress, dekker dette, og kapittel 2.10, Luftgap-installasjon (air-gapped), dekker den samme kopieringen for et anlegg uten rute ut.

Trinn 4: les avbildningslåsen

Et Nexus-chart navngir aldri et avbild med en tagg. Det navngir hvert enkelt etter sjekksummen (digest) til dets multiplattform-indeks, hentet fra avbildslåsen, en fil chartet har med seg som files/images.lock.json. Den frakoblede pakken har med seg den samme låsen som release/images.lock.json.

Hent chartet og pakk det ut for å lese 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 nivå angir hvilken utgivelse og hvilken utgave den tilhører. Hver oppføring under images beskriver ett avbild:

Felt Hva den inneholder
svc Tjenesten, som nexus-auth eller nexus-postgres
index sha256:-sjekksummen til avbildets indeks, som dekker både linux/amd64 og linux/arm64
edition community, enterprise eller all for datalaget
kind service, migrations eller data-tier for de fem datalagrene og OpenBao
verified Når utgivelsesbygget verifiserte signaturen og attestasjonene sine

Chartet gjengir hvert avbild som <global.imageRegistry>/nexus/<svc>@<index>. Så med global.imageRegistry: registry.adverant.ai er påloggingstjenesten registry.adverant.ai/nexus/nexus-auth@sha256: etterfulgt av 64 heksadesimale tegn, og ingenting i klyngen kan bytte den ut med noe annet med samme navn.

Låsen er spesifikk per utgave. En Community-lås fører kun opp avbilder der utgaven er community eller all. En Enterprise-lås fører opp disse pluss Enterprise-byggene. Chartet kontrollerer dette hver gang det gjengis, og nekter i stedet for å gjette:

Hva chartet sier Hvorfor
edition=enterprise but enterprise.enabled=false: they must agree De to utgaveverdiene i verdifilen din samsvarer ikke
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 låsen hører ikke sammen; hent chartet på nytt
image ... is in the lock but was never verified by build-all Låsoppføringen mangler verifiseringstidspunkt; ikke installer fra den
NEXUS_EDITION_INVALID edition er tom eller ikke en av community og enterprise
RELEASE_VERSION_MISSING Låsen oppgir ingen versjon

Før opp hvert avbild og hver sjekksum på én gang:

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

Trinn 5: verifiser signaturen til hver avbildning

Hver avbildsindeks er signert, og det samme er hvert plattformmanifest inni den. Verifiser etter sjekksum, rett fra låsen, slik at du kontrollerer nøyaktig det chartet vil kjø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 skal starte med OK. På forbindelsen vår tok løkken noen få minutter, og mesteparten av tiden gikk med til å vente på registeret. Den leser kun signaturene og henter ingen avbildslag (image layers), noe som gjør det raskt og rimelig å gjenta etter hver oppgradering. En FAILED-linje betyr stopp: neste avsnitt forklarer hva hver melding betyr.

For ett enkelt avbild alene kan du droppe omdirigeringen og lese hva cosign kontrollerte:

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 heksadesimale tegnene fra låsens index for det aktuelle avbildet. Enterprise-avbilder trenger hentetokenet ditt for denne kontrollen, akkurat som ved enhver annen henting fra registeret.

En vertikal kjede med fem bokser bundet sammen av piler som peker nedover. Øverst: «Offentlig utgivelsesnøkkel, fingeravtrykk kontrollert mot kontrakten din». Andre: «Chartpakke nexus-1.0.0-alpha.1, signert». Tredje: «Avbildslås inni chartet: hvert avbild etter indekssjekksum, én utgave». Fjerde: «Hver avbildsindeks, signert, med programvareinnholdsliste (SBOM) og opprinnelsesattestasjoner». Nederst: «Podder i navnerommet nexus, hentet etter sjekksum». En sidepil fra den øverste boksen peker mot den andre og fjerde boksen, merket «cosign verify, offline».
Hva som går god for hva, fra nøkkelen du kontrollerte til poddene som kjører.

Begge plattformer, og hva du skal ta vare på

Hver avbildsindeks inneholder to plattformmanifester, linux/amd64 og linux/arm64, og hvert av dem er også signert. cosign verify lykkes på indekssjekksummen og på begge plattformsjekksummene, slik at en klynge med blandede noder dekkes av den samme kontrollen. For å se de to plattformene bak en indeks, kan du be registeret om råindeksen:

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

Listen manifests oppgir én amd64-oppføring og én arm64-oppføring.

Ta vare på utdataene fra løkken ovenfor i endringsloggen din, ved siden av fingeravtrykket du kontrollerte. Når noen spør, måneder senere, hvordan du vet at klyngen kjører det Adverant leverte, gir den filen og låsens sjekksummer svaret. Revisoren vår hos Harrow stilte nettopp det spørsmålet, og svaret tok et minutt.

Trinn 6: les attestasjonene

Hvert avbild har også med seg to signerte attestasjoner, opprettet fra avbildet på byggetidspunktet: en programvareinnholdsliste (SBOM – software bill of materials) og en opprinnelseserklæring (provenance statement).

SBOM-en er i SPDX-format (Software Package Data Exchange), én per plattform, så en indeks har med seg to. Den fører opp hver pakke i avbildet med tilhørende lisens. Før utgivelse kontrolleres disse lisensene mot en blokkeringsliste; ingen Community-avbilder inneholder kode under GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) eller Business Source License (BUSL). Opprinnelseserklæringen er på nivået Supply-chain Levels for Software Artifacts (SLSA) v1. Den oppgir kildekode-commiten avbildet ble bygget fra, sjekksummene til basisavbildene samt byggeverktøyene og versjonene deres, slik at et avbild kan spores tilbake til den gjennomgåtte kildekoden uten å måtte spørre Adverant.

Begge kontrolleres mot utgivelsesnøkkelen 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 skriver ut to resultater, ett for hver plattforms SBOM. For å se alt som er knyttet til et avbild uten å verifisere det, bruker du cosign tree:

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

Den fører opp én signaturpakke, to spdx.dev/Document-attestasjoner og én slsa.dev/provenance/v1-attestasjon. Hvis du ber om en type som avbildet ikke har med seg, for eksempel --type cyclonedx, feiler det med none of the attestations matched the predicate type: cyclonedx. Denne feilen er korrekt; utgivelsen legger ved SPDX, ikke CycloneDX.

Trinn 7: verifiser chartet og nedlastingene

Chartet i registeret er signert på sin OCI-sjekksum (OCI er Open Container Initiative, formatet for avbilder og artefakter som registre bruker). helm pull skriver ut sjekksummen den hentet; kontroller denne sjekksummen på samme måte som et avbild:

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

For en chartfil du har lastet ned, eller for den frakoblede pakken, kontrollerer nexusctl verify filen mot Adverants utgivelsesnøkkel:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Et godkjent resultat avsluttes med å oppgi Adverants utgivelsesnøkkel og starten på fingeravtrykket dens. Sammenlign disse gruppene med fingeravtrykket du kontrollerte i trinn 1.

Den frakoblede pakken er én ukomprimert tar-fil per utgave, 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 av. Inni inneholder den:

Sti Hva det er
release/images.lock.json Avbildslåsen for den aktuelle utgaven
release/facts.json Utgivelsesfakta: versjon, utgave, arkitekturer og utgivelsesnøkkelens fingeravtrykk
images/<service>/ Hvert avbild med begge plattformer, signaturen og attestasjonene
charts/nexus-1.0.0-alpha.1.tgz Chartet
sbom/ SPDX SBOM-en for hvert avbild, per plattform
docs/ Utgivelsesnotatene, installasjonsveiledningen for luftgap (air-gap) og eksempelverdier
SHA256SUMS og SHA256SUMS.sigstore.json Kontrollsummen for hver fil, og dens signatur

Den offentlige utgivelsesnøkkelen ligger aldri inni pakken; en nøkkel som leveres sammen med det den signerer, beviser ingenting. Kontroller hele pakken med to kommandoer, fra innsiden av mappen dens:

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

Hver linje i den første skal slutte med OK, og den andre skal skrive ut Verified OK. Kapittel 2.10, Luftgap-installasjon (air-gapped), tar pakken videre derfra: innlasting av avbildene i ditt eget register, ny verifisering av hvert enkelt avbild der, og pakkens egen ende-til-ende-kontroll.

Slik kontrollerer du en nedlasting
Slik kontrollerer du en nedlasting
Slik kontrollerer du en nedlasting, i Adverant-kontoen. To frakoblede kontroller, et bilde av et godkjent og et mislykket resultat, samt utgivelsesnøkkelens fingeravtrykk i grupper på fire for visuell sammenligning.

Når en signatur ikke lar seg verifisere

Stopp. Ikke installer, og ikke endre kommandoen for å få den til å gå gjennom. En mislykket signaturkontroll betyr at systemet fungerer som det skal: det betyr at filen du har, ikke er filen Adverant signerte, eller at nøkkelen du har, ikke tilhører Adverant.

Hva dere ser Hva det betyr Hva du skal gjøre
accepted signatures do not match threshold, Found: 0, Expected 1 (avslutningskode 1) Avbildet er signert, men ikke med nøkkelen du oppga Kontroller at du brukte utgivelsesnøkkelen med fingeravtrykket du sjekket i trinn 1
no signatures found (avslutningskode 10) Ingenting på den sjekksummen er signert Kontroller at sjekksummen kom fra låsen; verifiser aldri en tagg
not enough verified log entries from transparency log: 0 < 1 --insecure-ignore-tlog=true mangler Legg til flagget; det er ingenting galt med avbildet
none of the attestations matched the predicate type Du ba om en attestasjonstype som avbildet ikke har med seg Bruk spdxjson eller slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature En nedlastet fil ble endret etter at den ble signert Last den ned på nytt
FAILED fra sha256sum -c En fil er ikke den filen det ble beregnet kontrollsum for Last den ned på nytt

Hvis en nedlasting feiler to ganger, oppretter du en støttehenvendelse fra kontoen din og oppgir filnavnet og meldingen. Ta vare på filen som feilet; sikkerhetsteamet ditt kan ønske å se nærmere på den.

På en installasjon som laster inn utgivelser fra disk, kjører konsollen de samme kontrollene og avviser en utgivelse der signaturen ikke samsvarer med den installerte nøkkelen, med MEDIA_SIGNATURE_INVALID. Den forteller hva den kontrollerte, i hvilken rekkefølge, hvor den stoppet, og at ingenting ble endret: ingen avbilder ble lastet inn, og den kjørende versjonen er urørt.

Import fra medier mislyktes
Import fra medier mislyktes
En utgivelse på disk som ikke bestod signaturkontrollen. Legg merke til kontrollene i rekkefølge med den som stoppet prosessen, forventet og funnet nøkkelfingeravtrykk, og den tydelige meldingen om at ingenting ble lastet inn eller endret.

Når nøkkelen, avbildene og chartet har bestått kontrollen, er neste trinn en forhåndskontroll mot klyngen din, i kapittel 2.5, Forhåndskontroll med nexusctl.