Prihlásiť saRezervovať brífing

Kapitola 2.4

Získanie a overenie vydania

Kde sa nachádza každá časť vydania Nexus, ako sa obrazy Enterprise sťahujú pomocou pull tokenu a ako offline dokázať, že každý obraz, chart a stiahnutý súbor prišiel od spoločnosti Adverant nezmenený predtým, než čokoľvek nainštalujete.

Táto stránka bola preložená pomocou AI z anglického originálu. V prípade akýchkoľvek nejasností je rozhodujúca anglická verzia stránky. Prečítať túto stránku v angličtine

15 min čítania

Každý obraz vo vydaní Nexus je podpísaný vydávacím kľúčom spoločnosti Adverant a každý obraz je pomenovaný svojím odtlačkom (digest), nikdy nie značkou (tag). Chart vygeneruje iba obrazy uvedené podľa odtlačku vo svojom vlastnom zámku obrazov (images lock). Dokopy to znamená, že na vlastnej pracovnej stanici a bez akéhokoľvek pripojenia k čomukoľvek môžete dokázať, že to, čo sa chystáte spustiť, je presne to, čo spoločnosť Adverant zostavila.

V Harrow Port Authority sme pred prvou inštaláciou všetko skontrolovali. Trvalo to asi dvadsať minút a väčšinu z toho zabral cyklus kontroly obrazov. Táto kapitola prechádza rovnakou cestou: kde sa nachádza každá časť vydania, sťahovací token (pull token) pre obrazy Enterprise, zámok obrazov, kontroly pomocou cosign s ich presnými príkazmi a čo robiť, keď kontrola zlyhá.

Kde sa vydanie nachádza

Adresa Čo tam stiahnete
registry.adverant.ai Obrazy platformy na registry.adverant.ai/nexus/<service>@sha256:<digest> a Helm chart na oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ Verejný kľúč vydania a jeho odtlačok (fingerprint), binárne súbory nexusctl a offline balíky
https://account.adverant.ai Váš účet Adverant: Na stiahnutie, Sťahovacie tokeny a inštalačné príkazy, Nasadenia a stránky licencií

Obrazy Community a chart Community sú verejné; môžete ich stiahnuť bez prihlásenia. Obrazy Enterprise sa sťahujú pomocou sťahovacieho tokenu z vášho účtu a chart a balík Enterprise sa nachádzajú na stránke Na stiahnutie vo vašom účte, ktorá sa riadi vašou licenciou.

Na stiahnutie
Na stiahnutie
Sekcia Na stiahnutie v účte Adverant podľa verzie a kanála. Každý súbor má vedľa seba svoj kontrolný súčet a podpis a časti mimo licencie zostávajú v zozname sivé s uvedením dôvodu.

Pred všetkým ostatným si prečítajte poznámky k vydaniu

Poznámky k vydaniu sa dodávajú v každom balíku ako docs/RELEASE-NOTES.md, sú uvedené v jeho SHA256SUMS a rovnaké poznámky sa nachádzajú na stránke vydania vo vašom účte. Prečítajte si ich pred inštaláciou alebo aktualizáciou. Pre verziu 1.0.0-alpha.1 sú krátke. Je to prvé vydanie, takže čistá inštalácia neobsahuje žiadne z bodov aktualizácie, ktoré opisujú, a v zozname známych problémov sa uvádza, že nič z neho neovplyvňuje čistú inštaláciu, ktorá postupuje podľa zdokumentovaných krokov. Neskoršie vydania uvádzajú každý známy problém spolu s verziou, ktorá ho opravuje.

Stránka vydania tiež v troch riadkoch uvádza, čo sľubuje alfa vydanie: funkcie sa pred prvou stabilnou verziou môžu zmeniť, aktualizácia zachová vaše údaje a najprv vytvorí zálohu a bezpečnostné opravy prichádzajú do 7 dní. Túto stránku sme v Harrow vytlačili a vložili do záznamu o zmenách, pretože je to najbližšie k vyhláseniu o podpore, ktoré by komisia pre zmeny mohla požadovať.

Krok 1: získajte kľúč vydania a skontrolujte ho druhou cestou

Všetko uvedené nižšie stojí na jednom súbore: verejnom kľúči vydania spoločnosti Adverant. Kľúč, ktorý pochádza z rovnakého miesta ako vec, za ktorú ručí, dokazuje len veľmi málo, preto skontrolujte jeho odtlačok (fingerprint) oproti kópii, ktorá sa k vám dostala iným spôsobom.

  1. Stiahnite si kľúč z priečinka vydania na stránke Na stiahnutie.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Vypočítajte jeho odtlačok. Odtlačok je hodnota SHA-256 (Secure Hash Algorithm 256) samotného súboru kľúča.

    sha256sum release.pub

    V systéme macOS dáva rovnakú odpoveď príkaz shasum -a 256 release.pub.

  3. Porovnajte ho, znak po znaku, s odtlačkom vytlačeným vo vašej zmluve so spoločnosťou Adverant a v poznámkach k vydaniu. Stránka Na stiahnutie zverejňuje odtlačok tiež, ale táto kópia prišla rovnakou cestou ako kľúč, takže neslúži ako kontrola.

Ak sa akýkoľvek znak líši, zastavte. Neinštalujte a nehľadajte inú kópiu kľúča na internete. Otvorte žiadosť o podporu zo svojho účtu a uveďte, čo ste videli.

Krok 2: získajte nexusctl

nexusctl je rozhranie príkazového riadka (CLI) operátora systému Nexus. Beží na vašej pracovnej stanici a číta váš klaster cez váš súbor kubeconfig. Stránka Na stiahnutie ponúka štyri zostavy:

Súbor Platforma
nexusctl-linux-amd64 Linux na procesoroch Intel alebo AMD
nexusctl-darwin-arm64 macOS na čipoch Apple silicon
nexusctl-darwin-amd64 macOS na procesoroch Intel
nexusctl-windows-amd64.exe Windows

Vedľa každého súboru je jeho balík podpisov s rovnakým názvom a príponou .sigstore.json na konci. Pred spustením binárny súbor skontrolujte:

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

Potom ho pridajte do premennej PATH a vyžiadajte si jeho verziu:

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

Od tejto chvíle môže kontroly súborov vykonávať nexusctl verify za vás. Kapitola 2.5, Predletová kontrola pomocou nexusctl, sa venuje jeho hlavnej úlohe – predletovej kontrole (preflight).

Prečo príznak obsahuje slovo „insecure“

Každý príkaz cosign v tejto kapitole obsahuje príznak --insecure-ignore-tlog=true. Vydania Nexus sú podpísané kľúčom spoločnosti Adverant a nezaznamenávajú sa do žiadneho verejného záznamu transparentnosti, takže kontrola vydania nikdy nepotrebuje pripojenie k nikomu, vrátane služby Sigstore. Štandardne cosign trvá na zázname v protokole; tento príznak mu hovorí, aby sa spoliehal iba na kľúč. Bez neho kontrola zlyhá takto:

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

Keď je príznak nastavený, cosign stále vypíše vetu „Existence of the claims in the transparency log was verified offline“. Ide o pevnú formuláciu v nástroji cosign; žiadny záznam v protokole za ňou nie je. Kontrola podpisu voči kľúču je skutočná a to je tá časť, na ktorej záleží.

Krok 3: pull token pre Enterprise

Obrazy Enterprise sú chránené sťahovacím tokenom. Vytvoríte si ho vo svojom účte na stránke Sťahovacie tokeny a inštalačné príkazy:

  1. Stlačte tlačidlo Pridať token.
  2. Zadajte, pre ktorý klaster je určený, čo môže sťahovať a kedy končí jeho platnosť.
  3. Stlačte tlačidlo Kopírovať token a vložte ho priamo tam, kde uchovávate prihlasovacie údaje, pretože stránka ho zobrazí iba tento jeden raz.

Každý token je obmedzený na to, čo môže sťahovať, a má dátum ukončenia platnosti. Odvolanie tokenu okamžite zastaví nové sťahovania; obrazy, ktoré už klaster stiahol, bežia ďalej. V Harrow sme vytvorili jeden token pre každý klaster, takže odvolanie tokenu testovacieho klastra sa nikdy nedotkne produkcie. Inštalácia edície Community nepotrebuje vôbec žiadny token; vytvoríte si ho až pri prechode na edíciu Enterprise a môžete ho vytvoriť v ten istý deň.

Sťahovacie tokeny a inštalačné príkazy
Sťahovacie tokeny a inštalačné príkazy
Sťahovacie tokeny v účte Adverant. Každý token ukazuje, čo môže sťahovať, kto ho vytvoril a kedy končí jeho platnosť; nový token sa zobrazí raz a jeho odvolanie zastaví nové sťahovania bez zastavenia čohokoľvek, čo už beží.

Chart nemá žiadnu hodnotu pull-secret. Obrazy sťahujú vaše uzly, takže token patrí behovému prostrediu kontajnerov (container runtime) na uzloch. V prostredí k3s pridajte register do súboru /etc/rancher/k3s/registries.yaml na každom uzle a reštartujte tam k3s:

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

<registry-user> je používateľské meno registra vo vašej pozvánke od spoločnosti Adverant a <pull-token> je token, ktorý ste skopírovali. Súbor obsahuje prihlasovacie údaje, preto ho uchovávajte čitateľný iba pre používateľa root.

V spravovanom klastri, ktorého uzly tento súbor nečítajú, skopírujte obrazy do registra, ktorému vaše uzly už dôverujú, a nastavte naň global.imageRegistry; každý uzol musí dôverovať certifikátu TLS (Transport Layer Security) daného registra. Kapitola 2.11, Variácie: externé úložiská, TLS a ingress, sa venuje tomuto postupu a kapitola 2.10, Inštalácia v izolovanej sieti (air-gapped), opisuje rovnaké kopírovanie pre lokalitu bez pripojenia von.

Krok 4: prečítajte si zámok obrazov (images lock)

Chart systému Nexus nikdy nepomenúva obraz pomocou značky (tag). Každý obraz pomenúva pomocou odtlačku (digest) jeho multiplatformového indexu, prevzatého zo zámku obrazov (images lock) – súboru, ktorý chart obsahuje ako files/images.lock.json. Offline balík obsahuje rovnaký zámok ako release/images.lock.json.

Stiahnite chart a rozbaľte ho, aby ste si prečítali zámok:

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

Najvyššia úroveň zámku hovorí, ku ktorému vydaniu a ktorej edícii patrí. Každá položka pod images opisuje jeden obraz:

Pole Čo obsahuje
svc Službu, ako napríklad nexus-auth alebo nexus-postgres
index Odtlačok sha256: indexu obrazu, ktorý pokrýva linux/amd64 aj linux/arm64
edition community, enterprise alebo all pre dátovú vrstvu
kind service, migrations alebo data-tier pre päť dátových úložísk a OpenBao
verified Čas, kedy zostava vydania overila jeho podpis a atestácie

Chart vygeneruje každý obraz ako <global.imageRegistry>/nexus/<svc>@<index>. Takže s global.imageRegistry: registry.adverant.ai je prihlasovacia služba registry.adverant.ai/nexus/nexus-auth@sha256: nasledovaná 64 hexadecimálnymi znakmi a nič v klastri ju nemôže vymeniť za niečo iné s rovnakým názvom.

Zámok je špecifický pre každú edíciu. Zámok Community uvádza iba obrazy, ktorých edícia je community alebo all. Zámok Enterprise uvádza tieto obrazy plus zostavy Enterprise. Chart to kontroluje pri každom generovaní a radšej odmietne pokračovať, než aby hádal:

Čo hovorí chart Prečo
edition=enterprise but enterprise.enabled=false: they must agree Dve hodnoty edície vo vašom súbore hodnôt (values) sa nezhodujú
files/images.lock.json is the community lock; this install is edition enterprise Inštalujete edíciu Enterprise z chartu Community alebo naopak
image nexus-auth is not in files/images.lock.json Chart a jeho zámok k sebe nepatria; stiahnite chart znova
image ... is in the lock but was never verified by build-all Položka zámku nemá čas overenia; neinštalujte z neho
NEXUS_EDITION_INVALID Premenná edition je prázdna alebo nemá jednu z hodnôt community a enterprise
RELEASE_VERSION_MISSING Zámok neuvádza žiadnu verziu

Vypíšte zoznam všetkých obrazov a odtlačkov naraz:

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

Krok 5: overte podpis každého obrazu

Každý index obrazu je podpísaný a rovnako aj každý manifest platformy v ňom. Overujte podľa odtlačku priamo zo zámku, aby ste skontrolovali presne to, čo chart spustí:

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

Každý riadok by sa mal začínať reťazcom OK. Na našom pripojení trval cyklus niekoľko minút, pričom väčšinu času zabralo čakanie na register. Číta iba podpisy a nesťahuje žiadne vrstvy obrazov, vďaka čomu je nenáročné zopakovať ho po každej aktualizácii. Riadok FAILED znamená zastaviť: nasledujúca časť vysvetľuje, čo jednotlivé správy znamenajú.

Pre jeden samostatný obraz vynechajte presmerovanie a prečítajte si, čo cosign skontroloval:

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> je 64 hexadecimálnych znakov z poľa index v zámku pre daný obraz. Obrazy Enterprise potrebujú na túto kontrolu váš sťahovací token, rovnako ako pri akomkoľvek sťahovaní z registra.

Zvislý reťazec piatich polí spojených šípkami smerujúcimi nadol. Hore: „Verejný kľúč vydania, odtlačok skontrolovaný oproti vašej zmluve“. Druhé: „Balík chartu nexus-1.0.0-alpha.1, podpísaný“. Tretie: „Zámok obrazov vo vnútri chartu: každý obraz podľa odtlačku indexu, jedna edícia“. Štvrté: „Každý index obrazu, podpísaný, so zoznamom softvérových komponentov (SBOM) a atestáciami o pôvode“. Dole: „Pody v mennom priestore nexus, stiahnuté podľa odtlačku“. Bočná šípka z horného poľa ukazuje na druhé a štvrté pole s označením „cosign verify, offline“.
Čo ručí za čo – od kľúča, ktorý ste skontrolovali, až po spustené pody.

Obe platformy a čo si uchovať

Každý index obrazu obsahuje dva manifesty platforiem, linux/amd64 a linux/arm64, a každý z nich je tiež podpísaný. Príkaz cosign verify uspeje pri odtlačku indexu aj pri odtlačku ktorejkoľvek platformy, takže klaster so zmiešanými uzlami je pokrytý tou istou kontrolou. Ak chcete vidieť dve platformy za indexom, vyžiadajte si z registra nespracovaný index:

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

Jeho zoznam manifests uvádza jednu položku amd64 a jednu položku arm64.

Výstup vyššie uvedeného cyklu si uložte k záznamu o zmenách vedľa odtlačku kľúča, ktorý ste skontrolovali. Keď sa o niekoľko mesiacov neskôr niekto opýta, ako viete, že v klastri beží to, čo dodala spoločnosť Adverant, tento súbor a odtlačky zo zámku na to odpovedia. Náš audítor v Harrow položil presne túto otázku a odpoveď trvala minútu.

Krok 6: prečítajte si atestácie

Každý obraz tiež nesie dve podpísané atestácie vytvorené z obrazu v čase zostavenia: zoznam softvérových komponentov (SBOM – software bill of materials) a vyhlásenie o pôvode (provenance statement).

SBOM je vo formáte Software Package Data Exchange (SPDX), jeden pre každú platformu, takže index nesie dva. Uvádza každý balík v obraze spolu s jeho licenciou. Pred vydaním sa tieto licencie kontrolujú oproti zoznamu zakázaných licencií; žiadny obraz Community neobsahuje kód pod licenciou GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) ani Business Source License (BUSL). Vyhlásenie o pôvode je vo formáte Supply-chain Levels for Software Artifacts (SLSA) v1. Uvádza zdrojový commit, z ktorého bol obraz zostavený, odtlačky základných obrazov a nástroje zostavenia s ich verziami, takže obraz je možné vysledovať späť ku skontrolovanému zdrojovému kódu bez dopytovania spoločnosti Adverant.

Obe atestácie sa kontrolujú voči vydávaciemu kľúču, ktorý už máte:

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>

Kontrola spdxjson vypíše dva výsledky, jeden pre SBOM každej platformy. Ak chcete vidieť všetko pripojené k obrazu bez overovania, použite cosign tree:

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

Vypíše jeden balík podpisov, dve atestácie spdx.dev/Document a jednu atestáciu slsa.dev/provenance/v1. Vyžiadanie typu, ktorý obraz nenesie, ako napríklad --type cyclonedx, zlyhá s chybou none of the attestations matched the predicate type: cyclonedx. Toto zlyhanie je správne; vydanie pripája formát SPDX, nie CycloneDX.

Krok 7: overte chart a stiahnuté súbory

Chart v registri je podpísaný na svojom odtlačku OCI (OCI je Open Container Initiative, formát obrazov a artefaktov, ktorý používajú registre). Príkaz helm pull vypíše odtlačok, ktorý stiahol; skontrolujte tento odtlačok rovnakým spôsobom ako obraz:

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

Pre súbor chartu, ktorý ste si stiahli, alebo pre offline balík skontroluje nexusctl verify súbor voči vydávaciemu kľúču spoločnosti Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Dobrý výsledok sa končí uvedením vydávacieho kľúča spoločnosti Adverant a začiatkom jeho odtlačku (fingerprint). Porovnajte tieto skupiny s odtlačkom, ktorý ste skontrolovali v kroku 1.

Offline balík je jeden nekomprimovaný súbor tar pre každú edíciu, nexus-alpha-1.0.0-alpha.1-community.tar alebo nexus-alpha-1.0.0-alpha.1-enterprise.tar, so súborom .sha256 vedľa neho. Vo vnútri obsahuje:

Cesta Čo to je
release/images.lock.json Zámok obrazov pre danú edíciu
release/facts.json Údaje o vydaní: verziu, edíciu, architektúry a odtlačok vydávacieho kľúča
images/<service>/ Každý obraz s oboma platformami, jeho podpisom a jeho atestáciami
charts/nexus-1.0.0-alpha.1.tgz Chart
sbom/ SBOM vo formáte SPDX každého obrazu pre každú platformu
docs/ Poznámky k vydaniu, príručku inštalácie v izolovanej sieti (air-gap) a príklady hodnôt
SHA256SUMS a SHA256SUMS.sigstore.json Kontrolný súčet každého súboru a jeho podpis

Verejný kľúč vydania sa nikdy nenachádza vo vnútri balíka; kľúč, ktorý sa dodáva s vecou, ktorú podpisuje, nič nedokazuje. Skontrolujte celý balík dvoma príkazmi z jeho priečinka:

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

Každý riadok prvého príkazu by sa mal končiť OK a druhý by mal vypísať Verified OK. Kapitola 2.10, Inštalácia v izolovanej sieti (air-gapped), odtiaľto pokračuje v práci s balíkom: nahráva obrazy do vášho vlastného registra, každý z nich tam znova overuje a vykonáva vlastnú komplexnú kontrolu balíka.

Ako skontrolovať stiahnutý súbor
Ako skontrolovať stiahnutý súbor
Ako skontrolovať stiahnutý súbor v účte Adverant. Dve offline kontroly, ukážka dobrého a zlého výsledku a odtlačok vydávacieho kľúča v skupinách po štyroch znakoch na vizuálne porovnanie.

Keď sa podpis nepodarí overiť

Zastavte. Neinštalujte a nemeňte príkaz, kým neprejde. Neúspešná kontrola podpisu znamená, že systém funguje: znamená to, že súbor, ktorý máte, nie je súbor, ktorý spoločnosť Adverant podpísala, alebo kľúč, ktorý držíte, nepatrí spoločnosti Adverant.

Čo vidíte Čo to znamená Čo robiť
accepted signatures do not match threshold, Found: 0, Expected 1 (návratový kód 1) Obraz je podpísaný, ale nie kľúčom, ktorý ste zadali Skontrolujte, či ste použili vydávací kľúč, ktorého odtlačok ste overili v kroku 1
no signatures found (návratový kód 10) Na danom odtlačku nie je nič podpísané Skontrolujte, či odtlačok pochádza zo zámku; nikdy neoverujte značku (tag)
not enough verified log entries from transparency log: 0 < 1 Chýba --insecure-ignore-tlog=true Pridajte príznak; s obrazom nie je nič v neporiadku
none of the attestations matched the predicate type Vyžiadali ste si typ atestácie, ktorý obraz nenesie Použite spdxjson alebo slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Stiahnutý súbor bol po podpísaní zmenený Stiahnite ho znova
FAILED z sha256sum -c Súbor sa nezhoduje so súborom, pre ktorý bol vytvorený kontrolný súčet Stiahnite ho znova

Ak sťahovanie zlyhá dvakrát, otvorte žiadosť o podporu zo svojho účtu a uveďte názov súboru a chybovú správu. Chybný súbor si ponechajte; váš bezpečnostný tím ho môže chcieť vidieť.

Pri inštalácii, ktorá načítava vydania z disku, konzola spúšťa rovnaké kontroly a odmietne vydanie, ktorého podpis sa nezhoduje s nainštalovaným kľúčom, s chybou MEDIA_SIGNATURE_INVALID. Uvedie, čo skontrolovala, v akom poradí, kde sa zastavila, a že sa nič nezmenilo: nenačítal sa žiadny obraz, bežiaca verzia zostala nedotknutá.

Import z média zlyhal
Import z média zlyhal
Vydanie na disku, ktoré neprešlo kontrolou podpisu. Všimnite si poradie kontrol s tou, ktorá proces zastavila, očakávaný a nájdený odtlačok kľúča a jasné vyhlásenie, že sa nič nenačítalo ani nezmenilo.

Keď kľúč, obrazy aj chart úspešne prejdú kontrolou, ďalším krokom je predletová kontrola (preflight) vášho klastra v kapitole 2.5, Predletová kontrola pomocou nexusctl.