Přihlásit seDomluvit prezentaci

Kapitola 2.4

Získání a ověření vydání

Kde se nachází každá část vydání systému Nexus, jak se obrazy Enterprise stahují pomocí pull tokenu a jak offline prokázat, že každý obraz, chart a stažený soubor pochází od společnosti Adverant v nezměněné podobě, ještě než cokoli nainstalujete.

Tato stránka byla přeložena pomocí AI z anglického originálu. Pokud je cokoliv nejasné, směrodatná je anglická stránka. Přečíst tuto stránku v angličtině

15 min čtení

Každý obraz ve vydání systému Nexus je podepsán klíčem vydání společnosti Adverant a každý obraz je pojmenován pomocí svého otisku (digest), nikdy pomocí štítku (tag). Balíček (chart) vykreslí pouze obrazy uvedené pomocí otisku ve svém vlastním zámku obrazů (images lock). Dohromady to znamená, že můžete na své vlastní pracovní stanici a bez připojení k čemukoli prokázat, že to, co se chystáte spustit, je přesně to, co společnost Adverant sestavila.

V Harrow Port Authority jsme před první instalací vše zkontrolovali. Trvalo to asi dvacet minut a většinu toho času zabral cyklus procházející obrazy. Tato kapitola jde stejnou cestou: kde se nachází každá část vydání, stahovací token (pull token) pro obrazy edice Enterprise, zámek obrazů, kontroly pomocí cosign s jejich přesnými příkazy a co dělat, když kontrola selže.

Kde se vydání nachází

Adresa Co zde získáte
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/ Veřejný klíč vydání a jeho otisk (fingerprint), binární soubory nexusctl a offline balíčky
https://account.adverant.ai Váš účet Adverant: Ke stažení, Stahovací tokeny a instalační příkazy, Nasazení a stránky s licencemi

Obrazy edice Community a chart Community jsou veřejné; můžete je stáhnout bez přihlášení. Obrazy edice Enterprise se stahují pomocí stahovacího tokenu z vašeho účtu a chart a balíček Enterprise jsou na stránce Ke stažení ve vašem účtu, která se řídí vaší licencí.

Ke stažení
Ke stažení
Položky ke stažení v účtu Adverant, podle verze a kanálu. Každý soubor má vedle sebe svůj kontrolní součet a podpis a části mimo licenci zůstávají v seznamu zobrazeny šedě s uvedením důvodu.

Především si přečtěte poznámky k vydání

Poznámky k vydání jsou součástí každého balíčku jako docs/RELEASE-NOTES.md, jsou uvedeny v jeho SHA256SUMS a stejné poznámky jsou na stránce vydání ve vašem účtu. Přečtěte si je před instalací nebo upgradem. Pro 1.0.0-alpha.1 jsou krátké. Jedná se o první vydání, takže čistá instalace neobsahuje žádné body pro upgrade, které popisují, a seznam známých problémů uvádí, že nic v něm neovlivňuje čistou instalaci, která postupuje podle zdokumentovaných kroků. Pozdější vydání uvádějí každý známý problém spolu s verzí, která jej opravuje.

Stránka vydání také ve třech řádcích uvádí, co slibuje alfa vydání: funkce se mohou před první stabilní verzí změnit, upgrade zachová vaše data a nejprve provede zálohu a bezpečnostní opravy dorazí do 7 dnů. Tuto stránku jsme vytiskli a vložili do záznamu o změnách v Harrow, protože je to nejblíže prohlášení o podpoře, které by komise pro změny požadovala.

Krok 1: získejte klíč vydání a zkontrolujte jej druhou cestou

Vše níže uvedené spočívá na jednom souboru: veřejném klíči vydání společnosti Adverant. Klíč, který pochází ze stejného místa jako věc, za kterou ručí, dokazuje jen velmi málo, proto zkontrolujte jeho otisk oproti kopii, která se k vám dostala jinou cestou.

  1. Stáhněte si klíč ze složky vydání na stránce Ke stažení.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Vypočítejte jeho otisk. Otisk je hodnota SHA-256 (Secure Hash Algorithm 256) samotného souboru klíče.

    sha256sum release.pub

    V systému macOS dává shasum -a 256 release.pub stejný výsledek.

  3. Porovnejte jej, znak po znaku, s otiskem vytištěným ve vaší smlouvě se společností Adverant a v poznámkách k vydání. Stránka Ke stažení otisk zveřejňuje také, ale tato kopie přišla stejnou cestou jako klíč, takže neslouží jako kontrola.

Pokud se kterýkoli znak liší, zastavte. Neinstalujte a nehledejte jinou kopii klíče na internetu. Otevřete požadavek na podporu ze svého účtu a uveďte, co jste zjistili.

Krok 2: získejte nexusctl

nexusctl je rozhraní příkazového řádku (CLI) operátora systému Nexus. Běží na vaší pracovní stanici a čte váš cluster prostřednictvím vašeho souboru kubeconfig. Stránka Ke stažení nabízí čtyři sestavení:

Soubor Platforma
nexusctl-linux-amd64 Linux na procesorech Intel nebo AMD
nexusctl-darwin-arm64 macOS na čipech Apple silicon
nexusctl-darwin-amd64 macOS na procesorech Intel
nexusctl-windows-amd64.exe Windows

Vedle každého souboru je jeho balíček s podpisem, který má stejný název s příponou .sigstore.json na konci. Před spuštěním binární soubor zkontrolujte:

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

Poté jej umístěte do své systémové cesty (PATH) a dotazem zjistěte jeho verzi:

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

Od této chvíle může nexusctl verify provádět kontroly souborů za vás. Kapitola 2.5, Předletová kontrola s nexusctl, se věnuje jeho hlavnímu úkolu, předletové kontrole (preflight).

Proč příznak obsahuje slovo „insecure“

Každý příkaz cosign v této kapitole obsahuje --insecure-ignore-tlog=true. Vydání systému Nexus jsou podepsána klíčem společnosti Adverant a nejsou zaznamenána v žádném veřejném protokolu transparentnosti, takže kontrola vydání nikdy nepotřebuje připojení k čemukoli, včetně služby Sigstore. Ve výchozím nastavení cosign trvá na záznamu v protokolu; příznak mu říká, aby se spolehl pouze na klíč. Bez něj kontrola selže takto:

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

Když je příznak nastaven, cosign stále vypisuje větu „Existence of the claims in the transparency log was verified offline“. To je pevná formulace v cosign; žádný záznam v protokolu za tím není. Kontrola podpisu oproti klíči je skutečná a je to ta část, na které záleží.

Krok 3: pull token pro edici Enterprise

Obrazy edice Enterprise jsou chráněny stahovacím tokenem. Vytvoříte si jej ve svém účtu na stránce Stahovací tokeny a instalační příkazy:

  1. Stiskněte Přidat token.
  2. Uveďte, pro který cluster je určen, co může stahovat a kdy končí jeho platnost.
  3. Stiskněte Zkopírovat token a vložte jej rovnou tam, kde uchováváte přístupové údaje, protože stránka jej zobrazí pouze tentokrát.

Každý token je omezen na to, co může stahovat, a má datum ukončení platnosti. Odvolání tokenu okamžitě zastaví nová stahování; obrazy, které cluster již stáhl, běží dál. V Harrow jsme vytvořili jeden token pro každý cluster, takže odvolání tokenu testovacího clusteru se nikdy nedotkne produkce. Instalace edice Community nepotřebuje žádný token; vytvoříte si jej až při přechodu na edici Enterprise a můžete si jej vytvořit v ten samý den.

Stahovací tokeny a instalační příkazy
Stahovací tokeny a instalační příkazy
Stahovací tokeny v účtu Adverant. Každý token ukazuje, co může stahovat, kdo jej vytvořil a kdy končí jeho platnost; nový token se zobrazí jednou a jeho odvolání zastaví nová stahování, aniž by zastavilo cokoli, co již běží.

Chart nemá žádnou hodnotu pull-secret. Obrazy stahují vaše uzly, takže token patří běhovému prostředí kontejnerů (container runtime) na uzlech. V systému k3s přidejte registr do /etc/rancher/k3s/registries.yaml na každém uzlu a restartujte tam k3s:

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

<registry-user> je uživatelské jméno registru z vaší pozvánky od společnosti Adverant a <pull-token> je token, který jste zkopírovali. Soubor obsahuje přístupový údaj, proto jej ponechte čitelný pouze pro uživatele root.

Ve spravovaném clusteru, jehož uzly tento soubor nečtou, zkopírujte obrazy do registru, kterému vaše uzly již důvěřují, a nastavte na něj global.imageRegistry; každý uzel musí důvěřovat certifikátu TLS (Transport Layer Security) daného registru. Tomu se věnuje kapitola 2.11, Variace: externí úložiště, TLS a ingress, a kapitola 2.10, Instalace v izolovaném prostředí (air-gapped), popisuje stejné kopírování pro lokalitu bez přístupu ven.

Krok 4: přečtěte si zámek obrazů

Chart systému Nexus nikdy nepojmenovává obraz pomocí štítku (tag). Každý obraz pojmenovává pomocí otisku (digest) jeho multiplatformního indexu, převzatého ze zámku obrazů (images lock), což je soubor, který chart obsahuje jako files/images.lock.json. Offline balíček obsahuje stejný zámek jako release/images.lock.json.

Stáhněte chart a rozbalte jej, abyste si mohli přečíst zámek:

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

Nejvyšší úroveň zámku uvádí, ke kterému vydání a které edici patří. Každá položka pod images popisuje jeden obraz:

Pole Co obsahuje
svc Službu, například nexus-auth nebo nexus-postgres
index Otisk sha256: indexu obrazu, který pokrývá jak linux/amd64, tak linux/arm64
edition community, enterprise nebo all pro datovou vrstvu
kind service, migrations nebo data-tier pro pět datových úložišť a OpenBao
verified Kdy sestavení vydání ověřilo svůj podpis a atestace

Chart vykreslí každý obraz jako <global.imageRegistry>/nexus/<svc>@<index>. Takže s global.imageRegistry: registry.adverant.ai je přihlašovací služba registry.adverant.ai/nexus/nexus-auth@sha256: následovaná 64 hexadecimálními znaky a nic v clusteru ji nemůže zaměnit za něco jiného se stejným názvem.

Zámek je specifický pro každou edici. Zámek edice Community uvádí pouze obrazy, jejichž edice je community nebo all. Zámek edice Enterprise uvádí tyto obrazy plus sestavení Enterprise. Chart to kontroluje při každém vykreslení a raději akci odmítne, než aby hádal:

Co hlásí chart Proč
edition=enterprise but enterprise.enabled=false: they must agree Dvě hodnoty edice ve vašem souboru hodnot (values) si odporují
files/images.lock.json is the community lock; this install is edition enterprise Instalujete edici Enterprise z chartu Community nebo naopak
image nexus-auth is not in files/images.lock.json Chart a jeho zámek k sobě nepatří; stáhněte chart znovu
image ... is in the lock but was never verified by build-all Položka zámku nemá čas ověření; neinstalujte z něj
NEXUS_EDITION_INVALID Hodnota edition je prázdná nebo není jednou z hodnot community a enterprise
RELEASE_VERSION_MISSING Zámek neuvádí žádnou verzi

Vypište každý obraz a otisk najednou:

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

Krok 5: ověřte podpis každého obrazu

Každý index obrazu je podepsán a stejně tak i každý manifest platformy uvnitř něj. Ověřujte pomocí otisku přímo ze zámku, abyste zkontrolovali přesně to, co 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ý řádek by měl začínat OK. Na naší lince trval cyklus několik minut, z čehož většinu času zabralo čekání na registr. Čte pouze podpisy a nestahuje žádné vrstvy obrazů, díky čemuž je nenáročné jej opakovat po každém upgradu. Řádek FAILED znamená zastavit: další část uvádí, co jednotlivé zprávy znamenají.

Pro jeden samostatný obraz vynechte přesměrování a přečtěte si, co cosign zkontroloval:

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álních znaků z index v zámku pro daný obraz. Obrazy edice Enterprise potřebují pro tuto kontrolu váš stahovací token, stejně jako pro jakékoli stahování z registru.

Svislý řetězec pěti polí spojených šipkami směřujícími dolů. Nahoře: „Veřejný klíč vydání, otisk zkontrolován oproti vaší smlouvě“. Druhé: „Balíček chartu nexus-1.0.0-alpha.1, podepsaný“. Třetí: „Zámek obrazů uvnitř chartu: každý obraz podle otisku indexu, jedna edice“. Čtvrté: „Každý index obrazu, podepsaný, se soupisem softwarových materiálů (SBOM) a atestacemi původu“. Dole: „Pody ve jmenném prostoru nexus, stažené podle otisku“. Boční šipka z horního pole ukazuje na druhé a čtvrté pole a je označena „cosign verify, offline“.
Co za co ručí, od klíče, který jste zkontrolovali, až po pody, které běží.

Obě platformy a co si ponechat

Každý index obrazu obsahuje dva manifesty platforem, linux/amd64 a linux/arm64, a každý z nich je rovněž podepsán. Příkaz cosign verify uspěje u otisku indexu i u otisku kterékoli platformy, takže cluster se smíšenými uzly je pokryt stejnou kontrolou. Chcete-li vidět dvě platformy za indexem, požádejte registr o nezpracovaný index:

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

Jeho seznam manifests uvádí jednu položku amd64 a jednu položku arm64.

Výstup výše uvedeného cyklu si ponechte u svého záznamu o změnách, vedle otisku klíče, který jste zkontrolovali. Když se o několik měsíců později někdo zeptá, jak víte, že cluster provozuje to, co společnost Adverant dodala, tento soubor a otisky v zámku na to odpoví. Náš auditor v Harrow položil přesně tuto otázku a odpověď trvala minutu.

Krok 6: přečtěte si atestace

Každý obraz také nese dvě podepsané atestace, vytvořené z obrazu v době sestavení: soupis softwarových materiálů (SBOM) a prohlášení o původu (provenance statement).

SBOM je ve formátu SPDX (Software Package Data Exchange), jeden pro každou platformu, takže index nese dva. Uvádí každý balíček v obrazu spolu s jeho licencí. Před vydáním jsou tyto licence zkontrolovány oproti seznamu zakázaných položek; žádný obraz edice Community neobsahuje kód pod licencemi GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) ani Business Source License (BUSL). Prohlášení o původu odpovídá standardu SLSA (Supply-chain Levels for Software Artifacts) v1. Uvádí zdrojový commit, ze kterého byl obraz sestaven, otisky základních obrazů a nástroje pro sestavení a jejich verze, takže obraz lze vysledovat zpět ke zkontrolovanému zdrojovému kódu bez dotazování společnosti Adverant.

Obojí se kontroluje oproti klíči vydání, který již 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 pro SBOM každé platformy. Chcete-li zobrazit vše připojené k obrazu bez ověřování, použijte cosign tree:

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

Vypíše jeden balíček s podpisem, dvě atestace spdx.dev/Document a jednu atestaci slsa.dev/provenance/v1. Dotaz na typ, který obraz nenese, například --type cyclonedx, selže s chybou none of the attestations matched the predicate type: cyclonedx. Toto selhání je správné; vydání připojuje formát SPDX, nikoli CycloneDX.

Krok 7: ověřte chart a stažené soubory

Chart v registru je podepsán na svém otisku OCI (OCI je Open Container Initiative, formát obrazů a artefaktů, který registry používají). Příkaz helm pull vypíše otisk, který stáhl; zkontrolujte tento otisk stejným způsobem jako obraz:

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

U souboru chartu, který jste stáhli, nebo u offline balíčku zkontroluje nexusctl verify soubor oproti klíči vydání společnosti Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Dobrý výsledek končí uvedením klíče vydání společnosti Adverant a začátku jeho otisku. Porovnejte tyto skupiny s otiskem, který jste zkontrolovali v kroku 1.

Offline balíček je jeden nekomprimovaný soubor tar pro každou edici, nexus-alpha-1.0.0-alpha.1-community.tar nebo nexus-alpha-1.0.0-alpha.1-enterprise.tar, se souborem .sha256 vedle něj. Uvnitř obsahuje:

Cesta Co to je
release/images.lock.json Zámek obrazů pro danou edici
release/facts.json Údaje o vydání: verze, edice, architektury a otisk klíče vydání
images/<service>/ Každý obraz s oběma platformami, jeho podpisem a jeho atestacemi
charts/nexus-1.0.0-alpha.1.tgz Chart
sbom/ SPDX SBOM každého obrazu, pro každou platformu
docs/ Poznámky k vydání, příručku pro instalaci v izolovaném prostředí (air-gap) a příklady hodnot
SHA256SUMS a SHA256SUMS.sigstore.json Kontrolní součet každého souboru a jeho podpis

Veřejný klíč vydání není nikdy uvnitř balíčku; klíč, který se dodává s věcí, kterou podepisuje, nic nedokazuje. Zkontrolujte celý balíček dvěma příkazy zevnitř jeho složky:

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

Každý řádek prvního příkazu by měl končit OK a druhý by měl vypsat Verified OK. Kapitola 2.10, Instalace v izolovaném prostředí (air-gapped), odtud s balíčkem pokračuje dál: načtení obrazů do vašeho vlastního registru, opětovné ověření každého z nich na tomto místě a vlastní komplexní kontrola balíčku.

Jak zkontrolovat stažený soubor
Jak zkontrolovat stažený soubor
Jak zkontrolovat stažený soubor v účtu Adverant. Dvě offline kontroly, ukázka dobrého a špatného výsledku a otisk klíče vydání ve skupinách po čtyřech pro vizuální porovnání.

Když se podpis nepodaří ověřit

Zastavte. Neinstalujte a neměňte příkaz, dokud neprojde. Neúspěšná kontrola podpisu znamená, že systém funguje: znamená to, že soubor, který máte, není soubor, který společnost Adverant podepsala, nebo klíč, který držíte, nepatří společnosti Adverant.

Co vidíte Co to znamená Co dělat
accepted signatures do not match threshold, Found: 0, Expected 1 (návratový kód 1) Obraz je podepsán, ale ne klíčem, který jste zadali Zkontrolujte, zda jste použili klíč vydání, jehož otisk jste zkontrolovali v kroku 1
no signatures found (návratový kód 10) Nic na tomto otisku není podepsáno Zkontrolujte, zda otisk pochází ze zámku; nikdy neověřujte štítek (tag)
not enough verified log entries from transparency log: 0 < 1 Chybí --insecure-ignore-tlog=true Přidejte příznak; s obrazem není nic v nepořádku
none of the attestations matched the predicate type Požádali jste o typ atestace, který obraz nenese Použijte spdxjson nebo slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Stažený soubor byl po podepsání změněn Stáhněte jej znovu
FAILED z sha256sum -c Soubor není tím souborem, u kterého byl vytvořen kontrolní součet Stáhněte jej znovu

Pokud stahování selže dvakrát, otevřete požadavek na podporu ze svého účtu a uveďte název souboru a zprávu. Nevyhovující soubor si ponechte; váš bezpečnostní tým jej může chtít.

V instalaci, která načítá vydání z disku, spouští konzole stejné kontroly a odmítne vydání, jehož podpis neodpovídá nainstalovanému klíči, s chybou MEDIA_SIGNATURE_INVALID. Uvede, co kontrolovala, v jakém pořadí, kde se zastavila a že nebylo nic změněno: nebyl načten žádný obraz, běžící verze zůstala nedotčena.

Import z média selhal
Import z média selhal
Vydání na disku, které neprošlo kontrolou podpisu. Všimněte si kontrol v pořadí s tou, která proces zastavila, očekávaného a nalezeného otisku klíče a jasného prohlášení, že nebylo nic načteno ani změněno.

Jakmile klíč, obrazy i chart projdou kontrolou, dalším krokem je předletová kontrola (preflight) vašeho clusteru v kapitole 2.5, Předletová kontrola s nexusctl.