Logga inBoka en genomgång

Kapitel 2.4

Hämta och verifiera en utgåva

Var varje del av en Nexus-utgåva finns, hur Enterprise-avbildningar hämtas med en pull-token och hur ni offline bevisar att varje avbildning, chart och nedladdning kommer oförändrad från Adverant innan ni installerar något.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

15 minuters läsning

Varje avbildning i en Nexus-utgåva är signerad med Adverants utgåvenyckel, och varje avbildning namnges med sin kontrollsumma (digest), aldrig med en tagg. Helm-chartet renderar endast avbildningar som anges med kontrollsumma i dess egen låsfil för avbildningar (images lock). Sammantaget innebär det att du på din egen arbetsstation och utan anslutning till någon annan kan bevisa att det du står i begrepp att köra är exakt vad Adverant har byggt.

På Harrow Port Authority kontrollerade vi allt före den första installationen. Det tog ungefär tjugo minuter, varav merparten utgjordes av loopen över avbildningarna. Det här kapitlet följer samma väg: var varje del av utgåvan finns, pull-token för Enterprise-avbildningar, låsfilen för avbildningar, kontrollerna med cosign och deras exakta kommandon samt vad du ska göra när en kontroll misslyckas.

Var utgåvan finns

Adress Vad du hämtar där
registry.adverant.ai Plattformsavbildningarna på registry.adverant.ai/nexus/<service>@sha256:<digest> och Helm-chartet på oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ Utgåvans publika nyckel och dess fingeravtryck, nexusctl-binärfilerna och offlinepaketen
https://account.adverant.ai Ditt Adverant-konto: Nedladdningar, Pull-tokens och installationskommandon, Driftsättningar samt licenssidorna

Community-avbildningar och Community-chartet är publika; du kan hämta dem utan att logga in. Enterprise-avbildningar hämtas med en pull-token från ditt konto, och Enterprise-chartet samt paketet finns på kontots sida Nedladdningar, som följer din licens.

Nedladdningar
Nedladdningar
Nedladdningar i Adverant-kontot, efter version och kanal. Varje fil har sin kontrollsumma och signatur bredvid sig, och delar som ligger utanför licensen förblir listade men utgråade, med angiven orsak.

Läs versionsinformationen före allt annat

Versionsinformationen levereras inuti varje paket som docs/RELEASE-NOTES.md, listad i dess SHA256SUMS, och samma information finns på utgåvesidan i ditt konto. Läs den innan du installerar eller uppgraderar. För 1.0.0-alpha.1 är den kort. Det är den första utgåvan, så en nyinstallation omfattas inte av några av de uppgraderingspunkter som beskrivs, och listan över kända problem anger att ingenting i den påverkar en nyinstallation som följer de dokumenterade stegen. Senare utgåvor listar varje känt problem tillsammans med den version som åtgärdar det.

Utgåvesidan anger också på tre rader vad en alfautgåva utlovar: funktioner kan ändras före den första stabila versionen, en uppgradering behåller dina data och tar först en säkerhetskopia, och säkerhetsuppdateringar levereras inom 7 dagar. Vi skrev ut den sidan och lade den i ändringsloggen på Harrow, eftersom det är det närmaste ett supportåtagande som ändringsrådet skulle efterfråga.

Steg 1: hämta utgåvenyckeln och kontrollera den via en andra väg

Allt nedan vilar på en enda fil: Adverants publika utgåvenyckel. En nyckel som kommer från samma plats som det den intygar bevisar väldigt lite, så kontrollera dess fingeravtryck mot en kopia som har nått dig på något annat sätt.

  1. Ladda ner nyckeln från utgåvans mapp under Nedladdningar.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Ta fram dess fingeravtryck. Fingeravtrycket är SHA-256 (Secure Hash Algorithm 256) för själva nyckelfilen.

    sha256sum release.pub

    På macOS ger shasum -a 256 release.pub samma svar.

  3. Jämför det, tecken för tecken, med det fingeravtryck som är tryckt i ditt avtal med Adverant och i versionsinformationen. Nedladdningar publicerar också fingeravtrycket, men den kopian kom samma väg som nyckeln och utgör därför ingen kontroll.

Om något tecken skiljer sig åt, avbryt. Installera inte och leta inte efter en annan kopia av nyckeln på internet. Öppna ett supportärende från ditt konto och ange exakt vad du såg.

Steg 2: hämta nexusctl

nexusctl är Nexus-operatörens kommandoradsgränssnitt (CLI). Det körs på din arbetsstation och läser ditt kluster via din kubeconfig. Under Nedladdningar finns fyra versioner:

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

Bredvid varje fil finns dess signaturpaket, med samma namn följt av .sigstore.json på slutet. Kontrollera binärfilen innan du kör 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

Lägg sedan till den i din sökväg (PATH) och kontrollera dess version:

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

Härifrån kan nexusctl verify utföra filkontrollerna åt dig. Kapitel 2.5, Förkontroll med nexusctl, behandlar dess huvuduppgift, förkontrollen (preflight).

Varför flaggan heter "insecure"

Varje cosign-kommando i det här kapitlet innehåller --insecure-ignore-tlog=true. Nexus-utgåvor signeras med Adverants nyckel och registreras inte i någon publik transparenslogg, så att kontrollen av en utgåva aldrig kräver en anslutning till någon annan, inklusive Sigstore. Som standard kräver cosign en loggpost; flaggan instruerar verktyget att enbart lita på nyckeln. Utan den misslyckas kontrollen så här:

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

När flaggan är satt skriver cosign ändå ut meningen "Existence of the claims in the transparency log was verified offline". Det är en fast formulering i cosign; det finns ingen loggpost bakom den. Signaturkontrollen mot nyckeln är äkta, och det är den delen som har betydelse.

Steg 3: en pull-token, för Enterprise

Enterprise-avbildningar skyddas av en pull-token. Du skapar en sådan i ditt konto, under Pull-tokens och installationskommandon:

  1. Tryck på Lägg till en token.
  2. Ange vilket kluster den gäller för, vad den får hämta och när den slutar gälla.
  3. Tryck på Kopiera token och klistra in den direkt där du förvarar inloggningsuppgifter, eftersom sidan bara visar den denna enda gång.

Varje token är begränsad till vad den får hämta och har ett utgångsdatum. Om du återkallar en token stoppas nya hämtningar omedelbart, men avbildningar som ett kluster redan har hämtat fortsätter att köras. På Harrow skapade vi en token per kluster, så att en återkallelse av testklustrets token aldrig påverkar produktionen. En Community-installation kräver ingen token alls; du skapar en först när du går över till Enterprise, och du kan skapa den samma dag.

Pull-tokens och installationskommandon
Pull-tokens och installationskommandon
Pull-tokens i Adverant-kontot. Varje token visar vad den får hämta, vem som skapade den och när den slutar gälla; en ny token visas en gång, och att återkalla en token stoppar nya hämtningar utan att stoppa något som redan körs.

Chartet har inget värde för pull-secret. Det är dina noder som hämtar avbildningarna, så din token tillhör nodernas container-runtime. På k3s lägger du till registret i /etc/rancher/k3s/registries.yaml på varje nod och startar om k3s där:

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

<registry-user> är registrets användarnamn i din Adverant-inbjudan, och <pull-token> är den token du kopierade. Filen innehåller en inloggningsuppgift, så se till att den endast kan läsas av root.

På ett hanterat kluster vars noder inte läser den filen kopierar du avbildningarna till ett register som dina noder redan litar på och sätter global.imageRegistry till detta; varje nod måste lita på det registrets TLS-certifikat (Transport Layer Security). Kapitel 2.11, Variationer: externa datalager, TLS och ingress, behandlar detta, och kapitel 2.10, Luftgapad installation, behandlar motsvarande kopiering för en plats utan utgående förbindelse.

Steg 4: läs låsfilen för avbildningar

Ett Nexus-chart namnger aldrig en avbildning med en tagg. Det namnger var och en med kontrollsumman (digest) för dess multiplattformsindex, hämtad från låsfilen för avbildningar (images lock), en fil som chartet innehåller som files/images.lock.json. Offlinepaketet innehåller samma låsfil som release/images.lock.json.

Hämta chartet och packa upp det för att läsa låsfilen:

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åsfilens översta nivå anger vilken utgåva och vilken utgåveversion (edition) den tillhör. Varje post under images beskriver en avbildning:

Fält Vad den innehåller
svc Tjänsten, till exempel nexus-auth eller nexus-postgres
index sha256:-kontrollsumman för avbildningens index, som täcker både linux/amd64 och linux/arm64
edition community, enterprise eller all för dataskiktet
kind service, migrations eller data-tier för de fem datalagren och OpenBao
verified När utgåvans bygge verifierade dess signatur och intyg (attestations)

Chartet renderar varje avbildning som <global.imageRegistry>/nexus/<svc>@<index>. Med global.imageRegistry: registry.adverant.ai blir inloggningstjänsten alltså registry.adverant.ai/nexus/nexus-auth@sha256: följt av 64 hexadecimala tecken, och ingenting i klustret kan byta ut den mot något annat med samma namn.

Låsfilen är specifik för varje utgåveversion (edition). En Community-låsfil listar endast avbildningar vars utgåveversion är community eller all. En Enterprise-låsfil listar dessa plus Enterprise-byggena. Chartet kontrollerar detta varje gång det renderas och nekar hellre än att gissa:

Vad chartet säger Varför
edition=enterprise but enterprise.enabled=false: they must agree De två värdena för utgåveversion i din values-fil stämmer inte överens
files/images.lock.json is the community lock; this install is edition enterprise Du installerar Enterprise från Community-chartet, eller tvärtom
image nexus-auth is not in files/images.lock.json Chartet och dess låsfil hör inte ihop; hämta chartet igen
image ... is in the lock but was never verified by build-all Posten i låsfilen saknar verifieringstidpunkt; installera inte från den
NEXUS_EDITION_INVALID edition är tom eller är inte ett av värdena community och enterprise
RELEASE_VERSION_MISSING Låsfilen anger ingen version

Lista varje avbildning och kontrollsumma på en gång:

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

Steg 5: verifiera varje avbildnings signatur

Varje avbildningsindex är signerat, och detsamma gäller varje plattformsmanifest inuti det. Verifiera med kontrollsumma direkt från låsfilen, så att du kontrollerar exakt vad chartet kommer att köra:

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

Varje rad ska börja med OK. På vår förbindelse tog loopen några minuter, varav det mesta var väntetid mot registret. Den läser bara signaturerna och hämtar inga avbildningslager, vilket gör det snabbt och resurssnålt att upprepa efter varje uppgradering. En FAILED-rad betyder stopp: nästa avsnitt förklarar vad varje meddelande betyder.

För en enskild avbildning kan du ta bort omdirigeringen och läsa vad cosign kontrollerade:

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> är de 64 hexadecimala tecknen från låsfilens index för den avbildningen. Enterprise-avbildningar kräver din pull-token för den här kontrollen, precis som vid alla hämtningar från registret.

En vertikal kedja med fem rutor sammanbundna med nedåtriktade pilar. Överst: "Utgåvans publika nyckel, fingeravtryck kontrollerat mot ditt avtal". Andra: "Chart-paket nexus-1.0.0-alpha.1, signerat". Tredje: "Låsfil för avbildningar inuti chartet: varje avbildning med indexets kontrollsumma, en utgåveversion". Fjärde: "Varje avbildningsindex, signerat, med innehållsförteckning för programvara (SBOM) och ursprungsintyg". Nederst: "Poddar i namnrymden nexus, hämtade med kontrollsumma". En sidopil från den översta rutan pekar på den andra och fjärde rutan, märkt "cosign verify, offline".
Vad som intygar vad, från nyckeln du kontrollerade till de poddar som körs.

Båda plattformarna och vad du ska spara

Varje avbildningsindex innehåller två plattformsmanifest, linux/amd64 och linux/arm64, och vart och ett av dem är också signerat. cosign verify lyckas på indexets kontrollsumma och på båda plattformarnas kontrollsummor, så ett kluster med blandade noder täcks av samma kontroll. För att se de två plattformarna bakom ett index, fråga registret efter råindexet:

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

Dess manifests-lista anger en amd64-post och en arm64-post.

Spara utdata från loopen ovan i din ändringslogg, bredvid det fingeravtryck du kontrollerade. När någon månader senare frågar hur du vet att klustret kör det som Adverant levererade, ger den filen och låsfilens kontrollsummor svaret. Vår revisor på Harrow ställde exakt den frågan, och svaret tog en minut.

Steg 6: läs attesteringarna

Varje avbildning bär också två signerade intyg (attestations), skapade från avbildningen vid byggtillfället: en innehållsförteckning för programvara (SBOM, software bill of materials) och ett ursprungsintyg (provenance statement).

SBOM-filen är i SPDX-format (Software Package Data Exchange), en per plattform, så ett index innehåller två. Den listar varje paket i avbildningen tillsammans med dess licens. Före utgivning kontrolleras dessa licenser mot en förbudslista; ingen Community-avbildning innehåller kod under GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) eller Business Source License (BUSL). Ursprungsintyget följer Supply-chain Levels for Software Artifacts (SLSA) v1. Det anger den källkods-commit som avbildningen byggdes från, kontrollsummorna för basavbildningarna samt byggverktygen och deras versioner, så att en avbildning kan spåras tillbaka till den granskade källkoden utan att du behöver fråga Adverant.

Båda kontrolleras mot den utgåvenyckel du redan 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>

Kontrollen med spdxjson skriver ut två resultat, ett för varje plattforms SBOM. För att se allt som är kopplat till en avbildning utan att verifiera det, använd cosign tree:

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

Den listar ett signaturpaket, två spdx.dev/Document-intyg och ett slsa.dev/provenance/v1-intyg. Om du frågar efter en typ som avbildningen inte har, såsom --type cyclonedx, misslyckas det med none of the attestations matched the predicate type: cyclonedx. Det felet är korrekt; utgåvan bifogar SPDX, inte CycloneDX.

Steg 7: verifiera chartet och nedladdningarna

Chartet i registret är signerat på sin OCI-kontrollsumma (OCI står för Open Container Initiative, det format för avbildningar och artefakter som register använder). helm pull skriver ut kontrollsumman som hämtades; kontrollera den kontrollsumman på samma sätt som för en avbildning:

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

För en chart-fil som du har laddat ner, eller för offlinepaketet, kontrollerar nexusctl verify filen mot Adverants utgåvenyckel:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Ett godkänt resultat avslutas med att ange Adverants utgåvenyckel och början på dess fingeravtryck. Jämför dessa grupper med det fingeravtryck du kontrollerade i steg 1.

Offlinepaketet är en okomprimerad tar-fil per utgåveversion, nexus-alpha-1.0.0-alpha.1-community.tar eller nexus-alpha-1.0.0-alpha.1-enterprise.tar, med en .sha256-fil bredvid sig. Inuti innehåller det:

Sökväg Vad det är
release/images.lock.json Låsfilen för avbildningar för den utgåveversionen
release/facts.json Utgåvefakta: version, utgåveversion, arkitekturer och utgåvenyckelns fingeravtryck
images/<service>/ Varje avbildning med båda plattformarna, dess signatur och dess intyg
charts/nexus-1.0.0-alpha.1.tgz Chartet
sbom/ SPDX SBOM för varje avbildning, per plattform
docs/ Versionsinformationen, installationsguiden för luftgapade miljöer och exempelvärden
SHA256SUMS och SHA256SUMS.sigstore.json Kontrollsumman för varje fil samt dess signatur

Utgåvans publika nyckel finns aldrig inuti paketet; en nyckel som levereras tillsammans med det den signerar bevisar ingenting. Kontrollera hela paketet med två kommandon inifrån dess mapp:

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

Varje rad i det första ska sluta med OK, och det andra ska skriva ut Verified OK. Kapitel 2.10, Luftgapad installation, tar vid med paketet därifrån: att läsa in avbildningarna i ditt eget register, verifiera var och en igen där samt paketets egen helhetskontroll.

Så kontrollerar du en nedladdning
Så kontrollerar du en nedladdning
Så kontrollerar du en nedladdning, i Adverant-kontot. Två offlinekontroller, en bild av ett godkänt och ett underkänt resultat samt utgåvenyckelns fingeravtryck i grupper om fyra för visuell jämförelse.

När en signatur inte går att verifiera

Stopp. Installera inte, och ändra inte kommandot tills det går igenom. En misslyckad signaturkontroll betyder att systemet fungerar: det innebär att filen du har inte är den fil som Adverant signerade, eller att nyckeln du har inte är Adverants.

Vad ni ser Vad det innebär Vad du ska göra
accepted signatures do not match threshold, Found: 0, Expected 1 (exit 1) Avbildningen är signerad, men inte med den nyckel du angav Kontrollera att du använde den utgåvenyckel vars fingeravtryck du kontrollerade i steg 1
no signatures found (exit 10) Ingenting på den kontrollsumman är signerat Kontrollera att kontrollsumman kom från låsfilen; verifiera aldrig en tagg
not enough verified log entries from transparency log: 0 < 1 --insecure-ignore-tlog=true saknas Lägg till flaggan; det är inget fel på avbildningen
none of the attestations matched the predicate type Du frågade efter en intygstyp som avbildningen inte har Använd spdxjson eller slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature En nedladdad fil har ändrats efter att den signerades Ladda ner den igen
FAILED från sha256sum -c En fil är inte samma fil som kontrollsumman beräknades för Ladda ner den igen

Om en nedladdning misslyckas två gånger, öppna ett supportärende från ditt konto och ange filnamnet och meddelandet. Behåll den felaktiga filen; ditt säkerhetsteam kan vilja ha den.

På en installation som läser in utgåvor från disk kör konsolen samma kontroller och nekar en utgåva vars signatur inte stämmer överens med den installerade nyckeln, med MEDIA_SIGNATURE_INVALID. Den anger vad den kontrollerade, i vilken ordning, var den stannade och att ingenting ändrades: ingen avbildning lästes in och den version som körs lämnades orörd.

Import från media misslyckades
Import från media misslyckades
En utgåva på disk som inte klarade signaturkontrollen. Lägg märke till kontrollerna i ordningsföljd med den som stoppade förloppet, de förväntade och funna nyckelfingeravtrycken samt det tydliga beskedet att ingenting lästes in eller ändrades.

När nyckeln, avbildningarna och chartet alla har godkänts är nästa steg en förkontroll mot ditt kluster, i kapitel 2.5, Förkontroll med nexusctl.