Skip to main content
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).

Authentication

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:
chainloop auth login

Initialize the Attestation process

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
└───────────────────────────┴──────────────────────────────────────────────┘

Add Pieces of Evidence (a.k.a materials)

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_IMAGE
INF 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.

Sign and Store the Attestation

Finally, we sign and push the attestation to Chainloop for permanent preservation using.
chainloop att push
INF push completed
┌───────────────────────────┬─────────────────────────────────────────────────────────────────────────┐
 Initialized At 13 May 25 09:44 UTC
├───────────────────────────┼─────────────────────────────────────────────────────────────────────────┤
 Attestation ID da728652-b646-41c1-a618-10d0392a102c
 Digest sha256:99124501a003e3dc646711b6604d90f515b25e2cff866bce08f073bd8a734a39
 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
└───────────────────────────┴─────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────────────┐
 Materials
├─────────────┬─────────────────────────────────────────────────────────────────────────┤
 Name material-1747129596943160000
 Type CONTAINER_IMAGE
 Set Yes
 Required No
 Value ghcr.io/chainloop-dev/chainloop/control-plane:latest
 Digest sha256:beffeac0c87b0412d3d578e1aacec67cc85121e6bb709dbae0db8e6b0e4bef6e
├─────────────┼─────────────────────────────────────────────────────────────────────────┤
 Name material-1747129602198087000
 Type SBOM_CYCLONEDX_JSON
 Set Yes
 Required No
 Value sbom.json
 Digest sha256:f2888d10bcd93dc58431049a13acac1bc402231fb066e9e58fd986d91dec05f1
 Annotations ------
 chainloop.material.tool.name: syft
 chainloop.material.tool.version: 1.19.0
└─────────────┴─────────────────────────────────────────────────────────────────────────┘

Inspect the Attestation

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. info 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 info

Verifying your attestation

You can verify the integrity of the attestation by downloading the bundle (in Sigstore format) and running the verification command. info
chainloop att verify -b bundle.json
Under the hood, the command is:
  • Checking the validity of the signing certificate included in the bundle, against the Chainloop trusted root
  • Checking the validity of the timestamp signature
  • Verifying the payload integrity (the in-toto attestation included in the bundle) and its signature.
Visit the signing reference for more information about signing and verification methods.
I