Kernloom

Table of contents

Kernloom

Kernloom is a two-part L3/L4 protection stack built on XDP:

  • Kernloom Shield (binary: klshield) — XDP dataplane (telemetry + allow/deny/rate-limit)
  • Kernloom IQ (binary: kliq) — controller (progressive enforcement + tuning + exemptions)

You run both together: Shield provides the dataplane and pinned maps; IQ reads telemetry and writes enforcement decisions.

Kernloom Overview

Architecture (high level)

Data flow

  1. Packets arrive on the NIC.
  2. Kernloom Shield runs in XDP:
    • applies allow/deny and token-bucket rate limiting
    • updates per-source counters (telemetry)
    • optionally emits sampled events (ring buffer)
  3. Kernloom IQ polls telemetry every tick (default 1s):
    • computes per-IP deltas (PPS, SYN/s, scan/s, DropRL/s)
    • computes severity, updates per-IP FSM state
    • writes enforcement decisions back to pinned maps

Enforcement levels (IQ)

For each source IP (IPv4 + IPv6), IQ can apply:

  • OBSERVE: no action
  • RATE_SOFT: per-IP token bucket (gentle throttle)
  • RATE_HARD: stricter per-IP token bucket
  • BLOCK: deny entry

What gets pinned (default)

Pinned link:

  • /sys/fs/bpf/kernloom_shield_xdp_link

Pinned maps:

  • totals (per-CPU): /sys/fs/bpf/kernloom_totals
  • per-source telemetry: /sys/fs/bpf/kernloom_src4_stats, /sys/fs/bpf/kernloom_src6_stats
  • allow lists (LPM): /sys/fs/bpf/kernloom_allow4_lpm, /sys/fs/bpf/kernloom_allow6_lpm
  • deny lists (hash): /sys/fs/bpf/kernloom_deny4_hash, /sys/fs/bpf/kernloom_deny6_hash
  • runtime config: /sys/fs/bpf/kernloom_cfg
  • global RL config: /sys/fs/bpf/kernloom_rl_cfg
  • per-IP RL overrides: /sys/fs/bpf/kernloom_rl_policy4, /sys/fs/bpf/kernloom_rl_policy6
  • events ring buffer: /sys/fs/bpf/kernloom_events

Current IQ build enforces IPv4/IPv6 Current IQ build enforces IPv4 + IPv6 via /sys/fs/bpf/kernloom_rl_policy4, /sys/fs/bpf/kernloom_rl_policy6 and /sys/fs/bpf/kernloom_deny4_hash, /sys/fs/bpf/kernloom_deny6_hash.

Install (build + directories)

Build binaries

go build -o klshield .
go build -o kliq .

sudo mkdir -p /etc/kernloom/iq /var/lib/kernloom/iq
sudo touch /etc/kernloom/iq/whitelist.txt /var/lib/kernloom/iq/feedback.json
sudo chmod 755 /etc/kernloom/iq /var/lib/kernloom/iq

1) Attach Kernloom Shield

sudo ./klshield attach-xdp -iface eth0 -obj bpf/klshield.bpf.o
sudo ./klshield stats
sudo ./klshield top-src -n 20 -by pkts

Optional: low-rate events while onboarding

sudo ./klshield set-sampling 1023
sudo ./klshield events

2) Start Kernloom IQ in dry-run

sudo ./kliq \
  --profile ziti-controller-bootstrap \
  --interval 1s \
  --top 50 \
  --dry-run=true \
  --state-file /var/lib/kernloom/iq/state.json \
  --whitelist /etc/kernloom/iq/whitelist.txt \
  --feedback-file /var/lib/kernloom/iq/feedback.json

3) Enable enforcement

sudo ./kliq \
  --profile ziti-controller \
  --interval 1s \
  --top 100 \
  --dry-run=false \
  --state-file /var/lib/kernloom/iq/state.json \
  --whitelist /etc/kernloom/iq/whitelist.txt \
  --feedback-file /var/lib/kernloom/iq/feedback.json

Where to go next

  • Kernloom Shield reference: /kernloom-shield/
  • Kernloom IQ reference: /kernloom-iq/
  • Exemptions, state, operations: /kernloom-ops/