The check runs docker inspect across the running containers with the template {{if or (not .HostConfig.PidsLimit) (le .HostConfig.PidsLimit 0)}}{{.Name}} {{end}}, so it reads a single field: .HostConfig.PidsLimit, the per-container cap set by --pids-limit. A field that is missing, null or ≤ 0 counts as unlimited, -1 being Docker's explicit unlimited, and puts that container's name on the list; any positive value passes whatever its size. An empty list is the PASS, and otherwise the WARN reports how many of the running containers are uncapped and names up to five.
Needs a reachable daemon and at least one running container; otherwise SKIP. It tests .HostConfig.PidsLimit per running container and treats missing, null or a value ≤ 0 as unlimited (-1 is Docker's explicit "unlimited"). Any positive value passes, regardless of size - the check does not assess whether the cap is appropriate. Only the container's own setting counts: a systemd TasksMax on docker.service or an nproc ulimit caps something else and leaves the container reported as unlimited.
| Result | When | What it means |
|---|---|---|
| SKIP | No running containers | Nothing was verified. No process cap was read anywhere, so the check did not confirm that a single container is protected. |
| PASS | Every container caps PIDs | Every running container has a positive --pids-limit, though the check never judges whether the number is high or low. |
| WARN | Some do not | The named containers can fork without limit, so one runaway process inside them can exhaust the host process table. |
A fork bomb inside a container exhausts the host PID table (default kernel.pid_max 32768 or 4194304) and prevents even root from spawning a shell to fix it. The pids cgroup controller caps it per container. CIS Docker 5.28 "Ensure that the PIDs cgroup limit is used"; OWASP Docker Cheat Sheet Rule #7.
- Docker sets no PID limit unless you ask for one. Some distros' systemd
TasksMaxondocker.servicelimits the daemon's own total but not each container. - An
nproculimit (--ulimit nproc=...) is a per-user limit, not a per-container one, and does not satisfy this check. - Value
0in older API versions meant "unlimited";-1is the explicit unlimited today; both are treated as unlimited. - Java/Go apps with many threads need generous limits (threads count as PIDs): measure
docker toporcat /sys/fs/cgroup/pids.current.
Measure the real process count
Threads count against the limit, so read the cgroup's own counter under normal load rather than counting processes:
sh docker exec <name> cat /sys/fs/cgroup/pids.currentA typical web server runs 10 to 30, a PHP-FPM pool 50 to 100, and JVM or Node services with large thread pools several hundred.
Set a positive limit
Two to three times the measured count leaves room for spikes while still stopping a fork loop.
sh docker run --pids-limit 256 ...In Compose:
yaml services: app: pids_limit: 256Apply it
Recreate the container, or change a running one in place. Keep the Compose file in step, or the next recreate removes the cap.
sh docker compose up -d --force-recreate# or, in place:docker update --pids-limit 256 <name>Confirm the cap
sh docker exec <name> cat /sys/fs/cgroup/pids.maxIt should print your number, not
max.
docker inspect -f '{{.Name}} pids={{.HostConfig.PidsLimit}}' $(docker ps -q)# expected: a positive number for every container# The cgroup's view, and current usage:docker exec <name> sh -c 'cat /sys/fs/cgroup/pids.max; cat /sys/fs/cgroup/pids.current'# expected: a number rather than "max", with current well below it# Prove a cap holds, on a throwaway container rather than a production one:docker run --rm --pids-limit 20 alpine sh -c 'for i in $(seq 50); do sleep 5 & done; wait' 2>&1 | head -3# expected: "can't fork" errors once the 20th process is reached- This one message covers two different cases: the audit could not reach the Docker daemon, or it reached it and nothing was running. Run
docker psas the audit user, thensudo docker ps. If both fail, the daemon is unreachable: checksystemctl status docker, then run the audit as root or give the account sudo. If they work but list nothing, there is genuinely nothing to evaluate, and a stopped container is never checked. The Docker Inventory check reports the two cases separately, so its result tells you which one you hit. - Expected: the check reads only each container's own
PidsLimit.TasksMaxlimits the Docker service as a whole, andnprocapplies per user ID, so neither stops one container filling the process table for the others. Set--pids-limit(Composepids_limit:) on each container. - Truncated with
head -5; the count is complete. Full list:docker inspect -f '{{if or (not .HostConfig.PidsLimit) (le .HostConfig.PidsLimit 0)}}{{.Name}}{{end}}' $(docker ps -q). - The cap is too low for its thread count. Size it from
pids.currentunder load; JVM and Node applications with large thread pools routinely need several hundred. 512 or 1024 is a common starting point. - The limit may be far larger than needed, or the culprit ran outside a container. Compare each container's
pids.maxagainst real usage, and check the host-wide ceiling withsysctl kernel.pid_max.
