Policy Mappings

Introduction

The Mapping feature of the Policy Editor creates rules that define which policies and allowlists should be used to perform the policy evaluation of a source repository, SBOM, or container image based on various factors.

The policy editor lets you set up different rule-sets that will be used on different artifacts based on the use case. For example the policy applied to a web-facing service may have different security and operational best practices rules than a database backend service.

Each artifact type supported by policy has it’s own set of mapping rules. The mapping rules 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.

It is recommended that a final catch-all mapping exists for each artifact types to ensure that all artifacts are mapped to a policy. This catch-all mapping should specify wildcards in all the matching fields.

Each mapping can specify a list of rule-sets to be evaluated, as well as an optional list of allowlists to apply.

Image Mappings

An image mapping matches on the parts of a container pull string, Registry, Repository, and Tag.

More information about Image mappings can be found at Container Image Mapping.

Source Mappings

A source mapping matches on the base host url of the source code as well as the specific repository.

More information about Source mappings can be found at Source Repository Mapping.

SBOM Mappings

An SBOM mapping matches on the name and version of the SBOMs.

More information about SBOM mappings can be found at SBOM Mapping.

Mapping JSON Structure

Within a policy bundle, each entry in the mappings array is a JSON object of the following shape:

{
  "name": "DockerHub",
  "registry": "docker.io",
  "repository": "library/postgres",
  "image": { "type": "tag", "value": "latest" },
  "rule_set_ids": [ "policy1", "policy2" ],
  "allowlist_ids": [ "allowlist1", "allowlist2" ]
}

• name — human-readable label for the mapping.
• registry, repository — selection filters on the image source; wildcards (*) are supported.
• image — the tag, digest, or image ID to match. type is one of tag, digest, or id, and value is the matching string. Wildcards are supported in value.
• rule_set_ids — the rule sets in the same bundle that should be evaluated when this mapping matches. IDs reference entries in the bundle’s rule_sets array.
• allowlist_ids — the allowlists in the same bundle that should be applied to the evaluation. IDs reference entries in the bundle’s allowlists array.

A typical bundle ends with a catch-all mapping that uses wildcards for every selection field, ensuring every artifact gets mapped to at least one 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" ]
  }
]

Mappings are evaluated in order; the first match wins.