Introduction
In the previous section, we created a workflow definition, a contract and an API Token in the control plane. Next, we'll perform an attestation crafting example using Chainloop.
The lifecycle of a crafting process has the following stages: init, add, push or reset. As you can see, it mimics the workflow of a commonly used version control tool, and this is not by coincidence. Chainloop wants to make sure that the tooling feels familiar to developers and that no security jargon leaks into this stage of the process. For a developer, creating an attestation must be as simple as initializing it, adding materials to it, and pushing it.
A brief description of the different stages below.
attestation init
During this stage, the crafting tool will contact the control plane to
Signal the intent of starting an attestation.
Retrieve or create the associated workflow contract
If the contract has a specified runner context type, check that we are compliant with it.
Initialize environment variables, explicitly stated in the contract and other contextual information.
attestation add
Add the materials required by the contract and any other additional pieces of evidence, i.e artifact, OCI image ref, SBOM.
The add command knows how to handle each kind of material transparently to the user.
For example
ARTIFACT kinds will be uploaded to your artifact registry and referenced by their content digest.
CONTAINER_IMAGE kinds will be resolved to obtain their repository digests using the local authentication keychain.
SBOM_CYCLONEDX_JSON will validate the right SBOM format and upload it to the artifact registry.
For a complete list of available material types, see the reference.
attestation push
This stage will take the current crafting state, validate that it has all the required materials, and
Create a signed, in-toto attestation envelope.
Push it to the control plane for storage
attestation reset
By using the reset command we can indicate to the control plane that something went wrong or we want to abort the attestation process.
attestation status
See the state of the current crafting process.
Crafting our first attestation locally
Two things are required to create an attestation: the Chainloop crafting tool and an API Token.
Alternatively to Chainloop API tokens. You can now perform attestations from Gitlab.com runners leveraging Gitlab's OIDC ephemeral tokens. More info here
The crafting tool is currently bundled within the Chainloop command-line tool. To install it, follow the installation instructions.
The API Token was created during the previous step, and it's required during all the stages of the crafting process. It can be provided via the --token flag or the $CHAINLOOP_TOKEN environment variable.
$ export CHAINLOOP_TOKEN=deadbeef
Initialization
Options
chainloop attestation init supports the following options
--tokentoken provided by the SecOps team. Alternatively, you can set theCHAINLOOP_TOKENenvironment variable (required).--workflowname of the workflow to run the attestation (required). It will create the workflow if it doesn't exist--projectname of the project of the workflow (required).--dry-run; do not store the attestation in the Control plane, and do not fail if the runner context or required env variables can not be resolved. Useful for development (default:false).
tip
If the workflow with name --workflow in project --project doesn't exist, it will be created with the default contract (or with the contract specified by --contract).
To initialize a new crafting process just run attestation init and the system will retrieve the latest version (if no specific revision is set via the --revision flag) of the contract.
$ chainloop attestation init --workflow build-and-test --project skynet
INF Attestation initialized! now you can check its status or add materials to it
┌───────────────────┬──────────────────────────────────────┐
│ Initialized At │ 02 Nov 22 10:04 UTC │
├───────────────────┼──────────────────────────────────────┤
│ Workflow │ 2d289d33-8241-47b7-9ea2-8bd8b7c126f8 │
│ Name │ build-and-test │
│ Team │ cyberdyne core │
│ Project │ skynet │
│ Contract Revision │ 2 │
└───────────────────┴──────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ Materials │
├──────────────────────┬─────────────────┬─────┬──────────┬───────────┤
│ NAME │ TYPE │ SET │ REQUIRED │ IS OUTPUT │
├──────────────────────┼─────────────────┼─────┼──────────┼───────────┤
│ skynet-control-plane │ CONTAINER_IMAGE │ No │ Yes │ x │
│ rootfs │ ARTIFACT │ No │ Yes │ │
│ dockerfile │ ARTIFACT │ No │ No │ │
│ build-ref │ STRING │ No │ Yes │ │
│ skynet-sbom │ SBOM_CYCLONEDX_JSON│No│ Yes │ │
└──────────────────────┴─────────────────┴─────┴──────────┴───────────┘
As you can see, we have some work to do to complete this attestation, we have three required materials not set, let's do that next.
Adding Materials
# Add container image
$ chainloop attestation add --name skynet-control-plane --value ***.dkr.ecr.us-east-1.amazonaws.com/skynet-control-plane:v0.7.6
INF material added to attestation
# Add rootfs artifact
$ chainloop attestation add --name rootfs --value rootfs.tar.gz
rootfs.tar.gz@sha256:f8a581d4bce57f792444b2230b5706a6f902fbac19a374e76f6a56f030d35cf2 ... done! [7B in 0s; 34B/s]
INF material added to attestation
# Add build-ref artifact
$ chainloop attestation add --name build-ref --value 80e461e9b385c6986cdb8096c9dc99928943d667
# Add Software Bill Of Materials
$ chainloop attestation add --name skynet-sbom --value sbom.cyclonedx.json
There is also the option of leaving Chainloop CLI to figure out the material type when adding a piece of evidence in an attestation, learn more about auto-discover here.
Inspecting the crafting status
If we check the status of the attestation, we'll see that the three required materials have been added
$ chainloop attestation status --full
┌───────────────────┬──────────────────────────────────────┐
│ Initialized At │ 02 Nov 22 10:04 UTC │
├───────────────────┼──────────────────────────────────────┤
│ Workflow │ 2d289d33-8241-47b7-9ea2-8bd8b7c126f8 │
│ Name │ build-and-test │
│ Team │ cyberdyne core │
│ Project │ skynet │
│ Contract Revision │ 2 │
└───────────────────┴──────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Materials │
├──────────────────────┬─────────────────┬─────┬──────────┬───────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NAME │ TYPE │ SET │ REQUIRED │ IS OUTPUT │ VALUE │
├──────────────────────┼─────────────────┼─────┼──────────┼───────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ skynet-control-plane │ CONTAINER_IMAGE │ Yes │ Yes │ x │ **.dkr.ecr.us-east-1.amazonaws.com/skynet-control-plane@sha256:963237021c5fd0d31741a9b873e1e8af08c76459cf30e34332925510e0cb3731 │
│ rootfs │ ARTIFACT │ Yes │ Yes │ │ rootfs.tar.gz@sha256:f8a581d4bce57f792444b2230b5706a6f902fbac19a374e76f6a56f030d35cf2 │
│ dockerfile │ ARTIFACT │ No │ No │ │ │
│ build-ref │ STRING │ Yes │ Yes │ │ 80e461e9b385c6986cdb8096c9dc99928943d667 │
│ skynet-sbom │ SBOM_CYCLONEDX_ │ Yes │ Yes │ │ deadbeefddaaae-redacted │
└──────────────────────┴─────────────────┴─────┴──────────┴───────────┴─────────────────────────────────────────────────────────────────────────────
Encode, sign and push attestation
Chainloop supports multiple signing methods, by default, we leverage keyless signing powered by ephemeral certificates. To learn about other signing methods, please review this guide
Since all the required materials have been attached, a signed in-toto statement can now be generated and sent for storage.
$ chainloop attestation push
The resulting attestation will be rendered, signed, and pushed to the control plane.
CI integration
Native CI/CD runner integrations (e.g., Jenkins plugin, GitHub action) are under development, but the process stated above can be implemented in any CI pipeline by using the Chainloop CLI.
You can find CI pipeline examples here.