サインインブリーフィングを予約

第 2.4 章

リリースの取得と検証

Nexusリリースの各要素がどこに配置されているか、プルトークンを使用してEnterpriseイメージをどのように取得するか、そして何かをインストールする前に、すべてのイメージ、チャート、ダウンロードが変更されることなくAdverantから提供されたことをオフラインで証明する方法について説明します。

このページは英語の原文から AI によって翻訳されました。不明な点がある場合は、英語のページを正としてご参照ください。 このページを英語で読む

読了時間 15 分

NexusリリースのすべてのイメージはAdverantのリリースキーによって署名されており、すべてのイメージはタグではなくダイジェストによって名前が付けられています。チャートは、自身のイメージロック内にダイジェストでリストされているイメージのみをレンダリングします。これらを合わせると、ご自身のワークステーション上で、誰とも接続することなく、これから実行しようとしているものがAdverantがビルドしたものと完全に一致することを証明できることを意味します。

Harrow Port Authorityでは、最初のインストールの前にすべてを確認しました。これには約20分かかりましたが、その大部分はイメージに対するループ処理でした。この章では同じ手順をたどります。リリースの各パーツがどこにあるか、Enterpriseイメージ用のプルトークン、イメージロック、正確なコマンドを用いたcosignによるチェック、そしてチェックが失敗したときの対処法について説明します。

リリースの配置場所

アドレス そこで取得するもの
registry.adverant.ai registry.adverant.ai/nexus/<service>@sha256:<digest>にあるプラットフォームイメージ、およびoci://registry.adverant.ai/nexus/charts/nexusにあるHelmチャート
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ リリース公開鍵とそのフィンガープリント、nexusctlバイナリ、およびオフラインバンドル
https://account.adverant.ai Adverantアカウント:ダウンロード、プルトークンとインストールコマンド、デプロイメント、およびライセンスページ

CommunityイメージとCommunityチャートは公開されており、サインインせずにプルできます。Enterpriseイメージはアカウントからのプルトークンを使用してプルされ、Enterpriseチャートとバンドルはライセンスに従うアカウントのダウンロードページにあります。

ダウンロード
ダウンロード
バージョンおよびチャネルごとの、Adverantアカウント内のダウンロード。各ファイルの横にはそのチェックサムと署名があり、ライセンス外のパーツは理由とともにグレー表示でリストされたままになります。

何よりも先にリリースノートを読む

リリースノートはすべてのバンドル内にdocs/RELEASE-NOTES.mdとして同梱され、そのSHA256SUMSにリストされており、同じノートがアカウントのリリースページにもあります。インストールまたはアップグレードの前にこれらをお読みください。1.0.0-alpha.1については短い内容となっています。これは最初のリリースであるため、新規インストールには記載されているアップグレードの注意点は一切なく、既知の問題リストには、文書化された手順に従った新規インストールに影響を与えるものはないと記載されています。以降のリリースでは、各既知の問題とそれを修正するバージョンがリストされます。

また、リリースページには、アルファリリースが約束する内容が3行で記載されています。最初の安定版の前に機能が変更される可能性があること、アップグレードはデータを保持し最初にバックアップを取得すること、そしてセキュリティ修正は7日以内に到着することです。Harrowでは、変更諮問委員会が求めるサポート声明に最も近いものであったため、そのページを印刷して変更記録に保管しました。

ステップ1:リリースキーを取得し、別経路で確認する

以下のすべては、1つのファイル、つまりAdverantのリリース公開鍵に依存しています。それが保証する対象と同じ場所から入手した鍵はほとんど何も証明しないため、別の方法で届いたコピーとフィンガープリントを照合してください。

  1. ダウンロードにあるリリースのフォルダから鍵をダウンロードします。

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. そのフィンガープリントを算出します。フィンガープリントは、鍵ファイル自体のSHA-256(Secure Hash Algorithm 256)です。

    sha256sum release.pub

    macOSでは、shasum -a 256 release.pubが同じ結果を返します。

  3. Adverantとの契約書およびリリースノートに印刷されているフィンガープリントと、1文字ずつ比較します。ダウンロードでもフィンガープリントは公開されていますが、そのコピーは鍵と同じ経路で入手したものであるため、確認にはなりません。

1文字でも異なる場合は、中止してください。インストールせず、インターネット上で鍵の別のコピーを探し回ったりしないでください。アカウントからサポートリクエストを開き、確認された内容をそのままお伝えください。

ステップ2:nexusctlを取得する

nexusctlは、Nexusオペレーターのコマンドラインインターフェース(CLI)です。ワークステーション上で実行され、kubeconfigを介してクラスターを読み取ります。ダウンロードでは4つのビルドが提供されています。

ファイル プラットフォーム
nexusctl-linux-amd64 IntelまたはAMD上のLinux
nexusctl-darwin-arm64 Appleシリコン上のmacOS
nexusctl-darwin-amd64 Intel上のmacOS
nexusctl-windows-amd64.exe Windows

各ファイルの横には、同じ名前の末尾に.sigstore.jsonが付いた署名バンドルがあります。実行する前にバイナリを確認してください。

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

次に、それをパスに配置し、バージョンを確認します。

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

これ以降は、nexusctl verifyがファイルチェックを代行できます。第2.5章「nexusctlによるプリフライト」では、その主な役割であるプリフライトについて説明します。

フラグに「insecure」と付いている理由

この章のすべてのcosignコマンドには--insecure-ignore-tlog=trueが付いています。NexusリリースはAdverantの鍵で署名されており、公開の透明性ログには記録されません。これは、リリースの確認においてSigstoreを含む誰との接続も一切必要としないようにするためです。デフォルトではcosignはログエントリを要求しますが、このフラグは鍵のみに依拠するよう指示します。これがない場合、チェックは次のように失敗します。

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

フラグが設定されている場合でも、cosignは「Existence of the claims in the transparency log was verified offline」という文を出力します。これはcosignにおける固定の文言であり、その背後にログエントリは存在しません。鍵に対する署名チェックは本物であり、それが重要な部分です。

ステップ3:Enterprise用のプルトークン

Enterpriseイメージはプルトークンによって保護されています。アカウントの「プルトークンとインストールコマンド」でトークンを作成します。

  1. トークンを追加を押します。
  2. どのクラスター用か、何を取得できるか、いつ終了するかを指定します。
  3. ページにはこの1回しか表示されないため、トークンをコピーを押して、認証情報を保管している場所に直接貼り付けます。

各トークンは取得できるものが制限されており、終了日があります。トークンを取り消すと新しいプルは即座に停止しますが、クラスターがすでにプルしたイメージは実行され続けます。Harrowではクラスターごとに1つのトークンを作成したため、テストクラスターのトークンを取り消しても本番環境には一切影響しません。Communityインストールではトークンは全く必要ありません。Enterpriseに移行するときにのみ作成すればよく、当日に作成することができます。

プルトークンとインストールコマンド
プルトークンとインストールコマンド
Adverantアカウント内のプルトークン。各トークンには、取得できるもの、作成者、終了日が表示されます。新しいトークンは1回だけ表示され、トークンを取り消すと、すでに実行中のものを停止することなく新しいプルを停止します。

チャートにはプルシークレットの値がありません。ノードがイメージをプルするため、トークンはノードのコンテナランタイムに属します。k3sでは、すべてのノードの/etc/rancher/k3s/registries.yamlにレジストリを追加し、そこでk3sを再起動します。

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

<registry-user>はAdverantの招待状に記載されているレジストリのユーザー名であり、<pull-token>はコピーしたトークンです。このファイルには認証情報が含まれているため、rootのみが読み取れるようにしてください。

ノードがそのファイルを読み取らないマネージドクラスターでは、ノードがすでに信頼しているレジストリにイメージをコピーし、そこにglobal.imageRegistryを設定します。すべてのノードがそのレジストリのTransport Layer Security(TLS)証明書を信頼している必要があります。第2.11章「バリエーション:外部ストア、TLS、およびイングレス」でこれについて説明し、第2.10章「エアギャップ環境へのインストール」では、外部へのルートがないサイトにおける同じコピーについて説明します。

ステップ4:イメージロックを読み取る

Nexusチャートは、タグによってイメージを指定することは決してありません。チャートがfiles/images.lock.jsonとして保持するファイルであるイメージロックから取得した、マルチプラットフォームインデックスのダイジェストによって各イメージを指定します。オフラインバンドルは同じロックをrelease/images.lock.jsonとして保持します。

ロックを読み取るには、チャートをプルして解凍します。

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

ロックのトップレベルには、それがどのリリースおよびどのエディションに属するかが示されています。imagesの下の各エントリは、1つのイメージを記述しています。

フィールド 保持する内容
svc nexus-authやnexus-postgresなどのサービス
index linux/amd64とlinux/arm64の両方をカバーする、イメージのインデックスのsha256:ダイジェスト
edition データ層用のcommunity、enterprise、またはall
kind 5つのデータストアとOpenBao用のservice、migrations、またはdata-tier
verified リリースビルドがその署名とアテステーションを検証した日時

チャートはすべてのイメージを<global.imageRegistry>/nexus/<svc>@<index>としてレンダリングします。したがって、global.imageRegistry: registry.adverant.aiの場合、サインインサービスはregistry.adverant.ai/nexus/nexus-auth@sha256:の後に64個の16進文字が続くものになり、クラスター内の何がそれを同じ名前の別のものに置き換えることもできません。

ロックはエディションごとです。Communityロックには、エディションがcommunityまたはallであるイメージのみがリストされます。Enterpriseロックには、それらに加えてEnterpriseビルドがリストされます。チャートはレンダリングするたびにこれを確認し、推測するのではなく拒否します。

チャートの出力内容 理由
edition=enterprise but enterprise.enabled=false: they must agree valuesファイル内の2つのエディション値が一致していません
files/images.lock.json is the community lock; this install is edition enterprise CommunityチャートからEnterpriseをインストールしようとしているか、その逆です
image nexus-auth is not in files/images.lock.json チャートとそのロックの対応関係が正しくありません。チャートを再取得してください
image ... is in the lock but was never verified by build-all ロックエントリに検証日時がありません。これからインストールしないでください
NEXUS_EDITION_INVALID editionが空であるか、communityとenterpriseのいずれでもありません
RELEASE_VERSION_MISSING ロックにバージョンが指定されていません

すべてのイメージとダイジェストを一度にリストします。

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

ステップ5:すべてのイメージの署名を検証する

各イメージインデックスは署名されており、その中の各プラットフォームマニフェストも同様です。チャートが実行するものを正確に確認できるよう、ロックから直接ダイジェストによって検証します。

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

すべての行がOKで始まる必要があります。私たちの回線ではループに数分かかりましたが、その大部分はレジストリの待機時間でした。これは署名のみを読み取り、イメージレイヤーは取得しないため、アップグレードのたびに手軽に繰り返すことができます。FAILEDの行は停止を意味します。次のセクションで、各メッセージの意味を説明します。

単一のイメージについて確認する場合は、リダイレクトを外して、cosignが何を確認したかを読み取ります。

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>は、そのイメージに対するロックのindexからの64個の16進文字です。Enterpriseイメージでは、レジストリからのプルと同様に、この確認にもプルトークンが必要です。

下向きの矢印で結ばれた5つのボックスの垂直チェーン。一番上:「リリース公開鍵、契約書と照合されたフィンガープリント」。2番目:「チャートパッケージ nexus-1.0.0-alpha.1、署名済み」。3番目:「チャート内のイメージロック:インデックスダイジェストによるすべてのイメージ、1つのエディション」。4番目:「各イメージインデックス、署名済み、ソフトウェア部品表(SBOM)およびプロビナンスアテステーション付き」。一番下:「名前空間 nexus 内のポッド、ダイジェストによりプル」。一番上のボックスからの横の矢印は、「cosign verify, offline」とラベル付けされ、2番目と4番目のボックスを指しています。
確認した鍵から実行されるポッドまで、何が何を保証するか。

両方のプラットフォーム、および保管すべきもの

各イメージインデックスはlinux/amd64とlinux/arm64の2つのプラットフォームマニフェストを保持しており、それぞれも署名されています。cosign verifyはインデックスダイジェストおよびいずれかのプラットフォームダイジェストで成功するため、異なるノードが混在するクラスターも同じチェックでカバーされます。インデックスの背後にある2つのプラットフォームを確認するには、レジストリに生のインデックスを要求します。

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

そのmanifestsリストには、1つのamd64エントリと1つのarm64エントリが指定されています。

上記のループの出力は、確認したフィンガープリントの横に、変更記録とともに保管してください。数か月後に、クラスターがAdverantが出荷したものを実行しているとどうしてわかるのかと誰かに尋ねられたとき、そのファイルとロックのダイジェストが答えになります。Harrowの監査人はまさにその質問をし、回答には1分しかかかりませんでした。

ステップ6:アテステーションを読み取る

また、各イメージは、ビルド時にイメージから作成された2つの署名付きアテステーション、つまりソフトウェア部品表(SBOM)とプロビナンス(来歴)声明を保持しています。

SBOMはSoftware Package Data Exchange(SPDX)形式であり、プラットフォームごとに1つずつあるため、インデックスは2つ保持しています。これには、イメージ内のすべてのパッケージがそのライセンスとともにリストされています。リリース前に、それらのライセンスは拒否リストと照合されます。Communityイメージには、GNU Affero General Public License(AGPL)、Server Side Public License(SSPL)、Redis Source Available License(RSAL)、またはBusiness Source License(BUSL)のコードは一切含まれていません。プロビナンス声明はSupply-chain Levels for Software Artifacts(SLSA)v1です。これには、イメージがビルドされた元のソースコミット、ベースイメージのダイジェスト、およびビルドツールとそのバージョンが記載されているため、Adverantに問い合わせることなく、イメージからレビュー済みのソースまで遡ることができます。

どちらも、すでに保持しているリリースキーと照合されます。

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チェックは、各プラットフォームのSBOMに対して1つずつ、計2つの結果を出力します。検証せずにイメージに添付されているすべてのものを確認するには、cosign treeを使用します。

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

これには、1つの署名バンドル、2つのspdx.dev/Documentアテステーション、および1つのslsa.dev/provenance/v1アテステーションがリストされます。--type cyclonedxなど、イメージが保持していないタイプを要求すると、none of the attestations matched the predicate type: cyclonedxで失敗します。リリースにはCycloneDXではなくSPDXが添付されているため、その失敗は正しい動作です。

ステップ7:チャートとダウンロードを検証する

レジストリ内のチャートは、そのOCIダイジェストに対して署名されています(OCIはOpen Container Initiativeであり、レジストリが使用するイメージおよびアーティファクトの形式です)。helm pullはプルしたダイジェストを出力します。イメージと同じ方法でそのダイジェストを確認してください。

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

ダウンロードしたチャートファイル、またはオフラインバンドルについては、nexusctl verifyがAdverantリリースキーに対してファイルをチェックします。

nexusctl verify nexus-1.0.0-alpha.1.tgz

正常な結果は、最後にAdverantリリースキーとそのフィンガープリントの先頭を示します。それらのグループを、ステップ1で確認したフィンガープリントと比較してください。

オフラインバンドルは、エディションごとに1つの非圧縮tarファイル(nexus-alpha-1.0.0-alpha.1-community.tarまたはnexus-alpha-1.0.0-alpha.1-enterprise.tar)であり、その横に.sha256ファイルがあります。内部には以下が保持されています。

パス その内容
release/images.lock.json そのエディションのイメージロック
release/facts.json リリース情報:バージョン、エディション、アーキテクチャ、およびリリースキーのフィンガープリント
images/<service>/ 両方のプラットフォーム、その署名、およびそのアテステーションを含む各イメージ
charts/nexus-1.0.0-alpha.1.tgz チャート
sbom/ プラットフォームごとの、すべてのイメージのSPDX SBOM
docs/ リリースノート、エアギャップインストールガイド、および設定値の例
SHA256SUMSおよびSHA256SUMS.sigstore.json すべてのファイルのチェックサム、およびその署名

リリース公開鍵がバンドル内に入っていることは決してありません。署名対象と一緒に同梱されている鍵は何も証明しないためです。バンドルのフォルダ内から、2つのコマンドでバンドル全体を確認します。

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

1つ目のすべての行はOKで終わる必要があり、2つ目はVerified OKを出力する必要があります。第2.10章「エアギャップ環境へのインストール」では、そこからバンドルを扱います。つまり、独自のレジストリへのイメージのロード、そこでの各イメージの再検証、およびバンドル自体のエンドツーエンドのチェックです。

ダウンロードの確認方法
ダウンロードの確認方法
Adverantアカウントでの、ダウンロードの確認方法。2つのオフラインチェック、正常な結果と異常な結果の画像、および目視で比較するための4文字ずつのグループになったリリースキーのフィンガープリント。

署名を検証できない場合

中止してください。インストールせず、パスするまでコマンドを変更したりしないでください。署名チェックの失敗は、システムが機能している証拠です。つまり、お持ちのファイルがAdverantが署名したファイルではないか、お持ちの鍵がAdverantのものではないことを意味します。

表示内容 意味 対処法
accepted signatures do not match threshold, Found: 0, Expected 1 (exit 1) イメージは署名されていますが、指定した鍵によるものではありません ステップ1でフィンガープリントを確認したリリースキーを使用したか確認してください
no signatures found (exit 10) そのダイジェストには署名されたものがありません ダイジェストがロックからのものであることを確認してください。タグは決して検証しないでください
not enough verified log entries from transparency log: 0 < 1 --insecure-ignore-tlog=trueが不足しています フラグを追加してください。イメージには問題ありません
none of the attestations matched the predicate type イメージが保持していないアテステーションタイプを要求しました spdxjsonまたはslsaprovenance1を使用してください
Error: invalid signature when validating ASN.1 encoded signature ダウンロードされたファイルが署名後に変更されました もう一度ダウンロードしてください
sha256sum -cからのFAILED ファイルがチェックサム計算時のファイルと異なります もう一度ダウンロードしてください

ダウンロードが2回失敗する場合は、アカウントからサポートリクエストを開き、ファイル名とメッセージをそのままお伝えください。失敗したファイルは保管しておいてください。セキュリティチームが必要とする場合があります。

ディスクからリリースをロードするインストールでは、コンソールが同じチェックを実行し、インストールされている鍵と署名が一致しないリリースをMEDIA_SIGNATURE_INVALIDで拒否します。コンソールは、何をどの順序で確認したか、どこで停止したか、そして何も変更されていないこと(イメージはロードされず、実行中のバージョンはそのまま維持されていること)を示します。

メディアからのインポートに失敗しました
メディアからのインポートに失敗しました
署名チェックに失敗したディスク上のリリース。停止した箇所を含む順序どおりのチェック、期待される鍵のフィンガープリントと検出された鍵のフィンガープリント、および何もロードまたは変更されていないという明確な記述に注目してください。

鍵、イメージ、およびチャートがすべてパスしたら、次のステップは第2.5章「nexusctlによるプリフライト」にある、クラスターに対するプリフライトです。