Seccomp and AppArmor — restricting what a container can do · Docker & Containers

Capabilities narrow what a container can do at the kernel-authority level. Seccomp narrows it further by restricting which syscalls a process can make. AppArmor and SELinux go further still, applying mandatory access control to file, capability, and network operations.

Seccomp

Seccomp (secure computing mode) is a Linux kernel feature that filters syscalls. A seccomp profile is an allowlist of syscalls plus a default action for everything not on it.

Docker applies a default seccomp profile whose allowlist names over 400 syscalls; everything else is denied. The denied ones are those that have caused real-world container escapes: unshare and clone with namespace flags, bpf, keyctl, add_key, perf_event_open, mount and umount2, pivot_root, setns, kexec_load, and the kernel-module family.

How seccomp actually works, and what Docker's default action really is

When a process makes a syscall, the kernel’s seccomp filter runs before the syscall handler. The filter is a BPF program that inspects the syscall number and arguments and returns one of:

SECCOMP_RET_ALLOW — let the syscall proceed.
SECCOMP_RET_ERRNO — do not run the syscall; return the configured errno to the caller.
SECCOMP_RET_KILL_PROCESS — kill the whole process.
SECCOMP_RET_KILL_THREAD — kill only the offending thread.
SECCOMP_RET_TRAP — send SIGSYS (handler can recover).
SECCOMP_RET_LOG — allow, but log the call.
SECCOMP_RET_TRACE — hand the syscall to a tracer.

Docker’s default profile does not kill anything. Its defaultAction is SCMP_ACT_ERRNO with defaultErrnoRet set to 1, which is EPERM. A container that makes a denied syscall does not die; the syscall returns -1 with errno set to EPERM and the application carries on with whatever its own error handling does next.

That distinction is the entire operational story of this lesson, because a process that dies leaves an exit code and a dmesg line, and a process that gets EPERM leaves an application-level error message that points somewhere else entirely.

A few entries in the profile override the default errno on purpose. clone3 is denied with ENOSYS rather than EPERM, because glibc 2.34 and later probe for clone3 and fall back to clone when the kernel reports “not implemented” — but interpret EPERM as a real failure and abort. That single choice is why containers built on newer glibc run at all on hosts with an older profile.

A seccomp denial arrives as EPERM from a syscall nobody was thinking about

The workload is a backup sidecar that mounts a FUSE filesystem, or a Kerberos client, or a profiler. It has run for months. Someone upgrades the base image and it starts failing:

mount: /mnt/remote: permission denied.

The first diagnosis is always filesystem permissions, because that is what “permission denied” means everywhere else in Unix. So the directory gets chmod 777, then the container gets USER root, then the volume gets :z for SELinux, then someone bind-mounts the parent directory instead. None of it helps, because the file permissions were never consulted — the mount(2) syscall never reached the kernel’s mount code at all. Seccomp returned EPERM before it got there.

Why it hides so well. EPERM from a denied syscall is indistinguishable, at the application layer, from EPERM for a genuine permission problem. strace shows mount(...) = -1 EPERM, which reads exactly like a real denial. There is no log line: the default profile uses SCMP_ACT_ERRNO, not SCMP_ACT_LOG, so the kernel records nothing.

How to tell in one step. Re-run the identical command with the filter removed. If it succeeds with --security-opt seccomp=unconfined and fails without it, the profile is the cause and no permission change will ever fix it. This is a diagnostic, not a fix: put the filter back and add the one syscall you need to a derived profile.

Read-only / Safebisect a denial: is it seccomp or is it permissions?— Run the failing command twice, once under the default profile and once unconfined. Two different results identify seccomp; two identical failures rule it out and send you back to file permissions.

IMAGE=debian:bookworm-slim
docker run --rm "$IMAGE" sh -c 'unshare --user --map-root-user true; echo "default profile: exit $?"'
docker run --rm --security-opt seccomp=unconfined "$IMAGE" \
  sh -c 'unshare --user --map-root-user true; echo "unconfined:      exit $?"'

unshare: unshare failed: Operation not permitted
default profile: exit 1
unconfined:      exit 0

Illustrative output

Two different exit codes for the same command is the signature. If both runs fail identically, seccomp is not involved and you are back to ownership, mode bits, or an LSM.

Read-only / Safeconfirm which profile a container is actually running under— SeccompProfile is empty when the container uses the built-in default. 'unconfined' means the filter is off, and a path means someone supplied a custom profile.

CONTAINER=web
docker inspect --format '{{.HostConfig.SecurityOpt}}' "$CONTAINER"
docker exec "$CONTAINER" grep Seccomp /proc/1/status

[]
Seccomp:	2
Seccomp_filters:	1

Illustrative output

Seccomp: 2 in /proc/<pid>/status means filter mode is active. Seccomp: 0 means the process has no filter at all — which, in a container, means somebody set seccomp=unconfined and probably did not write it down.

Custom seccomp profiles

Configuration changeapply custom seccomp— Apply a custom seccomp profile to a container. The profile must be valid JSON.

docker run --security-opt seccomp=./seccomp.json nginx

Read-only / Safeinspect the default profile— The profile lives in the moby/profiles repository. Read the default action first — it is the field that decides whether a denial kills the container or merely fails one call.

URL=https://raw.githubusercontent.com/moby/profiles/main/seccomp/default.json
curl -fsS "$URL" \
  | jq '{defaultAction, defaultErrnoRet, groups: (.syscalls | length), allowed: ([.syscalls[].names[]] | length)}'

{
"defaultAction": "SCMP_ACT_ERRNO",
"defaultErrnoRet": 1,
"groups": 33,
"allowed": 442
}

defaultErrnoRet: 1 is EPERM. Read that output again before you write a custom profile: whatever you deny, the container will keep running and the failure will surface inside the application.

Read-only / Safefind the syscalls with a non-default errno— A handful of entries deliberately return something other than EPERM. Knowing which ones explains behaviour that otherwise looks like a bug.

URL=https://raw.githubusercontent.com/moby/profiles/main/seccomp/default.json
curl -fsS "$URL" \
  | jq -r '.syscalls[] | select(.action != "SCMP_ACT_ALLOW") | "\(.action) errno=\(.errnoRet) \(.names | join(","))"'

SCMP_ACT_ERRNO errno=38 clone3

Errno 38 is ENOSYS. clone3 is the one syscall the profile lies about on purpose, so that glibc’s runtime probe concludes “this kernel is too old” and takes its clone fallback path instead of treating the denial as fatal.

Custom profiles are most commonly used to:

Tighten the default profile (remove syscalls your workload does not use).
Loosen the default profile (re-enable a syscall the workload needs but Docker blocks).
Comply with a specific security baseline (CIS Docker Benchmark, PSP, etc.).

The cost of a custom profile is operational, and it is deferred. When the workload upgrades to a library version that reaches for a syscall you did not allow, the profile has to be updated — but the bill does not arrive as a crash at deploy time. It arrives as EPERM on some code path that only runs during a failover, a backup, or a certificate rotation, weeks later, to whoever is on call. Every custom profile you own is a promise to re-test it on every dependency bump.

AppArmor

AppArmor is a Linux Security Module (LSM) that confines programs to a set of file, capability, and network permissions. It is path- based (Ubuntu’s preferred LSM) and ships with templates for many applications.

Docker applies a default AppArmor profile named docker-default. To use a custom profile:

Configuration changecustom apparmor— Apply a custom AppArmor profile to a container. The profile must be loaded into the kernel first.

sudo apparmor_parser -r /etc/apparmor.d/docker-custom
docker run --security-opt apparmor=docker-custom nginx

AppArmor profiles are especially useful for:

Filesystem containment (deny writes to /proc, /sys outside expected paths).
Network containment (deny outbound except to specific peers).
Capability containment (override the capability set with capability rules).

Finding an AppArmor denial, and why `dmesg` lies about how many there were

An AppArmor denial produces a kernel audit record, not an application-visible error. The application sees EACCES or EPERM; the reason lives in the audit stream. Where that stream goes depends on whether auditd is running, and the two cases look completely different:

No auditd. Records go to the kernel ring buffer and are readable with dmesg. The ring buffer is rate-limited: under a burst the kernel prints audit: N callbacks suppressed and drops the rest. So a tight retry loop that trips one denial per request shows a handful of lines in dmesg and hides thousands. Counting denials in dmesg and concluding “it only happened twice” is a wrong conclusion drawn from a correct command.
auditd running. The kernel hands records to the daemon instead, and they stop appearing in dmesg altogether. dmesg goes silent, which reads exactly like “no denials” — but the records are in /var/log/audit/audit.log.

Check both, and always check whether auditd is running before you trust an empty result from either.

Read-only / Safefind AppArmor denials for a container— Establish where the audit stream is going first, then read it. An empty dmesg with auditd active tells you nothing.

systemctl is-active auditd || echo 'auditd not running: denials go to dmesg'
dmesg | grep -E 'apparmor=("DENIED"|"AUDIT")|callbacks suppressed' | tail -20
sudo ausearch -m AVC -ts recent 2>/dev/null | tail -20

inactive
[172834.119284] audit: type=1400 audit(1754899201.882:412): apparmor="DENIED" operation="mount" class="mount" profile="docker-default" name="/mnt/remote/" pid=48821 comm="mount" fstype="fuse.sshfs"
[172834.119401] audit: 37 callbacks suppressed

Illustrative output

The callbacks suppressed line is the important one. It is the kernel telling you the count you just read is not the count that happened.

Read-only / Safeconfirm which AppArmor profile a container is confined by— An empty AppArmorProfile means the container is unconfined — either AppArmor is not enabled on the host, or someone passed apparmor=unconfined.

CONTAINER=web
docker inspect --format '{{.AppArmorProfile}}' "$CONTAINER"
docker exec "$CONTAINER" cat /proc/1/attr/current 2>/dev/null || echo 'no AppArmor label'
aa-status --profiled 2>/dev/null || sudo aa-status | head -5

docker-default
docker-default (enforce)

Illustrative output

docker-default (enforce) is the working state. (complain) means the profile logs but does not block — useful while developing a profile, and a silent hole if it reaches production by accident.

SELinux

SELinux is the other major LSM. It is label-based (RHEL’s preferred LSM) and significantly more expressive than AppArmor.

Docker integrates with SELinux via the --security-opt label=... flag. By default, containers run with the container_t type and limited MCS labels. To customise:

Configuration changeselinux label— Run a container with a specific SELinux label, allowing access to host paths labelled accordingly.

docker run --security-opt label=type:container_myapp_t \
  -v /srv/data:/srv/data:z \
  nginx

The :z and :Z mount options tell Docker to relabel the host volume for the container. Misconfiguration here is one of the most common SELinux + Docker issues.

What to do in practice

Start with the default Docker security profile. Verify the workload runs without customisation.
If a syscall or capability is missing, identify the specific call. Add only what is needed.
Test the workload under the custom profile. A profile that breaks the workload is worse than no profile.
Document the rationale for each customisation. Auditors will ask.
Re-test after every dependency upgrade. New libraries introduce new syscalls.

Seccomp

Custom seccomp profiles

AppArmor

Finding an AppArmor denial, and why dmesg lies about how many there were

SELinux

What to do in practice

Knowledge check

Finding an AppArmor denial, and why `dmesg` lies about how many there were