Writing Chainloop policies
Chainloop policies consists of a YAML document with some metadata and a Rego script which holds the policy logic. You can check this document for a quick reference on policies. Read the following sections for a better understanding on how to write Rego code for your Chainloop policies.
Rego language
Rego language, from Open Policy Agent initiative, has become the de-facto standard for writing software supply chain policies. It's a rule-oriented language, suitable for non-programmers that want to communicate and enforce business and security requirements in their pipelines.
Chainloop Rego implementation
A typical Chainloop Rego policy looks like this:
package main
import rego.v1
# (1)
################################
# Common section do NOT change #
################################
# (2)
result := {
"skipped": skipped,
"violations": violations,
"skip_reason": skip_reason,
}
default skip_reason := ""
skip_reason := m if {
not valid_input
m := "invalid input"
}
default skipped := true
skipped := false if valid_input
########################################
# EO Common section, custom code below #
########################################
# Validates if the input is valid and can be understood by this policy (3)
valid_input if {
# insert code here
}
# If the input is valid, check for any policy violation here (4)
violations contains msg if {
valid_input
# insert code here
}
In the above template we can see there is a common section (1). Chainloop will look for the main rule result
, if present. Older versions of Chainloop will only check for a violations
rule.
result
object has essentially three fields:
skipped
: whether the policy evaluation was skipped. This property would be set to true when the input, for whatever reason, cannot be evaluated (unexpected format, etc.). This property is useful to avoid false positives.skip_reason
: if the policy evaluation was skipped, this property will contain some informative explanation of why this policy wasn't evaluated.violations
: will hold the list of policy violations for a given input. Note that in this case,skipped
will be setfalse
, denoting that the input was evaluated against the policy, and it didn't pass.
Note that there is no need to modify the common section. Policy developers will only need to fill in the valid_input
and violations
rules:
valid_input
would fail if some preconditions were not met, like the input format.
Example
Let's say we want to write a policy that checks our SBOM in CycloneDX format to match a specific version. A valid_input
rule would look like this:
# It's a valid input if format is CycloneDX and has specVersion field that we can check later
valid_input if {
input.bomFormat == "CycloneDX"
input.specVersion
}
violations
rule would return the list of policy violations, given that valid_input
evaluates to true
. If we wanted the CycloneDX report to be version 1.5
:
violations contains msg if {
valid_input
input.specVersion != "1.5"
msg := sprintf("wrong CycloneDX version. Expected 1.5, but it was %s", [input.specVersion])
}
When evaluated against an attestation, The policy will generate an output similar to this:
{
"result": {
"skipped": false,
"violations": [
"wrong CycloneDX version. Expected 1.5, but it was 1.4"
]
}
}
Make sure you test your policies in the Rego Playground.
Chainloop policy
Once we have our Rego logic for our policy, we can create a Chainloop policy like this:
# cyclonedx-version.yaml
apiVersion: workflowcontract.chainloop.dev/v1
kind: Policy
metadata:
name: cyclonedx-version
spec:
policies:
- kind: SBOM_CYCLONEDX_JSON
name: cyclonedx-version.rego
and finally attach it to a contract:
schemaVersion: v1
policies:
materials:
- ref: file://cyclonedx-version.yaml
Check our policies reference for more information on how to attach policies to contracts.
Policy engine constraints (Rego)
To ensure the policy engine work as pure and as fast as possible, we have deactivated some of the OPA built-in functions. The following functions are not allowed in the policy scripts:
opa.runtime
rego.parse_module
trace
Also http.send
has been isolated so only requests to the following domains are allowed:
chainloop.dev
cisa.gov
This prevents unexpected behavior and potential remote exploits, particularly since these policies are evaluated client-side.