terok-shield
Default-deny egress firewall for rootless Podman containers.
terok-shield enforces default-deny outbound network filtering on
Podman containers using nftables. Containers can only reach
explicitly allowed destinations — everything else is rejected with
an ICMP error and a per-packet audit entry.
Where it sits in the stack
terok-shield is the firewall layer of the terok ecosystem.
The hardened-Podman runtime
(terok-sandbox) installs
the OCI hooks at setup time; the operator-in-the-loop verdict
service (terok-clearance)
mutates the live ruleset on Allow / Deny decisions. The shield
itself is independent of all of these — it works on any rootless
Podman container, with or without the rest of terok.
Features
- Default-deny egress with curated allowlists (domains and IPs)
- Dynamic DNS allowlisting — per-container dnsmasq with
--nftset auto-populates allow sets on every DNS resolution,
handling IP rotation at runtime; degrades to resolution at launch
when dnsmasq lacks nftset support or is unavailable, and says so
- Live allow/deny at runtime for individual containers
- Per-container isolation — each container gets its own state
bundle and audit log
- Connection audit logging (JSON-lines lifecycle logs +
kernel-level per-packet nftables logs)
- Fail-closed — hook failure prevents the container from
starting
Requirements
- Linux with nftables (
nft binary) — tested on Fedora 43,
Debian 12 and 13, and Ubuntu 24.04, also works on other modern
Linux distros
- Podman (rootless, recommended ≥ 5.6.0, untested < 4.3.1)
- Python 3.12+
dnsmasq (recommended) for dynamic DNS-based egress control;
dig (dnsutils / bind-utils) as fallback
Installation
pip install terok-shield
Quick start
1. Choose your allowlists
terok-shield ships with several bundled profiles
(see Allowlist Profiles):
| Profile | Domains |
|---|
base | DNS roots, NTP, OCSP, OS package repos |
dev-standard | GitHub, Docker Hub, PyPI, npm, crates.io, Go |
dev-python | Conda, Read the Docs, Python docs |
dev-node | Yarn, jsDelivr, unpkg |
nvidia-hpc | CUDA, NGC, NVIDIA drivers |
No profile applies unless you name one. To add a custom allowlist,
create a .txt file in ~/.config/terok/shield/profiles with one
+-prefixed (allow) or --prefixed (deny) entry per line — a domain,
an IP or CIDR, optionally :port — or +localhost:PORT to reach a
service on the host's own loopback (as host.containers.internal:PORT
inside the container):
e.g. ~/.config/terok/shield/profiles/my-project.txt
+api.example.com
+cdn.example.com
+203.0.113.10
+localhost:9931
2. Start a container with the shield
terok-shield setup
terok-shield run my-container --profiles dev-standard -- alpine:latest sh
Setup installs global OCI hooks; run resolves DNS and launches the container
with a default-deny firewall — only destinations in the
dev-standard profile are reachable. To use custom profiles:
terok-shield run my-container --profiles dev-standard,my-project -- alpine:latest sh
To see — or apply by hand — the ruleset those profiles produce, without
setup, podman or any state:
terok-shield preview --profiles dev-standard,my-project > rules.nft
3. Allow a domain at runtime
terok-shield allow my-container example.com
# Allowed example.com -> <resolved-ip> for my-container
terok-shield deny my-container example.com # revoke later
License
Apache-2.0 — see LICENSES/Apache-2.0.txt.
