An attestation is a unit of data sent to Chainloop. Users and CI systems use the Chainloop CLI to initialize an attestation process, add pieces of evidence to them, and “push” them to Chainloop service (the evidence store).
In this step, we’ll use the CLI locally to craft an attestation referencing a container image and a Software Bill of materials (SBOM).
First, you need to authenticate the CLI to Chainloop service. Currently we support two authentication methods during the attestation process, user authentication and API key authentication, for this step we’ll use the user authentication, which can be done by running the following command:
In a nutshell, an attestation process has three steps: initialization, adding evidence, and storage. Refer to this section to learn more about the attestation lifecycle.
We’ll start by initializing an attestation. The attestation process requires the name of a workflow and a project to associate with it. Chainloop workflows represent any CI or process that you want to attest. Projects and project versions represent your software product lifecycle.
chainloop att init --workflow build-container-image --project myproject
┌───────────────────────────┬──────────────────────────────────────────────┐│ Initialized At │ 13 May 25 09:44 UTC │├───────────────────────────┼──────────────────────────────────────────────┤│ Attestation ID │ da728652-b646-41c1-a618-10d0392a102c ││ Organization │ gs-demo ││ Name │ build-container-image ││ Project │ myproject ││ Version │ none ││ Contract │ myproject-build-container-image (revision 1) ││ Timestamp Authority │ http://timestamp.digicert.com ││ Policy violation strategy │ ADVISORY │└───────────────────────────┴──────────────────────────────────────────────┘
Once the attestation process is initiated, we can attach as many pieces of evidence as we want. In this case, we are adding a reference to a container image. Many other material types are supported - check the supported list.
chainloop att add --value ghcr.io/chainloop-dev/chainloop/control-plane
INF material kind detected kind=CONTAINER_IMAGEINF material added to attestation┌──────────┬─────────────────────────────────────────────────────────────────────────┐│ Name │ material-1741811432481645000 │├──────────┼─────────────────────────────────────────────────────────────────────────┤│ Type │ CONTAINER_IMAGE │├──────────┼─────────────────────────────────────────────────────────────────────────┤│ Required │ No │├──────────┼─────────────────────────────────────────────────────────────────────────┤│ Value │ ghcr.io/chainloop-dev/chainloop/control-plane:latest │├──────────┼─────────────────────────────────────────────────────────────────────────┤│ Digest │ sha256:9e0c48652ddf82e04dd1c7b8feb57b7300b74e1d39252830373f88c425fb9c63 │└──────────┴─────────────────────────────────────────────────────────────────────────┘
We just attached a reference to a container image, note how the digest was automatically resolved and injected.
Next, let’s add a Software Bill Of Materials (SBOM) by pointing to its remote URL (using the local file path works too).
chainloop att add --value https://raw.githubusercontent.com/chainloop-dev/chainloop/refs/heads/main/docs/examples/quickstart/sbom.json
┌─────────────┬─────────────────────────────────────────────────────────────────────────┐│ Name │ material-1747129602198087000 │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ Type │ SBOM_CYCLONEDX_JSON │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ Required │ No │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ Value │ sbom.json │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ Digest │ sha256:f2888d10bcd93dc58431049a13acac1bc402231fb066e9e58fd986d91dec05f1 │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ Annotations │ ------ │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ │ chainloop.material.tool.name: syft │├─────────────┼─────────────────────────────────────────────────────────────────────────┤│ │ chainloop.material.tool.version: 1.19.0 │└─────────────┴─────────────────────────────────────────────────────────────────────────┘
In this other case, the file’s content will get uploaded to the Content Addressable Storage of your choice and referenced in the attestation also by its digest.
Congratulations! We’ve performed our first attestation, now we can head to the workflow runs section in the platform UI and inspect the attestation we just created.
The “Attestation” tab will provide the full attestation payload, consisting of an in-toto attestation with a Chainloop predicate. After a quick inspection, we can confirm that our pieces of evidence (the container image reference and the SBOM) are included in the attestation