Content Addressable Storage (CAS) backend

As part of an attestation process, you might want to collect different pieces of evidence such as Software Bill Of Materials (SBOMs), test results, runner logs, etc and then attach them to the final in-toto attestation. Chainloop helps with this process by providing a Content Addressable Storage API proxy that:

Abstracts away the underlying storage backend. Currently, we support OCI registries as storage backends but you can expect blob storage, Artifactory and other storage backends to be supported in the future.
Makes sure that the pieces of evidence are stored in a tamper-proof manner. This is achieved by storing the evidences named after their SHA256 content digest, which is calculated by the client, verified by the CAS server.
Enables support of large pieces of evidence since the content digest reference is what will be stored in the attestation.

Manage Storage Backends

You can setup as many CAS backends as you want, but you can only have one enabled as default and one as fallback at the time. This default backend will be used during the attestation process to store the pieces of evidence. The fallback backend will be used when the default backend fails or is unreachable,

Chainloop periodically validates the credentials of configured CAS backends. Only backends that are marked as default or fallback and are not the built-in inline backend are checked. If any of these backends start to fail authentication or access checks, Chainloop will automatically send an email notification to the organization’s owners so they can rotate or fix the credentials.

Fallback Backend

The fallback backend provides high availability for your artifact storage. When configured:

Chainloop first attempts to store artifacts in the default backend
If the default backend is unreachable or fails validation, Chainloop automatically switches to the fallback backend
Your attestation process continues without interruption

Web UI
CLI

You can manage your CAS backends in the Storage Backends Section.

In Chainloop, CAS backends can be managed with the chainloop cas-backend command.

$ chainloop cas-backend ls

Command Output

┌─────────────────────────────────┬──────────┬─────────────────────────────────────┬───────────────┬─────────┬──────────┐
│ LOCATION                        │ PROVIDER │ DESCRIPTION                         │ LIMITS        │ DEFAULT │ FALLBACK │
├─────────────────────────────────┼──────────┼─────────────────────────────────────┼───────────────┼─────────┼──────────┤
│                                 │ INLINE   │ Embed artifacts content in the atte │ MaxSize: 500K │ false   │ false    │
│                                 │          │ station                             │               │         │          │
├─────────────────────────────────┼──────────┼─────────────────────────────────────┼───────────────┼─────────┼──────────┤
│ ghcr.io/cyberdyne/chainloop-lab │ OCI      │                                     │ MaxSize: 100M │ true    │ false    │
└─────────────────────────────────┴──────────┴─────────────────────────────────────┴───────────────┴─────────┴──────────┘

Storage Backend providers

New CAS Backends will be added over time. If yours is not implemented yet, please let us know

Platform operators: Chainloop Enterprise can also auto-provision a dedicated CAS backend for every organization in your installation via Managed CAS, so end users don’t need to bring their own storage.

Inline

Chainloop comes pre-configured with what we call an inline backend that embeds the pieces of evidence in the resulting attestations.

Inline backend is useful to get started quickly but since the metadata is embedded in the attestation, its max size is limited.We recommend to switch to a more robust backend such when moving to production.

OCI registry

Add a new OCI registry backend

Google Artifact Registry
Azure Container Registry
GitHub packages
DockerHub
AWS Container Registry

  # Using json-based service account
  # https://console.cloud.google.com/iam-admin/serviceaccounts

  $ chainloop cas-backend add oci \
    --name [cas-backend-name] \
    # i.e us-east1-docker.pkg.dev/my-project/chainloop-cas-devel
    --repo [region]-docker.pkg.dev/[my-project]/[my-repository] \
    --username _json_key \
    --password "$(cat service-account.json)" \
    --default

  # Using token-auth with push (content/read + content/write) permissions
  # https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions

  $ chainloop cas-backend add oci \
    --name [cas-backend-name] \
    # i.e chainloopcas.azurecr.io/cas
    --repo [registry-name].azurecr.io/[my-repository] \
    --username [token-name] \
    --password [token-password] \
    --default

  # Using personal access token with write:packages permissions
  # https://github.com/settings/tokens

  $ chainloop cas-backend add oci \
    --name [cas-backend-name] \
    # i.e ghcr.io/chainloop-dev/chainloop-cas
    --repo ghcr.io/[username or org]/[my-repository] \
    --username [username] \
    --password [personal access token] \
    --default

# Create a personal access token at
# https://hub.docker.com/settings/security

$ chainloop cas-backend add oci \
    --name [cas-backend-name] \
    --repo index.docker.io/[username] \
    --username [username] \
    --password [personal access token] \
    --default

Rotate credentials

chainloop cas-backend update oci --name [BACKEND_NAME] --username [NEW_USERNAME] --password [NEW_PASSWORD]

Set as default

chainloop cas-backend update oci --name [BACKEND_NAME] --default=true

Set as fallback

chainloop cas-backend update oci --name [BACKEND_NAME] --fallback=true

AWS S3

Chainloop also supports storing artifacts in AWS S3 Blob Storage.

Pre-requisites

To connect your AWS account to Chainloop you’ll need:

S3 Bucket Name
Bucket Region
AccessKeyID
SecretAccessKey

Create an S3 bucket Create an S3 bucket and take note of the bucket name and region

Create an IAM user with access to that bucket Next we are going to create a policy that has write/read permissions to the bucket. You can use the snippet below by just replacing [bucketName] with the actual name of the bucket you created in the step before.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": [
				"s3:ListBucket"
			],
			"Resource": "arn:aws:s3:::[bucketName]"
		},
		{
			"Effect": "Allow",
			"Action": [
				"s3:GetObject",
				"s3:PutObject"
			],
			"Resource": "arn:aws:s3:::[bucketName]/*"
		}
	]
}

Then create an user, attach the policy to it and click on “create access Key”

Then select third-party service and copy the access key ID and secret access key We are now ready to connect our AWS account to Chainloop

 $ chainloop cas-backend add aws-s3 \
    --name [BACKEND_NAME] \
    --access-key-id [accessKeyID] \
    --secret-access-key [secretAccessKey] \
    --region [region] \
    --bucket [bucketName]

Rotate credentials

chainloop cas-backend update aws-s3 --name [BACKEND_NAME] --access-key-id [new-accessKeyID] --secret-access-key [new-secretAccessKey] --region [new-region]

Azure Blob Storage

Chainloop also supports storing artifacts in Azure Blob Storage.

Pre-requisites

To connect your Azure storage account you’ll need the following information

Active Directory Tenant ID
Service Principal ID
Service Principal Secret
Storage account name

We’ll walk you through the process of how to find this information Register an application to create the service principal First, you’ll need to register an application in your Azure Active Directory tenant. You can do this using the Azure CLI or from the Azure portal

Once done, in the application overview you should be able to find the tenantID, and Service principal ID

Next, let’s create a secret for the service principal

Create a storage account and give permissions to the service principal Next, we’ll create a storage account (or you can use an existing one), take a note on the storage account name.

And once created, we’ll give permissions to the service principal, go to IAM assign-roles.

Search for the application we just registered and assign the Storage Blob Data Contributor role

At thi point we have all the information we need to connect our Azure storage account to Chainloop

 $ chainloop cas-backend add azure-blob \
    --name [BACKEND_NAME] \
    --client-id [servicePrincipalID] \
    --client-secret [servicePrincipalSecret] \
    --tenant [Active directory tenant] \
    --storage-account [Storage Account name] \
    --container [optional Storage account container] \
    --endpoint [optional custom endpoint suffix, e.g., blob.core.usgovcloudapi.net]

Rotate credentials

chainloop cas-backend update azure-blob --name [BACKEND_NAME] --client-id [new-clientID] --client-secret [new secret] --tenant [updated tenant]

Cloudflare R2

Cloudflare R2 is compatible with AWS S3 and can be configured in Chainloop by providing a custom endpoint. Pre-requisites

AccessKeyID
SecretAccessKey
Bucket Name
Endpoint

Follow this instructions to create a compatible AccessKeyID and SecretAccessKey. Then copy the bucket name and endpoint from the bucket settings.

Finally register the Cloudflare R2 bucket using the aws-s3 provider and providing the custom endpoint.

 $ chainloop cas-backend add aws-s3 \
    --name [BACKEND_NAME] \
    --access-key-id [accessKeyID] \
    --secret-access-key [secretAccessKey] \
    --bucket [bucketName] \
    --endpoint [endpoint] # provide the custom endpoint

Minio

Minio is an S3-compatible blob storage that can be configured in Chainloop by providing a custom endpoint. Pre-requisites

AccessKeyID
SecretAccessKey
Bucket Name
Minio Endpoint

You can create a new AccessKey from the Minio console.

Then copy the bucket name and Minio endpoint.

Finally register the Minio bucket using the aws-s3 provider and providing the custom endpoint

 $ chainloop cas-backend add aws-s3 \
    --name [BACKEND_NAME] \
    --access-key-id [accessKeyID] \
    --secret-access-key [secretAccessKey] \
    --bucket [bucketName] \
    --endpoint [endpoint] # provide the custom endpoint

Give it a try

If everything went well, you should be able to upload and download artifact materials, let’s give it a try

Upload a file to your OCI repository

$ chainloop artifact upload -f myfile
myfile@sha256:c5cc0a2c712497c29f29c3ba11e7fcc0c3cc725ab591720db595e5d6469f3f37 ... done! [1.03KB in 0s; 5.48KB/s]

Download by content digest (sha256)

$ chainloop artifact download -d sha256:c5cc0a2c712497c29f29c3ba11e7fcc0c3cc725ab591720db595e5d6469f3f37
INF downloading file name=myfile to=/tmp/myfile
INF file downloaded! path=/tmp/myfile

Getting Started

Concepts

Guides

References

Misc

Content Addressable Storage (CAS) backend

Manage Storage Backends

Fallback Backend

Storage Backend providers

Inline

OCI registry

Add a new OCI registry backend

Rotate credentials

Set as default

Set as fallback

AWS S3

Pre-requisites

Rotate credentials

Azure Blob Storage

Pre-requisites

Rotate credentials

Cloudflare R2

Minio

Give it a try

​Manage Storage Backends

​Fallback Backend

​Storage Backend providers

​Inline

​OCI registry

​Add a new OCI registry backend

​Rotate credentials

​Set as default

​Set as fallback

​AWS S3

​Pre-requisites

​Rotate credentials

​Azure Blob Storage

​Pre-requisites

​Rotate credentials

​Cloudflare R2

​Minio

​Give it a try

Manage Storage Backends

Fallback Backend

Storage Backend providers

Inline

OCI registry

Add a new OCI registry backend

Rotate credentials

Set as default

Set as fallback

AWS S3

Pre-requisites

Rotate credentials

Azure Blob Storage

Pre-requisites

Rotate credentials

Cloudflare R2

Minio

Give it a try