eBPF-Kuber

eBPF-Kuber is a distributed, multi-tenant runtime security fabric designed for Kubernetes clusters. It leverages eBPF (Extended Berkeley Packet Filter) to track malicious behavior—specifically unauthorized binary executions—directly inside the Linux kernel across all cluster nodes.

This telemetry is enriched with live Kubernetes metadata, streamed to a centralized control plane, and evaluated against declarative security policies. Policies are defined as standard Kubernetes Custom Resources (CRDs) and enforced by writing configurations directly back into kernel-space eBPF maps.

Architecture

The system consists of four primary components, all written in Rust:

1. eBPF Kernel Probe (src/ebpf-kuber-ebpf): An un-bypassable kernel probe attached to the sys_enter_execve tracepoint. It intercepts system calls, checks the execution against a BPF Hash Map of policies, and pushes telemetry to user-space via a lockless BPF Ring Buffer.
2. Node Agent (src/ebpf-kuber-agent): A user-space daemon (deployed as a Kubernetes DaemonSet) that loads the eBPF bytecode, polls the ring buffer, enriches events with Kubernetes metadata (Namespace, Pod, Container), and streams them upstream via gRPC. It also receives policy updates and writes them to the kernel BPF maps.
3. Central Control Plane (src/ebpf-kuber-server): A centralized gRPC server that ingests telemetry from all node agents, persists it to ClickHouse for auditing, evaluates events against in-memory policies, and broadcasts policy updates to node agents.
4. Policy Controller (src/ebpf-kuber-controller): A Kubernetes operator that watches for ContainerSecurityPolicy Custom Resources. It translates declarative YAML policies into gRPC commands distributed by the Central Control Plane.

Project Structure

eBPF-kuber/
├── Cargo.toml                          # Cargo workspace configuration
├── .cargo/                             # Cargo build configuration and aliases
├── src/                                # Core project crates
│   ├── ebpf-kuber-common/              # Shared types (kernel <-> user-space)
│   ├── ebpf-kuber-ebpf/                # eBPF kernel-space probes
│   ├── ebpf-kuber-agent/               # Node Agent (DaemonSet)
│   ├── ebpf-kuber-server/              # Central Control Plane server
│   └── ebpf-kuber-controller/          # Kubernetes CRD operator
├── proto/                              # gRPC Protobuf definitions
├── manifests/                          # Kubernetes deployment YAMLs (CRDs, RBAC, etc.)
├── docker/                             # Dockerfiles and development Docker Compose
├── xtask/                              # Build automation tool
├── docs/                               # Project documentation
├── examples/                           # Example policies and usage
└── tests/                              # Integration tests

Getting Started

Prerequisites

• Rust (Nightly): The eBPF components require the nightly Rust toolchain.

  rustup toolchain install nightly --component rust-src

• eBPF Tooling:

  cargo install bpf-linker

• Protobuf Compiler: Required for compiling the gRPC services. (apt install protobuf-compiler or brew install protobuf)

• Docker & Docker Compose: For running the local ClickHouse datastore.

Building the Project

This project uses a custom xtask alias for build automation to handle the complex requirements of compiling eBPF bytecode.

# Compile the eBPF kernel probe
cargo xtask build-ebpf

# Build the node agent
cargo xtask build-agent

# Build everything
cargo xtask build-all

Local Development Environment

You can spin up a local ClickHouse instance and Grafana for telemetry storage and visualization using Docker Compose:

docker compose -f docker/docker-compose.dev.yaml up -d

Kubernetes Deployment

Kubernetes manifests are located in the manifests/ directory.

1. Install the CRD:

   kubectl apply -f manifests/crds/containersecuritypolicy.yaml

2. Deploy the Control Plane:

   kubectl apply -f manifests/server/
   kubectl apply -f manifests/controller/

3. Deploy the Node Agent (DaemonSet):

   kubectl apply -f manifests/agent/

Writing Policies

Security policies are declarative Kubernetes Custom Resources. See manifests/examples/sample-policy.yaml for an example.

apiVersion: security.ebpf-kuber.io/v1
kind: ContainerSecurityPolicy
metadata:
  name: block-shell-tools
  namespace: ebpf-kuber-system
spec:
  targetNamespace: production
  podSelector:
    app: frontend
  blockBinaries:
    - /bin/sh
    - /bin/bash
    - /usr/bin/curl