Policy

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 Working with Policies for more detail on manipulating and configuring policies using the system CLI.

Components of a Policy

A policy is a single JSON document, composed of several parts:

• Policies - 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:

1. The mapping section to determine which policies and allowlists to select for evaluation against the given image and tag
2. The output of the policies’ triggers and applied allowlists.
3. Denylisted images section
4. 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 Policies 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 Checks

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.

3 - Policy Mappings

Mappings in the policy are a set of rules, evaluated in order, that describe matches on an image, id, digest, or tag and the corresponding sets of policies and allowlists to apply to any image that matches the rule’s criteria.

Policies can contain one or more mapping rules that are used to determine which rule_sets and allowlists apply to a given image. They match images on the registry and repository, and finally be one of id, digest, or tag.

A mapping has:

• Registry - The registry url to match, including wildcards (e.g. ‘docker.io’, ‘quay.io’, ‘gcr.io’, ‘*’)
• Repository - The repository name to match, including wildcards (e.g. ’library/nginx’, ‘mydockerhubusername/myrepositoryname’, ’library/*’, ‘*’)
• Image - The way to select an image that matches the registry and repository filters
  • type: how to reference the image and the expected format of the ‘value’ property
    • “tag” - just the tag name itself (the part after the ‘:’ in a docker pull string: e.g. nginx:latest -> ’latest’ is the tag name)
    • “id” - the image id
    • “digest” - the image digest (e.g. sha256@abc123)
  • value: the value to match against, including wildcards

Note: Unlike other parts of the policy, Mappings are evaluated in order and will halt on the first matching rule. This is important to understand when combined with wildcard matches since it enables sophisticated matching behavior.

Examples

Example 1, all images match a single catch-all rule:

[
  {
    "registry": "*",
    "repository": "*",
    "image": { "type": "tag", "value": "*"},
    "rule_set_ids": ["defaultpolicy"],
    "allowlist_ids": ["defaultallowlist"]
  }
]

Example 2, all “official” images from DockerHub are evaluated against officialspolicy and officialsallowlist (made up names for this example), while all others from DockerHub will be evaluated against defaultpolicy and defaultallowlist , and private GCR images will be evaluated against gcrpolicy and gcrallowlist:

[
  {
    "registry": "docker.io",
    "repository": "library/*",
    "image": { "type": "tag", "value": "*"},
    "rule_set_ids": [ "officialspolicy"],
    "allowlist_ids": [ "officialsallowlist"]
  },
  {
    "registry": "gcr.io",
    "repository": "*",
    "image": { "type": "tag", "value": "*"},
    "rule_set_ids": [ "gcrpolicy"],
    "allowlist_ids": [ "gcrallowlist"]
  },
  {
    "registry": "*",
    "repository": "*",
    "image": { "type": "tag", "value": "*"},
    "rule_set_ids": [ "defaultpolicy"],
    "allowlist_ids": [ "defaultallowlist"]
  }
]

Example 3, all images from a unknown registry will be evaluated against defaultpolicy and defaultallowlist, and an internal registry’s images will be evaluated against a different set (internalpolicy and internalallowlist):

[
  {
    "registry": "myregistry.mydomain.com:5000",
    "repository": "*",
    "image": { "type": "tag", "value": "*"},
    "policy_ids": [ "internalpolicy"],
    "allowlist_ids": [ "internalallowlist"]
  },
  {
    "registry": "*",
    "repository": "*",
    "image": { "type": "tag", "value": "*"},
    "policy_ids": [ "defaultpolicy"],
    "allowlist_ids": [ "defaultallowlist"]
  }
]

Using Multiple Policies and Allowlists

The result of the evaluation of the mapping section of a policy is the list of rule sets and allowlists that will be used for actually evaluating the image. Because multiple rule sets and allowlists can be specified in each mapping rule, you can use granular rule sets and allowlists and then combined them in the mapping rules.

Examples of schemes to use for how to split-up policies include:

• Different policies for different types of checks such that each policy only uses one or two gates (e.g. vulnerabilities, packages, dockerfile)
• Different policies for web servers, another for database servers, another for logging infrastructure, etc.
• Different policies for different parts of the stack: os-packages vs. application packages

Next Steps

Read more about the allowlists component of a policy.

4 - Allowlists

Allowlists provide a mechanism within a policy to explicitly override a policy-rule match. An allowlist is a named set of exclusion rules that match trigger outputs.

Example allowlist:

{
  "id": "allowlist1",
  "name": "My First Allowlist",
  "comment": "A allowlist for my first try",
  "version": "2",
  "items": [
    {
      "gate": "vulnerabilities",
      "trigger_id": "CVE-2018-0737+*",
      "id": "rule1",
      "expires_on": "2019-12-30T12:00:00Z"
    }
  ]
}

The components:

• Gate: The gate to allowlist matches from (ensures trigger_ids are not matched in the wrong context)
• Trigger Id: The specific trigger result to match and allowlist. This id is gate/trigger specific as each trigger may have its own trigger_id format. We’ll use the most common for this example: the CVE trigger ids produced by the vulnerability->package gate-trigger. The trigger_id specified may include wildcards for partial matches.
• id: an identifier for the rule, must only be unique within the allowlist object itself
• Expires On: (optional) specifies when a particular allowlist item expires. This is an RFC3339 date-time string. If the rule matches, but is expired, the policy engine will NOT allowlist according to that match.

The allowlist is processed if it is specified in the mapping rule that was matched during policy evaluation and is applied to the results of the policy evaluation defined in that same mapping rule. If a allowlist item matches a specific policy trigger output, then the action for that output is set to go and the policy evaluation result notes that the trigger output was matched for a allowlist item by associating it with the allowlist id and item id of the match.

An example of a allowlisted match from a snippet of a policy evaluation result (See Policies for more information on the format of the policy evaluation result). This a single row entry from the result:

[
  {
    "trigger_id": "CVE-2018-0737+openssl",
    "gate": "package",
    "trigger": "vulnerabilities",
    "message": "MEDIUM Vulnerability found in os package type (dpkg) - openssl (fixed in: 1.0.1t-1+deb8u9) - (CVE-2018-0737 - https://security-tracker.debian.org/tracker/CVE-2018-0737)",
    "action": "go",
    "policy_id": "myfirstpolicy",
    "recommendation": "Upgrade the package",
    "rule_id": "rule1",
    "allowlisted": true,
    "allowlist_match": {
      "matched_rule_id": "rule1",
      "allowlist_id": "allowlist1",
      "allowlist_name": "My First Allowlist"
    },
    "inherited_from_base": false
  },
]

Note: Allowlist are evaluated only as far as necessary. Once a policy rule match has been allowlisted by one allowlist item, it will not be checked again for allowlist matches. But, allowlist items may be evaluated out-of-order for performance optimization, so if multiple allowlist items match the same finding any one of them may be the item that is actually matched against a given trigger_id.

Next Steps

Read more about the Anchore Policy Checks for a complete list of gates and triggers.

5 - Anchore Policy Checks

Introduction

In this document, we describe the current anchore gates (and related triggers/parameters) that are supported within anchore policy.

Gate: dockerfile

Checks against the content of a dockerfile if provided, or a guessed dockerfile based on docker layer history if the dockerfile is not provided.

Gate: files

Checks against files in the analyzed image including file content, file names, and filesystem attributes.

Gate: passwd_file

Content checks for /etc/passwd for things like usernames, group ids, shells, or full entries.

Gate: packages

Distro package checks

Gate: vulnerabilities

CVE/Vulnerability checks.

Gate: licenses

License checks against found software licenses in the container image

Gate: ruby_gems

Ruby Gem Checks

Gate: npms

NPM Checks

Gate: secret_scans

Checks for secrets and content found in the image using configured regexes found in the “secret_search” section of analyzer_config.yaml.

Gate: metadata

Checks against image metadata, such as size, OS, distro, architecture, etc.

Gate: always

Triggers that fire unconditionally if present in policy, useful for things like testing and deny-listing.

Gate: retrieved_files

Checks against content and/or presence of files retrieved at analysis time from an image

Gate: Malware

Gate: Tag Drift

Compares the SBOM from the evaluated image’s tag and the tag’s previous image, if found. Provides triggers to detect packages added, removed or modified.

Gate: Image Source Drift

Triggers for evaluating diffs of an image’s source repo sbom and the built image. Operates on the diffs defined by ‘contains’ relationships where the image is the ‘source’ and the source revisions that are the ’target’ for the relationship.

Gate: Ancestry

Checks the image ancestry against approved images.

Next Steps

Now that you have a good grasp on the core concepts and architecture, check out the Requirements section for running Anchore.