Container Pull Policies

Policies enable you to filter and restrict Chainguard artifact updates. You do this by defining policies that control and restrict versions that will be pulled from Chainguard.

Note: Policies is in beta. Contact your Chainguard account team to enable it for your organization.

Definitions

This is how policies uses the following terms.

• Policy — A reusable rule that determines whether an image is allowed. Each policy has a name, a description, and the resource types it applies to. Policies apply to registry repositories.
• Binding — A link between a policy and an organization. While a binding exists, the policy is active for image pulls under that organization. Without a binding, the policy has no effect.
• Mode — A binding’s mode controls what happens when the policy denies an image:
  • ENFORCE — Block the pull.
  • DRY_RUN — Allow the pull but record the violation.

The default mode for new bindings is DRY_RUN.

Usage

Policies are managed using chainctl. System policies are shipped with the platform.

See which policies are available to your organization:

chainctl policies list --parent=$ORGANIZATION

Inspect a policy to see its full definition and configurable parameters before enabling it:

chainctl policies describe --policy=$POLICY --parent=$ORGANIZATION

See which policies are currently active:

chainctl policies binding list --parent=$ORGANIZATION

Activate a policy in DRY_RUN mode. This example activates the “no end-of-life” artifacts policy. Chainguard recommends that you roll out policies using DRY_RUN mode first and track for a time to be certain it has the impact you intend before moving to ENFORCE.

chainctl policies enable --policy=no-eol --mode=DRY_RUN --parent=$ORGANIZATION

Some policies accept parameters. Use --param=KEY=VALUE to supply them:

chainctl policies enable --policy=cooldown --mode=DRY_RUN --param=days=7 --parent=$ORGANIZATION

Promote a policy to ENFORCE:

chainctl policies enable --policy=no-eol --mode=ENFORCE --parent=$ORGANIZATION

Check the results of specific policies on an image, including DRY_RUN policies which wouldn’t cause the registry to block a pull:

chainctl policies check cgr.dev/$ORGANIZATION/bash:latest

  POLICY  |  MODE   | RESULT
----------|---------|---------
 cooldown | DRY_RUN | DENIED
 no-eol   | DRY_RUN | ALLOWED

Disable a policy:

chainctl policies disable --policy=no-eol --parent=$ORGANIZATION

See chainctl policies --help or the chainctl reference pages for more information.