|
This is unreleased documentation for Runtime Enforcer 0.11-dev. |
Check a policy against its images
This page is for a reviewer who wants to know if a policy still matches the
images of its workload. A policy that was learned or drafted some months ago
can allow paths that an image update removed. wpgen check compares the
allowed paths of a policy with the executables of the images. It reports the
paths that are not in the image. It returns exit code 1 when it finds one,
or when a container of the workload has no rules in the policy. A CI job can
use the exit code to stop a pull request.
Before you start, install wpgen.
The examples use docker.io/library/caddy:2.9 and
docker.io/library/caddy:2.10. The output was recorded on 2026-10-30. A tag
can move to a new image, and then the counts and the paths change.
Find stale paths after an image update
A team drafted a policy for a Deployment that runs caddy:2.9, as
Draft policies from a workload file shows. The policy is in
policies.yaml. A pull request now bumps the image to caddy:2.10.
-
Run
wpgen checkwith the policy file and the updated workload file:wpgen check policies.yaml --workload caddy-deploy.yaml --image-src registry Loading image "docker.io/library/caddy:2.10"... Loaded image "docker.io/library/caddy:2.10" from source "registry" (linux/amd64) Loading image "docker.io/library/alpine:3.20"... Loaded image "docker.io/library/alpine:3.20" from source "registry" (linux/amd64) Policy deploy-caddy (namespace web) ┌───────────────────┬────────────────────────────────────────┬────────┬────────────────────────────────┐ │ CONTAINER │ PATH │ STATUS │ NOTE │ ├───────────────────┼────────────────────────────────────────┼────────┼────────────────────────────────┤ │ │ /usr/lib/libcap.so.2.70 │ stale │ not an executable in the image │ │ │ /usr/lib/libpsx.so.2.70 │ stale │ not an executable in the image │ │ │ /bin/busybox │ ok │ │ │ │ /etc/ca-certificates/update.d/certhash │ ok │ │ │ │ /etc/network/if-up.d/dad │ ok │ │ │ │ /sbin/apk │ ok │ │ │ │ /sbin/ldconfig │ ok │ │ │ │ /usr/bin/c_rehash │ ok │ │ │ │ /usr/bin/caddy │ ok │ │ │ │ /usr/bin/getconf │ ok │ │ │ caddy │ /usr/bin/getent │ ok │ │ │ │ /usr/bin/iconv │ ok │ │ │ │ /usr/bin/ldd │ ok │ │ │ │ /usr/bin/scanelf │ ok │ │ │ │ /usr/bin/ssl_client │ ok │ │ │ │ /usr/sbin/capsh │ ok │ │ │ │ /usr/sbin/getcap │ ok │ │ │ │ /usr/sbin/getpcaps │ ok │ │ │ │ /usr/sbin/setcap │ ok │ │ │ │ /usr/sbin/update-ca-certificates │ ok │ │ │ │ /usr/share/udhcpc/default.script │ ok │ │ ├───────────────────┼────────────────────────────────────────┼────────┼────────────────────────────────┤ │ │ /bin/busybox │ ok │ │ │ │ /etc/network/if-up.d/dad │ ok │ │ │ │ /sbin/apk │ ok │ │ │ │ /sbin/ldconfig │ ok │ │ │ │ /usr/bin/getconf │ ok │ │ │ fetch-site (init) │ /usr/bin/getent │ ok │ │ │ │ /usr/bin/iconv │ ok │ │ │ │ /usr/bin/ldd │ ok │ │ │ │ /usr/bin/scanelf │ ok │ │ │ │ /usr/bin/ssl_client │ ok │ │ │ │ /usr/share/udhcpc/default.script │ ok │ │ └───────────────────┴────────────────────────────────────────┴────────┴────────────────────────────────┘ ┌───────────────────┬───────────────────────────────┬─────────┬────┬───────┬─────────┬─────────────┐ │ CONTAINER │ IMAGE │ ALLOWED │ OK │ STALE │ SKIPPED │ NOT ALLOWED │ ├───────────────────┼───────────────────────────────┼─────────┼────┼───────┼─────────┼─────────────┤ │ caddy │ docker.io/library/caddy:2.10 │ 21 │ 19 │ 2 │ 0 │ 4 │ │ fetch-site (init) │ docker.io/library/alpine:3.20 │ 11 │ 11 │ 0 │ 0 │ 0 │ └───────────────────┴───────────────────────────────┴─────────┴────┴───────┴─────────┴─────────────┘ 2 allowed paths are not executables in the images: caddy: /usr/lib/libcap.so.2.70, /usr/lib/libpsx.so.2.70 -
Read the exit code:
echo $? 1
The report has two tables:
-
The first table has one row for each allowed path. The rows of each container start with the paths that need an action:
stalefirst, thenskipped, thenok. Here,caddy:2.10shipslibcap2.76 in place of 2.70, so the two paths with the old version in their name arestale. Remove them from the policy. -
The second table counts the paths of each status for each container. The
NOT ALLOWEDcolumn counts the executables of the image that the policy does not allow.caddy:2.10adds/usr/bin/curland/usr/bin/wcurl, and the two newlibcapfiles. For a learned policy, this number is usually high. This is not a problem. The policy blocks these executables in protect mode, which is the goal.
The last lines go to standard error. They are the verdict. They repeat the
stale paths, so that you see them in a CI log without the table. The verdict
also counts the allowed paths that wpgen skipped, and the containers of
the policy that it did not check.
The exit code is 1 because at least one path is stale. It is 0 in all
other cases. The init container fetch-site has no stale path, so it does
not change the exit code.
Containers of the policy and of the workload
The workload file must contain one workload. wpgen matches the containers
of the policy and of the workload by name:
-
A container of the workload without rules in the policy, for example a new container, makes the check fail. The agent does not protect this container. The verdict names it, and the exit code is
1. -
A container of the policy that is not in the workload is not checked. Its rules have no effect.
wpgenprints a notice, and the check does not fail.
If the policy and the workload have no container in common, wpgen stops
with an error. The next example shows a container without rules.
The STATUS column
The STATUS column has one of these values:
-
stale: the path is not an executable in the image. A path can be stale after an image update. It can also come from a volume or a foreign root. In that case, keep it in the policy. The agent needs it, even ifwpgencannot see it. -
skipped: the path is a shared library or an unknown file.wpgenskips these kinds, unless you use--include-librariesor--include-unknown. See Which files wpgen allows. A skipped path does not change the exit code. -
ok: the path is an executable in the image. -
not allowed: an executable of the image that the policy does not allow. The first table shows these rows only with--list-not-allowed. See Find the executables that the policy does not allow.
Find the executables that the policy does not allow
The second table counts the executables that the policy does not allow. To
see their paths, use --list-not-allowed. The rows appear after the ok
rows of each container.
After an image update, the list shows the executables that the new image
adds. For caddy:2.10, these are curl, wcurl, and the two new libcap
files:
wpgen check policies.yaml --workload caddy-deploy.yaml --image-src registry --list-not-allowed
...
│ │ /usr/share/udhcpc/default.script │ ok │ │
│ │ /usr/bin/curl │ not allowed │ │
│ │ /usr/bin/wcurl │ not allowed │ │
│ │ /usr/lib/libcap.so.2.76 │ not allowed │ │
│ │ /usr/lib/libpsx.so.2.76 │ not allowed │ │
...
Read the list with the workload in mind:
For a learned or trimmed policy, the list is long, because the policy allows
only what the workload runs. The two rows for libcap 2.76 replace the two
stale rows for libcap 2.70. If the workload needed the old files, the
new ones go into the policy.
Find symbolic links in a hand-written policy
The agent reports the path of the real file, never the path of a
symbolic link. A policy written by hand often allows a link. In an Alpine
image, /bin/sh is a link to /bin/busybox. Such an entry never matches.
This policy has a link and a path that does not exist in the image:
apiVersion: runtimeenforcer.kubewarden.io/v1alpha1
kind: WorkloadPolicy
metadata:
name: deploy-caddy
namespace: web
spec:
mode: protect
rulesByContainer:
caddy:
executables:
allowed:
- /bin/sh
- /usr/bin/caddy
- /usr/bin/caddy-reload.sh
- /usr/bin/ssl_client
The NOTE column shows the real path behind the link. The policy has no
rules for the init container fetch-site. wpgen prints a notice before
the report, and the verdict names the container:
wpgen check policy.yaml --workload caddy-deploy.yaml --image-src registry
The policy has no rules for container "fetch-site" of Deployment "caddy".
Loading image "docker.io/library/caddy:2.9"...
Loaded image "docker.io/library/caddy:2.9" from source "registry" (linux/amd64)
Policy deploy-caddy (namespace web)
┌───────────┬──────────────────────────┬────────┬────────────────────────────────────────────────────┐
│ CONTAINER │ PATH │ STATUS │ NOTE │
├───────────┼──────────────────────────┼────────┼────────────────────────────────────────────────────┤
│ │ /bin/sh │ stale │ symbolic link to /bin/busybox, the enforcer │
│ │ │ │ reports the target │
│ caddy │ /usr/bin/caddy-reload.sh │ stale │ not an executable in the image │
│ │ /usr/bin/caddy │ ok │ │
│ │ /usr/bin/ssl_client │ ok │ │
└───────────┴──────────────────────────┴────────┴────────────────────────────────────────────────────┘
┌───────────┬─────────────────────────────┬─────────┬────┬───────┬─────────┬─────────────┐
│ CONTAINER │ IMAGE │ ALLOWED │ OK │ STALE │ SKIPPED │ NOT ALLOWED │
├───────────┼─────────────────────────────┼─────────┼────┼───────┼─────────┼─────────────┤
│ caddy │ docker.io/library/caddy:2.9 │ 4 │ 2 │ 2 │ 0 │ 19 │
└───────────┴─────────────────────────────┴─────────┴────┴───────┴─────────┴─────────────┘
2 allowed paths are not executables in the images:
caddy: /bin/sh, /usr/bin/caddy-reload.sh
1 container of the workload has no rules in the policy, so the enforcer does not protect it:
fetch-site
Replace /bin/sh with /bin/busybox in the policy. Remove
/usr/bin/caddy-reload.sh, or keep it if a volume provides it. Then add an
entry for fetch-site to spec.rulesByContainer. Without it, the check
still fails, and the agent does not protect the init container.
Check a policy against one image
When there is no workload file, give the image with --image. If the policy
has more than one container, name the container with --container-name:
wpgen check policy.yaml --image docker.io/library/caddy:2.9 \
--container-name caddy --image-src registry
Loading image "docker.io/library/caddy:2.9"...
Loaded image "docker.io/library/caddy:2.9" from source "registry" (linux/amd64)
Policy deploy-caddy (namespace web)
┌───────────┬────────────────┬────────┬──────┐
│ CONTAINER │ PATH │ STATUS │ NOTE │
├───────────┼────────────────┼────────┼──────┤
│ caddy │ /bin/busybox │ ok │ │
│ │ /usr/bin/caddy │ ok │ │
└───────────┴────────────────┴────────┴──────┘
┌───────────┬─────────────────────────────┬─────────┬────┬───────┬─────────┬─────────────┐
│ CONTAINER │ IMAGE │ ALLOWED │ OK │ STALE │ SKIPPED │ NOT ALLOWED │
├───────────┼─────────────────────────────┼─────────┼────┼───────┼─────────┼─────────────┤
│ caddy │ docker.io/library/caddy:2.9 │ 2 │ 2 │ 0 │ 0 │ 19 │
└───────────┴─────────────────────────────┴─────────┴────┴───────┴─────────┴─────────────┘
No allowed path is stale.
This policy allows /bin/busybox and /usr/bin/caddy. Both are in the
image, so the exit code is 0. The verdict says only what wpgen checked.
When some allowed paths are skipped, or some containers of the policy are
not in the workload, the verdict counts them.
wpgen check also reads a WorkloadPolicyProposal. Use - as the policy
file to read from standard input, for example from kubectl get:
kubectl get workloadpolicy deploy-caddy -n web -o yaml | \
wpgen check - --workload caddy-deploy.yaml --image-src registry
Output options
wpgen check writes the report to standard output. The verdict and the
other messages go to standard error. The default format, -o table, is for
people. For a machine-readable report, use -o json. The
document has one entry for each container. This is the report of the image
bump above, with --list-not-allowed. The allowed and executables lists
are cut for this page:
wpgen check policies.yaml --workload caddy-deploy.yaml --image-src registry \
-o json --list-not-allowed 2>/dev/null
{
"policy": {
"name": "deploy-caddy",
"namespace": "web"
},
"containers": [
{
"name": "caddy",
"init": false,
"image": "docker.io/library/caddy:2.10",
"allowed": ["/bin/busybox", "/etc/ca-certificates/update.d/certhash", "..."],
"executables": ["/bin/busybox", "/etc/ca-certificates/update.d/certhash", "..."],
"stale": [
{"path": "/usr/lib/libcap.so.2.70"},
{"path": "/usr/lib/libpsx.so.2.70"}
],
"skipped": [],
"notAllowedCount": 4,
"notAllowed": [
"/usr/bin/curl",
"/usr/bin/wcurl",
"/usr/lib/libcap.so.2.76",
"/usr/lib/libpsx.so.2.76"
]
},
{
"name": "fetch-site",
"init": true,
"image": "docker.io/library/alpine:3.20",
"allowed": ["/bin/busybox", "/etc/network/if-up.d/dad", "..."],
"executables": ["/bin/busybox", "/etc/network/if-up.d/dad", "..."],
"stale": [],
"skipped": [],
"notAllowedCount": 0,
"notAllowed": []
}
],
"containersOnlyInPolicy": [],
"containersOnlyInWorkload": []
}
-
executablesare the allowed paths that are executables in the image. -
staleare the allowed paths that are not.linkTargetis set when the path is a symbolic link. -
skippedare the allowed paths that are shared libraries or unknown files, with theirkind. -
notAllowedis present only with--list-not-allowed.
The exit code is the same as with the table report. The messages on standard error are the same too. Redirect them, as in the example, when a tool reads the JSON.
Run the check in CI
A CI job that runs wpgen check on each pull request stops an image bump
that makes the policy stale. It also stops a change that adds a container
that the policy does not protect. Install wpgen in the job as
Installation describes. Use
--image-src registry, so that the job reads the image that the cluster
will pull. The job runs one command:
wpgen check deploy/policies.yaml --workload deploy/caddy.yaml \
--image-src registry -o json --list-not-allowed > wpgen-report.json
The job fails when the exit code is 1. Keep wpgen-report.json as a build
artifact, so that a reviewer can read the full report. The stale paths also
appear in the job log, because wpgen repeats them on standard error. If
the log shows colors, set CLICOLOR_FORCE=1 to color the verdict. See
Colors.
When the check fails, the author of the pull request has three options:
-
Remove the stale paths from the policy.
-
Keep a path that comes from a volume or a foreign root, and accept the failure for this run.
-
Add rules for a new container of the workload.