Cerberus

Network Guardian - Real-time Traffic Monitoring & Device Discovery

Cerberus is a high-performance network monitoring tool built with eBPF (Extended Berkeley Packet Filter) that provides real-time visibility into network traffic, device discovery, and Layer 7 protocol analysis.

Features

Real-time Traffic Capture: Monitor ARP, TCP, UDP, ICMP, DNS, HTTP, and TLS traffic at the kernel level using eBPF
Layer 7 Protocol Inspection: Deep packet inspection for DNS queries, HTTP requests, and TLS handshakes
Device Discovery: Automatically detect new devices joining your network
Traffic Classification: Identify and classify network protocols with intelligent pattern recognition
Vendor Identification: Lookup device manufacturers using IEEE OUI database
Pattern Tracking: Track unique communication patterns with LRU caching
Statistics Dashboard: Real-time network statistics and device behavior analysis
Smart Deduplication: Only alert on new traffic patterns (first occurrence)
Persistent Storage: Local database for historical data with Redis migration path
Control Room (Web UI): Hash-routed dashboard for summary, devices, rule alerts, anomalies, and raw JSON
Behavioral anomaly & abuse-style signals: ML-lite windows highlight SYN-heavy, high-volume, and unusual-port patterns (consistent with scans/floods); rule alerts flag DNS/TCP/target spread; see docs/threat-and-anomaly-patterns.md for scope and limits (not a full IDS; no dedicated reverse-tunnel classifier)

Full system behavior, data flow, and UI breakdown live in docs/. Step-by-step how to trigger alerts (rule vs anomaly) is in docs/how-to-alerts.md.

Web UI wireframe (Control Room)

The dashboard is a single-page shell: the top bar shows the product title and theme toggle; tabs switch hash routes; one main region shows the active page (all panels refresh on a short interval).

┌──────────────────────────────────────────────────────────────────────────┐
│  Network Guardian                                                        │
│  Cerberus Control Room                                    [ Dark mode ]  │
├──────────────────────────────────────────────────────────────────────────┤
│  Overview │ All devices │ Rule alerts │ Anomalies │ Raw JSON             │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─ Route: #/ (Overview) ─────────────────────────────────────────┐     │
│   │  ┌─────────────────────┐  ┌─────────────────────┐              │     │
│   │  │ Live summary        │  │ Recent devices      │              │     │
│   │  │ (packet counters)   │  │ (links → device)    │              │     │
│   │  └─────────────────────┘  └─────────────────────┘              │     │
│   │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │     │
│   │  │ Top services │ │ Top vendors  │ │ DNS ranks    │            │     │
│   │  └──────────────┘ └──────────────┘ └──────────────┘            │     │
│   │  ┌──────────────────────────────────────────────────────────┐  │     │
│   │  │ Anomaly detection (status, "what it means", metrics,     │  │     │
│   │  │ recent alerts + link to full history)                    │  │     │
│   │  └──────────────────────────────────────────────────────────┘  │     │
│   └────────────────────────────────────────────────────────────────┘     │
│                                                                          │
│   Other routes:  #/devices (table)  #/device/<mac> (full device JSON)    │
│                  #/alerts (table)   #/anomalies (full anomaly UI)        │
│                  #/raw/<endpoint>   (pretty-printed API JSON)            │
└──────────────────────────────────────────────────────────────────────────┘

See docs/web-ui.md for per-screen layout, routes, and which REST endpoints feed each view.

Why Cerberus?

Built with Pure Go + eBPF - Cerberus uses cilium/ebpf instead of CGO-based alternatives, delivering:

Zero CGO dependencies - No libbpf version conflicts, works everywhere
95% smaller binaries - 19.5MB vs 447MB Docker images
64% faster builds - 31s vs 87s compilation time
Production-proven - Same library powering Cilium, Falco, and Tetragon

Cerberus is portable, maintainable, and battle-tested at scale.

Architecture

flowchart TD
    subgraph UserSpace["User Space"]
        direction TB
        Monitor["Monitor<br/>Traffic Analysis & Classification"]
        L7["Layer 7 Inspector<br/>DNS/HTTP/TLS Analysis"]
        Cache["LRU Cache<br/>Device & Pattern Tracking"]
        DB["BuntDB<br/>Persistent Storage"]
        OUI["OUI Database<br/>Vendor Lookup"]
        Services["Service Database<br/>Port Mapping"]
        
        Monitor --> L7
        L7 --> Cache
        Monitor --> Cache
        Cache --> DB
        Monitor --> OUI
        Monitor --> Services
    end
    
    RingBuffer["Ring Buffer<br/>(Kernel ↔ User Communication)"]
    
    subgraph KernelSpace["Kernel Space"]
        direction TB
        eBPF["eBPF TC Classifier<br/>Packet Parser"]
        ARPHandler["ARP Handler"]
        TCPHandler["TCP Handler"]
        UDPHandler["UDP Handler"]
        ICMPHandler["ICMP Handler"]
        DNSHandler["DNS Handler"]
        HTTPHandler["HTTP Handler"]
        TLSHandler["TLS Handler"]
        NetIF["Network Interface<br/>(TC Ingress Hook)"]
        
        NetIF -->|Raw Packets| eBPF
        eBPF --> ARPHandler
        eBPF --> TCPHandler
        eBPF --> UDPHandler
        eBPF --> ICMPHandler
        eBPF --> DNSHandler
        eBPF --> HTTPHandler
        eBPF --> TLSHandler
    end
    
    ARPHandler -->|Events| RingBuffer
    TCPHandler -->|Events| RingBuffer
    UDPHandler -->|Events| RingBuffer
    ICMPHandler -->|Events| RingBuffer
    DNSHandler -->|Events| RingBuffer
    HTTPHandler -->|Events| RingBuffer
    TLSHandler -->|Events| RingBuffer
    RingBuffer -->|Poll| Monitor
    
    Network["Network Traffic"] --> NetIF
    
    style UserSpace fill:#e1f5ff,stroke:#01579b,stroke-width:3px
    style KernelSpace fill:#fff3e0,stroke:#e65100,stroke-width:3px
    style Monitor fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    style L7 fill:#b2dfdb,stroke:#00695c,stroke-width:2px
    style Cache fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    style DB fill:#f8bbd0,stroke:#c2185b,stroke-width:2px
    style eBPF fill:#ffccbc,stroke:#d84315,stroke-width:2px
    style RingBuffer fill:#d1c4e9,stroke:#512da8,stroke-width:2px
    style Network fill:#b2dfdb,stroke:#00695c,stroke-width:2px

Prerequisites

Linux kernel 5.10+ (with eBPF support)
Go 1.24+
Clang/LLVM
Root/sudo privileges (for eBPF and TC hooks)

System Requirements

# Ubuntu/Debian
sudo apt-get install -y \
    clang \
    llvm \
    libbpf-dev \
    linux-headers-$(uname -r) \
    make \
    gcc

# Verify kernel support
uname -r  # Should be 5.10+
grep CONFIG_BPF_SYSCALL /boot/config-$(uname -r)  # Should output =y

Quick Start

Installation

# Clone the repository
git clone https://github.com/zrougamed/cerberus.git
cd cerberus

# Install Go dependencies
go mod download

# Build
make

# Run
sudo ./build/cerberus

Usage

# Basic usage
sudo ./build/cerberus

Output Examples

New Device Detection

NEW DEVICE DETECTED!
   MAC:     dc:62:79:2f:39:28
   IP:      192.168.0.108
   Vendor:  IoT Device
   First Seen: 2024-12-06 16:51:12

Traffic Patterns

[TCP] 192.168.0.100 (aa:bb:cc:dd:ee:ff) [Apple] → 8.8.8.8:443 (HTTPS)
[UDP] 192.168.0.100 (aa:bb:cc:dd:ee:ff) [Apple] → 1.1.1.1:53 (DNS)
[DNS] 192.168.0.100 (aa:bb:cc:dd:ee:ff) [Apple] → 8.8.8.8:53 (DNS) [google.com]
[HTTP] 192.168.0.100 (aa:bb:cc:dd:ee:ff) [Apple] → 93.184.216.34:80 (HTTP) [GET /index.html]
[TLS] 192.168.0.100 (aa:bb:cc:dd:ee:ff) [Apple] → 142.250.185.46:443 (TLS) [TLS]
[ICMP] 192.168.0.100 (aa:bb:cc:dd:ee:ff) [Apple] → 8.8.8.8 (ICMP_ECHO_REQUEST)
[TCP] 192.168.0.50 (11:22:33:44:55:66) [Raspberry Pi] → 192.168.0.200:22 (SSH)
[ARP] 0.0.0.0 (aa:bb:cc:dd:ee:ff) [Apple] → 192.168.0.100 (ARP_PROBE)
[ARP] 192.168.0.1 (6c:4f:89:7e:9c:e0) [Router/Gateway] → 192.168.0.1 (ARP_ANNOUNCE)

Statistics Summary

╔════════════════════════════════════════════════════════════════╗
║              NETWORK STATISTICS SUMMARY                        ║
╠════════════════════════════════════════════════════════════════╣
║ Total Devices: 15                                              ║
║ Total Packets: 45821                                           ║
║   - ARP:  1245                                                 ║
║   - TCP:  38456                                                ║
║   - UDP:  6120                                                 ║
║   - ICMP: 245                                                  ║
║   - DNS:  892                                                  ║
║   - HTTP: 156                                                  ║
║   - TLS:  1834                                                 ║
╚════════════════════════════════════════════════════════════════╝

Device Statistics

┌─ Device: aa:bb:cc:dd:ee:ff
│  IP: 192.168.1.100 | Vendor: Apple
│  ARP: Req=5 Reply=3 | TCP: 42 | UDP: 15 | ICMP: 8
│  DNS Queries: 23 | Top Domains: google.com(5) facebook.com(3) twitter.com(2)
│  HTTP Requests: 12
│  TLS Connections: 18
│  Top Services: HTTPS(18) DNS(23) HTTP(12) ICMP_ECHO_REQUEST(8)
│  First: 14:32:15 | Last: 15:47:32
│  Recent Targets: [8.8.8.8, 142.250.185.46, 93.184.216.34]
└─

Traffic Classification

Supported Protocols

ARP Traffic:

ARP_REQUEST - Standard ARP requests
ARP_REPLY - ARP responses
ARP_PROBE - Address conflict detection (0.0.0.0 source)
ARP_ANNOUNCE - Gratuitous ARP announcements
ARP_SCAN - Network scanning behavior

TCP Traffic:

TCP_SYN - Connection initiation
TCP_SYNACK - Connection acknowledgment
TCP_ACK - Data acknowledgment
TCP_FIN - Connection termination
TCP_RST - Connection reset
TCP_HTTP - Port 80 traffic
TCP_HTTPS - Port 443 traffic
TCP_SSH - Port 22 traffic
TCP_CUSTOM - Other TCP services

UDP Traffic:

UDP_DNS - Port 53 (DNS queries)
UDP_DHCP - Port 67/68 (DHCP)
UDP_NTP - Port 123 (Time sync)
UDP_SNMP - Port 161/162 (Network management)
UDP_CUSTOM - Other UDP services

ICMP Traffic:

ICMP_ECHO_REQUEST - Ping requests (type 8)
ICMP_ECHO_REPLY - Ping replies (type 0)
ICMP_DEST_UNREACHABLE - Destination unreachable (type 3)
ICMP_TIME_EXCEEDED - TTL exceeded (type 11)
ICMP_REDIRECT - Redirect messages (type 5)
ICMP_CUSTOM - Other ICMP types

DNS Traffic:

DNS_QUERY - DNS query requests
DNS_RESPONSE - DNS query responses
Extracts queried domain names from packets

HTTP Traffic:

HTTP_GET - HTTP GET requests
HTTP_POST - HTTP POST requests
HTTP_REQUEST - Other HTTP methods
Extracts request method and path

TLS Traffic:

TLS_CLIENT_HELLO - TLS handshake initiation
TLS_SERVER_HELLO - TLS handshake response
TLS_HANDSHAKE - Generic TLS handshake
Detects encrypted connections

Layer 7 Protocol Inspection

Cerberus performs deep packet inspection to extract application-layer information:

DNS Inspection

Parses DNS query names from QNAME field
Supports label-based domain name format
Tracks domains queried per device
Example: [DNS] 192.168.1.100 → 8.8.8.8:53 (DNS) [example.com]

HTTP Inspection

Identifies HTTP methods (GET, POST, HEAD, PUT, DELETE)
Extracts request paths from HTTP requests
Tracks HTTP hosts contacted per device
Example: [HTTP] 192.168.1.100 → 93.184.216.34:80 (HTTP) [GET /api/v1/users]

TLS Inspection

Detects TLS handshake records (0x16)
Identifies Client Hello and Server Hello messages
Tracks TLS connections per device
Example: [TLS] 192.168.1.100 → 142.250.185.46:443 (TLS) [TLS]

Packet Structure

The eBPF program captures 208 bytes per event:

struct network_event {
    __u8 event_type;       // 1 byte  - Event type (ARP/TCP/UDP/ICMP/DNS/HTTP/TLS)
    __u8 src_mac[6];       // 6 bytes - Source MAC address
    __u8 dst_mac[6];       // 6 bytes - Destination MAC address
    __u32 src_ip;          // 4 bytes - Source IP address
    __u32 dst_ip;          // 4 bytes - Destination IP address
    __u8 is_ipv6;          // 1 byte  - 0 for IPv4, 1 for IPv6
    __u8 src_ipv6[16];     // 16 bytes - Source IPv6 address
    __u8 dst_ipv6[16];     // 16 bytes - Destination IPv6 address
    __u16 src_port;        // 2 bytes - Source port
    __u16 dst_port;        // 2 bytes - Destination port
    __u8 protocol;         // 1 byte  - IP protocol number
    __u8 tcp_flags;        // 1 byte  - TCP flags
    __u16 arp_op;          // 2 bytes - ARP operation code
    __u8 arp_sha[6];       // 6 bytes - ARP source hardware address
    __u8 arp_tha[6];       // 6 bytes - ARP target hardware address
    __u8 icmp_type;        // 1 byte  - ICMP message type
    __u8 icmp_code;        // 1 byte  - ICMP code
    __u8 l7_payload[128];  // 128 bytes - Layer 7 payload for inspection
} __attribute__((packed));
// Total: 208 bytes

Configuration

GeoIP Location Tracking

Cerberus supports optional GeoIP enrichment for public IPs when a MaxMind GeoLite2 City database is provided:

CERBERUS_GEOIP_DB=/path/to/GeoLite2-City.mmdb sudo ./build/cerberus

Network Interface

By default, Cerberus monitors all physical network interfaces. To customize:

// In main.go
// Modify the interface selection logic to target specific interfaces

Cache Size

// Adjust LRU cache size (default: 1000 devices)
monitor, err := monitor.NewNetworkMonitor(1000, "network.db")

Statistics Interval

// Change statistics printing interval (default: 60 seconds)
statsTicker := time.NewTicker(60 * time.Second)

Project Structure

cerberus/
├── .ci/                # CI/CD tests for compatibility
├── build/              # Compiled binaries
├── cmd/
│   └── cerberus/       # Main application entry point (eBPF + monitor + HTTP)
├── docs/               # System, API, and web UI documentation
├── ebpf/               # eBPF C programs
│   └── cerberus_tc.c   # TC classifier for packet capture
├── internal/
│   ├── api/            # REST API, Prometheus /metrics, embedded Control Room
│   ├── cache/          # LRU cache implementation
│   ├── databases/      # IEEE OUI + IANA service-name databases
│   ├── models/         # Data structures (events, devices, alerts, anomalies)
│   ├── monitor/        # Core monitoring, classification, persistence, rules
│   ├── network/        # Network utilities
│   └── utils/          # Helper functions (includes L7 inspection)
├── scripts/            # Utility scripts
│   └── cleanup.sh      # TC hook cleanup
├── Makefile            # Build automation
└── go.mod              # Go dependencies

Development

Build from Source

# Build eBPF program
make bpf

# Build Go binary
make build

# Clean build artifacts
make clean

Testing

sudo ./build/cerberus

Testing Layer 7 Inspection

# Test DNS traffic
nslookup google.com
dig example.com

# Test HTTP traffic
curl http://example.com

# Test TLS traffic
curl https://google.com

# Test ICMP traffic
ping 8.8.8.8

Debugging

# Check TC hooks
sudo tc filter show dev enp3s0 ingress

# List loaded BPF programs
sudo bpftool prog show

# Check BPF maps
sudo bpftool map show

# View ringbuffer events
sudo bpftool map dump name events

Troubleshooting

"Operation not permitted"

# Ensure you're running with sudo
sudo ./build/cerberus

"Interface not found"

# List available interfaces
ip link show

# Update interface name in code if needed

"TC hook already exists"

# Clean up existing hooks
make cleanup
# Or manually:
sudo tc qdisc del dev eth0 ingress

No traffic detected

# Verify interface has traffic
sudo tcpdump -i eth0 -c 10

# Generate test traffic
ping google.com
curl https://zrouga.email

Short packet warnings

# If you see "Short packet: X bytes (expected 208)"
# This indicates a mismatch between eBPF and Go code
# Ensure both are using the same structure size (208 bytes)

Security Considerations

Requires root privileges for eBPF and TC operations
Captures network metadata and first 128 bytes of payload for L7 inspection
Does NOT capture or store complete packet payloads
Local database stored at network.db
No external network connections by default; optional IEEE/IANA database downloads if CERBERUS_DB_ONLINE is enabled (see docs/system-overview.md)
L7 inspection is limited to protocol identification and metadata extraction

Known Limitations

TLS SNI Extraction: Full SNI parsing may require deeper handshake parsing. Current implementation captures more handshake context and detects TLS version.
HTTP Host Header: Host extraction depends on header bytes being present in captured payload and does not yet parse absolute-form URIs.
DNS Response Parsing: Parses response codes and answer domains from observed payload windows; full RR-set parsing may require deeper packet capture.
Encrypted Traffic: Cannot inspect encrypted payloads (TLS/HTTPS content).

Roadmap

Performance

Zero-copy packet processing using eBPF ring buffers
LRU caching for efficient device tracking
Batch database writes every 30 seconds
Minimal CPU overhead with kernel-level filtering
Memory efficient with configurable cache sizes

Example Docker resource use at high link throughput (low CPU/RSS, container NET I/O often zero because traffic is not proxied) is documented in docs/deployment-and-performance.md.

Compatibility

Go Version: 1.24+
Kernel: 5.10+ with eBPF support
Dependencies: No external runtime dependencies
Database: Backward compatible with existing network.db files

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contact

Mohamed Zrouga

Acknowledgments

Built with Cilium eBPF
Uses BuntDB for storage
Uses golang-lru for caching
Inspired by network security monitoring tools

Supported Distributions

Cerberus has been successfully built and tested on the following Linux distributions:

Distribution	Status
Ubuntu 22.04	Passed
Ubuntu 24.04	Passed
Debian 12	Passed
Arch Linux	Passed

Made with ❤️ and eBPF

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.ci		.ci
.github		.github
cmd/cerberus		cmd/cerberus
docs		docs
ebpf		ebpf
internal		internal
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

Cerberus

Features

Web UI wireframe (Control Room)

Why Cerberus?

Architecture

Prerequisites

System Requirements

Quick Start

Installation

Usage

Output Examples

New Device Detection

Traffic Patterns

Statistics Summary

Device Statistics

Traffic Classification

Supported Protocols

Layer 7 Protocol Inspection

DNS Inspection

HTTP Inspection

TLS Inspection

Packet Structure

Configuration

GeoIP Location Tracking

Network Interface

Cache Size

Statistics Interval

Project Structure

Development

Build from Source

Testing

Testing Layer 7 Inspection

Debugging

Troubleshooting

"Operation not permitted"

"Interface not found"

"TC hook already exists"

No traffic detected

Short packet warnings

Security Considerations

Known Limitations

Roadmap

Performance

Compatibility

License

Contributing

Contact

Acknowledgments

Supported Distributions

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages