Table of contents
FAQ
General
Is Kernloom free?
Yes. Kernloom is free and open source, licensed under MPL-2.0. You can use it in production at no cost. The source is on GitHub.
What licence does Kernloom use?
MPL-2.0 (Mozilla Public License 2.0). You can use, modify, and distribute it — including commercially — as long as modifications to the Kernloom source files themselves are shared back under the same licence.
Who built Kernloom?
Kernloom is developed by Adrian Enderlin, an IT security specialist based in Switzerland. Adrian has introduced and architected Zero Trust solutions across a range of organisations, from SMEs to companies in the financial sector.
He built Kernloom out of a practical need: a lightweight, host-based enforcement layer that works on any Linux machine without requiring a service mesh, a cloud dependency, or expensive appliances. Kernloom is the tool he uses himself, both personally and in professional engagements.
Is Kernloom production-ready?
Kernloom is intentionally kept at v0.x.x. Adrian runs it in production on his own infrastructure, but broad production use requires repeatable, automated testing across hardware configurations and kernel versions — which does not exist yet.
v0.x.x signals: the tool works and is actively used, but you should evaluate it carefully in your own environment before relying on it for critical enforcement. If you find a bug or an untested scenario, opening an issue on GitHub is the most direct way to help.
Is Kernloom used in production?
Yes. Adrian uses Kernloom on his own infrastructure and in client engagements where Zero Trust enforcement at the network level is required. The built-in profiles — particularly ziti-controller, ziti-router, and idp — reflect real operational requirements from those deployments.
What it does and doesn’t do
Is Kernloom a WAF?
No. Kernloom is L3/L4 enforcement. It does not inspect HTTP content, decrypt TLS, or understand application protocols. It complements WAFs and reverse proxies by filtering abusive traffic before it reaches them.
Does it decrypt TLS or inspect payloads?
No. Kernloom makes decisions based only on packet counts, connection patterns, and source behaviour — not content. It works without TLS termination.
What does it protect against?
- Port scans and connection probing
- SYN floods and connection pressure on login/API endpoints
- Persistent low-rate abusers that erode capacity over time
- Noisy internet background radiation (scanners, bots)
- Lateral movement from a compromised internal workload (with graph learning)
What does it not protect against?
- Application-layer attacks (SQLi, XSS, SSRF) — use a WAF for those
- Large-scale volumetric DDoS at multi-Gbit/s — use a scrubbing service or CDN
- Attacks from already-whitelisted sources
Does it replace DDoS appliances or CDNs?
No — it complements them. Kernloom handles traffic that still burns CPU and connection state downstream of a CDN or scrubber. It is particularly effective for backend protection where traffic is lower-volume but targeted.
Deployment
Where do I deploy it?
On any Linux host that sees the traffic first: edge/ingress nodes, reverse proxy hosts, API gateways, cloud VMs, internal chokepoints, or even a Raspberry Pi.
What Linux version is required?
Linux kernel 5.10 LTS or newer. 5.10 is the minimum tested baseline for stable BPF ring buffer and XDP support. The XDP data plane requires a NIC driver with XDP support; if unavailable, Kernloom falls back to generic XDP mode automatically. On Synology NAS systems this requires a newer nk-platform (DSM 7.2+ on supported models).
Does it work with IPv6?
Yes. Shield and IQ both handle IPv4 and IPv6 natively. All enforcement maps, telemetry counters, whitelist entries, and feedback targets support both address families.
Does it work in containers or Kubernetes?
Kernloom runs on the Linux host, not inside containers. For Kubernetes, the typical deployment is on the node that handles ingress (e.g., the node running your ingress controller or load balancer). It does not run as a sidecar.
Cilium coexistence: Kernloom Shield attaches at the XDP hook (driver mode, with generic mode fallback) rather than TC. Cilium’s main data path runs at the TC hook, so in most setups Kernloom and Cilium coexist without interference.
The exception is Cilium’s optional XDP acceleration features. When XDP acceleration is active, Cilium attaches its own XDP program to the interface — since only one XDP program can be attached per interface at a time, this conflicts with Kernloom Shield on the same interface.
To check before deploying:
ip link show eth0 # "xdp" in the output means XDP is already in use
If Cilium’s XDP features are not enabled (the default for most cluster setups), Kernloom and Cilium coexist without issue.
Is Kernloom related to OpenZiti?
Kernloom includes built-in profiles (ziti-controller, ziti-router, etc.) tuned for OpenZiti deployments. It is an independent project and works with any Linux service, not just OpenZiti.
How it works
Can I run in observe-only mode?
Yes — and you should start there. Pass --dry-run=true and Kernloom will print every decision it would make without writing anything to the kernel enforcement maps.
How long does bootstrap take?
Bootstrap runs for 14 days by default and adapts thresholds to your real traffic in three phases:
| Phase | Duration | Autotune interval |
|---|---|---|
| Phase 1 | 0 → 48h | every 1h |
| Phase 2 | 48h → 5d | every 6h |
| Phase 3 | 5d → 14d | every 24h |
After 14 days the system enters steady-state autotune (every 84h). You can safely enable enforcement before bootstrap is complete — thresholds continue improving in the background.
Will it block legitimate users behind NAT?
Kernloom is NAT-safe by design. It escalates through rate-limiting stages before considering a block, and the block gate (--block-min-sev, --block-min-dur) requires sustained abnormal behaviour. A shared NAT gateway with a few misbehaving users will be throttled, not immediately blocked.
What happens if IQ restarts?
IQ saves its tuned thresholds and bootstrap metadata to /var/lib/kernloom/iq/state.json and reloads them on restart. The bootstrap timeline is preserved. After restart, Shield’s enforcement maps may contain stale entries — run sudo klshield reset to clear them so IQ starts fresh.
How much overhead does Kernloom add?
Shield runs in the kernel at XDP hook — enforcement decisions happen before the kernel’s TCP stack. Per-packet overhead by feature profile:
| Feature profile | BPF map ops/packet | Estimated overhead | Est. single-core throughput |
|---|---|---|---|
klshield-light | ~4–5 ops | ~60–100 ns | ~10–16 Mpps |
iq-learning | ~5–6 ops | ~80–130 ns | ~8–12 Mpps |
graph-learning / graph-enforce | ~8–11 ops | ~120–200 ns | ~5–8 Mpps |
These are estimates based on known BPF map performance characteristics — not measured Kernloom benchmarks. Actual numbers depend on NIC driver, kernel version, CPU cache size, and traffic pattern. See the Benchmarks page for throughput measurements. IQ adds negligible CPU in userspace regardless of feature profile.
Graph learning
Can I run progressive enforcement and graph learning at the same time?
Yes, and this is the recommended approach for internal nodes. Start both together from day one:
sudo /opt/kernloom/attested/kliq \
--pdp-config=/opt/kernloom/attested/etc/pdp/idp-bootstrap.yaml \
--graph --graph-mode=learn \
--dry-run=true --whitelist-learn=true
Progressive enforcement handles anomalous sources immediately. The graph learner silently records communication paths in the background. After ~14 days, freeze the graph and switch to frozen-enforce for strict Zero Trust.
How long should I run in learn mode before freezing the graph?
Minimum 7 days, ideally 14. You want the graph to have seen all normal traffic patterns — including scheduled jobs, backup windows, monitoring, and less-frequent API clients.
Why can’t graph learning be used on public-facing nodes?
The XDP flow telemetry map (xdp_flow4_stats) holds a maximum of 32k (src IP, dst port, protocol) tuples. On a public-facing node, thousands of different internet client IPs arrive continuously and fill this map within seconds. Once full, new flows evict old ones and the graph never converges.
BPF map limits for reference:
| Map | Limit | Notes |
|---|---|---|
xdp_src4_stats (source telemetry) | 128k IPv4 sources | LRU |
xdp_deny_hash (source blocklist) | 1M IPv4 sources | Hash |
xdp_rl_policy4 (per-source RL) | 256k IPv4 sources | Hash |
xdp_flow4_stats (flow telemetry) | 32k tuples | LRU — binding constraint for graph learning |
edge4_deny / edge4_allow | 65k tuples each | LRU |
Graph learning only works on internal nodes with a small, known set of clients: identity providers, databases, internal APIs, NAS. Do not enable --graph on Ziti controllers, routers, public web servers, or reverse proxies.