​
Overview

Policies are rules evaluated against materials and/or the whole attestation document. They represent acceptance criteria for the system to ingest those materials. Even in failure cases (when there are policy violations), attestations are still sent to Chainloop but marked as “not compliant.” This way, Chainloop keeps track of everything happening in the system, even if it’s unacceptable. Policies are written in Rego language. Policies are also a fundamental piece in Chainloop’s compliance platform, as they are directly related to framework requirements. With the assistance of SecOps and developers, Requirements are matched to specific logic in Policies (programmed) written in the OPA Rego language. Rego is a rule engine and language used to automate the analysis of different reports and inputs to the system. Policies can also be grouped into Policy Groups to facilitate reuse across different products. For instance, a SAST (static application security testing) policy group can consist of a “no-vulnerabilities” policy, a “CWE” policy for common weaknesses, and a “secrets detection” policy.

​
Policy types

Policies can be of two types:
  • Built-in: policies that are part of the Chainloop platform
  • Custom: policies that are created and stored in the Chainloop platform

​
Built-in policies

Chainloop provides a curated set of policies tailored to common compliance controls, like:
  • SBOM sanity checks,
  • Artifact signature verification,
  • Licenses and component versions ban policies
  • SAST, linters result checks, code quality and coverage
  • CVE scans,
  • etc.
They can be found in the “Policies” section in Chainloop platform: Policies If none of the built-in policies fit your needs, you can create your own, more on that later.

​
Custom policies

Custom policies are policies created by the user that can be stored in the Chainloop platform or in a local or remote file.

​
Using Policies

​
Attaching policies to a contract

Policies are attached to a contract via the policies section. Policies can be applied to any material, but also to the attestation statement as a whole.

​
Option 1 - By reference

You can reference policies via three methods:
  • If it’s a policy stored in the Chainloop platform (either built-in and custom), you can reference it by name
  • If it’s a custom policy, you can reference it by URL or by path
schemaVersion: v1
materials:
  - name: sbom
    type: SBOM_CYCLONEDX_JSON
  - name: another-sbom
    type: SBOM_CYCLONEDX_JSON
  - name: my-image
    type: CONTAINER_IMAGE
policies:
  materials: # policies applied to materials
     - ref: sbom-banned-licenses # (1) built-in policy
       # or optionally with the digest appended, see integrity checks below
       # - ref: sbom-banned-licenses@sha256:5b40425cb7bcba16ac47e3d8a8d3af7288afeeb632096994e741decedd5d38b3
       with:
         licenses: "AGPL-10, AGPL-3.0"
  attestation: # policies applied to the whole attestation
    - ref: https://my-org.chainloop.dev/policies/my-custom-remotepolicy.yaml # (2) custom remote policy
Here we can see that:
  • (1) is a built-in policy referenced by name. Since that policy is compatible with SBOM_CYCLONEDX_JSON, only SBOM materials (sbom and another-sbom in this case) will be evaluated against it. If we wanted to only evaluate the policy against one specific sbom material, and skip the other, we should filter them by name: 
    policies:
  materials:
    - ref: sbom-banned-licenses # (1)
      selector:
        name: sbom
    Here, we are making explicit that only sbom material must be evaluated by the sbom-banned-licenses policy.
  • (2) the attestation in-toto statement as a whole will be evaluated against the remote policy my-custom-remotepolicy.yaml, which has a type property set to ATTESTATION. This brings the opportunity to validate global attestation properties, like annotations, the presence of a material, etc. You can see this policy and other examples in the examples folder.
Finally, note that material policies are evaluated during chainloop attestation add commands, while attestation policies are evaluated in chainloop attestation push command.
Optionally, you can append the sha256 hash of the policy file content to your policy attachment reference. By doing so, the policy engine will make sure the resolved policy matches the expected hash in the contract reference.For policies stored in the Chainloop platform, you can find the sha256 hash in the policy details page:Policies

​
Option 2 - Embedded

As an alternative to referencing policies, you can also embed them in your contract. This is useful if you want to ensure that the policy source cannot be changed, as it’s stored and versioned within the contract. 
  policies:
    materials:
      - embedded:
          apiVersion: workflowcontract.chainloop.dev/v1
          kind: Policy
          metadata:
            name: cve-policy
          spec:
            policies:
            - kind: SBOM_CYCLONEDX_JSON
              path: cves-cyclonedx.rego

​
Understanding policy evaluation results

Once configured, Policies are evaluated against inputs (inputs, materials, and artifacts, will be explained in the following sections). Evaluation results will include:
  • Overall result: success, failure, skipped
  • Policy violations: if the evaluation failed, what were the failures. For example: “component x, version y has critical vulnerabilities”
  • Skip reason: if the policy couldn’t be evaluated, what’s the reason (input might have the wrong format, for example)
Policy evaluation The results of policy evaluations are stored in Chainloop on every attestation and can be queried through the user interface: Policy evaluation results

​
Configuring Enforcement

Security and Compliance teams can set policy evaluation strategies to ENFORCED by default in their organization settings. Policy evaluation results This means that during any attestation process that contains policy violations, the CLI will return with an error code in addition to recording the attestation result and the fact that the pipeline was blocked. Policy evaluation results But I can hear what you are saying. Breaking pipelines might not be a good idea! We hear you. That’s why developers can provide the flag —exception-bypass-policy-check as an exception path when unblocking their pipelines. This will make their CI pipeline run as expected, but the exception has been recorded and exposed to the compliance team for verification. Policy evaluation results

​
Writing policies

You can learn more about writing policies in the custom policies guide.