|
This is unreleased documentation for Runtime Enforcer 0.11-dev. |
wpgen CLI Reference
This page lists all commands and flags of wpgen. wpgen drafts a
WorkloadPolicy from the executables found inside container images. It also
compares an existing policy with the images of a workload. It does not need a
cluster. For installation steps and common workflows, see
Draft policies from container images with wpgen.
This document contains the help content for the wpgen command-line program.
Command Overview:
wpgen
wpgen drafts a WorkloadPolicy from the executables found inside container images.
The output is a starting point, not a final policy. A container image often contains many executables that the workload never runs. Run the policy in monitor mode first, and prefer the learn phase of runtime-enforcer to build a policy from the real behavior of the workload.
wpgen only sees the file system of the image. It does not see files on volumes, files that the workload creates at runtime, or executables from a foreign root.
Colors are used only for the lines that matter: the check verdict, warnings, notices and errors. With --color=auto, the default, colors are on only when the output is a terminal. The NO_COLOR environment variable turns them off, and CLICOLOR_FORCE=1 turns them on. --color=always and --color=never win over both.
Options
--color string When to use colors: auto, always or never. auto follows NO_COLOR and CLICOLOR_FORCE (default "auto") -h, --help help for wpgen -v, --version version for wpgen
SEE ALSO
-
wpgen check- Compare a WorkloadPolicy with the images of a workload -
wpgen image- Draft a WorkloadPolicy from a single container image -
wpgen workload- Draft one WorkloadPolicy per workload of a manifest file
wpgen check
Compare a WorkloadPolicy with the images of a workload.
POLICY_FILE has one WorkloadPolicy or one WorkloadPolicyProposal. Use "-" to read from standard input. The images come from the one workload of the file given with --workload, or from --image.
For each container of the policy, wpgen lists the allowed paths that are not executables in the image, and counts the executables of the image that the policy does not allow. A learned policy usually does not allow most of the executables of the image, so this count is not a problem. Use --list-not-allowed to list them.
When an allowed path is a symbolic link in the image, wpgen shows its real path. The enforcer reports the real path, so the policy must allow it.
The exit code is 1 when at least one allowed path is not an executable in the image. This happens after an image update that removes a file. It also happens for a path on a volume or in a foreign root: keep these paths in the policy if the workload needs them.
The exit code is also 1 when a container of the workload has no rules in the policy, for example a new container. The enforcer does not protect such a container.
The report goes to standard output, as a table or as JSON. Other messages go to standard error. The last lines on standard error are the verdict. They also count the allowed paths that wpgen skipped, and the containers of the policy that it did not check.
Usage: wpgen check POLICY_FILE (--workload FILE | --image IMAGE) [flags]
Examples
# Compare a policy with the images of a Deployment wpgen check ./policy.yaml --workload ./deploy/nginx.yaml # Compare a policy with a single image wpgen check ./policy.yaml --image ghcr.io/example/api:2.3.0 --container-name api # Write the report as JSON, with the executables that the policy does not allow wpgen check ./policy.yaml --workload ./deploy/nginx.yaml -o json --list-not-allowed
Options
--container-name string Container of the policy that runs --image (default: the only container of the policy)
-h, --help help for check
--image string Image of one container of the policy
--image-src strings Image sources to try, in order. Valid values: containerd, daemon, dir, docker, docker-archive, file, oci-archive, oci-dir, oci-registry, podman, pull, registry, singularity (default [file,docker,podman,registry])
--include-libraries Count ELF shared libraries as executables. Programs load them, but do not run them
--include-unknown Count files that are neither ELF programs nor scripts as executables, for example data files with an execute bit
--list-not-allowed List the executables of the image that the policy does not allow, not only their number
-o, --output string Report format (table or json) (default "table")
--platform string Platform to select from a multi-platform image (default: linux/<host architecture>)
--workload string File with the workload that uses the policy ("-" for standard input)
Options inherited from parent commands
--color string When to use colors: auto, always or never. auto follows NO_COLOR and CLICOLOR_FORCE (default "auto")
SEE ALSO
-
wpgen- Draft WorkloadPolicy resources from container images
wpgen image
Draft a WorkloadPolicy from a single container image.
The policy has one container. wpgen treats the image as the main container of the pod. The policy allows the programs and the scripts of the image: the regular files that have an execute permission bit set, and that are ELF programs or start with "#!". wpgen skips the shared libraries, and the files that are neither programs nor scripts. Use --include-libraries and --include-unknown to keep them.
wpgen looks for the image in the sources given by --image-src, in order, and uses the first source that has it. A daemon source (docker, podman) pulls the image into the daemon when the daemon does not have it.
The policy goes to standard output. Messages go to standard error.
Usage: wpgen image IMAGE [flags]
Examples
# Draft a policy for the main container of a pod wpgen image docker.io/library/nginx:1.27 # Choose the container name, the policy name and the namespace wpgen image ghcr.io/example/api:2.3.0 --container-name api --name api --namespace prod # Always read the image from the registry wpgen image ghcr.io/example/api:2.3.0 --image-src registry
Options
--container-name string Name of the container in spec.rulesByContainer (default "main")
-h, --help help for image
--image-src strings Image sources to try, in order. Valid values: containerd, daemon, dir, docker, docker-archive, file, oci-archive, oci-dir, oci-registry, podman, pull, registry, singularity (default [file,docker,podman,registry])
--include-libraries Count ELF shared libraries as executables. Programs load them, but do not run them
--include-unknown Count files that are neither ELF programs nor scripts as executables, for example data files with an execute bit
--mode string Policy mode (monitor or protect) (default "monitor")
--name string Name of the policy (default: last path element of the image repository, or "todo" when wpgen cannot derive it)
--namespace string Namespace of the policy (default "default")
-o, --output string Output format (yaml or json) (default "yaml")
--platform string Platform to select from a multi-platform image (default: linux/<host architecture>)
--warn-threshold int Print a warning when a container allows more executables than this value (0 disables the warning) (default 50)
Options inherited from parent commands
--color string When to use colors: auto, always or never. auto follows NO_COLOR and CLICOLOR_FORCE (default "auto")
SEE ALSO
-
wpgen- Draft WorkloadPolicy resources from container images
wpgen workload
Draft one WorkloadPolicy per workload of a manifest file.
FILE has one or more YAML or JSON documents. Use "-" to read from standard input. wpgen reads these kinds: Deployment, ReplicaSet, DaemonSet, StatefulSet, Job and CronJob. It skips the other documents, and also bare pods, because the learn phase of runtime-enforcer does not cover them.
Each policy has one entry per container and init container. Each image is scanned once, also when more containers use it. As with wpgen image, the policy allows the programs and the scripts of the image, and skips the shared libraries and the other files, unless you use --include-libraries or --include-unknown.
The policy name is the value of the runtimeenforcer.kubewarden.io/policy label of the pod template. When the label is not there, the name is <short kind>-<workload name>, for example deploy-nginx, as for the WorkloadPolicyProposal that the learn phase creates. The policy has the namespace of the workload. When the workload has no namespace, the policy has none either, so that "kubectl apply -n" puts both in the same namespace.
The policies go to standard output. Messages go to standard error.
Usage: wpgen workload FILE [flags]
Examples
# Draft the policies of the workloads in a file wpgen workload ./deploy/nginx.yaml # Draft the policies of a Helm chart helm template my-release ./chart | wpgen workload -
Options
-h, --help help for workload
--image-src strings Image sources to try, in order. Valid values: containerd, daemon, dir, docker, docker-archive, file, oci-archive, oci-dir, oci-registry, podman, pull, registry, singularity (default [file,docker,podman,registry])
--include-libraries Count ELF shared libraries as executables. Programs load them, but do not run them
--include-unknown Count files that are neither ELF programs nor scripts as executables, for example data files with an execute bit
--mode string Policy mode (monitor or protect) (default "monitor")
-o, --output string Output format (yaml or json) (default "yaml")
--platform string Platform to select from a multi-platform image (default: linux/<host architecture>)
--warn-threshold int Print a warning when a container allows more executables than this value (0 disables the warning) (default 50)
Options inherited from parent commands
--color string When to use colors: auto, always or never. auto follows NO_COLOR and CLICOLOR_FORCE (default "auto")
SEE ALSO
-
wpgen- Draft WorkloadPolicy resources from container images