Membuat dan memvalidasi asal build

Halaman ini memberikan petunjuk cara membuat asal build, melihat output, dan memvalidasinya.

Provenance build adalah kumpulan data yang dapat diverifikasi tentang build. Metadata Provenance mencakup detail seperti ringkasan image yang dibangun, lokasi sumber input, argumen build, dan durasi build. Anda dapat menggunakan informasi ini untuk memastikan bahwa artefak build yang Anda gunakan akurat dan andal, yang dibuat oleh sumber dan builder tepercaya.

Cloud Build mendukung generasi provenance build yang memenuhi jaminan level Supply-chain Level 3 untuk Software Artifacts (SLSA) level 3 berdasarkan spesifikasi SLSA versi 0.1 dan 1.0.

Sebagai bagian dari dukungan untuk spesifikasi SLSA v1.0, Cloud Build memberikan detail buildType dalam provenance build. Anda dapat menggunakan skema buildType untuk memahami template berparameter yang digunakan untuk proses build, termasuk nilai yang dicatat Cloud Build, dan sumber nilai tersebut. Untuk mengetahui informasi selengkapnya, lihat Cloud Build buildType v1.

Batasan

• Cloud Build hanya menghasilkan provenance build untuk artefak yang disimpan di Artifact Registry.
• Untuk mendapatkan sumber SLSA v1.0 dan v0.1, Anda harus mem-build menggunakan pemicu. Jika Anda memulai build secara manual, dengan menggunakan gcloud CLI, Cloud Build hanya menyediakan provenance SLSA v0.1.

Sebelum memulai

1. Enable the Cloud Build, Container Analysis, and Artifact Registry APIs.

   Enable the APIs

2. Untuk menggunakan contoh command line dalam panduan ini, instal dan konfigurasi Google Cloud SDK.

3. Siapkan kode sumber Anda.

4. Memiliki repositori di Artifact Registry.

Membuat asal build

Petunjuk berikut menjelaskan cara membuat provenance build untuk image container yang Anda simpan di Artifact Registry:

1. Dalam file konfigurasi build, tambahkan kolom images untuk mengonfigurasi Cloud Build guna menyimpan image yang telah dibangun di Artifact Registry setelah build selesai.

   Cloud Build tidak dapat menghasilkan provenance jika Anda mengirim image ke Artifact Registry menggunakan langkah docker push eksplisit.

   Cuplikan berikut menunjukkan konfigurasi build untuk membangun image container dan menyimpan image di repositori Docker di Artifact Registry:

   YAML

     steps:
     - name: 'gcr.io/cloud-builders/docker'
       args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE', '.' ]
     images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE']
   

   Dengan keterangan:

   • LOCATION: lokasi regional atau multi-regional untuk repositori Anda.
   • PROJECT_ID: Project ID Google Cloud Anda.
   • REPOSITORY: nama repositori Artifact Registry Anda.
   • IMAGE: nama image container Anda.

   JSON

     {
     "steps": [
         {
             "name": "gcr.io/cloud-builders/docker",
             "args": [
                 "build",
                 "-t",
                 "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE",
                 "."
             ]
         }
     ],
     "images": [
         "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE"
     ]
     }
   

   Dengan keterangan:

   • LOCATION: lokasi regional atau multi-regional untuk repositori Anda.
   • PROJECT_ID: Project ID Google Cloud Anda.
   • REPOSITORY: nama repositori Artifact Registry Anda.
   • IMAGE: nama image container Anda.

2. Di bagian options pada konfigurasi build Anda, tambahkan opsi requestedVerifyOption dan tetapkan ke nilai VERIFIED.

   Setelan ini memungkinkan pembuatan provenance dan mengonfigurasi Cloud Build untuk memverifikasi keberadaan metadata asal. Build hanya akan ditandai berhasil jika provenance dibuat.

   YAML

   options:
     requestedVerifyOption: VERIFIED
   

   JSON

   {
       "options": {
           "requestedVerifyOption": "VERIFIED"
       }
   }
   

3. Mulai build Anda.

Melihat provenance build

Bagian ini menjelaskan cara melihat metadata asal build yang dibuat oleh Cloud Build. Anda dapat mengambil informasi ini untuk tujuan audit.

Anda dapat mengakses metadata provenance build untuk container menggunakan panel samping Security insights dalam Konsol Google Cloud, atau dengan menggunakan gcloud CLI.

  gcloud artifacts docker images describe \
  LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH \
  --show-provenance --format=FORMAT

Contoh output

Asal build-nya menyerupai berikut ini:

      image_summary:
      digest: sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
      fully_qualified_digest: us-central1-docker.pkg.dev/my-project/my-repo/my-image@sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
      registry: us-central1-docker.pkg.dev
      repository: my-repo
      slsa_build_level: 0
    provenance_summary:
      provenance:
      - build:
          inTotoSlsaProvenanceV1:
            _type: https://in-toto.io/Statement/v1
            predicate:
              buildDefinition:
                buildType: https://cloud.google.com/build/gcb-buildtypes/google-worker/v1
                externalParameters:
                  buildConfigSource:
                    path: cloudbuild.yaml
                    ref: refs/heads/main
                    repository: git+https://github.com/my-username/my-git-repo
                  substitutions: {}
                internalParameters:
                  systemSubstitutions:
                    BRANCH_NAME: main
                    BUILD_ID: e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
                    COMMIT_SHA: 525c52c501739e6df0609ed1f944c1bfd83224e7
                    LOCATION: us-west1
                    PROJECT_NUMBER: '265426041527'
                    REF_NAME: main
                    REPO_FULL_NAME: my-username/my-git-repo
                    REPO_NAME: my-git-repo
                    REVISION_ID: 525c52c501739e6df0609ed1f944c1bfd83224e7
                    SHORT_SHA: 525c52c
                    TRIGGER_BUILD_CONFIG_PATH: cloudbuild.yaml
                    TRIGGER_NAME: github-trigger-staging
                  triggerUri: projects/265426041527/locations/us-west1/triggers/a0d239a4-635e-4bd3-982b-d8b72d0b4bab
                resolvedDependencies:
                - digest:
                    gitCommit: 525c52c501739e6df0609ed1f944c1bfd83224e7
                  uri: git+https://github.com/my-username/my-git-repo@refs/heads/main
                - digest:
                    sha256: 154fcd4d2d65c6a35b06b98053a0829c581e223d530be5719326f5d85d680e8d
                  uri: gcr.io/cloud-builders/docker@sha256:154fcd4d2d65c6a35b06b98053a0829c581e223d530be5719326f5d85d680e8d
              runDetails:
                builder:
                  id: https://cloudbuild.googleapis.com/GoogleHostedWorker
                byproducts:
                - {}
                metadata:
                  finishedOn: '2023-08-01T19:57:10.734471Z'
                  invocationId: https://cloudbuild.googleapis.com/v1/projects/my-project/locations/us-west1/builds/e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
                  startedOn: '2023-08-01T19:56:57.451553160Z'
            predicateType: https://slsa.dev/provenance/v1
            subject:
            - digest:
                sha256: 7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
              name: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image
            - digest:
                sha256: 7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
              name: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest
        createTime: '2023-08-01T19:57:14.810489Z'
        envelope:
          payload:
          eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdMWQ0LWVjNGEtNGVhNi1hY2RkLWFjOGJiMTZkY2M3OSIsICJzdGFydGVkT24iOiIyMDIzLTA4LTAxVDE5OjU2OjU3LjQ1MTU1MzE2MFoiLCAiZmluaXNoZWRPbiI6IjIwMjMtMDgtMDFUMTk6NTc6MTAuNzM0NDcxWiJ9LCAiYnlwcm9kdWN0cyI6W3t9XX19fQ==...
          payloadType: application/vnd.in-toto+json
          signatures:
          - keyid: projects/verified-builder/locations/global/keyRings/attestor/cryptoKeys/google-hosted-worker/cryptoKeyVersions/1
            sig: MEUCIQCss8UlQL2feFePRJuKTE8VA73f85iqj4OJ9SvVPqTNwAIgYyuyuIrl1PxQC5B109thO24Y6NA4bTa0PJY34EHRSVE=
        kind: BUILD
        name: projects/my-project/occurrences/71787589-c6a6-4d6a-a030-9fd041e40468
        noteName: projects/argo-qa/notes/intoto_slsa_v1_e73ca1d4-ec4a-4ea6-acdd-ac8bb16dcc79
        resourceUri: https://us-central1-docker.pkg.dev/my-project/my-repo/my-image@sha256:7e9b6e7ba2842c91cf49f3e214d04a7a496f8214356f41d81a6e6dcad11f11e3
        updateTime: '2023-08-01T19:57:14.810489Z'
    

Beberapa hal penting yang perlu diperhatikan dalam contoh ini:

• Sumber: Build dipicu dari repositori GitHub.

• Referensi objek: Kolom bernama digest dan fileHash merujuk ke objek yang sama. Kolom digest yang disertakan dalam contoh output dienkode dalam basis 16 (berenkode hex). Jika Anda menggunakan origin SLSA versi 0.1, output Anda akan menggunakan kolom fileHash yang dienkode dalam base 64.

• Tanda tangan: Jika Anda menggunakan SLSA versi 0.1, output Anda berisi dua tanda tangan di kolom envelope. Tanda tangan pertama, yang memiliki nama kunci provenanceSigner, menggunakan tanda tangan yang sesuai dengan DSSE (yang diformat dengan Pre-Authentication Encoding (PAE)), yang dapat diverifikasi dalam kebijakan Otorisasi Biner. Sebaiknya gunakan tanda tangan ini dalam penggunaan baru bukti ini. Tanda tangan kedua, yang memiliki nama kunci builtByGCB, disediakan untuk penggunaan lama.

• Akun layanan: Tanda tangan yang otomatis disertakan dalam asal Cloud Build yang membantu Anda memverifikasi layanan build yang menjalankan build. Anda juga dapat mengonfigurasi Cloud Build untuk merekam metadata yang dapat diverifikasi tentang akun layanan yang digunakan untuk memulai build. Untuk mengetahui informasi selengkapnya, lihat menandatangani image container dengan cosign.

• Payload: Contoh asal yang ditampilkan di halaman ini dipersingkat agar mudah dibaca. Output sebenarnya akan lebih panjang, karena payload adalah versi berenkode base-64 dari semua metadata asal.

Melihat provenance untuk artefak non-container

Cloud Build menghasilkan metadata asal SLSA untuk aplikasi Java (Maven), Python, dan Node.js (npm) mandiri saat Anda mengupload artefak build ke Artifact Registry.

1. Guna membuat metadata asal untuk artefak Anda, jalankan build dengan Cloud Build. Gunakan salah satu panduan berikut:

   • Membangun aplikasi Java mandiri
   • Membangun aplikasi Python mandiri
   • Membangun aplikasi Node.js mandiri

   Setelah build selesai, catat BuildID.

2. Jalankan panggilan API berikut di terminal Anda, dengan PROJECT_ID sebagai ID yang terkait dengan project Google Cloud Anda:

   alias gcurl='curl -H"Authorization: Bearer $(gcloud auth print-access-token)"'
       gcurl 'https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/occurrences'
   

   Dalam kejadian di project Anda, telusuri berdasarkan BuildID untuk menemukan informasi bukti yang terkait dengan setiap artefak build.

Validasi origin

Bagian ini menjelaskan cara memvalidasi asal build untuk image container.

Memvalidasi asal build dapat membantu Anda:

• memastikan bahwa artefak build dihasilkan dari builder dan sumber tepercaya
• memastikan bahwa metadata asal yang menjelaskan proses build Anda sudah lengkap dan autentik

Untuk mengetahui informasi selengkapnya, lihat Membangun pengamanan.

Memvalidasi asal menggunakan pemverifikasi SLSA

Pemverifikasi SLSA adalah alat CLI open source untuk memvalidasi integritas build berdasarkan spesifikasi SLSA.

Jika pemverifikasi menemukan masalah, pemverifikasi akan menampilkan pesan error mendetail untuk membantu Anda memperbarui proses build dan mengurangi risiko.

Untuk menggunakan pemverifikasi SLSA:

1. Instal versi 2.1 atau yang lebih baru dari repositori slsa-verifier:

   go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@VERSION
   

2. Di CLI, tetapkan variabel untuk ID gambar Anda:

   export IMAGE=LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH
   

   Ganti nilai placeholder di perintah dengan kode berikut:

   • LOCATION: Lokasi regional atau multi-regional.
   • PROJECT_ID: ID project Google Cloud.
   • REPOSITORY: Nama repositori.
   • IMAGE: Nama gambar.
   • HASH: Nilai hash sha256 gambar. Anda dapat menemukannya dalam output build.

3. Izinkan gcloud CLI agar pemverifikasi SLSA dapat mengakses data asal Anda:

   gcloud auth configure-docker LOCATION-docker.pkg.dev
   

4. Ambil provenance untuk gambar Anda dan simpan sebagai JSON:

   gcloud artifacts docker images describe $IMAGE --format json --show-provenance > provenance.json
   

5. Verifikasi asalnya:

   slsa-verifier verify-image "$IMAGE" \
   --provenance-path provenance.json \
   --source-uri SOURCE \
   --builder-id=BUILDER_ID
   

   Dengan keterangan:

   • SOURCE adalah URI repositori sumber untuk gambar Anda, misalnya, github.com/my-repo/my-application.
   • BUILDER_ID ID unik untuk builder, misalnya https://cloudbuild.googleapis.com/GoogleHostedWorker

   Jika Anda ingin mencetak sumber yang divalidasi untuk digunakan dalam mesin kebijakan, gunakan perintah sebelumnya dengan tanda --print-provenance.

   Output-nya serupa dengan berikut ini: PASSED: Verified SLSA provenance atau FAILED: SLSA verification failed: <error details>.

Untuk mengetahui informasi selengkapnya tentang tanda opsional, lihat opsi.

Memvalidasi metadata asal dengan gcloud CLI

Jika ingin memverifikasi bahwa metadata asal build belum dimodifikasi, Anda dapat memvalidasi sumbernya dengan melakukan langkah-langkah berikut:

1. Buat direktori baru dan buka direktori tersebut.

   mkdir provenance && cd provenance
   

2. Dapatkan kunci publik menggunakan informasi dari kolom keyid.

   gcloud kms keys versions get-public-key 1 --location global --keyring attestor \
     --key builtByGCB --project verified-builder --output-file my-key.pub
   

3. payload berisi representasi JSON dari provenance tersebut, yang dienkode dalam base64url. Mendekode data dan menyimpannya dalam file.

   gcloud artifacts docker images describe \
   LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
     --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v0.1") | .envelope.payload' | tr '\-_' '+/' | base64 -d > provenance.json
   

   Kedua jenis asal SLSA versi 0.1 dan 1.0 disimpan jika tersedia. Jika Anda ingin memfilter versi 1.0, ubah predicateType agar menggunakan https://slsa.dev/provenance/v1. Contoh:

   gcloud artifacts docker images describe \
   LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
     --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v1") | .envelope.payload' | tr '\-_' '+/' | base64 -d > provenance.json
   

4. Amplop juga berisi tanda tangan di atas asalnya. Mendekode data dan menyimpannya dalam sebuah file.

     gcloud artifacts docker images describe LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
     --format=json | '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v0.1") | .envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
   

   Jika Anda ingin memfilter versi 1.0, ubah predicateType agar menggunakan https://slsa.dev/provenance/v1. Contoh:

   gcloud artifacts docker images describe LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:HASH --show-provenance \
   --format=json | jq -r '.provenance_summary.provenance[] | select(.build.intotoStatement.predicateType == "https://slsa.dev/provenance/v1") | .envelope.signatures[0].sig' | tr '\-_' '+/' | base64 -d > signature.bin
   

5. Perintah di atas merujuk ke tanda tangan asal pertama (.provenance_summary.provenance[0].envelope.signatures[0]) yang ditandatangani oleh kunci provenanceSigner. Payload ditandatangani melalui envelope berformat PAE. Untuk memverifikasinya, jalankan perintah ini untuk mengubah provenance ke format PAE "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(body) + SP + body yang diharapkan.

   echo -n "DSSEv1 28 application/vnd.in-toto+json $(cat provenance.json | wc -c) $(cat provenance.json)" > provenance.json
   

6. Validasi tanda tangan.

   openssl dgst -sha256 -verify my-key.pub -signature signature.bin provenance.json
   

   Setelah validasi berhasil, output-nya adalah Verified OK.

Langkah selanjutnya

• Mengonfigurasi Cloud Build untuk melacak siapa yang memulai build
• Menggunakan pemindaian kerentanan di pipeline Cloud Build
• Pelajari Perlindungan Pengiriman Software