メインコンテンツまでスキップ

Yabanin オフライン(エアギャップ)バンドル — ビルドと検証

ネットワークに接続されたマシンで自己完結型の Yabanin バンドルを作り、ネットワークが一切ないマシンで検証・インストールする方法です。バンドルが使うのは、make release-artifacts と docker build がすでに生成する成果物だけです。バイナリと SHA256SUMS、SBOM、NOTICE 草案、任意の cosign 署名、保存済みコンテナイメージです。Kubernetes ベースのエアギャップ導入は、install-guide.md と airgap-checklist.md で別途扱います。このドキュメントは、最小の Docker/compose の経路です。

バンドルの内容​

ファイル生成元用途
dist/release/yabanin-*make release-artifacts静的サービスバイナリ(-trimpath、スタンプ済みのバージョン/コミット)
dist/release/SHA256SUMSmake release-artifactsすべてのバイナリに対する sha256
dist/release/SHA256SUMS.sigmake release-artifacts(COSIGN_KEY が設定されている場合のみ)SHA256SUMS に対する cosign 鍵ペア署名(R078 D-B の署名対象)
dist/release/yabanin-release.pubmake release-artifacts(署名時)COSIGN_KEY に対応する公開鍵。自動的にエクスポートされる(公開物のみ)
dist/release/sbom.spdx.json または dist/release/*.buildinfo + sbom.sourcemake release-artifactsSBOM(syft SPDX)。syft がインストールされていない場合のフォールバックは go version -m のビルドマニフェスト。sbom.source は、どの経路で生成したかを記録する
dist/release/THIRD-PARTY-NOTICES.md(+ NOTICE、NOTICE-litellm.txt)scripts/release/notice_bundle.sh 経由の make release-artifactsライセンス棚卸しから作る配布用 NOTICE 草案。ライセンス識別子と、「全文は埋め込んでいない」という明示的な免責。レビュアーが配布前に全文を添付する
dist/release/UNSIGNED-RELEASE-DISCLOSURE.mdmake release-artifacts(未署名の場合のみ)未署名リリースに必要な、リリースノート用の開示フラグメント(D-D)
images/*.tar + images/sbom-<image>.spdx.jsonscripts/airgap/build_bundle.shイメージごとの SBOM を付けて保存したイメージ(syft。syft がない場合は、正直な buildinfo/UNAVAILABLE フォールバックマーカー。syft の出力は決して偽装しない)
images/image-digests.txt(+ .sig)scripts/airgap/build_bundle.shイメージごとに記録したレジストリダイジェスト。COSIGN_KEY が設定されている場合は、それらに対する cosign 鍵ペア署名(オフラインで検証可能。R078 D-B の対象)
images.tar.gzdocker saveハードニング済み Yabanin イメージ + pgvector/pgvector:pg16 + redis:7-alpine
manifest.sha256sha256sumバンドル内のすべてのファイルに対するチェックサム(イメージ、SBOM、ダイジェスト、NOTICE 資料 — インストール前の改ざんチェック)
compose/airgap-compose.ymldeploy/onprem/airgap-compose.ymlbuild: がなく、レジストリ参照もない最小 compose

秘密情報はバンドルに決して入れません。COSIGN_KEY も .env もパスワードも入れません。同梱するのは公開鍵だけです。

前提条件​

ネットワークに接続されたビルドマシンで必要なもの:

  • go と make(make release-artifacts 用)。
  • docker(イメージのビルド + docker save)。
  • cosign — 任意ですが、署名付きバンドルには必須です。インストールされていない場合、make release-artifacts は署名をスキップし、リリースノート用に UNSIGNED-RELEASE-DISCLOSURE.md を書き、strict モードは失敗します(下記を参照)。
  • syft — 任意です。インストールされていない場合、SBOM は go version -m のビルドマニフェスト(バイナリごとの .buildinfo。sbom.source に記録)にフォールバックします。これは正直なビルドメタデータですが、完全な SPDX SBOM ではありません。
  • COSIGN_KEY — 署名用の秘密鍵のパス(オーナー鍵ペア、決定 D-A)。対応する公開鍵は、署名時に dist/release/yabanin-release.pub へ自動的にエクスポートされます。

strict モード(R078、オーナー決定 D-D)​

RELEASE_STRICT=1 にすると、セットが不完全になる場合、両方の生成側が失敗します(exit 1、「incomplete release artifacts/bundle」)。不完全になる条件は、syft がない、COSIGN_KEY がない、NOTICE 草案用のライセンス監査がない、イメージごとの SBOM がない、または cosign が失敗することです(以前は build_bundle.sh 内の || true で握りつぶされていました)。

strict モードで未署名のまま出荷する唯一の方法は、明示的なオーナー上書きです。

RELEASE_STRICT=1 RELEASE_ALLOW_UNSIGNED=true make release-artifacts

上書きは、スクリプトの出力と UNSIGNED-RELEASE-DISCLOSURE.md にそのまま記録され、リリースノートに含めなければなりません。これは 2026-10-31 リリースで承認された経路です(開示付きで未署名のまま出荷します)。このリリースのあと、上書きなしの strict モードが必須です。検証側にも同じ規則が適用されます。strict 検証は、RELEASE_ALLOW_UNSIGNED=true が設定されていない限り、未署名または不完全なバンドルで FAIL します。許可したことは出力に表示されます。

執筆時点のリポジトリ作成環境では、cosign と syft はインストールされていません。完全な SPDX SBOM 付きの署名済みリリースを作る前に、インストールする前提条件として扱ってください。これらがなくても、バンドルはハッシュで検証できます。airgap-verify.sh は署名ステージを隠さず、SKIP(未署名)として報告します。--strict では FAIL になります。

ステップ 1 — リリース成果物のビルド(接続されたマシン)​

# Without signing (records UNSIGNED-RELEASE-DISCLOSURE.md for the notes):
make release-artifacts

# With signing (preferred for air-gap delivery; D-A owner key-pair):
COSIGN_KEY=/secure/path/cosign.key make release-artifacts
# dist/release/yabanin-release.pub is exported automatically; it used to be:
# cosign public-key --key /secure/path/cosign.key > dist/release/yabanin-release.pub

# Strict, unsigned via the ratified 2026-10-31 override (D-D):
RELEASE_STRICT=1 RELEASE_ALLOW_UNSIGNED=true make release-artifacts

# Strict and signed (mandatory after the 2026-10-31 release):
RELEASE_STRICT=1 COSIGN_KEY=/secure/path/cosign.key make release-artifacts

このターゲットは NOTICE 草案も出力します(make licenses-report の棚卸しから、scripts/release/notice_bundle.sh 経由で作る THIRD-PARTY-NOTICES.md。先に make licenses-report を実行します)。また、すべてのバイナリをスモークテストします(クリーンなディレクトリでチェックサムを再検証し、ビルド情報を読み、無効な設定に対してバイナリを実行します。速いローカル失敗であり、ネットワークは使いません)。

注意: サービスバイナリは --help をサポートしません。それらに対する速い「動くか」の確認は、意図的に無効な設定です。ゼロ以外で終了しなければなりません(make release-artifacts が内部で行っているのは、まさにこれです)。

ステップ 2 — イメージのビルドと保存(接続されたマシン)​

VERSION=$(git describe --tags --always)
docker build -f Dockerfile.hardened -t "yabanin:hardened-${VERSION}" .

# Pin third-party images by digest for reproducibility (record the digests you use):
docker pull pgvector/pgvector:pg16
docker pull redis:7-alpine

mkdir -p dist/offline
docker save "yabanin:hardened-${VERSION}" pgvector/pgvector:pg16 redis:7-alpine \
| gzip > "dist/offline/images-${VERSION}.tar.gz"

ステップ 3 — バンドルの組み立て(接続されたマシン)​

VERSION=$(git describe --tags --always)
B="dist/offline/yabanin-offline-${VERSION}"
mkdir -p "${B}/dist" "${B}/compose"
cp -R dist/release "${B}/dist/release"
cp "dist/offline/images-${VERSION}.tar.gz" "${B}/images.tar.gz"
cp deploy/onprem/airgap-compose.yml "${B}/compose/airgap-compose.yml"

cd "$B"
find . -type f ! -name manifest.sha256 -print0 | sort -z \
| xargs -0 sha256sum > manifest.sha256
cd - >/dev/null

tar -czf "dist/offline/yabanin-offline-${VERSION}.tar.gz" -C dist/offline "yabanin-offline-${VERSION}"

yabanin-offline-<version>.tar.gz を、承認済みの媒体(USB、プライベートリンク経由の scp)でエアギャップマシンへ転送します。転送前に、バンドルに秘密の材料が含まれていないことを確認します。grep -r "BEGIN PRIVATE" dist/offline/yabanin-offline-*/ は何も返してはなりません。

ステップ 4 — エアギャップマシンでの検証​

tar -xzf yabanin-offline-<version>.tar.gz
cd yabanin-offline-<version>

チェックサム — バンドル全体に対する改ざんチェック:

sha256sum -c manifest.sha256

署名(SHA256SUMS.sig と yabanin-release.pub がバンドルにある場合のみ):

cosign verify-blob --key yabanin-release.pub \
--signature dist/release/SHA256SUMS.sig \
--insecure-ignore-tlog dist/release/SHA256SUMS
  1. --insecure-ignore-tlog は、ネットワークが必要になる透明性ログの参照をスキップします(古いバージョンと新しいバージョンの cosign では、オフラインフラグの名前が異なります。cosign verify-blob --help を確認してください。airgap-verify.sh は正しいフラグを自動的に選びます)。scripts/airgap/build_bundle.sh で作ったバンドルでは、同じチェックが images/image-digests.txt.sig(記録済みイメージダイジェストに対する署名 — R078 D-B の対象)にも適用されます。署名の不一致は常に失敗します。strict モードでも非 strict モードでも同じです。

イメージの読み込み — ローカル操作であり、レジストリは使いません:

gunzip -k images.tar.gz
docker load -i images.tar

ネットワークを無効にしてイメージを実行する — イメージ自体に接続が不要であることを証明します。統合バイナリには version サブコマンドがありません(あるのは gateway、admin、loggerd、mcp、migrate、dev、license、completion、help だけです)。そのため --help を使います。

docker run --rm --pull=never --network none "yabanin:hardened-<version>" --help

上記のすべてを 1 つのコマンドで実行する:

scripts/release/airgap-verify.sh \
--artifacts dist/release \
--manifest manifest.sha256 \
--pubkey yabanin-release.pub \
--image-tar images.tar --image "yabanin:hardened-<version>" \
--compose compose/airgap-compose.yml
  1. スクリプトは、ステージごとに PASS/SKIP/FAIL を 1 行ずつ出力し、いずれかが FAIL ならゼロ以外で終了します。スキップは正直です(たとえば未署名バンドルは SKIP signature と報告し、合格としては数えません)。ネットワークを使える操作は、避けるか(--pull=never、curl/wget なし)、無効化します(--network none)。--strict(または RELEASE_STRICT=1)を付けると、未署名または不完全なセット(署名がない、NOTICE 草案がない、SPDX SBOM がない、イメージごとの SBOM がない、イメージダイジェストが未署名)は FAIL になります。未署名のまま回避できる唯一の方法は RELEASE_ALLOW_UNSIGNED=true です。出力にそのまま記録され、開示済みの未署名 2026-10-31 リリース(D-D)向けです。

ステップ 5 — 最小のオフライン compose​

オフラインでは deploy/quickstart/docker-compose.yml を使わないでください。build: セクションが含まれており、ビルドや pull が走ります。同梱の compose/airgap-compose.yml(ソース: deploy/onprem/airgap-compose.yml)は、事前に読み込んだイメージだけを参照します。

name: yabanin-airgap
services:
postgres:
image: pgvector/pgvector:pg16 # loaded from images.tar
environment:
POSTGRES_USER: yabanin
POSTGRES_PASSWORD: replace-me # generate: openssl rand -hex 16
POSTGRES_DB: yabanin
healthcheck:
test: ["CMD-SHELL", "pg_isready -U yabanin -d yabanin"]
interval: 2s
timeout: 5s
retries: 30

redis:
image: redis:7-alpine # loaded from images.tar
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
timeout: 5s
retries: 30

migrate:
image: yabanin:hardened-<version> # loaded from images.tar
command: ["migrate"]
restart: "no"
environment:
YABANIN_PG_URI: postgres://yabanin:replace-me@postgres:5432/yabanin?sslmode=disable
YABANIN_REGION: onprem
depends_on:
postgres:
condition: service_healthy

gateway:
image: yabanin:hardened-<version>
command: ["gateway"]
environment:
YABANIN_PG_URI: postgres://yabanin:replace-me@postgres:5432/yabanin?sslmode=disable
YABANIN_REGION: onprem
YABANIN_REDIS_ADDR: redis:6379
YABANIN_GATEWAY_LISTEN: ":8082"
ports:
- "127.0.0.1:8082:8082"
depends_on:
migrate:
condition: service_completed_successfully
redis:
condition: service_healthy

起動し、ホストからヘルスを確認します。ハードニング済みイメージは distroless で shell/curl がないため、ヘルスチェックはホスト側にあります。

docker compose -f compose/airgap-compose.yml up -d
curl -fsS http://127.0.0.1:8082/healthz # expect {"status":"ok"}

airgap-verify.sh --compose compose/airgap-compose.yml は、ファイルに build: が含まれるか、ローカルの docker ストアにないイメージを参照している場合(つまり何かが pull される場合)、compose ステージを失敗させます。

ステップ 6 — 更新​

  1. 接続されたマシンでコードを更新し、成果物を再ビルドし(make release-artifacts)、新しいバージョンタグでイメージを再ビルドし、新しい yabanin-offline-<new-version>.tar.gz を組み立てます(ステップ 1–3)。
  2. 転送して検証し(ステップ 4)、新しいイメージを docker load して、compose/airgap-compose.yml の image: タグを更新します。docker compose up -d がサービスを再作成します。
  3. ロールバックのために、以前のバンドルをアーカイブしたまま残します。

ステップ 7 — ロールバック​

gunzip -k images-<old-version>.tar.gz && docker load -i images-<old-version>.tar
# point compose image: tags back to yabanin:hardened-<old-version>
docker compose -f compose/airgap-compose.yml up -d

アプリケーションのロールバックはイメージ単位であり、安全です。データベースのマイグレーションは前方のみです。マイグレーションをまたいでロールバックするには、アップグレード前に取得したバックアップから Postgres を復元する必要があります。

制限事項(導入の承認前に読む)​

  • ビルド時に cosign/COSIGN_KEY がない場合、バンドルは未署名です。airgap-verify.sh は SKIP signature と報告します(--strict では FAIL。上書きできるのは、記録された RELEASE_ALLOW_UNSIGNED=true だけです。D-D)。リリースノート用に UNSIGNED-RELEASE-DISCLOSURE.md が生成されます。来歴を必須とする調達要件では、署名付きのバリアントが必要です。
  • syft がない場合、SBOM はバイナリごとの go version -m ビルドマニフェストであり、SPDX JSON ではありません(sbom.source に記録されます)。イメージごとの SBOM は、Yabanin イメージについては正直な buildinfo の抽出か、明示的な sbom-*.UNAVAILABLE.txt マーカーにフォールバックします。syft の出力は決して偽装せず、strict モードはすべてのフォールバックを拒否します。フォールバックのバリアントを配布ノートに記録してください。
  • THIRD-PARTY-NOTICES.md は、ライセンス棚卸しから生成した草案です。ライセンス識別子を列挙し、ライセンス全文を埋め込んでいないことを明示しています。配布前に、全文と対象を絞ったレビュー証跡(standards/license-compliance.md)を添付してください。
  • images/image-digests.txt はレジストリダイジェストを記録します。docker save/load はそれらを再計算しないため、オフラインチェックが検証するのは、記録済みリストを束縛する署名と、tarball に対する manifest.sha256 です。tar→ダイジェストの対応そのものは、(接続された)ビルドマシンから信頼します。
  • 最小 compose が公開するのは 127.0.0.1:8082 のゲートウェイだけであり、プレースホルダの資格情報を使います。本物の秘密情報を生成し(openssl rand -hex 16)、install-guide.md の完全な設定ガイドに従ってください。
  • yabanin <version> はサブコマンドとして存在しません。オフラインの実行チェックは --help です(ステップ 4.4 を参照)。version サブコマンドの追加は、RM-52 のフォローアップとして追跡されています。
  • scripts/airgap/build_bundle.sh はステップ 1–3 を自動化します(pull、save、イメージごとの SBOM、ダイジェストの記録、署名、マニフェスト、パッキング)。上記の手動ステップは、カスタムバンドル向けのレビュー済み経路のままです。元の RM-53 カードにある install.sh のパッケージングは、まだ実装されていません。airgap-verify.sh は検証側を自動化します。