|
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 |
|---|---|---|
|
A file with Kubernetes workloads |
One |
|
One image reference |
One |
|
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 |
|
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.
wpgencannot see these files.
Use wpgen when:
-
The workload is not deployed yet, and you want to ship the policy with the application. See Draft policies from a workload file.
-
You want a third-party image to run in
monitormode from the first day, without a period in which it runs with no policy. See Draft a policy from one image. -
You do not control the cluster, or learning is disabled in it. See Kubewarden Runtime Enforcer Learning Mode Configuration.
-
You want a policy that a reviewer can rebuild and compare in CI.
The two methods also work together:
-
Draft a policy with
wpgen, apply it inmonitormode, 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 checkon each image update to find the paths that the new image does not have.wpgen checkworks 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:
-
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_URLtohttps://github.com/kubewarden/runtime-enforcer/releases/latest/downloadinstead. -
Make sure that the checksum of the binary is correct:
sha256sum --check wpgen-linux-amd64.sha256If you use macOS, run
shasum -a 256 --checkinstead ofsha256sum --check. -
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 -
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.
The output is a draft
|
A draft is not a safe policy. Do not apply a draft in 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 |
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:
-
Apply the policy in
monitormode. This is the default mode of the output. -
Look at the violation events and at the list of allowed executables.
-
Remove the executables that the workload does not need.
-
Switch the policy to
protectmode.
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:
-
file: a tar archive made bydocker saveorpodman save, an OCI archive, or an OCI layout directory. -
docker: the local Docker daemon. -
podman: the local Podman daemon. -
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/shpoints 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.
-
Apply the policy in
monitormode. Add theruntimeenforcer.kubewarden.io/policylabel to the workload, so that the workload is bound to the policy. -
Let the workload run for a period that covers its normal activity.
-
Look at the violation events. The agent exports them through the OpenTelemetry collector. See Monitor phase for details.
-
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> -
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> -
When the list is correct, switch the policy to
protectmode: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 protectsetsspec.modetoprotect. Use it only for a policy that you trimmed and tested inmonitormode. A draft that you did not test must not run inprotectmode. -
-o jsonwrites the policy as JSON instead of YAML.kubectl apply -faccepts 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.