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.