This is unreleased documentation for Runtime Enforcer 0.11-dev.

Draft policies from container images with wpgen

wpgen drafts a WorkloadPolicy from the executables found inside container images. It also compares an existing policy with the images of a workload. wpgen does not need a cluster. You can run it on a workstation or in a CI pipeline.

The output of wpgen is a draft, not a finished policy. You must review it and test it in monitor mode before you switch it to protect mode. See The output is a draft.

wpgen has three commands:

Command Input Output

wpgen workload

A file with Kubernetes workloads

One WorkloadPolicy per workload

wpgen image

One image reference

One WorkloadPolicy

wpgen check

A policy file and its images

A report and an exit code

This section has one page for each command:

For the full list of commands and flags, see wpgen CLI Reference.

The examples in this section use docker.io/library/alpine:3.20, docker.io/library/caddy:2.9, and docker.io/library/nginx:1.27. The output was recorded on 2026-11-02. A tag can move to a new image, and then the counts and the paths change.

wpgen or the learn phase

Runtime Enforcer has two ways to build a WorkloadPolicy. The learn phase records the executables that a workload runs in a cluster. wpgen lists the executables that an image contains, without a cluster. The two methods differ in where the information comes from, and in what they can see.

Learn phase wpgen

Needs a cluster

Yes. Runtime Enforcer must run, and learning must be enabled for the namespace.

No. It runs on a workstation or in a CI pipeline.

When you can run it

After the workload is deployed.

Before the workload exists, for example on each pull request.

What it records

The executables that the workload ran while the agent watched it.

Every program and script in the image.

Size of the policy

Small. It is close to the minimum that the workload needs.

Large. You must trim it.

Sees files on volumes, files installed at runtime, and foreign roots

Yes. The agent sees every path that the kernel runs.

No. It sees only the file system of the image. See What wpgen does not see.

Sees code paths that did not run during the learn period

No. A task that runs once a month is missed if the learn period is shorter.

Yes, if the file is in the image.

Result

A proposal that you promote to a WorkloadPolicy.

A WorkloadPolicy file that you apply.

Repeatable

Partly. The result depends on what the workload did during the learn period.

Yes. The same image gives the same policy.

Use the learn phase when:

  • The workload already runs in a cluster, and you can restart it with learning enabled.

  • You want the smallest policy with the least work.

  • The workload runs executables from a volume, or installs packages when it starts. wpgen cannot see these files.

Use wpgen when:

The two methods also work together:

  • Draft a policy with wpgen, apply it in monitor mode, and trim it. This gives a policy as small as a learned one, and the workload is never without a policy. Trim the policy describes the steps.

  • Learn a policy in the cluster, then run wpgen check on each image update to find the paths that the new image does not have. wpgen check works on a learned policy and on a drafted policy. See Check a policy against its images.

The learn phase has limits that can affect the choice. It records only the exec events that occur after the agent starts. A proposal stops at 100 executables. A pod of a standalone ReplicaSet is learned as a plain Pod. See Known limitations for details.

Installation

Download a pre-built binary

Pre-built binaries for linux/amd64, linux/arm64, darwin/amd64, and darwin/arm64 are published on each GitHub Release. Next to each binary, the release has a .sha256 file with its checksum.

To install the binary for linux/amd64:

  1. Download the binary and its checksum file:

    VERSION=v0.10.1
    BASE_URL="https://github.com/kubewarden/runtime-enforcer/releases/download/$VERSION"
    curl -fLO "$BASE_URL/wpgen-linux-amd64"
    curl -fLO "$BASE_URL/wpgen-linux-amd64.sha256"

    To get the latest release, set BASE_URL to https://github.com/kubewarden/runtime-enforcer/releases/latest/download instead.

  2. Make sure that the checksum of the binary is correct:

    sha256sum --check wpgen-linux-amd64.sha256

    If you use macOS, run shasum -a 256 --check instead of sha256sum --check.

  3. Make sure that the release workflow of the repository built the binary. The checksum shows only that the file matches what the release page lists. This step needs the GitHub CLI:

    gh attestation verify wpgen-linux-amd64 --repo kubewarden/runtime-enforcer
  4. Install the binary with the name wpgen:

    sudo install -m 0755 wpgen-linux-amd64 /usr/local/bin/wpgen

For another platform, replace linux-amd64 with linux-arm64, darwin-amd64, or darwin-arm64 in all the commands.

Build from source

From the root of the Runtime Enforcer repository:

# Current platform
make wpgen          # output: bin/wpgen
# All supported platforms at once
make wpgen-cross    # output: bin/wpgen-dist/wpgen-<os>-<arch>

Verify

wpgen --version
wpgen --help

The output is a draft

A draft is not a safe policy. Do not apply a draft in protect mode.

The draft allows every executable of the image. The workload needs only a few of them, so the draft blocks almost nothing. The draft also misses the executables that are not in the image: files on volumes, files that the workload creates at run time, and executables from a foreign root. In protect mode, the agent blocks these executables, and the workload can fail.

A container image often contains many executables that the workload never runs. A policy that allows all of them gives little protection. For example, a policy for a Debian or Ubuntu base image allows several hundred executables.

The policy is correct only after you trim it and test it:

  1. Apply the policy in monitor mode. This is the default mode of the output.

  2. Look at the violation events and at the list of allowed executables.

  3. Remove the executables that the workload does not need.

  4. Switch the policy to protect mode.

Trim the policy describes these steps in detail.

How wpgen reads an image

This section explains where wpgen gets an image, which files of the image it puts in the policy, and which files it cannot see.

Where wpgen finds the images

wpgen looks for an image in a list of sources, in order. It uses the first source that has the image. The default order is:

  1. file: a tar archive made by docker save or podman save, an OCI archive, or an OCI layout directory.

  2. docker: the local Docker daemon.

  3. podman: the local Podman daemon.

  4. registry: the remote registry of the image reference.

A daemon source pulls the image into the daemon when the daemon does not have it. To read the image directly from the registry, use --image-src registry. This is useful in CI, where a local image can be out of date. The examples in this section use this flag, so that they give the same result on every machine.

A multi-platform image has one image per platform. wpgen selects linux with the architecture of the host. To select another platform, use --platform, for example --platform linux/arm64. The set of executables can differ between platforms. If the image does not have the selected platform, wpgen stops with an error. This is true for every image source, local archives included:

wpgen image docker.io/library/caddy:2.9 --platform linux/mips64le --image-src registry
Loading image "docker.io/library/caddy:2.9"...
Error: cannot load image "docker.io/library/caddy:2.9": registry: unable to detect input for 'docker.io/library/caddy:2.9', errs: failed to get image from registry: no child with platform linux/mips64le in index docker.io/library/caddy:2.9

Which files wpgen allows

The eBPF program of the agent records the path of each executable as the kernel sees it. wpgen produces the same paths:

  • It allows each regular file that has an execute permission bit set.

  • It allows each hard link to such a file.

  • It skips symbolic links. The kernel resolves a symbolic link before the agent sees the path. For example, in an Alpine image /bin/sh points to /bin/busybox, and the agent reports /bin/busybox.

A file with an execute bit is not always a program. wpgen reads each file and decides what kind of file it is:

  • A program: an ELF executable, linked dynamically or statically.

  • A script: a file that starts with #!.

  • A shared library: an ELF library, for example /lib/libz.so.1. Programs load libraries, but do not run them.

  • An unknown file: any other file, for example a certificate file with mode 0755.

By default, a policy allows only programs and scripts. The summary of each container shows how many files wpgen skipped. For alpine:3.20, half of the files with an execute bit are libraries:

wpgen image docker.io/library/alpine:3.20 --image-src registry > policy.yaml
Loading image "docker.io/library/alpine:3.20"...
Loaded image "docker.io/library/alpine:3.20" from source "registry" (linux/amd64)

┌───────────┬───────────────────────────────┬─────────────┬───────────────────┬───────────────┐
│ CONTAINER │ IMAGE                         │ EXECUTABLES │ SKIPPED LIBRARIES │ SKIPPED OTHER │
├───────────┼───────────────────────────────┼─────────────┼───────────────────┼───────────────┤
│ main      │ docker.io/library/alpine:3.20 │          11 │                10 │             0 │
└───────────┴───────────────────────────────┴─────────────┴───────────────────┴───────────────┘
Use --include-libraries to keep the skipped shared libraries.

Add this label to the pod template of the workload that runs this image:
  runtimeenforcer.kubewarden.io/policy: alpine
Make sure that the container is named "main" in the pod, or use --container-name.

To keep the skipped files, use --include-libraries or --include-unknown. With --include-libraries, the policy for alpine:3.20 grows from 11 to 21 paths, and includes files such as /lib/ld-musl-x86_64.so.1 and /lib/libssl.so.3. You need these flags in two rare cases:

  • The workload starts the dynamic loader directly, for example /lib64/ld-linux-x86-64.so.2 ./binary. A normal program does not need the loader in its policy. The kernel starts the loader without an exec event of its own.

  • The workload starts a script without a #! line directly from a shell. The agent checks the path of the script before the shell runs it, so the policy must allow the script.

In monitor mode, the agent reports these cases as violations.

What wpgen does not see

wpgen only sees the file system of the image. It does not see:

  • Files on volumes that the pod mounts over a path of the image.

  • Files that the workload creates at runtime, for example a package that a start script installs.

  • Executables from a foreign root.

In monitor mode, the agent reports these executables as violations. Add them to the policy by hand, or with the kubectl plugin command policy allow.

Large base images

wpgen image and wpgen workload print a warning when a container allows more than 50 executables. The nginx:1.27 image is based on Debian, and it allows 504:

wpgen image docker.io/library/nginx:1.27 --image-src registry > policy.yaml
Loading image "docker.io/library/nginx:1.27"...
Loaded image "docker.io/library/nginx:1.27" from source "registry" (linux/amd64)

┌───────────┬──────────────────────────────┬─────────────┬───────────────────┬───────────────┐
│ CONTAINER │ IMAGE                        │ EXECUTABLES │ SKIPPED LIBRARIES │ SKIPPED OTHER │
├───────────┼──────────────────────────────┼─────────────┼───────────────────┼───────────────┤
│ main      │ docker.io/library/nginx:1.27 │         504 │                 2 │             0 │
└───────────┴──────────────────────────────┴─────────────┴───────────────────┴───────────────┘
Use --include-libraries to keep the skipped shared libraries.

WARNING: container main allows 504 executables. A learned policy is usually
much smaller. Review the list before you switch the policy to protect mode.

Add this label to the pod template of the workload that runs this image:
  runtimeenforcer.kubewarden.io/policy: nginx
Make sure that the container is named "main" in the pod, or use --container-name.

A policy with 504 allowed executables blocks almost nothing. Keep the policy in monitor mode. Then trim it as the next section describes. To change the limit of the warning, use --warn-threshold. The value 0 disables it.

Trim the policy

A draft allows every program and script of the image. A container usually runs a few of them. For example, the policy for caddy:2.9 allows 21 executables, and the container runs one program, /usr/bin/caddy. The other 20 paths come from the Alpine base image. In monitor mode, the agent reports the executables that the policy does not allow, but it does not block them.

  1. Apply the policy in monitor mode. Add the runtimeenforcer.kubewarden.io/policy label to the workload, so that the workload is bound to the policy.

  2. Let the workload run for a period that covers its normal activity.

  3. Look at the violation events. The agent exports them through the OpenTelemetry collector. See Monitor phase for details.

  4. Remove the paths that the workload does not need. The kubectl plugin does this for you:

    kubectl runtime-enforcer policy deny <POLICY> <container> <executable-path> [<executable-path>...] -n <namespace>
  5. If a violation shows a path that the workload needs, add it:

    kubectl runtime-enforcer policy allow <POLICY> <container> <executable-path> [<executable-path>...] -n <namespace>
  6. When the list is correct, switch the policy to protect mode:

    kubectl runtime-enforcer policy protect <POLICY> -n <namespace>

See kubectl runtime-enforcer for the other commands of the plugin.

Output options

wpgen image and wpgen workload write the policy to standard output. Messages go to standard error. These flags change the output:

  • --mode protect sets spec.mode to protect. Use it only for a policy that you trimmed and tested in monitor mode. A draft that you did not test must not run in protect mode.

  • -o json writes the policy as JSON instead of YAML. kubectl apply -f accepts both formats.

When wpgen workload writes more than one policy, a --- line divides them in YAML. In JSON, the objects follow each other. kubectl apply -f accepts both.

To apply a draft without a file, pipe it into kubectl. The messages do not reach kubectl, because they go to standard error:

wpgen image docker.io/library/caddy:2.9 \
  --container-name caddy --name caddy --namespace web \
  --image-src registry | kubectl apply -f -

Use wpgen in CI

The exit codes and the color rules matter when a pipeline runs wpgen.

Exit codes

All the commands return 0 on success and 1 on an error. wpgen check also returns 1 when the policy is stale, as Check a policy against its images describes. When you stop wpgen with Ctrl-C, or with the SIGTERM signal, it prints Interrupted and returns 130.

Colors

wpgen uses colors only for the lines that you must not miss: the verdict of check, the WARNING: word, the notices about containers that are only in the policy or only in the workload, and errors. The tables have no colors.

By default, wpgen uses colors only when the output is a terminal. To turn them off, set the NO_COLOR environment variable, or use --color=never. To force them, for example in a CI log that shows colors, use --color=always or set CLICOLOR_FORCE=1. The --color flag wins over both variables.