SRodi/ebpf-server

eBPF Network Monitor

A modular eBPF monitoring system with HTTP API server for real-time network and system event monitoring. Supports both VM and Kubernetes deployments with automatic metadata enrichment.

🚀 Deployment Options

Kubernetes Deployment (Recommended)

Deploy across your entire Kubernetes cluster with automatic node metadata enrichment:

# Quick deployment with built-in script
./scripts/deploy.sh all --registry your-registry.com

# Or step by step
make docker-build
make docker-push REGISTRY=your-registry.com
make k8s-deploy

📖 - Detailed setup and configuration

Local Testing with Kind

Test the full Kubernetes deployment locally:

# Full automated test
make kind-full-test

# Or step by step:
make kind-cluster-create    # Create local cluster
make kind-deploy           # Deploy to kind cluster  
make kind-integration-test # Run comprehensive tests

To get detailed API documentation for the aggregator, available only in Kubernetes mode see API Aggregator Documentation

VM Deployment (Traditional)

For single-server deployments:

# Install dependencies (Ubuntu/Debian)
sudo apt install -y golang-go clang libbpf-dev linux-headers-$(uname -r)

# Build and run
make build
sudo ./bin/ebpf-server

# Test the API
curl http://localhost:8080/health
curl "http://localhost:8080/api/events?type=connection&limit=10"

📚 Interactive API Documentation - Test APIs in your browser

✨ Key Features

🔄 Dual Deployment Support

• Kubernetes Mode: DaemonSet + Aggregator architecture for cluster-wide monitoring
• VM Mode: Traditional single-server deployment
• Automatic Detection: Seamlessly detects environment and adapts behavior

🏷️ Kubernetes Metadata Enrichment

Events in Kubernetes include rich metadata:

{
  "id": "abc123",
  "type": "connection",
  "k8s_node_name": "worker-node-1",
  "k8s_pod_name": "ebpf-monitor-xyz",
  "k8s_namespace": "ebpf-system",
  ...
}

🏗️ Scalable Architecture

Kubernetes Mode: Distributed monitoring with centralized aggregation

┌─────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │    Node 1   │  │    Node 2   │  │        Node N   │  │
│  │ ┌─────────┐ │  │ ┌─────────┐ │  │   ┌─────────┐   │  │
│  │ │ eBPF    │ │  │ │ eBPF    │ │  │   │ eBPF    │   │  │
│  │ │ Agent   │ │  │ │ Agent   │ │  │   │ Agent   │   │  │
│  │ │+K8s Meta│ │  │ │+K8s Meta│ │  │   │+K8s Meta│   │  │
│  │ └────┬────┘ │  │ └────┬────┘ │  │   └────┬────┘   │  │
│  └──────┼──────┘  └──────┼──────┘  └────────┼────────┘  │
│         │                │                  │           │
│         └────────────────┼──────────────────┘           │
│                          │                              │
│                    ┌─────▼─────┐                        │
│                    │   eBPF    │                        │
│                    │ Aggregator│◄─── Unified API        │
│                    │           │                        │
│                    └───────────┘                        │
└─────────────────────────────────────────────────────────┘

VM Mode: Modular, interface-based monitoring system

┌─────────────────────────────────────────────────────┐
│                     eBPF Programs                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │ Connection  │  │ Packet Drop │  │   Custom    │  │
│  │ Monitor     │  │ Monitor     │  │   Monitors  │  │
│  └──────┬──────┘  └──────┬──────┘  └─────────┬───┘  │
└─────────┼─────────────────┼──────────────────┼-─────┘
          │                 │                  │
          └─────────────────┼──────────────────┘
                            ▼
               ┌─────────────────────────┐
               │    Event Processing     │
               │   (Manager + Storage)   │
               └─────────────┬───────────┘
                             ▼
               ┌─────────────────────────┐
               │       HTTP API          │
               │    (/api/events)        │
               └─────────────────────────┘

📊 Unified Monitoring

• Cross-Node Correlation: View events across entire Kubernetes cluster
• Node-Specific Filtering: Query events by specific nodes or pods
• Aggregated Statistics: Cluster-wide event statistics and metrics
• Backward Compatible: Existing VM deployments continue unchanged

📡 API Features

• Unified Event API: Single /api/events endpoint for all monitoring data
• Flexible Filtering: Filter by event type, PID, command, and time windows
• Kubernetes Filtering: Filter by node name, pod name, or namespace
• Program Status: View program status and metrics via /api/programs
• Auto-Generated Documentation: OpenAPI 3.0 spec from code annotations
• Interactive Testing: Built-in Swagger UI for API exploration

Core Endpoints

• GET /health - System health and status
• GET /api/events - Query events with filtering support
• GET /api/programs - List all programs and their status

Query Examples

# Get all connection events from the last hour
curl "http://localhost:8080/api/events?type=connection&since=2023-01-01T00:00:00Z"

# Get events for a specific process
curl "http://localhost:8080/api/events?pid=1234&limit=50"

# Kubernetes: Get events from specific node
curl "http://localhost:8080/api/events?k8s_node_name=worker-1"

Query Parameters

• type: Event type filter (e.g., "connection", "packet_drop")
• pid: Process ID filter
• command: Command name filter
• k8s_node_name, k8s_pod_name, k8s_namespace: Kubernetes filters
• since, until: RFC3339 timestamp filters
• limit: Maximum results (default: 100)

🛠️ Development

# Development build with debug logging
make build-dev && sudo ./bin/ebpf-server-dev

# Generate API docs
make docs

# Run tests
make test

# Build eBPF programs
make build-bpf

📚 - Detailed guide for creating new eBPF monitoring programs

📁 Project Structure

├── cmd/                 # Application entry points
│   ├── server/         # eBPF monitoring server
│   └── aggregator/     # Kubernetes aggregator
├── internal/
│   ├── core/          # Core interfaces and types
│   ├── events/        # Event system (BaseEvent, streams)
│   ├── programs/      # eBPF program implementations
│   ├── storage/       # Event storage and querying
│   ├── api/          # HTTP API handlers
│   ├── kubernetes/   # Kubernetes metadata integration
│   └── system/       # System initialization
├── bpf/              # eBPF C programs and headers
├── kubernetes/       # Kubernetes manifests
├── scripts/          # Deployment and testing scripts
└── docs/            # Documentation and API specs

🔧 Requirements

• Linux kernel 4.18+ with eBPF support
• Root privileges for eBPF program loading
• Dependencies: Go 1.23+, Clang, libbpf-dev, kernel headers
• Kubernetes: 1.20+ (for K8s deployment)

📖 Setup Guide:

📄 License

MIT License - see file.