kb control plane

kb-control-plane — kbd Daemon

Language: Go · Primary Maintainer: Tejaswini — Defensive Security, Control & Communication Pipelines · Collaborator: Pardhu Varma — Security & gRPC Support

The privileged userland daemon mediating between the eBPF observation layer and all higher-level components. Implements the two-tier storage architecture described in docs/shared-docs/ADR/ADR-1.md.

Structure

kb-control-plane/
├── cmd/kbd/                 Daemon entry point (Cobra CLI)
├── internal/
│   ├── controlplane/         Core orchestration + all 6 gRPC handlers
│   ├── ipc/                   UDS listener + wire protocol parser
│   ├── store/                 L1 (in-memory) / L2 (SQLite WAL) hybrid store
│   ├── policy/                YAML-defined policy engine
│   ├── enforcement/            Containment primitives
│   └── audit/                  SHA-256 hash-chained audit log
├── proto/                    gRPC service definitions (kb.proto)
├── config/                   kb.yaml, policy.yaml, allowlist.yaml
└── tests/

Two-Tier Storage (ADR-1)

• L1 (hot path): sync.Map, pure Go, lock-free — authoritative for live enforcement decisions. ~30–50ns access. No CGO, no disk I/O on the ingestion path.
• L2 (cold path): embedded SQLite compiled into the binary, WAL mode (journal_mode=WAL, synchronous=NORMAL) — durable persistence, audit trail, operator queries, and cold-start recovery. Single-writer (SetMaxOpenConns(1)), async write-behind via a buffered channel + background flush worker.

Rule: no enforcement decision may synchronously depend on disk I/O. Reads that back enforcement (VerifyStartTime, GetProcessState, ListZone) are served from L1 only.

On every daemon start, Store.Restore() sweeps L2 to rebuild L1 before the eBPF ingestion hook goes live — mitigating the "Volatile Memory Risk" called out in ADR-1 (a fresh L1 would otherwise miss VerifyStartTime for every already-tracked PID until a new ProcessState message arrived).

Kafka/Docker-based transport was considered and explicitly rejected: virtualization layers, JVM memory overhead, and network loopback constraints were judged unacceptable for an endpoint security tool's ingestion hot path. RocksDB/LevelDB were also rejected (single-process locking, compaction stalls, no relational query support).

internal/ipc — Transport

Unix Domain Socket listener + the Wire Protocol parser (wire.go, listener.go, wire_test.go). Transport-only: no behavioral analysis, policy evaluation, enforcement, or AI inference happens here.

internal/store — Process Store

In-memory + SQLite-backed behavioral state store. Canonical runtime state shared across the Control Plane and consumed by Policy, Audit, and AADS.

process.go      // Process state management (upsert, verify, list, restore)
schema.go       // Store struct + SQLite schema (process_state, zone_transitions, audit_log)
store_test.go   // Store tests

internal/policy — Policy Engine

Loads policy.yaml, exposes AutoTerminate(comm) to the control plane. Per-comm suspicious/borderlands thresholds are parsed (defSus/defBor defaults: 40/75) but — as of the current build — not yet consumed anywhere on the Go side; zone classification happens natively in kb-core's kb_scoring.c and arrives pre-computed. See Zone Model And Scoring for the full policy schema.

internal/enforcement — Containment

Applies graduated containment based on zone classification:

Level	Mechanism	Status
CGROUP	cgroup v2 CPU throttle	Implemented
SECCOMP	libseccomp network block	TODO
NAMESPACE	mnt/net/user namespace isolation	TODO
TERMINATE	SIGKILL	Implemented

SubmitAgentDecision enforces a minimum-confidence gate (currently 0.85) for TERMINATE actions submitted by AADS agents — the AI Dependency Constraint referenced in project docs (Sec 7.1 of the design doc): agent recommendations alone can never authorize the most destructive action.

Setup & Run

cd kb-control-plane
go get google.golang.org/grpc      # first time only
make proto                          # requires protoc + protoc-gen-go + protoc-gen-go-grpc
go mod tidy
make run                            # or: go run ./cmd/kbd
# or with a non-default config:
go run ./cmd/kbd --config path/to/kb.yaml

Tests

go test ./...

Coverage: scoring engine unit tests (EMA, weights, zones), enforcement logic, gRPC integration, and audit chain verification. controlplane_test.go specifically pins the PID-reuse guard behavior (VerifyStartTime) — stale transitions must not trigger enforcement or an audit entry, while unknown PIDs "fail open" by design (documented, not accidental).

See also: Wire Protocol, Zone Model And Scoring, Architecture.