implementing-sigstore-for-software-signing

ソフトウェア署名のための Sigstore の実装

使用するタイミング

• 長期間有効な暗号鍵を管理せずに、コンテナイメージやソフトウェアのアーティファクトに署名する場合
• OIDC によるアイデンティティの紐付けを用いて、CI/CD パイプラインでビルド成果物の検証可能な来歴を確立する場合
• Rekor トランスペアレンシーログを照会し、アーティファクトがいつ、誰によって署名されたかを監査する場合
• レジストリから取得したコンテナイメージが、認可されたアイデンティティおよび発行者によって署名されたことを検証する場合
• Kubernetes のアドミッションコントローラーに Sigstore の検証を組み込み、署名済みイメージのポリシーを強制する場合

使用しないでください 次のような場合には使用しないでください。OIDC 認証が利用できないエアギャップ環境やオフラインでの署名ワークフローが必要なアーティファクトへの署名の場合、パブリックな Sigstore 基盤（Fulcio、Rekor）に到達できず、プライベートインスタンスも展開されていない環境の場合、または規制コンプライアンスにより特定の鍵管理手順が義務付けられている場合の従来の PGP/GPG 署名の代替としての利用です。

前提条件

• Cosign CLI v2.4 以降がインストールされていること（go install github.com/sigstore/cosign/v2/cmd/cosign@latest またはバイナリリリースを使用）
• Fulcio がサポートする OIDC アイデンティティプロバイダー（Google、GitHub、Microsoft、またはカスタム OIDC 発行者）にアクセスできること
• コンテナイメージに署名する場合は、署名オブジェクトを保存するためのプッシュ権限を持つコンテナレジストリの認証情報があること
• 自動化エージェント用に、sigstore、requests、cryptography パッケージがインストールされた Python 3.9 以降があること
• fulcio.sigstore.dev、rekor.sigstore.dev、tuf-repo-cdn.sigstore.dev（またはプライベート Sigstore インスタンスの URL）へのネットワークアクセスがあること

ワークフロー

ステップ 1: Cosign のインストールと設定

Cosign をインストールし、Sigstore 基盤に接続できることを確認します。

• バイナリリリースからインストール: Cosign の GitHub リリースページから適切なバイナリをダウンロードし、チェックサムを検証します。Linux の場合は次のとおりです。curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 && chmod +x cosign-linux-amd64 && sudo mv cosign-linux-amd64 /usr/local/bin/cosign
• インストールの確認: cosign version を実行してバージョンを確認し、cosign initialize で Sigstore サービスへの接続を確認します。このコマンドは TUF のルート・オブ・トラストを取得します。
• カスタム基盤の設定（任意）: プライベートの Sigstore スタックを運用している場合は、--fulcio-url、--rekor-url、--oidc-issuer フラグを設定するか、環境変数 COSIGN_REKOR_URL および COSIGN_FULCIO_URL を使用します。

ステップ 2: Cosign と Fulcio によるキーレス署名

Fulcio が OIDC アイデンティティに紐付けた短期間有効の証明書を発行する、アイデンティティベースの署名を行います。

• コンテナイメージへの署名: cosign sign <IMAGE_DIGEST> を実行します。これにより OIDC 認証フローが開始されます。Cosign はエフェメラルな鍵ペアを生成し、公開鍵を OIDC アイデンティティに紐付ける短期間有効の証明書を Fulcio から取得し、イメージのダイジェストに署名して、署名イベントを Rekor に記録します。秘密鍵は署名直後に破棄されます。
• Blob（ファイル）への署名: cosign sign-blob <file> --bundle artifact.sigstore.json を実行して、任意のファイルに署名します。バンドルには、署名、証明書、タイムスタンプ、および Rekor の包含証明が含まれます。
• CI での非対話型署名: GitHub Actions の OIDC や GCP のワークロードアイデンティティなどから取得した有効な OIDC トークンを環境変数 SIGSTORE_ID_TOKEN に設定し、ブラウザベースの認証フローをスキップします:

  export SIGSTORE_ID_TOKEN=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
    "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=sigstore" | jq -r '.value')
  cosign sign $IMAGE_DIGEST
  

• サポートされる OIDC プロバイダー: Google（https://accounts.google.com）、GitHub（https://github.com/login/oauth）、Microsoft（https://login.microsoftonline.com）、GitLab（https://gitlab.com）、およびプライベート Fulcio インスタンスに登録されたカスタムプロバイダー

ステップ 3: 署名済みアーティファクトを検証する

アーティファクトが、想定された OIDC 発行者からの想定された ID によって署名されたことを検証します:

• コンテナイメージを検証する: cosign verify <IMAGE_URI> [email protected] --certificate-oidc-issuer=https://accounts.google.com を実行し、イメージが指定された ID によって署名されたことを確認します。Cosign は証明書チェーンを検証し、Rekor の包含証明を確認し、署名が現在のイメージダイジェストと一致することを検証します。
• 署名済み blob を検証する: cosign verify-blob <file> --bundle artifact.sigstore.json [email protected] --certificate-oidc-issuer=https://accounts.google.com を実行します
• CI ID の正規表現マッチング: --certificate-identity-regexp を使用して、CI ワークフローの ID に一致させます:

  cosign verify $IMAGE --certificate-identity-regexp="https://github.com/myorg/myrepo/.*" \
    --certificate-oidc-issuer=https://token.actions.githubusercontent.com
  

• 検証失敗のパターン: Cosign は失敗時に 0 以外の終了コードを返します。一般的な失敗には、証明書 ID の不一致、有効な Rekor タイムスタンプのない期限切れの証明書、Rekor エントリの欠落、およびイメージダイジェストの不一致（署名後にイメージが変更された）が含まれます。

ステップ 4: Rekor トランスペアレンシーログに問い合わせる

Rekor トランスペアレンシーログでエントリを検索し、検証して、署名イベントを監査します:

• メールアドレスの ID で検索する: rekor-cli search --email [email protected] を使用して、その ID のすべての署名イベントを検索します
• アーティファクトのハッシュで検索する: rekor-cli search --sha sha256:<hash> を使用して、特定のアーティファクトの署名イベントを検索します
• エントリを取得して検証する: rekor-cli get --uuid <entry_uuid> を使用して、証明書、署名、アーティファクトのハッシュを含むエントリの詳細をすべて取得します
• ログへの包含を検証する: rekor-cli verify --entry-uuid <uuid> を使用して、署名済みツリーヘッドに対するエントリの包含証明を検証し、そのエントリが追記専用ログに存在し、改ざんされていないことを確認します
• REST API による問い合わせ: POST ボディ {"hash": "sha256:<hash>"} を指定して https://rekor.sigstore.dev/api/v1/index/retrieve に問い合わせ、エントリ UUID を取得してから、/api/v1/log/entries/<uuid> から完全なエントリを取得します
• 一貫性の監視: rekor-monitor ツールまたは Omniwitness を使用して、ログが追記専用のままであり、エントリが変更または削除されていないことを継続的に検証します

ステップ 5: CI/CD パイプラインへの統合

署名と検証をビルドおよびデプロイのパイプラインに組み込みます:

• GitHub Actions: sigstore/cosign-installer アクションを使用して Cosign をインストールし、GitHub OIDC トークンを ID として使用してイメージに署名します。署名 ID はワークフローの URL になります（例: https://github.com/org/repo/.github/workflows/build.yml@refs/heads/main）。
• Kubernetes のアドミッションでの強制: Cosign の検証ポリシーを備えた Sigstore Policy Controller または Kyverno をデプロイし、アドミッション時に未署名または不正に署名されたイメージを拒否します
• サプライチェーンのメタデータ: cosign attest を使用して、in-toto アテステーション（SLSA provenance、SBOM、脆弱性スキャン結果）をイメージに添付します。これらは同じキーレスフローで署名され、利用者がアーティファクトとそのビルドメタデータの両方を検証できるようにします

主要な概念

用語	定義
キーレス署名	長期間有効な暗号鍵の代わりに、OIDC ID に紐づく Fulcio の短期間有効な証明書を使用する ID ベースの署名方式です。鍵管理の負担を解消します
Fulcio	Sigstore の認証局です。OIDC トークンを検証した後、検証済みの ID にエフェメラル公開鍵を紐づけた短期間有効な X.509 証明書を発行します
Rekor	Sigstore の不変で追記専用の透明性ログです。タイムスタンプ付きで署名イベントを記録し、監査者がアーティファクトがいつ、誰によって署名されたかを検証できるようにします
Cosign	Sigstore のインフラストラクチャ（Fulcio + Rekor）を使用して、コンテナイメージやブロブの署名と検証を行う主要な CLI ツールです
TUF Root of Trust	Sigstore のルート CA 証明書と Rekor の公開鍵を配布する The Update Framework の仕組みです。クライアントが正しい Sigstore インフラストラクチャを信頼できるようにします
OIDC Identity Binding	Fulcio が OpenID Connect トークンを通じてユーザーの ID を検証し、それを短期間有効な署名証明書に紐づけるプロセスです
Inclusion Proof	署名イベントのエントリが透明性ログの Merkle ツリー内に存在することを示す、Rekor が提供する暗号学的証明です

ツールとシステム

• Cosign: コンテナやブロブに署名し、署名を検証し、Sigstore のキーレス署名または従来の鍵ベースの署名を用いて Attestation を添付するための CLI ツールです
• Fulcio: OIDC による ID 検証に基づいて発行される、コードサイニング証明書のための無償のルート認証局です。有効期間は約 10 分です
• Rekor: 署名メタデータを改ざん検知可能な形で保存する透明性ログサーバーです。ID、アーティファクトのハッシュ、公開鍵で検索できます
• Sigstore Policy Controller: Kubernetes のアドミッション Webhook です。Pod の作成を許可する前に Cosign の署名と Attestation を検証することで、イメージ署名ポリシーを適用します
• rekor-cli: Rekor の透明性ログのエントリを照会、アップロード、検証するためのコマンドラインクライアントです

よくあるシナリオ

シナリオ: キーレス署名によるコンテナイメージのビルドパイプラインの保護

背景: DevOps チームは GitHub Actions でコンテナイメージをビルドし、Kubernetes クラスターにデプロイしています。侵害されたレジストリや不正なプッシュによるサプライチェーン攻撃を防ぐため、CI パイプラインでビルドされたイメージだけをデプロイできるようにする必要があります。

手順:

1. GitHub Actions のワークフローに sigstore/cosign-installer@v3 を追加し、id-token: write で OIDC トークンの権限を有効にします
2. イメージをビルドしてプッシュした後、GitHub Actions の OIDC ID を自動的に使用して cosign sign $IMAGE_DIGEST でイメージに署名します
3. --certificate-identity-regexp=https://github.com/myorg/myrepo/.* および --certificate-oidc-issuer=https://token.actions.githubusercontent.com の署名を要求する ClusterImagePolicy を使って、Sigstore Policy Controller を Kubernetes クラスターにデプロイします
4. イメージのダイジェストのハッシュで照会し、署名エントリが Rekor に記録されていることを確認して、透明性ログにイベントが記録されたことを確かめます
5. 未署名のイメージのデプロイを試み、ポリシー違反のエラーで拒否されることを確認して、アドミッションコントローラーをテストします

落とし穴:

• イメージのダイジェストではなくタグに署名すると（cosign sign myimage:latest と cosign sign myimage@sha256:abc...）、タグが別のダイジェストを指すように更新されたときに検証が失敗します
• 検証時に --certificate-oidc-issuer を固定しないと、どの OIDC プロバイダーからの署名でも通過してしまい、ID 紐づけの目的が損なわれます
• GitHub Actions で id-token: write 権限の設定を忘れると、OIDC トークンの取得に失敗し、署名エラーが発生します
• 本番環境の検証ポリシーで --certificate-identity-regexp=.* を使うと、事実上 ID 検証が無効になります

出力形式

## Sigstore Signing Verification Report

**Artifact**: ghcr.io/myorg/myapp@sha256:a1b2c3d4...
**Verification Status**: PASSED

**Certificate Details**:
  Subject: https://github.com/myorg/myapp/.github/workflows/build.yml@refs/heads/main
  Issuer: https://token.actions.githubusercontent.com
  Valid From: 2026-03-19T10:00:00Z
  Valid To: 2026-03-19T10:10:00Z

**Rekor Entry**:
  UUID: 24296fb24b8ad77a8d52...
  Log Index: 89234567
  Integrated Time: 2026-03-19T10:00:05Z
  Inclusion Proof: VERIFIED (tree size: 92000000, root hash: e4f5a6...)

**Policy Check**: Image signed by authorized CI workflow identity