Architecture

New to Kernloom? Start with Core Concepts for a plain-language overview. To install and run, see Getting started.

Kernel requirement: 5.10 LTS or newer. Kernloom relies on BPF ring buffer (available from 5.8) and stable XDP driver support. 5.10 LTS is the minimum tested and recommended baseline. On Synology NAS systems this requires a newer nk-platform (DSM 7.2+ on supported models).

The model: PDP and PEP

Kernloom is structured around the standard Zero Trust pattern of separating policy decisions from policy enforcement:

• Policy Decision Point (PDP) — Kernloom IQ (kliq). Reads telemetry, computes per-source severity, decides what action to take.
• Policy Enforcement Point (PEP) — Kernloom Shield (klshield). Applies decisions at line rate in the kernel. First PEP adapter in the Kernloom ecosystem.

This split matters: IQ’s policy logic is PEP-agnostic. Future adapters (nginx, nftables, OpenZiti) can plug in without changing how IQ reasons about traffic. Configuration files — PolicyPack and PDPConfig YAML — are written once and work across all adapters.

Data flow

Packets arrive at NIC
        │
        ▼
[ Shield / XDP — kernel space ]
  1. Check allowlist (CIDR, LPM trie)
  2. Check denylist (exact IP, hash map)
  3. Apply rate-limit (token bucket, per-source override)
  4. Update per-source telemetry counters
  5. PASS or DROP
        │
        ▼ (kernel eBPF maps, pinned to /sys/fs/bpf/)
        │
[ IQ — userspace, every tick (default 1s) ]
  1. Read per-source deltas (PPS, SYN/s, scan/s, DropRL/s)
  2. Compute per-source severity score
  3. Run per-source FSM: OBSERVE → RATE_SOFT → RATE_HARD → BLOCK
  4. Write enforcement decisions back to Shield's maps
  5. (if graph enabled) Record source→destination edges

Enforcement levels

For each source IP (IPv4 and IPv6), IQ manages one of four states:

Escalation is gradual. IQ requires sustained signals across multiple ticks before escalating, and requires a streak of clean ticks before stepping down. See IQ reference for the full engine description.

Pinned maps (reference)

Shield and IQ communicate exclusively through eBPF maps pinned at /sys/fs/bpf/:

Graph Learner

The Graph Learner is an optional IQ module that builds a baseline of observed source→destination communication edges.

Edge lifecycle:

candidate  →  learned  →  frozen
     └──────────────────→  denied   (explicit)
                           approved (explicit override)

Modes:

Baseline is stored in a unified SQLite database (kliq.db, at /var/lib/kernloom/iq/kliq.db). Since v0.2.0 this database contains graph edges, edge baselines, and source baseline data in separate tables. Suspicious sources (already being rate-limited or blocked) are automatically excluded from the learning corpus.

Two deployment scenarios

Kernloom serves two fundamentally different use cases with different feature profile choices:

Scenario A — DoS prevention (public-facing nodes)

Used when the node faces the internet or a large number of unknown clients: Ziti controller, Ziti router, public web server, reverse proxy.

Graph learning is not useful here — new internet client IPs appear constantly and xdp_flow4_stats (32k entries) fills instantly. The maximum useful feature profile on a public-facing node is iq-learning: per-source EWMA baseline and progressive enforcement, but no flow telemetry and no graph.

Focus: early source-level rate limiting and autotune-based progressive enforcement. Protects WAF, proxy, and application from absorbing connection noise.

Scenario B — Microsegmentation (internal nodes)

Used when the node communicates with a small, stable set of internal services: identity provider, database, internal API, NAS. These are the nodes behind the public-facing layer — they never see raw internet clients directly.

Graph learning maps all communication edges over 7–14 days; freeze creates a Zero Trust boundary enforced at XDP level. Use feature profile graph-learning → graph-enforce.

Focus: learn normal service-to-service communication, freeze the baseline, block any unrecognised path immediately. Catches lateral movement and unintended communication.

The two scenarios are complementary, not competing. A typical deployment has public-facing nodes (Scenario A) absorbing internet noise and passing clean traffic inward, while internal nodes (Scenario B) enforce microsegmentation between services. Scenario A protects the perimeter; Scenario B limits blast radius if something gets through.

Configuration files

From v0.1.2, IQ can be driven by two structured YAML files instead of CLI flags:

• PDPConfig — how IQ operates (thresholds, autotune settings, graph mode, intervals). Scoped to the IQ instance.
• PolicyPack — what to enforce (profiles, block gates, rate-limit levels). PEP-agnostic — the same PolicyPack works with Shield today and future adapters.

Both formats are forward-compatible with Kernloom Forge. See IQ reference for YAML schema details.

Coming: Kernloom Forge

In standalone mode (current), IQ is configured and managed per node. Kernloom Forge is the upcoming Policy Management System:

Kernloom Forge (PMS)
  ├── compile PolicyPacks
  ├── sign + version bundles
  └── distribute to registered IQ nodes

kliq node-01        kliq node-02
  └── enforces         └── enforces
  └── receipts         └── receipts

Every enforcement decision IQ makes produces a signed receipt. Forge will aggregate these for fleet-wide audit and anomaly detection.

PolicyPack and PDPConfig files you write today will work with Forge without migration.

Build from source

If you prefer to build manually:

# BPF object (requires clang + llvm + bpftool)
make -C shield/bpf

# Go binaries
go build -o bin/klshield ./shield/cmd/klshield
go build -o bin/kliq    ./iq/cmd/kliq

See Getting started for the one-liner installer.

See also