diff --git a/getting_started/policies.md b/getting_started/policies.md index 926504ff..fd648912 100644 --- a/getting_started/policies.md +++ b/getting_started/policies.md @@ -89,7 +89,7 @@ artifacts: ### Exceptions -You can add exceptions to policy rules using [policy expressions](/policy-reference/environment_policy#policy-expressions). +You can add exceptions to policy rules using [policy expressions](/policy-reference/environment_policy#policy-expressions). Note how expressions behave when a value is [missing](/policy-reference/environment_policy#missing-values), which is common for artifacts reported without provenance. ```yaml _schema: https://docs.kosli.com/schemas/policy/v1 diff --git a/policy-reference/environment_policy.mdx b/policy-reference/environment_policy.mdx index 3b2baedf..4c5cd2f0 100644 --- a/policy-reference/environment_policy.mdx +++ b/policy-reference/environment_policy.mdx @@ -60,6 +60,8 @@ An environment policy is a YAML file that declares compliance requirements for a List of attestations every artifact must have. Each element is a required-attestation rule. + A rule is evaluated against the newest attestation whose `name` and `type` match the rule, including override attestations — an override supersedes the status of the attestation it overrides. Overriding a non-compliant attestation can therefore bring an environment back to compliant, and overriding a compliant one down to non-compliant makes the environment non-compliant. + The [attestation type](#attestation-types) to require. Cannot be `*` when `name` is also `*`. @@ -152,6 +154,17 @@ Parentheses control precedence: `${{ flow.name == 'prod' and (flow.tags.team == | `exists(arg)` | Returns `true` if `arg` is not null. | `${{ exists(flow) }}` | | `matches(input, regex)` | Returns `true` if `input` matches the regular expression. | `${{ matches(artifact.name, "^datadog:.*") }}` | +### Missing values + +A value is missing when the context does not supply it. This is common rather than exceptional: + +- `flow` is missing for any artifact reported without provenance. +- `flow.tags.` is missing for a tag the flow does not have. + +The comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`), the membership operator `in`, and the functions `exists()` and `matches()` all evaluate to `false` when either operand is missing. A missing operand is not an error — the comparison is simply not satisfied. + +To branch on whether a value is present at all, test it with `exists()` rather than relying on a comparison against it. + ## Constraints - `_schema` is the only required field. All other fields are optional and use server defaults when omitted.