podman/docs/source/markdown/options/source-policy-file.md

####> This option file is used in: ####> podman build, farm build ####> If file is edited, make sure the changes ####> are applicable to all of those.

--source-policy-file=pathname

Specifies the path to a BuildKit-compatible source policy JSON file. When specified, source references (e.g., base images in FROM instructions) are evaluated against the policy rules before being used.

Source policies allow controlling which images can be used as base images and optionally converting image references (e.g., pinning tags to specific digests) without modifying Containerfiles. This is useful for enforcing organizational policies and ensuring build reproducibility.

The policy file is a JSON document containing an array of rules. Each rule has:

• action: The action to take when the rule matches. Valid actions are:
  • ALLOW: Explicitly allow the source (no transformation).
  • DENY: Block the source and fail the build.
  • CONVERT: Transform the source to a different reference specified in updates.
• selector: Specifies which sources the rule applies to.
  • identifier: The source identifier to match (e.g., docker-image://docker.io/library/alpine:latest).
  • matchType: How to match the identifier. Valid types are EXACT and WILDCARD (supports * and ? glob patterns). Defaults to WILDCARD if not specified.
• updates: For CONVERT actions, specifies the replacement identifier.

Rules are evaluated in order; the first matching rule wins. If no rule matches, the source is allowed by default.

Note: Source policy CONVERT rules are processed after --build-context substitutions but before any substitutions specified in containers-registries.conf(5). This provides multiple ways to override which base image is used for a particular stage, in order of precedence: --build-context, then source policy, then registries.conf.

Example policy file that pins alpine:latest to a specific digest:

{
  "rules": [
    {
      "action": "CONVERT",
      "selector": {
        "identifier": "docker-image://docker.io/library/alpine:latest"
      },
      "updates": {
        "identifier": "docker-image://docker.io/library/alpine@sha256:..."
      }
    }
  ]
}

Example policy file that denies all ubuntu images:

{
  "rules": [
    {
      "action": "DENY",
      "selector": {
        "identifier": "docker-image://docker.io/library/ubuntu:*",
        "matchType": "WILDCARD"
      }
    }
  ]
}