Architecture

Architecture

Kernel Borderlands is built in four strict layers. Each layer communicates only with its immediate neighbors, limiting blast radius in the event of component failure. The AADS layer (Layer 3) is optional and advisory — deterministic enforcement continues without it.

┌─────────────────────────────────────────────┐
│ Layer 1 — eBPF Observability (Ring 0)        │  C · eBPF
├─────────────────────────────────────────────┤
│ Layer 2 — Control Plane (kbd daemon)         │  Go
├─────────────────────────────────────────────┤
│ Layer 3 — AADS (Judge / Jury / Executor)     │  Python  (optional)
├─────────────────────────────────────────────┤
│ Layer 4 — Operator Interface                 │  React · Go · Rust
└─────────────────────────────────────────────┘

Two Engineering Pillars

KB is architecturally centered on two foundational components:

• kb-core — the systems and runtime foundation (eBPF + native behavioral scoring).
• kb-aads — the AADS subsystem, the intelligence layer.

All remaining subsystems (kb-control-plane, kb-checker, kb-dashboard, kb-tui, kb-mcp, scripts) extend, orchestrate, validate, or provide operational interfaces for these two.

                           Kernel Borderlands
                ┌─────────────────────────────┐
                │          kb-core            │
                │ Systems Runtime & eBPF       │
                │ Framework                    │
                └─────────────┬───────────────┘
                              │
            ┌─────────────────┴─────────────────┐
            │                                   │
            ▼                                   ▼
    kb-aads                           kb-control-plane

Autonomous Agentic                  Orchestration & Communication
Defense System                            Services
│                                   ▲
└───────────────┬───────────────────┘
│
▼
Agent Coordination
Policy Execution
Event Processing
│
▼
kb-checker
Validation & Safety Engine
│
┌───────────────────────┼───────────────────────┐
│                       │                       │
▼                       ▼                       ▼
kb-dashboard               kb-tui                  kb-mcp
Dashboard & Vis           Terminal UI             MCP Server
                            ▲
                            │
                         scripts
          Development Automation & Testing

Layer 1 — eBPF Observability (Ring 0)

eBPF programs are loaded into the kernel and verified by the kernel's built-in verifier. Six hook points capture the full behavioral surface of every process:

• tracepoint:syscalls — all syscall entry/exit
• tracepoint:sched — fork, exec, exit events
• kprobe:commit_creds — privilege changes
• bpf_lsm — file access (LSM hooks)
• tracepoint:net — network activity
• kprobe:mmap_region — memory mapping

Events are emitted via a shared perf/ring buffer for zero-copy delivery to userspace. See Kernel Hook Points for the full (including proposed) hook inventory, and kb-core for implementation detail.

Layer 2 — Control Plane (kbd)

The Go daemon (kbd) is the privileged userland process mediating between the eBPF layer and everything above it:

• Consumes ring-buffer events over a Unix Domain Socket bridge from kbd_sensor.
• Maintains a dual-tier state topology: an L1 thread-safe sync.Map in-memory cache backed by an async L2 embedded SQLite WAL store (durable, never on the hot path).
• Evaluates YAML-defined operator policies.
• Exposes a gRPC-over-UDS/TCP API.
• Performs a cold-start recovery sweep (Restore()) rebuilding L1 from L2 before the eBPF ingestion hook goes live.
• Writes a SHA-256 hash-chained, tamper-evident audit log.

All enforcement actions are authorized and executed exclusively through this layer. See kb-control-plane.

Layer 3 — AADS (optional, advisory)

The Autonomous Agentic Defense System reasons over KB's behavioral stream using a Judge → Jury → Executor pipeline, backed by a wider swarm of specialized sub-agents. Agents coordinate over a brokerless ZeroMQ mesh and a Kafka event bus, using Protocol Buffers–encoded messages.

No enforcement action may be taken solely on the basis of an agent recommendation without corresponding policy authorization. Disable AADS entirely and deterministic enforcement keeps running unaffected. See kb-aads.

Layer 4 — Operator Interface

Four independent surfaces for watching and steering the system:

• kb-dashboard — React + TypeScript, real-time zone distribution, per-process scores, D3.js force-graph swarm topology, over WebSockets (under `kb-op/kb-dashboard`).
• kbctl — Go/Cobra CLI exposing the full gRPC API for scripted management.
• kb-tui — SSH-accessible terminal interface (Bubble Tea + Wish), served on port 2222 (under `kb-op/kb-tui`).
• kb-mcp — Standardized Model Context Protocol server exposing tool integration to external AI engines and clients (under `kb-op/kb-mcp`).

See kb-dashboard, kb-tui, and kb-mcp.

Enforcement Ladder

Zone	Score	Action
Safe	0–39	Passive observation only
Suspicious	40–74	seccomp network filter applied (<1ms); AADS Judge notified
Borderlands	75–100	Namespace isolation + cgroup v2 throttling (<5ms P99); SIGKILL available if policy authorizes

See also: Zone Model And Scoring, Wire Protocol, Event Contract.