Menandatangani image dengan Cosign: verifikasi identitas, bukan sekadar centang

Untuk menandatangani container image tanpa menyimpan kunci privat statis di CI, dorong image ke registry, ambil digest hasil build, lalu jalankan Cosign secara keyless pada alamat image berbasis digest. Panduan penandatanganan container Sigstore menjelaskan penggunaan identitas OIDC dan kunci sementara, serta pilihan menyimpan materi tanda tangan sebagai bundle tanpa mengunggah tanda tangan ke registry.

Sesudah sign, jalankan cosign verify pada digest yang sama dengan identitas penanda tangan dan issuer OIDC yang ditetapkan dalam kebijakan rilis. Panduan verifikasi Cosign menjelaskan pemeriksaan klaim digest secara bawaan, verifikasi identitas, dan pemeriksaan terhadap transparency log. Perintah yang berhasil hanya menjawab kebutuhan rilis jika nilai identitas yang diharapkan sudah ditentukan oleh tim, bukan diambil dari tanda tangan yang sedang diperiksa.

Gunakan digest hasil push sebagai alamat image

Tag seperti release atau latest dapat dipindahkan ke manifest image lain. Digest sha256 menunjuk manifest tertentu; karena itu, alamat berbentuk ghcr.io/ORG/REPO@sha256:... memberi sign, verify, dan deploy rujukan yang sama. ORG, REPO, dan digest pada contoh ini adalah placeholder, bukan image yang telah ditandatangani.

Bangun dan dorong image terlebih dahulu, kemudian ambil digest yang dikembalikan langkah push. Simpan alamat lengkap beserta digest sebagai keluaran job build agar tahap berikutnya tidak perlu menafsirkan ulang sebuah tag. Digest berkas lokal tidak boleh diasumsikan sama dengan digest manifest yang tersimpan di registry. Jika tahap deploy kembali memakai tag yang bisa berubah, keberhasilan verifikasi pada digest sebelumnya tidak memastikan objek yang dijalankan tetap sama.

Tandatangani secara keyless dan tentukan lokasi tanda tangan

Setelah variabel IMAGE berisi alamat berbasis digest, perintah intinya ialah cosign sign --yes $IMAGE. Dalam CI yang menyediakan token OIDC, proses keyless mengaitkan kunci penandatanganan sementara dengan identitas pekerjaan. Opsi --yes melewati konfirmasi interaktif; opsi itu tidak menetapkan identitas mana yang kelak boleh lolos verifikasi.

Alur penandatanganan biasa menempatkan tanda tangan yang terkait dengan image di registry. Jika materi tanda tangan perlu dibawa sebagai artefak terpisah, gunakan cosign sign --bundle=bundle.sigstore.json --upload=false $IMAGE. Pilihan --upload=false menghentikan unggahan tanda tangan ke registry, bukan menghilangkan kebutuhan akses registry untuk menangani container image. Simpan bundle bersama alamat image berbasis digest dan atur cara tahap verifikasi menerima bukti itu. Job yang hanya mencari tanda tangan di registry tidak akan menemukannya melalui alur tersebut.

Putuskan lokasi bukti sebelum memasang gerbang rilis. Untuk alur registry, verifier mengambil tanda tangan yang terkait dengan image di sana. Untuk alur bundle, distribusi berkas dan kemampuan verifier yang dipakai untuk membaca formatnya menjadi bagian dari rancangan pipeline. Jangan beralih ke bundle hanya untuk mengatasi izin tulis registry tanpa memastikan tahap rilis dapat mengakses dan memverifikasi bukti yang dihasilkan.

Contoh CI minimal dari build hingga verify

Contoh berikut bersifat ilustratif untuk GitHub Actions dan GitHub Container Registry. Contoh CI Sigstore memakai izin id-token: write, pemasangan Cosign, digest keluaran build, serta verifikasi dengan identitas workflow dan issuer token GitHub Actions. Ganti organisasi, repositori, nama berkas workflow, dan cabang sesuai pipeline yang benar-benar diberi wewenang merilis image.

1. Jalankan workflow release.yml dari cabang main. Berikan job izin contents: read untuk checkout, packages: write untuk push ke ghcr.io, dan id-token: write untuk meminta token OIDC. Tempatkan izin tersebut pada job yang membangun serta menandatangani image.
2. Lakukan checkout, login ke ghcr.io, lalu pasang Cosign melalui sigstore/cosign-installer. Bangun dan dorong image dengan docker/build-push-action menggunakan push: true dan tag ghcr.io/ORG/REPO:release. Jika langkah build diberi id push, ambil digest dari steps.push.outputs.digest.
3. Bentuk IMAGE sebagai ghcr.io/ORG/REPO@${{ steps.push.outputs.digest }}. Jalankan cosign sign --yes $IMAGE, kemudian cosign verify $IMAGE --certificate-identity=https://github.com/ORG/REPO/.github/workflows/release.yml@refs/heads/main --certificate-oidc-issuer=https://token.actions.githubusercontent.com. Buat job gagal saat verify gagal, sehingga tahap deploy tidak menerima image tersebut.

Sign dan verify dalam satu job membantu memastikan perintah serta akses registry tersusun dengan benar. Untuk keputusan deploy, ulangi verifikasi di tahap yang benar-benar melepas image, menggunakan digest hasil build dan identitas yang telah ditetapkan sebagai kebijakan. Tahap itu juga harus menjalankan image berdasarkan digest tersebut; jika kembali memilih tag, hubungan antara objek yang diverifikasi dan objek yang dijalankan terputus.

Batasi identitas dan pertahankan pemeriksaan log

Identitas pada contoh GitHub Actions menyebut repositori, lokasi berkas workflow, dan referensi cabang. Issuer token workflow ialah https://token.actions.githubusercontent.com; nilainya berbeda dari issuer untuk login GitHub oleh pengguna. Karena itu, salin nilai yang sesuai dengan jenis penandatanganan yang dipakai, lalu tetapkan sebagai nilai yang diharapkan dalam konfigurasi verifikasi. Pola identitas yang menerima semua workflow terlalu luas untuk gerbang deploy.

Kebijakan rilis perlu mengikat digest image yang akan dijalankan, issuer OIDC yang dipercaya, identitas workflow yang diizinkan, serta pemeriksaan transparency log. Pertahankan pemeriksaan klaim digest bawaan Cosign. Opsi --check-claims=false menonaktifkan pemeriksaan klaim dalam payload, sedangkan --insecure-ignore-tlog melewati verifikasi transparency log. Jika pipeline hanya berhasil setelah salah satu pemeriksaan itu dilewati, hasilnya tidak memenuhi kebijakan yang sama.

Untuk syarat tambahan yang jelas nilainya, anotasi dapat dipasang saat sign dan dicocokkan dengan opsi -a saat verify. Attestasi memiliki jalur pemeriksaan tersendiri melalui cosign verify-attestation. Dengan demikian, verify yang berhasil untuk tanda tangan image belum menyatakan bahwa isi sebuah attestasi juga telah diterima oleh kebijakan rilis.

Telusuri kegagalan berdasarkan objek dan bukti

• Identitas tidak cocok: bandingkan nama repositori, lokasi release.yml, dan ref cabang dalam --certificate-identity dengan workflow yang menandatangani image. Perubahan nama berkas atau cabang perlu diikuti perubahan kebijakan yang disengaja.
• Issuer tidak cocok: periksa asal token OIDC yang dipakai saat sign. Alamat issuer untuk pekerjaan GitHub Actions dan alamat issuer untuk login interaktif GitHub bukan nilai yang dapat dipertukarkan.
• Digest berbeda: cocokkan digest keluaran push, alamat yang ditandatangani, alamat yang diverifikasi, dan alamat yang diteruskan ke deploy. Mengulang verify terhadap tag tidak menyelesaikan perbedaan objek.
• Tanda tangan tidak ditemukan: periksa apakah tanda tangan diunggah ke registry atau disimpan melalui --upload=false sebagai bundle. Pada alur registry, periksa akses baca ke image dan artefak terkait; pada alur bundle, periksa distribusi bukti ke tahap verifikasi.
• Pemeriksaan log gagal: telusuri materi transparency log yang terkait dengan tanda tangan dan konfigurasi verifier. Mengabaikan pemeriksaan log agar job menjadi hijau mengubah syarat penerimaan image.

Baca juga:

• Media kit kreator bukan sekadar pengikut—data ini yang dicari brand
• Hugging Face bukan sekadar gudang model: tiga bagiannya sering tertukar
• Claude melonggarkan akses biologi—verifikasi peneliti tetap wajib