Set Policies expectations - Chainloop Documentation

In the previous step, we created a contract that set the expectation of a container image, an SBOM and a vulnerability report. Our Compliance team now wants to verify that those comply with the company’s security and compliance criteria. We introduce Policies, which are rules evaluated against materials and/or the whole attestation document. Policies can be grouped into Policy Groups to be able to attach a set of policies to a workflow contract.

Attaching policies to the contract

Web UI
CLI
Chainloop OSS

As we did before, let’s “Update our contract”, but this time the contract will contain policies and policy groups.

Updating the contract to add policies and policy groups in the Chainloop UI

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: myproject-build-container-image
spec:
  materials:
    - name: container
      type: CONTAINER_IMAGE
    - name: sbom
      type: SBOM_CYCLONEDX_JSON
    - name: vulnerabilities-report
      type: SARIF
  # We can attach policies from the provided library of policies https://app.chainloop.dev/policies
  # or custom ones as explained here https://docs.chainloop.dev/concepts/policies
  policies:
    materials:
      # artifact-signed checks that all OCI artifacts such as Container Images and Charts are signed
      - ref: artifact-signed
      # Make sure we are not using latest in the container image
      - ref: artifact-tag-not-latest
  # alternatively to policies you can apply policy groups
  # https://docs.chainloop.dev/concepts/policy-groups#policy-groups
  policyGroups:
    - ref: slsa-checks
    - ref: vulnerability-management
    - ref: sbom-quality
      with:
        bannedComponents: [email protected]
        bannedLicenses: AGPL-1.0-only, AGPL-1.0-or-later, AGPL-3.0-only, AGPL-3.0-or-later

chainloop wf contract update --contract https://raw.githubusercontent.com/chainloop-dev/chainloop/refs/heads/main/docs/examples/quickstart/contract-with-policies.yaml

Use this command to create a contract from a remote location:

chainloop wf contract create --contract https://raw.githubusercontent.com/chainloop-dev/chainloop/refs/heads/main/docs/examples/quickstart/contract-with-policies-oss.yaml

In this contract, we added two policies and three policy groups.

artifact-signed policy checks that all OCI artifacts (container images and Helm Charts) are properly signed with Cosign or Notary
artifact-tag-not-latest checks that the container image is not using the latest tag
slsa-checks is a policy group that makes sure the attestation is compliant with the SLSA framework
vulnerability-management is a policy group that makes sure the attestation is compliant with the vulnerability management policy
sbom-quality is a policy group that makes sure the attestation is compliant with the SBOM quality policy

Chainloop comes with a set of built-in policies and policy groups, you can see them all in the “Policies library”.

The built-in policies library in the Chainloop UI

You can also create custom policies tailored to your needs. For more information about authoring policies, see this guide.

Evaluating policies

Let’s create an attestation and add our materials to see how policies are evaluated:

Initialize an attestation

chainloop att init --workflow build-container-image --project myproject --replace

Add the container image

chainloop att add --name container --value ghcr.io/chainloop-dev/chainloop/control-plane

You’ll notice how Chainloop will evaluate automatically as part of providing the container image.

Add the SBOM

chainloop att add --name sbom --value https://raw.githubusercontent.com/chainloop-dev/chainloop/refs/heads/main/docs/examples/quickstart/sbom.json

Add the vulnerability report

chainloop att add --name vulnerabilities-report --value https://raw.githubusercontent.com/chainloop-dev/chainloop/refs/heads/main/docs/examples/quickstart/vulnerability-report.json

Push the attestation

chainloop att push

CLI output showing policy evaluation results after pushing the attestation

We can see in the output that the policies have been evaluated and the only ones failing are:

the ones related to the build-environment, since we are running the attestation process locally.
the one that checks the container image is not using the latest tag.

You can give it a try and attach an old SBOM or Vulnerability report with vulnerabilities to see how the policies being evaluated and failing.

Inspecting policy evaluations

Now, the Chainloop platform gives us more insights into the status of the attestation. If we go to the workflow run view, besides the usual attestation and material information, we can now see the result of those policy evaluations.

Policy evaluation results shown in the workflow run view in the Chainloop UI

​Attaching policies to the contract

​Evaluating policies

​Inspecting policy evaluations

Attaching policies to the contract

Evaluating policies

Inspecting policy evaluations