Policy Groups

Overview

This feature allow operators to group related policies into one single entity that can be reused across the organization. With Policy Groups, materials and policies can be enforced in Chainloop contracts with little or no effort. For example, they might want to create a “SBOM quality” group with some SBOM-related policies. The policy groups can be defined this way:

# sbom-quality.yaml
apiVersion: workflowcontract.chainloop.dev/v1
kind: PolicyGroup
metadata:
  name: sbom-quality
  description: This policy group applies a number of SBOM-related policies
  annotations:
    category: SBOM
spec:
  inputs:
    - name: bannedLicenses
      description: comma separated list of licenses to ban
      required: true
    - name: bannedComponents
      description: comma separated list of components to ban
      required: true
  policies:
    materials:
      - name: sbom
        type: SBOM_CYCLONEDX_JSON
        policies:
        - ref: sbom-banned-licenses
          with:
            licenses: {{ inputs.bannedLicenses }}
        - ref: sbom-banned-components
          with:
            components: {{ inputs.bannedComponents }}

Policy groups can also be stored and managed in the platform using the Enterprise Edition CLI. For a complete guide on managing policy groups and other resources declaratively via YAML, see Declarative Resource Management.

Using Policy Groups

This policy group could be applied to any contract:

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: example-contract
spec:
  policyGroups:
    - ref: file://groups/sbom-quality-group.yaml
      with:
        bannedComponents: [email protected]
        bannedLicenses: AGPL-1.0-only, AGPL-1.0-or-later, AGPL-3.0-only, AGPL-3.0-or-later

As we introduced earlier, policy groups define both materials and policies applied to them. Once they are included to a contract, they become part of the contract. From this point of view, they can be seen as subcontracts, as they can also be used to enforce materials to be present in the attestation. For example, after applying the above contract, doing an attestation push would fail until the required material is provided:

$ chainloop att init --workflow mywf --project myproject
INF Attestation initialized! now you can check its status or add materials to it
┌────────────────┬──────────────────────────────────────┐
│ Initialized At │ 30 Dec 24 12:26 UTC                  │
├────────────────┼──────────────────────────────────────┤
│ Attestation ID │ a52f082c-ca4a-4952-bb07-fa9117c04a90 │
│ Organization   │ my-org                               │
│ Name           │ mywf                                 │
│ Project        │ myproject                            │
│ Version        │ v0.148.0 (prerelease)                │
│ Contract       │ myproject-mywf (revision 76)         │
└────────────────┴──────────────────────────────────────┘
┌────────────────────────────────┐
│ Materials                      │
├──────────┬─────────────────────┤
│ Name     │ sbom                │
│ Type     │ SBOM_CYCLONEDX_JSON │
│ Set      │ No                  │
│ Required │ Yes                 │
└──────────┴─────────────────────┘

$ chainloop att push
ERR some materials have not been crafted yet: sbom
exit status 1

Policy group parameters

In the same way as policies, groups can accept arguments, which are specified in the inputs section. Then those inputs can be passed down to policies using interpolation. In the example above, bannedComponents input parameter (which is mandatory) is passed to the underlying policy with the expression {{ inputs.bannedComponents }}

        - ref: sbom-banned-components
          with:
            components: {{ inputs.bannedComponents }}

Skipping specific policies

Sometimes you may want to use a policy group but temporarily or permanently exclude certain policies from evaluation without modifying the group definition itself. This is useful when:

A specific policy doesn’t apply to a particular workflow
You need to temporarily bypass a policy during development or migration
Different workflows need different subsets of policies from the same group

You can use the skip field to selectively exclude policies by their metadata name:

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: example-contract
spec:
  policyGroups:
    - ref: sbom-quality-group
      with:
        bannedComponents: [email protected]
      skip:
        - sbom-banned-licenses  # Skip the license check for this workflow

Policy names in the skip list refer to the policy’s metadata name (the name field in the policy definition)

This feature provides flexibility in policy enforcement per workflow without requiring multiple versions of the same policy group.

Using placeholders in material names

In the previous example, our policy group enforces a sbom material. But what if our contract requires multiple SBOMs (because we are building several images in the same pipeline, for example)? By using parameters and placeholders in material names, we can add as many instances of the same policy group as we need:

apiVersion: workflowcontract.chainloop.dev/v1
kind: PolicyGroup
metadata:
  name: sbom-quality
spec:
  inputs:
    - name: container_name
      description: name of the enforced material
      required: true
  policies:
    materials:
      - name: "{{ inputs.container_name }}" # This will materialize when doing an `attestation init`
        type: SBOM_CYCLONEDX_JSON

In our contract:

apiVersion: chainloop.dev/v1
kind: Contract
metadata:
  name: multi-sbom-contract
spec:
  policyGroups:
    - ref: file://groups/sbom-quality-group.yaml
      with:
        container_name: "sbom-from-image-1"
    - ref: file://groups/sbom-quality-group.yaml
      with:
        container_name: "sbom-from-image-2"

And finally, in our attestation, we can see the new configuration applied:

$ chainloop att init --workflow mywf --project myproject
INF Attestation initialized! now you can check its status or add materials to it
┌────────────────┬──────────────────────────────────────┐
│ Initialized At │ 30 Dec 24 13:21 UTC                  │
├────────────────┼──────────────────────────────────────┤
│ Attestation ID │ 0837859e-0abf-414e-b205-d455da6dfe7e │
│ Organization   │ my-org                               │
│ Name           │ mywf                                 │
│ Project        │ myproject                            │
│ Version        │ v0.148.0 (prerelease)                │
│ Contract       │ myproject-mywf (revision 77)         │
└────────────────┴──────────────────────────────────────┘
┌────────────────────────────────┐
│ Materials                      │
├──────────┬─────────────────────┤
│ Name     │ sbom-from-image-1   │
│ Type     │ SBOM_CYCLONEDX_JSON │
│ Set      │ No                  │
│ Required │ Yes                 │
├──────────┼─────────────────────┤
│ Name     │ sbom-from-image-2   │
│ Type     │ SBOM_CYCLONEDX_JSON │
│ Set      │ No                  │
│ Required │ Yes                 │
└──────────┴─────────────────────┘

Getting Started

Concepts

Guides

References

Misc

Overview

Using Policy Groups

Policy group parameters

Skipping specific policies

Using placeholders in material names

​Overview

​Using Policy Groups

​Policy group parameters

​Skipping specific policies

​Using placeholders in material names

Overview

Using Policy Groups

Policy group parameters

Skipping specific policies

Using placeholders in material names