Policies and Evaluation
Introduction
Policies are the unit of policy definition and evaluation in Anchore Enterprise. A user may have multiple policies, but for a policy evaluation, the user must specify a policy to be evaluated or default to the policy currently marked ‘active’. See Policies Overview for more detail on manipulating and configuring policies.
Components of a Policy
A policy is a single JSON document, composed of several parts:
- Policy Gates - The named sets of rules and actions.
- Allowlists - Named sets of rule exclusions to override a match in a policy rule.
- Mappings - Ordered rules that determine which policies and allowlists should be applied to a specific image at evaluation time.
- Allowlisted Images - Overrides for specific images to statically set the final result to a pass regardless of the policy evaluation result.
- Blocklisted Images - Overrides for specific images to statically set the final result to a fail regardless of the policy evaluation result.
Example JSON for an empty policy, showing the sections and top-level elements:
{
"id": "default0",
"version": "2",
"name": "My Default policy",
"comment": "My system's default policy",
"allowlisted_images": [],
"denylisted_images": [],
"mappings": [],
"allowlists": [],
"rule_sets": []
}
Policies
A policy contains zero or more rule sets. The rule sets in a policy define the checks to make against an image and the actions to recommend if the checks find a match.
Example of a single rule set JSON object, one entry in the rule_set array of the larger policy document:
{
"name": "DefaultPolicy",
"version": "2",
"comment": "Policy for basic checks",
"id": "ba6daa06-da3b-46d3-9e22-f01f07b0489a",
"rules": [
{
"action": "STOP",
"gate": "vulnerabilities",
"id": "80569900-d6b3-4391-b2a0-bf34cf6d813d",
"params": [
{ "name": "package_type", "value": "all" },
{ "name": "severity_comparison", "value": ">=" },
{ "name": "severity", "value": "medium" }
],
"trigger": "package"
}
]
}
The above example defines a stop action to be produced for all package vulnerabilities found in an image that are severity medium or higher.
For information on how Rule Sets work and are evaluated, see: Rule Sets
Allowlists
An allowlist is a set of exclusion rules for trigger matches found during policy evaluation. An allowlist defines a specific gate and trigger_id (part of the output of a policy rule evaluation) that should have it’s action recommendation statically set to go. When a policy rule result is allowlisted, it is still present in the output of the policy evaluation, but it’s action is set to go and it is indicated that there was an allowlist match.
Allowlists are useful for things like:
- Ignoring CVE matches that are known to be false-positives
- Ignoring CVE matches on specific packages (perhaps if they are known to be custom patched)
Example of a simple allowlist as a JSON object from a policy:
{
"id": "allowlist1",
"name": "Simple Allowlist",
"version": "2",
"items": [
{ "id": "item1", "gate": "vulnerabilities", "trigger": "package", "trigger_id": "CVE-10000+libssl" },
{ "id": "item2", "gate": "vulnerabilities", "trigger": "package", "trigger_id": "CVE-10001+*" }
]
}
For more information, see Allowlists
Mappings
Mappings are named rules that define which rule sets and allowlists to evaluate for a given image. The list of mappings is evaluated in order, so the ordering of the list matters because the first rule that matches an input image will be used and all others ignored.
Example of a simple mapping rule set:
[
{
"name": "DockerHub",
"registry": "docker.io",
"repository": "library/postgres",
"image": { "type": "tag", "value": "latest" },
"rule_set_ids": [ "policy1", "policy2" ],
"allowlist_ids": [ "allowlist1", "allowlist2" ]
},
{
"name": "default",
"registry": "*",
"repository": "*",
"image": { "type": "tag", "value": "*" },
"rule_set_ids": [ "policy1" ],
"allowlist_ids": [ "allowlist1" ]
}
]
For more information about mappings see Mappings
Allowlisted Images
Allowlisted images are images, defined by registry, repository, and tag/digest/imageId, that will always result in a pass status for policy evaluation unless the image is also matched in the denylisted images section.
Example image allowlist section:
{
"name": "AllowlistDebianStable",
"registry": "docker.io",
"repository": "library/debian",
"image": { "type": "tag", "value": "stable" }
}
Denylisted Images
Denylisted images are images, defined by registry, repository, and tag/digest/imageId, that will always result in a policy policy evaluation status of fail. It is important to note that denylisting an image does not short-circuit the mapping evaluation or policy evaluations, so the full set of trigger matches will still be visible in the policy evaluation result.
Denylisted image matches override any allowlisted image matches (e.g. a tag matches a rule in both lists will always be blocklisted/fail).
Example image denylist section:
{
"name": "BlAocklistDebianUnstable",
"registry": "docker.io",
"repository": "library/debian",
"image": { "type": "tag", "value": "unstable" }
}
A complete policy example with all sections containing data:
{
"id": "default0",
"version": "2",
"name": "My Default policy",
"comment": "My system's default policy",
"allowlisted_images": [
{
"name": "AllowlistDebianStable",
"registry": "docker.io",
"repository": "library/debian",
"image": { "type": "tag", "value": "stable" }
}
],
"denylisted_images": [
{
"name": "DenylistDebianUnstable",
"registry": "docker.io",
"repository": "library/debian",
"image": { "type": "tag", "value": "unstable" }
}
],
"mappings": [
{
"name": "DockerHub",
"registry": "docker.io",
"repository": "library/postgres",
"image": { "type": "tag", "value": "latest" },
"rule_set_ids": [ "policy1", "policy2" ],
"allowlist_ids": [ "allowlist1", "allowlist2" ]
},
{
"name": "default",
"registry": "*",
"repository": "*",
"image": { "type": "tag", "value": "*" },
"rule_set_ids": [ "policy1" ],
"allowlist_ids": [ "allowlist1" ]
}
],
"allowlists": [
{
"id": "allowlist1",
"name": "Simple Allowlist",
"version": "2",
"items": [
{ "id": "item1", "gate": "vulnerabilities", "trigger": "package", "trigger_id": "CVE-10000+libssl" },
{ "id": "item2", "gate": "vulnerabilities", "trigger": "package", "trigger_id": "CVE-10001+*" }
]
},
{
"id": "allowlist2",
"name": "Simple Allowlist",
"version": "2",
"items": [
{ "id": "item1", "gate": "vulnerabilities", "trigger": "package", "trigger_id": "CVE-1111+*" }
]
}
],
"rule_sets": [
{
"name": "DefaultPolicy",
"version": "2",
"comment": "Policy for basic checks",
"id": "policy1",
"rules": [
{
"action": "STOP",
"gate": "vulnerabilities",
"trigger": "package",
"id": "rule1",
"params": [
{ "name": "package_type", "value": "all" },
{ "name": "severity_comparison", "value": ">=" },
{ "name": "severity", "value": "medium" }
]
}
]
},
{
"name": "DBPolicy",
"version": "1_0",
"comment": "Policy for basic checks on a db",
"id": "policy2",
"rules": [
{
"action": "STOP",
"gate": "vulnerabilities",
"trigger": "package",
"id": "rule1",
"params": [
{ "name": "package_type", "value": "all" },
{ "name": "severity_comparison", "value": ">=" },
{ "name": "severity", "value": "low" }
]
}
]
}
]
}
Policy Evaluation
A policy evaluation results in a status of pass or fail and that result based on the evaluation:
- The mapping section to determine which policies and allowlists to select for evaluation against the given image and tag
- The output of the policies’ triggers and applied allowlists.
- Denylisted images section
- Allowlisted images section
A pass status means the image evaluated against the policy and only go or warn actions resulted from the policy evaluation and allowlisted evaluations, or the image was allowlisted. A fail status means the image evaluated against the policy and at least one stop action resulted from the policy evaluation and allowlist evaluation, or the image was denylisted.
The flow chart for policy evaluation:
Next Steps
Read more about the Rule Sets component of a policy.
Last modified September 16, 2024