CI/ CD で sha512sum によるファイル整合性検証を自動化
パイプラインでファイルを使用する前に、sha512sum --check --strict checksums.sha512 で承認済みのチェックサムマニフェストと照合します。検証に失敗すると、コマンドは非ゼロの終了ステータスを返すため、成果物の変更や欠落によってジョブを停止できます。重要なのは、照合に使うチェックサムの取得元を決めることです。
信頼できる基準の選定
SHA-512 チェックサムは、ファイルのバイト列を表します。チェックサムが一致するだけでは、そのバイト列を誰が作成したかはわかりません。ファイルと照合用チェックサムの両方を置き換えられる場合、検証を通過することがあります。
自分で管理する固定アセットでは、承認済みファイルからマニフェストを生成し、マニフェストへの変更をレビューします。ダウンロードでは、認証された発行元の経路から照合用チェックサムを取得します。署名付きチェックサムが提供されている場合は、まず発行元の手順に従って署名を検証してください。Debian のイメージ検証ガイドでは、ダウンロードしたバイト列の確認と、その出所の認証の違いを説明しています。
以下の例では、小さなファイルを二つ記録して基準とし、CI でその基準を再利用します。CI が受け取った内容から毎回チェックサムを生成すると、比較の意味がなくなります。
ファイル検証のワークフロー
Bash と GNU coreutils を使用します。以下の例は、Ubuntu 22.04 上の Bash 5.1 と coreutils 8.32、および macOS 上の Bash 5.3 と coreutils 9.12 でテストしています。続ける前に、使用する実装を確認してください。
sha512sum --version
最初の行に GNU coreutils と表示されることを確認します。同名のコマンドでも、別の実装である場合があります。macOS では、Homebrew の coreutils パッケージが
GNU ツールを提供しています。接頭辞のない名前で使用するには、その gnubin の PATH 設定手順に従ってください。
以下の各 Bash ブロックは、同じ親ディレクトリから実行してください。丸括弧により、ディレクトリの変更はサブシェル内に限定されます。この準備処理は sha512-demo ディレクトリを新規作成し、既存のディレクトリは再利用しません。そのため、再実行してもファイルを上書きしません。
(
set -eC
mkdir sha512-demo
cd sha512-demo
mkdir assets
printf 'release 1\n' > assets/app.txt
printf '{"mode":"production"}\n' > assets/config.json
)
ここでは、set -e が失敗時にサブシェルを停止し、-C が出力リダイレクトによる既存の通常ファイルの上書きを防ぎます。準備に失敗した場合は、次のブロックに進む前にエラーを解消してください。別のデモ環境が必要な場合は、異なる親ディレクトリを選んでください。
ハッシュの生成
両方のファイルが承認済みのバイト列を含む状態で、マニフェストを一度だけ作成します。
(
set -eC
cd sha512-demo
sha512sum -- assets/app.txt assets/config.json > checksums.sha512
)
各行には、128 桁の 16 進数で表した SHA-512 ダイジェスト、モードマーカー、ファイル名が含まれます。ファイルを明示的に列挙することで、入力の欠落をエラーにし、マニフェスト自身のハッシュ計算を防ぎます。自分のファイルに適用する場合は、この一覧を置き換え、空白を含むファイル名を引用符で囲んでください。
このコマンドも、既存の checksums.sha512 の上書きを拒否します。生成に失敗した場合、新しく作成されたマニフェストは使用しないでください。空または不完全な可能性があります。意図した更新を準備する際は、以前の承認済みマニフェストを保持し、置き換える内容をレビューしてから採用してください。
ファイルの検証
相対ファイル名を記録したときと同じディレクトリから検証します。
(
cd sha512-demo &&
sha512sum --check --strict checksums.sha512
)
元のファイルでの出力は次のとおりです。
assets/app.txt: OK
assets/config.json: OK
--check はマニフェストを読み込み、記載された各ファイルを照合します。--strict を指定すると、ほかのエントリが一致していても、チェックサム行の形式が不正な場合は失敗します。空のマニフェストも失敗します。記載された成果物がすべて必須の場合は、--ignore-missing を追加しないでください。これらのオプションは、Debian が提供する GNU sha512sum マニュアルに記載されています。
失敗時の動作を試すには、sha512-demo/assets/app.txt を編集し、検証ブロックを再実行します。assets/app.txt: FAILED と報告され、非ゼロで終了します。以下の CI 成功例を使用する前に、元の承認済みバイト列に戻してください。マニフェストは変更しないでください。
エラー処理とよくある問題
権限の問題
検証には、マニフェストとファイルへの読み取り権限に加えて、親ディレクトリを経由するためのアクセス権限が必要です。権限を調べ、必要であれば所有者に適切なアクセス権限を依頼してください。検証を通過させるために、所有権を広範囲に変更したり、機密ファイルを公開したりしないでください。
ハッシュ不一致のトラブルシューティング
不一致は、バイト列が基準と異なることを意味します。ダウンロードの途切れ、改行コードの変更、意図的な編集などが原因になります。信頼できるコピーを再取得するか、変更を調査してください。照合用チェックサムを再生成すると、その変更が隠れてしまいます。
ファイルが見つからないエラーは、誤ったディレクトリからコマンドを実行した場合にも発生します。マニフェスト内の相対パスは、マニフェストの場所ではなく、プロセスの作業ディレクトリを基準に解決されます。行の形式が不正な場合は、ウェブページ上で整形されたチェックサム表をコピーするのではなく、元のマニフェストを取得してください。原因を確認できるよう、CI ログには標準出力と標準エラー出力の両方を残してください。
CI/CD への組み込み
この固定アセットの例では、sha512-demo/assets/ と承認済みの
sha512-demo/checksums.sha512 をリポジトリに追加します。以下の両ワークフローは、マニフェストを再生成せず、チェックアウトしたファイルを検証します。マニフェストの変更はレビューしてください。アセットと照合用ハッシュの両方を変更するプルリクエストは、この検証を通過することがあります。
検証は、ファイルを使用するステップの前に配置し、検証の成功をデプロイの条件にしてください。別のジョブから成果物を取得する場合は、検証前に取得し、承認済みマニフェストをそのジョブの生成出力とは別に管理してください。
GitHub Actions の例
以下を .github/workflows/integrity.yml として追加するか、検証ステップを既存のワークフローに組み込んでください。リポジトリの取得には actions/checkout を使用します。
name: Verify file integrity
on: [push, pull_request]
permissions:
contents: read
jobs:
verify:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v7
- name: Verify approved assets
working-directory: sha512-demo
shell: bash
run: sha512sum --check --strict checksums.sha512
GitHub で bash シェルを明示的に指定すると、コマンドの失敗がステップに伝播します。ワークフローのシェルに関するドキュメントを参照してください。このステップでは、失敗の抑制を無効のままにしてください。
GitLab CI の例
Docker executor を使用する GitLab runner では、このジョブを .gitlab-ci.yml に組み込んでください。
verify_integrity:
image: ubuntu:22.04
script:
- cd sha512-demo
- sha512sum --check --strict checksums.sha512
Ubuntu イメージには GNU coreutils が含まれています。GitLab は、スクリプトのコマンドが非ゼロで終了するとジョブを失敗させます。ディレクトリ変更の失敗も対象です。コマンドは個別のスクリプトエントリとして保持し、この検証ゲートでは allow_failure を有効にしないでください。
Docker ビルド後の変更検出
イメージからコピーした成果物を検証するには、配布前に、取り出したファイルを承認済みマニフェストと照合します。ビルド内で生成したマニフェストで、その後のバイト列の変更を検出できるのは、そのマニフェストが信頼できる状態に保たれている間だけです。ビルド入力の真正性を証明することも、ファイルとマニフェストの両方の置き換えから保護することもできません。
検証成功が意味する範囲
検証では、記載されたすべてのファイルを読み取るため、大きな成果物では全バイトを再度読み取る必要があります。記載のないファイルや、ファイルの所有権、権限、タイムスタンプは検証しません。成功は、記載されたファイルのバイト列が基準と一致することを意味します。ディレクトリに承認済みファイルだけが含まれることや、ビルドに再現性があることを証明するものではありません。
