Creazione di attestazioni

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Questa pagina descrive i passaggi per creare un'autorizzazione binaria attestato.

Utilizza le attestazioni per autorizzare il deployment di immagini container specifiche sulle piattaforme come Google Kubernetes Engine (GKE) e Cloud Run. Per utilizzare le attestazioni, devi richiedere le attestazioni nella regola appropriata del tuo criterio.

Una singola attestazione può autorizzare immagini identiche archiviate in più posizioni o in diversi registry, come Artifact Registry, Container Registry o un Container Registry esterno.

Al momento del deployment, Autorizzazione binaria utilizza gli attestatori per verificare le attestazioni.

Per configurare Autorizzazione binaria su Cloud Run, GKE, Cluster Anthos su VMware e Anthos Service Mesh, consulta Configura piattaforme e seleziona la tua piattaforma.

Utenti GKE: per un tutorial end-to-end che descrive l'applicazione basata sull'attestazione mediante Autorizzazione binaria e Google Kubernetes Engine (GKE), consulta la guida introduttiva all'utilizzo dello strumento a riga di comando o la guida introduttiva a Google Cloud Console.

Prima di iniziare

La panoramica delle attestazioni fornisce i passaggi da completare prima di creare un'attestazione.

Configura l'ambiente

  1. Specifica gli ID progetto:

    ATTESTOR_PROJECT_ID=ATTESTOR_PROJECT_ID
ATTESTATION_PROJECT_ID=ATTESTATION_PROJECT_ID

    Sostituisci quanto segue:

    • ATTESTOR_PROJECT_ID: il nome del progetto in cui memorizzi i tuoi attestatori
    • ATTESTATION_PROJECT_ID: il nome del progetto in cui memorizzi le attestazioni

    Se vuoi che l'attestazione sia creata nello stesso progetto degli attestatori, utilizza lo stesso ID progetto per entrambe le variabili. Per un tutorial end-to-end che mostrerà separazioni di compiti con progetti diversi, consulta Configurazione di più progetti.

  2. Specifica il nome dell'attestatore e le informazioni sull'immagine:

    ATTESTOR_NAME=ATTESTOR_NAME
IMAGE_PATH=IMAGE_PATH
IMAGE_DIGEST=IMAGE_DIGEST
IMAGE_TO_ATTEST="${IMAGE_PATH}@${IMAGE_DIGEST}"

    Sostituisci quanto segue:

    • ATTESTOR_NAME: il nome dell'attestatore, ad esempio build-secure o prod-qa.

    • IMAGE_PATH: un URI che rappresenta un percorso dell'immagine. Anche se l'URI deve includere un nome di dominio e un'immagine, non deve necessariamente fare riferimento a un'immagine effettiva. Non è possibile accedere alle immagini durante la creazione dell'attestazione. Di seguito sono riportati esempi di percorsi di immagini:

      • us-docker.pkg.dev/google-samples/containers/gke/hello-app
      • gcr.io/example-project/quickstart-image
      • example.com/hello-app.

    • IMAGE_DIGEST: la sintesi del manifest immagine. Ad esempio, sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567 è la sintesi dell'immagine associata al percorso immagine di esempio us-docker.pkg.dev/google-samples/containers/gke/hello-app. Per informazioni su come ottenere un digest di un'immagine in Artifact Registry, consulta Gestione delle immagini; per un'immagine in Container Registry, consulta Elencare le versioni di un'immagine.

Concedi i ruoli IAM

Per creare attestazioni, devi concedere i seguenti ruoli Identity and Access Management (IAM) all'identità che crea l'attestatore, come descritto di seguito:

  • roles/containeranalysis.notes.attacher sulla risorsa nota associata all'attestatore.
  • roles/containeranalysis.occurrences.editor sulla risorsa del progetto di attestazione.

Crei un'attestazione basata su un attestatore. L'attestatore è associato a una nota Container Analysis. La creazione di un'attestazione a sua volta crea un'occorrenza di Container Analysis e la collega alla nota.

Scopri di più sulla concessione dell'accesso.

Per informazioni su come creare un'attestazione in una pipeline di Cloud Build, consulta Creazione di attestazioni utilizzando Kritis Signer.

Creare un'attestazione

Creare un'attestazione utilizzando una chiave archiviata localmente

Per creare un attestato firmato con una chiave locale, segui questi passaggi:

  1. Crea un file di payload della firma:

    gcloud

    Per creare il file del payload della firma, inserisci il seguente comando:

    gcloud container binauthz create-signature-payload \
    --artifact-url="${IMAGE_TO_ATTEST}" > /tmp/generated_payload.json

    Il file di payload in formato JSON è simile al seguente output:

    {
  "critical": {
    "identity": {
      "docker-reference": "us-docker.pkg.dev/google-samples/containers/gke/hello-app"
    },
    "image": {
      "docker-manifest-digest": "sha256:37e5287945774f27b418ce567cd77f4bbc9ef44a1bcd1a2312369f31f9cce567"
    },
    "type": "Google cloud binauthz container signature"
  }
}

    API REST

    Crea un file di payload denominato /tmp/generated_payload.json utilizzando le variabili di ambiente impostate in precedenza in questo documento:

    cat > /tmp/generated_payload.json << EOM
{
  "critical": {
    "identity": {
      "docker-reference": "${IMAGE_PATH}"
    },
    "image": {
      "docker-manifest-digest": "${IMAGE_DIGEST}"
    },
    "type": "Google cloud binauthz container signature"
  }
}
EOM

  2. Firma il payload con la tua chiave privata per generare un file di firma.

    Questa guida si avvale dell'algoritmo Elliptic Curve Digital Signing Algorithm (ECDSA) consigliato per la firma. Puoi anche utilizzare l'algoritmo RSA. Per saperne di più sulla firma degli algoritmi, consulta le finalità e gli algoritmi chiave. Questa guida utilizza anche il formato della firma Public-Key Infrastructure (X.509) (PKIX). Puoi anche utilizzare la PGP.

    PRIVATE_KEY_FILE=PRIVATE_KEY_FILE
openssl dgst -sha256 -sign ${PRIVATE_KEY_FILE} /tmp/generated_payload.json > /tmp/ec_signature

    Sostituisci PRIVATE_KEY_FILE con il percorso della chiave privata che hai generato al momento della creazione dell'attestatore.

  3. Ottieni l'ID della chiave pubblica.

    Puoi recuperare l'ID chiave pubblica dall'attestatore inserendo il seguente comando:

    PUBLIC_KEY_ID=$(gcloud container binauthz attestors describe ${ATTESTOR_NAME} \
  --format='value(userOwnedGrafeasNote.publicKeys[0].id)')

  4. Crea l'attestazione:

    gcloud

    Per creare e convalidare l'attestazione, inserisci quanto segue:

    gcloud container binauthz attestations create \
    --project="${ATTESTATION_PROJECT_ID}" \
    --artifact-url="${IMAGE_TO_ATTEST}" \
    --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}" \
    --signature-file=/tmp/ec_signature \
    --public-key-id="${PUBLIC_KEY_ID}" \
    --validate

    Il flag validate controlla che l'attestazione possa essere verificata dall'attestatore configurato nel criterio.

    Nota: l'ID chiave può essere qualsiasi stringa.

    API REST

    Per creare l'attestazione:

    1. Recupera l'attestatore associato all'attestato ed estrai l'ID chiave pubblica archiviato:

      curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors/"

      Autorizzazione binaria restituisce un oggetto JSON simile al seguente:

      {
  "name": "projects/example-project/attestors/test-attestor",
  "userOwnedGrafeasNote": {
    "noteReference": "projects/example-project/notes/test-attestor",
    "publicKeys": [
      {
        "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      }
    ],
    "delegationServiceAccountEmail": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2019-06-26T16:58:33.977438Z"
}

      La chiave pubblica è disponibile nel campo id.

    2. Crea in /tmp/attestation.json un file JSON che descriva l'attestazione:

      cat > /tmp/attestation.json << EOM
{
  "resourceUri": "${IMAGE_TO_ATTEST}",
  "note_name": "${NOTE_URI}",
  "attestation": {
     "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)",
     "signatures": [
        {
         "public_key_id": "${PUBLIC_KEY_ID}",
         "signature": "$(base64 --wrap=0 /tmp/ec_signature)"
        }
     ]
  }
 }
EOM

    3. Crea l'attestazione:

      curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-binary @/tmp/attestation.json \
    "https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"

Creare un'attestazione utilizzando Cloud KMS

Per creare un'attestazione con l'utilizzo di Cloud Key Management Service:

  1. Crea le variabili di ambiente:

    KMS_KEY_PROJECT_ID=KMS_KEY_PROJECT_ID
KMS_KEY_LOCATION=KMS_KEY_LOCATION
KMS_KEYRING_NAME=KMS_KEYRING_NAME
KMS_KEY_NAME=KMS_KEY_NAME
KMS_KEY_VERSION=KMS_KEY_VERSION

    Sostituisci quanto segue:

    • KMS_KEY_PROJECT_ID: ID del progetto in cui sono archiviate le tue chiavi di Cloud Management
    • KMS_KEY_LOCATION: la posizione della chiave (global è l'opzione predefinita)
    • KMS_KEYRING_NAME: nome del keyring
    • KMS_KEY_NAME: il nome della chiave
    • KMS_KEY_VERSION: versione della chiave

  2. Firma e crea l'attestazione:

    gcloud

    Inserisci questo comando:

    gcloud beta container binauthz attestations sign-and-create \
    --project="${ATTESTATION_PROJECT_ID}" \
    --artifact-url="${IMAGE_TO_ATTEST}" \
    --attestor="${ATTESTOR_NAME}" \
    --attestor-project="${ATTESTOR_PROJECT_ID}" \
    --keyversion-project="${KMS_KEY_PROJECT_ID}" \
    --keyversion-location="${KMS_KEY_LOCATION}" \
    --keyversion-keyring="${KMS_KEYRING_NAME}" \
    --keyversion-key="${KMS_KEY_NAME}" \
    --keyversion="${KMS_KEY_VERSION}"

    API REST

    1. Crea un file di payload denominato /tmp/generated_payload.json utilizzando le variabili di ambiente impostate sopra:

      cat > /tmp/generated_payload.json << EOM
{
  "critical": {
    "identity": {
      "docker-reference": "${IMAGE_PATH}"
    },
    "image": {
      "docker-manifest-digest": "${IMAGE_DIGEST}"
    },
    "type": "Google cloud binauthz container signature"
  }
}
EOM

    2. Firma il file di payload:

      curl \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
  --data '{"digest":  {"DIGEST_ALGORITHM": "'$(openssl dgst -sha256 -binary /tmp/generated_payload.json | openssl base64)'" }}' \
https://cloudkms.googleapis.com/v1/projects/${KMS_KEY_PROJECT_ID}/locations/${KMS_KEY_LOCATION}/keyRings/${KMS_KEYRING_NAME}/cryptoKeys/${KMS_KEY_NAME}/cryptoKeyVersions/${KMS_KEY_VERSION}:asymmetricSign?alt=json

      Sostituisci DIGEST_ALGORITHM con l'algoritmo per digerire l'input. Gli esempi in questa guida utilizzano una sintesi di sha256. Puoi utilizzare sha256, sha384 o sha512.

      In questo esempio, l'output ha un aspetto simile all'esempio seguente:

      {
  "signature": "<var>SIGNATURE</var>": "996305066",
  "name": "projects/<var>KMS_KEY_PROJECT_ID</var>/locations/<var>KMS_KEY_LOCATION</var>/keyRings/<var>KMS_KEYRING_NAME</var>/cryptoKeys/<var>KMS_KEY_NAME</var>/cryptoKeyVersions/<var>KMS_KEY_VERSION</var>"
}

      In questo output, SIGNATURE è la firma con codifica base64 del file di payload.

    3. Archivia la firma in una variabile di ambiente:

      PAYLOAD_SIGNATURE=PAYLOAD_SIGNATURE

    4. Recupera l'attestatore per conto del quale stai firmando l'attestatore ed estrai l'ID chiave pubblica e l'ID nota memorizzati:

      curl \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"  \
    -H "x-goog-user-project: ${ATTESTOR_PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/attestors/"

      Autorizzazione binaria restituisce un oggetto JSON simile al seguente:

      {
  "name": "projects/example-project/attestors/test-attestor",
  "userOwnedGrafeasNote": {
    "noteReference": "projects/example-project/notes/test-attestor",
    "publicKeys": [
      {
        "id": "ni:///sha-256;EwVxs8fNUAHq9FI2AMfh8WNIXVBuuTMeGtPH72U-I70",
        "pkixPublicKey": {
          "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXnpuYEfvLl1kj4fjxViFRwY1a+zC\n5qzlf9LJIK+rnjq42tiKGyyXMbnZKJiYPPdMDGyltnkrABnztg2jJ48aYQ==\n-----END PUBLIC KEY-----\n",
          "signatureAlgorithm": "ECDSA_P256_SHA256"
        }
      }
    ],
    "delegationServiceAccountEmail": "service-363451293945@gcp-sa-binaryauthorization.iam.gserviceaccount.com"
  },
  "updateTime": "2019-06-26T16:58:33.977438Z"
}

      Puoi trovare l'ID chiave pubblica nel campo id e l'ID nota nel campo noteReference.

    5. Archivia l'ID chiave pubblica in una variabile di ambiente:

      PUBLIC_KEY_ID="PUBLIC_KEY_ID"
NOTE_URI="NOTE_URI"

      Sostituisci quanto segue:

      • PUBLIC_KEY_ID: l'ID della chiave pubblica dell'attestatore.
      • NOTE_URI: l'URI della nota Container Analysis associata all'attestatore.

    6. Crea in /tmp/attestation.json un file JSON che descriva l'attestazione:

      cat > /tmp/attestation.json << EOM
{
  "resourceUri": "${IMAGE_TO_ATTEST}",
  "note_name": "${NOTE_URI}",
  "attestation": {
     "serialized_payload": "$(base64 --wrap=0 /tmp/generated_payload.json)",
     "signatures": [
         {
             "public_key_id": "${PUBLIC_KEY_ID}",
             "signature": "${PAYLOAD_SIGNATURE}"
         }
     ]
  }
}
EOM

    7. Crea l'attestazione:

      curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTATION_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    --data-binary @/tmp/attestation.json \
"https://containeranalysis.googleapis.com/v1/projects/${ATTESTATION_PROJECT_ID}/occurrences/"

Hai creato l'attestazione.

Verifica che l'attestazione sia stata creata

Per verificare che l'attestazione sia stata creata, puoi elencare le attestazioni associate all'immagine.

gcloud

Per recuperare un elenco di attestazioni, inserisci il seguente comando:

gcloud container binauthz attestations list\
    --project="${ATTESTATION_PROJECT_ID}"\
    --attestor="projects/${ATTESTOR_PROJECT_ID}/attestors/${ATTESTOR_NAME}"\
    --artifact-url="${IMAGE_TO_ATTEST}"

API REST

Per richiedere un elenco di attestazioni, inserisci il seguente comando:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22

Se sono presenti molte attestazioni, la risposta potrebbe contenere un valore nextPageToken. In questo caso, puoi recuperare la pagina successiva dei risultati ripetendo la richiesta, aggiungendo un parametro di ricerca pageToken, come segue:

NEXT_PAGE_TOKEN=NEXT_PAGE_TOKEN
curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: ${ATTESTOR_PROJECT_ID}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://containeranalysis.googleapis.com/v1/projects/${ATTESTOR_PROJECT_ID}/notes/${NOTE_ID}/occurrences?filter=resourceUrl%3D%22https%3A%2F%2F$(jq -rn --arg x ${IMAGE_TO_ATTEST} '$x|@uri')%22&pageToken=${NEXT_PAGE_TOKEN}

Sostituisci NEXT_PAGE_TOKEN con il valore nextPageToken nella risposta della richiesta precedente.

Quando nextPageToken è vuoto, significa che non ci sono più risultati.

Elimina l'attestazione

Prima di eliminare l'attestazione, devi:

  1. Comprendi le implicazioni dell'eliminazione. L'eliminazione di un'attestazione blocca finale le immagini container associate all'attestazione.

  2. Interrompi tutti i container in esecuzione associati alle attestazioni che intendi eliminare.

  3. Elimina tutte le copie delle attestazioni ovunque si trovino, ad esempio le attestazioni nei repository Artifact Registry e Container Analysis.

  4. Assicurati che il deployment delle immagini interessate sia effettivamente bloccato cercando di eseguirne nuovamente il deployment.

Per eliminare un'attestazione, esegui questi comandi:

  1. Elenco attestazioni:

    gcloud container binauthz attestations list \
  --attestor-project=${ATTESTOR_PROJECT_ID} \
  --attestor=${ATTESTOR_NAME}

    L'attestazione contiene un ID occorrenza. L'output ha il seguente aspetto:

    projects/ATTESTOR_PROJECT_ID/occurrences/OCCURRENCE_ID

  2. Salva l'ID occorrenza.

    Salva l'ID occorrenza dell'attestazione che vuoi eliminare.

    OCCURRENCE_ID=OCCURRENCE_ID

  3. Elimina l'attestazione:

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X DELETE \
  https://containeranalysis.googleapis.com/v1beta1/projects/${ATTESTATION_PROJECT_ID}/occurrences/${OCCURRENCE_ID}

    Verifica che le attestazioni siano state eliminate inserendole di nuovo.

Passaggi successivi