Operations
Security model
A container platform crosses a strong security boundary. Podos puts correctness and isolation ahead of convenience. This page describes what protects what today, and what is still missing.
The daemon runs as root
Available The daemon runs as root, like Docker and Kubernetes by default. Root lets it mount overlay filesystems, set cgroup limits, create networks and firewall rules (Available) and listen on ports 80 and 443 (Available). The cost: a bug in the daemon can give an attacker the whole server. The daemon therefore had an internal security review as part of M4 (Available); no high-severity finding is open. It has not had an independent audit.
Who can talk to the daemon
Available By default the only way in to the API is the Unix socket
/run/podos/podos.sock:
- the socket has mode 0600 and belongs to root;
- the daemon also checks the peer's credentials and accepts only root;
- no TCP port is open for the API. (Available The built-in proxy listens on ports 80 and 443 for your domains, and your services may publish ports.)
Anyone who is root on the server can do everything. Available The daemon can
also serve a remote HTTPS API with scoped, revocable tokens; it is off
unless you pass --listen. See the next sections.
Tokens and scopes
Available Remote requests carry a bearer token.
- Tokens are random and stored only as hashes.
podos setupprints the first admin token once;podos token createprints each later one once. A lost token cannot be shown again, only replaced. - A token has a kind, a scope and optionally an expiry. Kinds, from least to
most access:
read,deploy,namespace-admin,admin. Adeployorreadtoken is limited to one namespace, optionally to one environment. Anamespace-admintoken is limited to one namespace. Only an admin creates admin tokens or namespaces. - A deploy token can change env values and releases, but secrets only when it
was created with
--secrets-write. - Objects outside a token's scope answer "not found", the same as objects that do not exist, so a token cannot be used to find out what else is on the server.
podos token revokestops a token at once.podos logoutandpodos context removeonly delete the copy on your machine.- Too many failed authentication attempts from one address are answered with "rate limited" (exit code 3).
- The CLI keeps tokens in
contexts.jsonwith mode 0600 in a directory with mode 0700, takes them only from a no-echo prompt, standard input orPODOS_TOKEN, and never prints them.
A deploy token can read its environment's secrets indirectly, through the containers it deploys: a container can print its own environment. Grant deploy tokens as you would grant access to the secrets of that environment.
Remote connections and the CA
Available
- The HTTPS API uses a certificate from the server's internal CA. Plain HTTP
is never offered. The certificate covers the
--tls-namenames, otherHostnames are refused, and it is renewed and reloaded without a restart. podos loginpins the CA on first contact (trust on first use). You compare the CA fingerprint with the one printed bypodos setuporpodos ca fingerprinton the server. After that the server is verified strictly against the saved CA. If the CA ever differs, every command fails, with exit code 1, and nothing is trusted again silently.- Proxy environment variables are ignored for server connections.
Limits: there is no CA rotation yet, and HTTP proxies are not supported for server connections.
Web UI
Available The web UI is served by the daemon.
- Only over the HTTPS API. It is served on the
--listenaddress with the same certificate as the API. It is never served over plain HTTP and never on the Unix socket; the session cookie is refused there.podos setup --web-ui offorpodos daemon --web-ui offturns it off. - Login with a token. The browser sends the token once, in the body of the login request. The server stores only a hash of a random session value; the browser keeps only the cookie, never the token. A wrong, malformed, revoked or expired token all get the same answer, and failed logins are rate limited per address and for the whole server.
- The cookie. It is named
__Host-podos_session, which makes a browser accept it only withSecure,Path=/and noDomain. It isSecure,HttpOnlyandSameSite=Strict, and lasts at most 7 days. It is used only when the request carries no bearer token. - Changes need proof of origin. A request that changes anything and
carries the cookie must have an
Originheader equal to the server's own address and the headerX-Podos-Request: 1. The API answers no cross-origin (CORS) preflight, so a page on another site cannot send them. There is no separate CSRF token. Logging in and out follow the same rule. - Session lifetime. A session has the permissions and scope of its token.
It ends when the token is revoked or expires, after 12 hours without use,
after 7 days, or when you log out.
podos token revokeends the sessions of a token at once. The limits are not configurable. At most 20 sessions exist per token. - Page headers. The UI page carries a strict Content-Security-Policy (own
scripts and styles only, no framing, no other origins),
X-Frame-Options: DENY,X-Content-Type-Options: nosniffandReferrer-Policy: no-referrer. Pages are not cached; hashed assets are. - Setup in the browser.
podos setup --webprints no admin token. It prints a one-time setup code, valid 30 minutes, with a hash stored on the server. Five wrong codes pause the checks (30 seconds, growing to 5 minutes, and a right code is refused too during a pause); 40 wrong codes void the code. The count survives a daemon restart. Until the setup is finished the API answers only health and the setup. The admin token is created at the end and shown once in the browser. The code is printed on the terminal, or in the install script's output when that is not a terminal, so keep that output private. - The certificate warning. The browser does not know the server's internal
CA. Compare the CA fingerprint printed by
podos setup --webwith the CA certificate in the browser's warning before you enter the setup code or a token.
Limits: the UI has no second factor, and a token typed into a page on a compromised computer is lost like any token. Use tokens with a narrow scope and an expiry for people who only need to look.
A repository cannot redirect your deploy
Available A manifest can name a context for an environment. The manifest may
come from a repository you did not write, and the context holds a token for a
real server. So the first time a manifest selects a context for a namespace,
the CLI shows the context, the address and the namespace and asks you to
type yes, then remembers the choice. Without a terminal it refuses unless
you pass --context NAME. The key holds a context name only, never an
address or a token, and is not uploaded. See
Environments and overrides.
Every command that talks to a remote server also prints which context and URL it uses before it sends anything.
Containers
Available Each container runs with:
- a reduced set of Linux capabilities;
- a seccomp profile;
- no-new-privileges;
- read-only system paths and masked kernel interfaces;
- its own mount, PID, IPC, UTS, cgroup and network namespaces;
- CPU and memory limits when the manifest sets them.
Available Each namespace and environment pair has its own private network.
Other namespaces and environments are never reachable unless shared
explicitly (planned for 0.3). Services are private by default; they are
exposed only through domains or publish. Containers can reach the
internet and, by default, the server's private networks. An operator can
turn on strict egress with podos setup --strict-egress and list the
exceptions with --allow-egress. The cloud metadata address is always
blocked. Available Containers can never reach 169.254.0.0/16 (which holds
the metadata address of AWS, GCP and others), 168.63.129.16 (Azure),
100.100.100.200 (Alibaba Cloud) or 192.0.0.192 (Oracle Cloud), not even in
strict egress mode with an allow-list. Containers can use TCP, UDP and ping over IPv4 and Unix sockets,
but no raw sockets, packet capture or SCTP; IPv6 inside application networks
is off. A service without resources.memory gets 512 MiB. Podos refuses to
create containers when the data disk has less than 1 GiB or 5% of inodes
free.
Ingress and TLS
Available
- The built-in proxy serves only domains that a service claims. A domain belongs to one environment, and the first claim wins across the server. Public suffixes and reserved names are refused.
- Uploaded private keys (
podos cert set) are stored encrypted and never shown again.podos cert listshows no key material. - HTTP is redirected to HTTPS for routes with TLS.
tls = "auto"needspodos setup --acme-email, which records your agreement to the certificate authority's terms. It has only been tested against a test ACME server, not the real Let's Encrypt service.- Published ports are open to other machines. Protect them with the service's own authentication and the server's firewall.
- Volumes are directories in the server's data directory, bind-mounted into the container. They are never deleted unless you ask.
- Available Files are mounted read-only, owned by the
user the container runs as, with the mode the manifest gives (default
0400). Paths that Podos provides (/etc/resolv.conf,/etc/hosts,/etc/hostname,/proc,/sys,/dev) and paths inside a volume are refused, and an image cannot redirect a file onto them with a link.
Not yet
- Containers run as host root without user namespaces (planned right after 0.1).
- The disk space a container writes is not limited per container.
- An AppArmor profile is Planned (not built).
- Namespace quotas and a registry allow-list are Planned.
- Privileged containers and host mounts are not offered; they will be explicit opt-ins.
Images
Available
- Registry responses are validated: media types, sizes, digests, redirects and authentication challenges.
- Every blob is verified against its digest before use.
- Layers are unpacked safely: no path traversal, no absolute paths, no symbolic or hard links that escape the root filesystem, no device nodes, no unsafe ownership or permission changes.
- Registries on internal addresses and plain HTTP are refused unless the daemon is started with explicit development flags.
Builds on the server
Available A build runs your Dockerfile on the server, so its steps are
untrusted code. What limits them:
- Source upload. The CLI never follows symbolic links out of the build
directory, sends no sockets, devices or pipes, and refuses names that start
with
.wh.. The daemon unpacks the upload with the same safety rules as image layers (a private directory, no path traversal, no device nodes) and with size and entry limits. - No extra privileges.
RUN --security=insecureandRUN --network=hostare refused. No insecure entitlement is enabled in the builder. - Network. Build steps can reach the internet by the same rules as containers (the cloud metadata addresses are blocked). They cannot reach the environments' networks or the server's own services.
- Frontends.
# syntax=docker/dockerfile:1is allowed. A frontend from any other repository is refused. - No credentials. No registry credentials reach a build, so a build can use public base images only.
- Builder limits. The builder runs as a transient systemd unit in its own slice, with memory, CPU and task ceilings, a time limit per build and a capped cache. Builds of different namespaces never run at the same time. BuildKit's cache mounts are kept apart per namespace.
- The result is hostile input. The image archive that BuildKit writes is read like a downloaded image: only the expected entries, every blob checked against its digest. The release names the image by digest.
- Rate and queue. One token may start 10 builds per minute, and the number of builds that a namespace and the server hold is limited.
- Disk. A build is cancelled when free disk space falls below the server's minimum.
The install script (Available) downloads over HTTPS only and checks crun,
conmon and BuildKit against SHA-256 values pinned in the script, and the
podos binary against the SHA-256 published with the release; a mismatch
stops it before anything is installed. The systemd unit it writes runs the
daemon with NoNewPrivileges, no core dumps, a limited set of socket
families and a reduced capability bounding set. It drops, among others,
the capabilities to load kernel modules, reboot, set the system time and
read the audit log. The daemon looks up its helper programs (crun,
conmon, buildkitd, buildctl and others) in /usr/local/lib/podos/bin
and then the system directories, never in the caller's PATH. It uses a
program only when it is an executable regular file that group and others
cannot write, and, when it runs as root, when root owns the file and the
directories above it.
Secrets
Available
- Encrypted at rest with a key created by
podos setup, stored in the data directory with mode 0600. - Write-only: no command or API returns a secret value.
- Never accepted as a command-line argument or environment variable by the CLI; read from standard input or a no-echo prompt.
- Kept out of logs, the database in clear text and API responses. A release
stores
${secret.NAME}, not the value. - Resolved only from the release's own namespace and environment.
Available Secret files (podos file set --secret, see
Files in containers) follow the same rules:
- They are stored encrypted, like secrets, and are never shown again: no command or API returns their content.
- Writing or removing one needs the permission to write secrets.
- When mounted, they exist only in a memory file system of the daemon, never on the data disk. A template that refers to a secret is treated as a secret file. On Linux 6.4 or newer that memory is not swapped out; on an older kernel use encrypted swap or none.
- The content is mounted read-only with the mode the manifest gives, owned by the user the container runs as.
Limits of this protection:
- A container sees its secrets in its environment and can print them. Its
output, shown by
podos logs, can therefore contain secrets. - When a deployment fails, secret values are masked in the shown output on a best-effort basis only.
- Whoever can deploy to an environment can read its secrets, by deploying a
container that prints them. This includes a Available
deploytoken, with or without--secrets-write. - Whoever can deploy to an environment can mount its existing secret files
and read them from their own container, the same as with
${secret.NAME}. The permission to write secrets guards writing and removing a secret file, not this. - Whoever has the secrets key and the database can read every secret.
Input
Available Names, image references, paths, env values and container
output are treated as untrusted. The manifest is parsed strictly, values are
never passed through a shell, and terminal output is cleaned of control
characters (podos logs --raw turns that off for pipes).
Reporting a vulnerability
Please report security problems privately to the maintainers, not in a public issue. A security contact will be published with the first release.