1 - 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.
2 - Rule Sets
Overview
A rule set is a named set of rules, represented as a JSON object within a Policy. A rule set is made up of rules that define a specific check to perform and a resulting action.
A Rule Set is made up of:
- ID: a unique id for the rule set within the policy
- Name: a human readable name to give the policy (may contain spaces etc)
- A list of rules to define what to evaluate and the action to recommend on any matches for the rule
A simple example of a rule_set JSON object (found within a larger policy object):
{
"name": "DefaultPolicy",
"version": "2",
"comment": "Policy for basic checks",
"id": "policy1",
"rules": [
{
"action": "STOP",
"gate": "vulnerabilities",
"id": "rule1",
"params": [
{ "name": "package_type", "value": "all" },
{ "name": "severity_comparison", "value": ">=" },
{ "name": "severity", "value": "medium" }
],
"trigger": "package",
"recommendation": "Upgrade the 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.
Policy evaluation is the execution of all defined triggers in the rule set against the image analysis result and feed data and results in a set of output trigger matches, each of which contains the defined action from the rule definition. The final recommendation value for the policy evaluation is called the final action, and is computed from the set of output matches: stop, go, or warn.
Policy Rules
Rules define the behavior of the policy at evaluation time. Each rule defines:
- Gate - example: dockerfile
- Trigger - example: exposed_ports
- Parameters - parameters specific to the gate/trigger to customize its match behavior
- Action - the action to emit if a trigger evaluation finds a match. One of stop, go, warn. The only semantics of these values are in the aggregation behavior for the policy result.
Gates
A Gate is a logical grouping of trigger definitions and provides a broader context for the execution of triggers against image analysis data. You can think of gates as the “things to be checked”, while the triggers provide the “which check to run” context. Gates do not have parameters themselves, but namespace the set of triggers to ensure there are no name conflicts.
Examples of gates:
- vulnerabilities
- packages
- npms
- files
- …
For a complete listing see: Anchore Policy Checks
Triggers
Triggers define a specific condition to check within the context of a gate, optionally with one or more input parameters. A trigger is logically a piece of code that executes with the image analysis content and feed data as inputs and performs a specific check. A trigger emits matches for each instance of the condition for which it checks in the image. Thus, a single gate/trigger policy rule may result in many matches in final policy result, often with different match specifics (e.g. package names, cves, or filenames…).
Trigger parameters are passed as name, value pairs in the rule JSON:
{
"action": "WARN",
"parameters": [
{ "name": "param1", "value": "value1" },
{ "name": "param2", "value": "value2" },
{ "name": "paramN", "value": "valueN" }
],
"gate": "vulnerabilities",
"trigger": "packages",
}
For a complete listing of gates, triggers, and the parameters, see: Anchore Policy Gates
Policy Evaluation
- All rules in a selected rule_set are evaluated, no short-circuits
- Rules who’s triggers and parameters find a match in the image analysis data, will “fire” resulting in a record of the match and parameters. A trigger may fire many times during an evaluation (e.g. many cves found).
- Each firing of a trigger generates a trigger_id for that match
- Rules may be executed in any order, and are executed in isolation (e.g. conflicting rules are allowed, it’s up to the user to ensure that policies make sense)
A policy evaluation will always contain information about the policy and image that was evaluated as well as the Final Action. The evaluation can optionally include additional detail about the specific findings from each rule in the evaluated rule_set as well as suggested remediation steps.
Policy Evaluation Findings
When extra detail is requested as part of the policy evaluation, the following data is provided for each finding produced by the rules in the evaluated rule_set.
- trigger_id - An ID for the specific rule match that can be used to allowlist a finding
- gate - The name of the gate that generated this finding
- trigger - The name of the trigger within the Gate that generated this finding
- message - A human readable description of the finding
- action - One of go, warn, stop based on the action defined in the rule that generated this finding
- policy_id - The ID for the rule_set that this rule is a part of
- recommendation - An optional recommendation provided as part of the rule that generated this finding
- rule_id - The ID of the rule that generated this finding
- allowlisted - Indicates if this match was present in the applied allowlist
- allowlist_match - Only provided if allowlisted is true, contains a JSON object with details about a allowlist match (allowlist id, name and allowlist rule id)
- inherited_from_base - An optional field that indicates if this policy finding was present in a provided comparison image
Excerpt from a policy evaluation, showing just the policy evaluation output:
...json
"findings": [
{
"trigger_id": "CVE-2008-3134+imagemagick-6.q16",
"gate": "package",
"trigger": "vulnerabilities",
"message": "MEDIUM Vulnerability found in os package type (dpkg) - imagemagick-6.q16 (CVE-2008-3134 - https://security-tracker.debian.org/tracker/CVE-2008-3134)",
"action": "go",
"policy_id": "48e6f7d6-1765-11e8-b5f9-8b6f228548b6",
"recommendation": "Upgrade the package",
"rule_id": "rule1",
"allowlisted": false,
"allowlist_match": null,
"inherited_from_base": false
},
{
"trigger_id": "CVE-2008-3134+libmagickwand-6.q16-2",
"gate": "package",
"trigger": "vulnerabilities",
"message": "MEDIUM Vulnerability found in os package type (dpkg) - libmagickwand-6.q16-2 (CVE-2008-3134 - https://security-tracker.debian.org/tracker/CVE-2008-3134)",
"action": "go",
"policy_id": "48e6f7d6-1765-11e8-b5f9-8b6f228548b6",
"recommendation": "Upgrade the package",
"rule_id": "rule1",
"allowlisted": false,
"allowlist_match": null,
"inherited_from_base": false
}
]
Final Action
The final action of a policy evaluation is the policy’s recommendation based on the aggregation of all trigger evaluations defined in the policy and the resulting matches emitted.
The final action of a policy evaluation will be:
- stop - if there are any triggers that match with this action, the policy evaluation will result in an overall stop.
- warn - if there are any triggers that match with this action, and no triggers that match with stop, then the policy evaluation will result in warn.
- go - if there are no triggers that match with either stop or warn, then the policy evaluation is result is a go. go actions have no impact on the evaluation result, but are useful for recording the results of specific checks on an image in the audit trail of policy evaluations over time
The policy findings are one part of the broader policy evaluation which includes things like image allowlists and denylists and makes a final policy evaluation status determination based on the combination of several component executions. See policies for more information on that process.
Next Steps
Read more about the Mappings component of a policy.
