A mini OS for ARM64 containers, in one binary under 100 kB.
kContainerOS is a container userland written in Rust with no dependencies. One static binary is PID 1, a small shell and the core utilities. It has no libc, no std and no crates, and talks to the Linux kernel through raw system calls. Init locks the container down before your command starts.
Clone the kContainerOS repository, build with make build, then run:
docker run -it --rm kcontaineros
- Userland
- one binary
- Libc
- none
- Runs as
- nobody
- Platform
- linux/arm64
Get started
Build the image, then put your program on top.
The image builds inside Docker and always comes out as linux/arm64. make test runs the end-to-end tests against your local Docker daemon and needs an ARM64 host and python3.
git clone https://github.com/BackendStack21/kcontaineros.git cd kcontaineros # build: docker build --platform linux/arm64 -t kcontaineros . make build # end-to-end tests against the local Docker daemon make test # the same tests on an instrumented build, with a coverage report make coverage # look around docker run -it --rm kcontaineros
Put a binary on top of it
Your program must be statically linked. A plain COPY needs no root. examples/hello-http in the repository is a complete image built this way, with a small Rust HTTP server.
FROM kcontaineros COPY my-server /usr/local/bin/my-server CMD ["my-server"]
Before you build on it
- It runs as
nobody, not root. - Build steps that write need
USER 0first; switch back withUSER 65534:65534. Common questions shows how, and how to get a directory your program can write to. - Programs run only from
/bin,/sbinand/usr. - Put yours in
/usr/local/bin, or name its directory:ENV KCOS_EXEC=/app. Whatever directory holds programs cannot be written to at run time, together with the top-level directory it is in. Entries must be plain absolute paths:/, a trailing slash and.or..components are ignored. memfd_createis refused.- A few runtimes use it for JIT code or sealed memory; they need another base image.
- Your command holds no capabilities.
- That stays true whatever
--cap-addor--privilegedsay. Ports below 1024 still work, because Docker makes them unprivileged. - New top-level directories cannot be created at run time.
- Create them in the Dockerfile, or mount a volume there.
ENTRYPOINTis/sbin/init.CMDruns under it. If you set your ownENTRYPOINT, or pass--entrypoint, init and everything it enforces are gone. Keep it withENTRYPOINT ["/sbin/init", "--", "my-server"].- With
--read-only,/tmp,/var/tmpand/runare read-only too. - Add
--tmpfs /tmpif your program writes there.
The sealed variant
kcontaineros:sealed is init and nothing else: under 100 kB, no shell, no utilities, no writable directory. That binary is built without the shell and utility code, so there is none to reach by renaming it. Use it for the final stage when your image needs no RUN steps.
docker build --platform linux/arm64 --target sealed -t kcontaineros:sealed .
FROM kcontaineros:sealed COPY my-server /usr/local/bin/my-server CMD ["my-server"]
$ docker run --rm kcontaineros:sealed sh kcontaineros: sh: no such file or directory
What is inside
One binary. The name it is started under decides what it is.
/sbin/init, /bin/sh and every utility are symlinks to /bin/kcontaineros, which reads argv[0] to pick its part. Apart from them and a /var/run link, the image holds only directories and four small files in /etc.
/sbin/init
PID 1. Locks the container down, starts your command, forwards every signal to it, reaps orphaned zombies and exits with your command's status: 128 + signal when the command is killed. It never allocates and never polls; it sleeps in rt_sigtimedwait.
/bin/sh
A small shell, enough for Dockerfile RUN and CMD in shell form, simple entrypoint scripts and docker exec -it … sh. Quoting, variables, ${VAR:-default}, "$@", pipes, &&, ||, redirections, set -e and -x.
/bin/*
Core utilities with their common flags only, such as ls -la, rm -rf, mkdir -p, ln -s and chown UID:GID.
cat chmod chown cp echo env false kill ln ls mkdir mv ps pwd rm sleep touch true uname
A session as the default user
The $ prompt means you are not root. A program copied to /tmp does not run, the image's program directories cannot be written to, and ordinary files in /tmp work as usual.
$ docker run -it --rm kcontaineros / $ ps PID S COMMAND 1 S /sbin/init /bin/sh 7 S /bin/sh 8 R ps / $ cp /bin/ls /tmp/ls / $ /tmp/ls sh: /tmp/ls: permission denied / $ touch /usr/local/bin/x touch: /usr/local/bin/x: permission denied / $ mkdir /app mkdir: /app: permission denied / $ echo hi > /tmp/note; cat /tmp/note hi / $ exit 7 $ echo $? 7
Stopping
Init forwards every signal it receives to your command. A server with no signal handling of its own, like the one in examples/hello-http, still stops as soon as docker stop sends SIGTERM, and the container exits with status 143 (128 + 15). Run as PID 1 without init, the same server would not get the signal: the kernel does not deliver SIGTERM to a PID 1 that has no handler for it, so Docker waits out its timeout and then sends SIGKILL.
Every system call goes through one function
There is no libc underneath. This is the only place in the source where the binary enters the kernel.
unsafe fn sc(n: usize, a: usize, b: usize, c: usize, d: usize, e: usize, f: usize) -> isize { let ret: isize; asm!( "svc 0", in("x8") n, inlateout("x0") a => ret, in("x1") b, in("x2") c, in("x3") d, in("x4") e, in("x5") f, options(nostack) ); ret }
Utilities hardened after adversarial review
rm -rwalks the tree through directory descriptors opened without following symlinks, so a symlink swapped in during the walk cannot send it elsewhere. It refuses/,.and.., and trees deeper than 4096 levels.killaccepts only real process IDs:0,-1and numbers that would wrap around a 32-bit PID are rejected.cpnever copies setuid, setgid or sticky bits, and refuses to copy a file onto itself.psalways, andlson a terminal, replace everything but printable ASCII in names with?.- The shell rejects what it does not implement instead of running it as something else, and checks a whole script before running its first line.
- A utility whose output cannot be written, because the disk is full or the descriptor is closed, exits with status 1.
The lockdown
Restrictions applied before your command starts, enforced by the kernel.
The aim is that code running inside the container, including code an attacker has taken over, cannot gain privilege, cannot loosen its restrictions and cannot run a program it brought with it. Init applies the restrictions to itself before it starts your command. The kernel enforces them, every process inherits them, and none can be undone from inside.
- No privilege gainno_new_privs
- Setuid binaries and file capabilities grant nothing.
- No capabilitiesbounding, ambient and process sets emptied
- Root in the container is an ordinary user to the kernel, even under
--privileged. - Run or write, never bothLandlock, plus the filter for memory files
- Programs execute only from the image's program directories, and those cannot be written to, whatever the file permissions. A binary dropped in
/tmpor on a volume does not run, and memory files (memfd_create) cannot be created at all. - Reduced kernel surfaceseccomp filter, on top of Docker's
ptrace, reading or writing another process's memory, new namespaces, mounts,chroot, kernel modules,bpf,io_uring,perf, keyrings, clock and hostname changes, and switching off address randomisation are refused. System calls newer than the filter knows are answered "not implemented".- Nothing to tamper withread-only image files owned by root; default user nobody
- The default user cannot modify the image.
- PID 1 is opaquenot dumpable
- Other processes cannot read its memory or environment.
Checked against a privileged root attacker
make test checks each of these against the strongest attacker Docker can hand over: root, --privileged, and Docker's own system call filter switched off. It runs the same attempts without init as a control, where they succeed.
You can see the effect yourself. Even as root in a privileged container, the command holds no capabilities, cannot gain any, and runs under a seccomp filter (Seccomp: 2).
$ docker run --rm --privileged --user 0 kcontaineros \ sh -c 'cp /bin/ls /tmp/ls; /tmp/ls; touch /usr/local/bin/x; mkdir /app' sh: /tmp/ls: permission denied touch: /usr/local/bin/x: permission denied mkdir: /app: permission denied $ docker run --rm --privileged --user 0 kcontaineros cat /proc/self/status \ | grep -E '^(Cap(Inh|Prm|Eff|Bnd|Amb)|NoNewPrivs|Seccomp):' CapInh: 0000000000000000 CapPrm: 0000000000000000 CapEff: 0000000000000000 CapBnd: 0000000000000000 CapAmb: 0000000000000000 NoNewPrivs: 1 Seccomp: 2
How the binary is built
- Static PIE. The kernel loads it at a random address on every start and the binary relocates itself. Code, data, stack and heap are all randomised.
- Read-only after start. Function and string tables are made read-only once relocated (RELRO). No segment is both writable and executable, and the stack is not executable.
- Pinned and reproducible. The compiler image is pinned by digest, the toolchain by version, and a rebuild from scratch produces the identical image layer.
- No signal handlers and no threads. PID 1 consumes signals synchronously, so there is no handler code to race.
For AI agents
An agent that can run tools will sooner or later run something you did not intend. This image limits what that can turn into.
An AI agent acts through tools: a process that runs commands, edits files or calls services on the model's behalf. Text the model reads can steer it, so the tool process has to be treated as something an attacker may end up directing. What matters then is what is within reach from there. Put the tool server in this image and the usual next steps are refused by the kernel, not by instructions the model is asked to follow.
- Fetch a program and run itrun or write, never both
- Nothing written at run time can be executed: not from
/tmp, not from a volume, not from memory. The programs that run are the ones you built into the image. - Become root, or use rootno capabilities, no_new_privs
- There is nothing to escalate to. Root in the container is an ordinary user to the kernel.
- Replace its own toolsprogram directories are not writable
- The tool server and everything beside it cannot be modified or swapped while the container runs.
- Go after the kernelseccomp filter
- New namespaces, mounts,
ptrace,bpf,io_uringand the other usual first steps of a container escape are refused. - Use what is lying aroundthe sealed image
- There is no shell, no interpreter and no package manager in the image: only init and what you copy in.
- Keep running after you say stopinit forwards signals
docker stopreaches the tool server at once, even if it never set up signal handling. The short-lived processes agents leave behind are reaped.
A tool server in a sealed box
Build the tool server as a static binary and put it on the sealed image. The image cannot decide the network, memory, process count or what is mounted, so set those when you run it. A tool server that talks over standard input and output needs no network at all.
FROM kcontaineros:sealed COPY agent-tools /usr/local/bin/agent-tools CMD ["agent-tools"]
docker run -i --rm --read-only --network none \
--memory 512m --pids-limit 128 \
--tmpfs /work:uid=65534,gid=65534,mode=0700 \
my-agent-tools
Run that way, a tool server can write its working files to /work and nowhere else, cannot execute anything it writes there, has no network, and holds no privilege.
What this does not contain
- It does not limit the network. Without
--network noneor a network you restrict yourself, an agent can send anything it can read to anywhere it can reach. - It does not limit what can be read. Every file and secret you mount is readable by the tool server. Mount only what the tools need.
- It does not judge what your tools do. A tool that deletes files will delete them for a hijacked agent too. The image contains the process, not the purpose.
- An interpreter is a way around the run rule. Copy in Python, Node or a shell and the agent can run any script through it. The rule stops programs brought in at run time, not code fed to an interpreter you shipped. The full image ships a small shell; the sealed image does not.
- It is not a development environment. Agents that need compilers, package managers or dynamically linked tools do not fit. This is for a fixed set of tools built as static binaries.
- It has not been tested with any agent framework. The behaviour above was checked with a stand-in program run under exactly these options.
Common questions
Each answer was checked by running it against the image.
How do I get a directory my program can write to?
Under init, a top-level directory is either for running programs or for writing, never both. /bin, /sbin, /usr and anything named in KCOS_EXEC hold programs and cannot be written to. Every other top-level directory that exists when the container starts can be, subject to ordinary file permissions. Since the image runs as nobody (65534), the directory also has to belong to that user. Out of the box only /tmp and /var/tmp qualify.
A directory in the image. WORKDIR creates it owned by the current user, which is nobody:
FROM kcontaineros WORKDIR /data
Or create it as root and hand it over, for a path below an existing directory or when you do not want it to be the working directory:
FROM kcontaineros USER 0 RUN mkdir -p /var/lib/app && chown 65534:65534 /var/lib/app USER 65534:65534
A volume. Mount it on a directory prepared as above and a new named volume takes over that directory's owner:
docker run -v app-data:/data my-image
Mounted on a path the image does not have, the volume is owned by root and nobody cannot write to it. Bind mounts keep the permissions they have on the host.
A temporary filesystem, owned by the user from the start:
docker run --tmpfs /scratch:uid=65534,gid=65534,mode=0700 my-image
With --read-only nothing in the image is writable, so every writable path has to be a volume or a tmpfs: docker run --read-only --tmpfs /tmp my-image.
What cannot be made writable:
- anything under
/bin,/sbin,/usror the top-level directory of aKCOS_EXECentry, even as a volume or tmpfs mounted there; /itself:mkdir /newfails at run time, so create top-level directories in the Dockerfile or let a mount create them.
In the sealed image there is no /tmp. Mount one: --tmpfs /tmp:uid=65534,gid=65534,mode=0700.
My program fails with "permission denied" when it starts. Why?
Programs run only from /bin, /sbin and /usr. Copy yours to /usr/local/bin, or declare its directory in the Dockerfile:
ENV KCOS_EXEC=/app
Several directories are separated by colons. Each must be a plain absolute path. That directory's top-level directory then stops being writable, so a program in /app/bin cannot keep its data in /app/data.
A program that is dynamically linked fails differently, with "no such file or directory": its loader is missing. Build it statically.
A RUN step in my Dockerfile fails with "permission denied".
The image's user is nobody and its directories are read-only. Switch to root for the build steps that write, then back:
USER 0 RUN mkdir -p /etc/app && echo "mode=production" > /etc/app/config USER 65534:65534
COPY and WORKDIR need no switch.
Does my program need root? What about port 80?
No. Under init even root holds no capabilities, so running as root gains almost nothing and gives up the protection of the read-only image. Ports below 1024 work for any user, because Docker makes them unprivileged inside a container. --cap-add and --privileged have no effect on the command.
A program that starts as root and switches user itself (some servers do) will fail to switch: start it as the final user instead.
How do I check that the lockdown is active?
docker run --rm my-image cat /proc/self/status
Look for NoNewPrivs: 1, Seccomp: 2 and CapEff: 0000000000000000. If the kernel has no Landlock, init prints a warning line when the container starts. make test checks the restrictions themselves.
How do I get a shell in a running container?
docker exec -it CONTAINER sh. That shell starts outside init: it cannot gain privileges and is under the system call filter, but it is not held to the run-or-write rule. The sealed image has no shell; use docker cp to get files out and docker logs to see output.
Can I use my existing entrypoint script?
Only if it stays within the shell's subset: commands, variables, pipes, && and ||, redirections. A script with if, loops, $(…), [ or globs stops with a syntax error before its first command runs. Either put the logic in your program, or call the program directly:
ENTRYPOINT ["/sbin/init", "--", "my-server", "--config", "/etc/app/config"]
Keep /sbin/init first whenever you set ENTRYPOINT; without it nothing on this page is enforced.
How do I add CA certificates or timezone data?
Copy them from an image that has them:
FROM alpine AS certs RUN apk add --no-cache ca-certificates tzdata FROM kcontaineros COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ COPY --from=certs /usr/share/zoneinfo /usr/share/zoneinfo
My runtime fails on memfd_create, ptrace or io_uring.
Those calls are refused on purpose and there is no switch to allow them. A program that needs them needs another base image.
Does it work on Kubernetes, or with user namespaces?
Neither has been tested. Nothing in the image depends on Docker itself, but that is reasoning, not a result.
Limits
What it will not do, and what the lockdown does not promise.
What it will not do
- Static binaries only.
- There is no libc and no dynamic loader. Rust on musl and busybox are tested. Go with
CGO_ENABLED=0and Zig produce the same kind of binary but are not in the test suite. A dynamically linked program needs its loader and libraries copied in. - ARM64 only.
- linux/arm64 is the only supported architecture.
docker buildstops with an error for any other. - No CA certificates, timezone data or
/etc/services. - Copy them in if your program makes TLS connections or needs local time.
- The shell is not POSIX-complete.
- It has no
if,for,whileorcase, no functions, no globbing, no$(…), no here-documents and no[ortest. Scripts that use them stop with a syntax error before doing anything. Copy in another shell if a script needs more. - One command, no supervisor.
- Init runs a single command and does not restart it. Use the shell's
&andwaitfor more than one process. - No package manager and no
adduser. - Add files with
COPY./etc/passwdhasrootandnobody. - A userland, not a bootable OS.
- The kernel comes from the container runtime. kContainerOS does not boot on bare metal or in a VM.
What the lockdown does not guarantee
No image can honestly claim these, and this one does not.
- It is not a guarantee against kernel bugs. The filter removes the interfaces most exploits start from; it cannot remove the kernel.
- Code that is already running can still compute. An attacker with code execution inside your server can use what your server can reach: its files, its network, its memory. The restrictions stop them going further, not from being there.
- Processes of the same user can write each other's memory through
/proc/PID/memunless the host enables Yama. Run one service per container. docker exec,--entrypointandRUNsteps start outside init. A shell or utility started that way still appliesno_new_privsand the filter to itself, but keeps the capabilities Docker gave it and is not under the Landlock rules: build steps have to be able to write the image. Other programs started that way get only what Docker gives them.- The shell will interpret a script from anywhere, including one an attacker wrote to
/tmp. It cannot be executed directly, and the shell running it is under the same restrictions, but it is attacker-chosen logic. The sealed image has no shell. - On kernels without Landlock (before 5.19, or with it disabled) init prints a warning and the run-or-write rule is not enforced. Everything else is; if the filter itself cannot be installed, init refuses to start.
- Started as non-root, init cannot empty the capability bounding set. It does not matter: with
no_new_privsnothing can draw on it. - No stack protector or branch protection (BTI/PAC). Both need a nightly compiler for this target. For the same reason the unwind tables of the prebuilt
corelibrary are still in the binary, unused; the picture at the top shows them. - User-namespace remapping has not been tested.