README
¶
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.mdfor scope and limits (not a full IDS; no dedicated reverse-tunnel classifier) - Outbound notifications: Optional Slack, Microsoft Teams, generic webhook, and syslog for rule alerts, anomalies, and new devices (
docs/notifications.md)
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.26+
- 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 requestsARP_REPLY- ARP responsesARP_PROBE- Address conflict detection (0.0.0.0 source)ARP_ANNOUNCE- Gratuitous ARP announcementsARP_SCAN- Network scanning behavior
TCP Traffic:
TCP_SYN- Connection initiationTCP_SYNACK- Connection acknowledgmentTCP_ACK- Data acknowledgmentTCP_FIN- Connection terminationTCP_RST- Connection resetTCP_HTTP- Port 80 trafficTCP_HTTPS- Port 443 trafficTCP_SSH- Port 22 trafficTCP_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 requestsDNS_RESPONSE- DNS query responses- Extracts queried domain names from packets
HTTP Traffic:
HTTP_GET- HTTP GET requestsHTTP_POST- HTTP POST requestsHTTP_REQUEST- Other HTTP methods- Extracts request method and path
TLS Traffic:
TLS_CLIENT_HELLO- TLS handshake initiationTLS_SERVER_HELLO- TLS handshake responseTLS_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
Declarative alerts
Thresholds, security baselines, and anomaly detector settings live in a YAML/JSON file (optional). Without a file, built-in defaults match the former hardcoded values. Scenario examples live under configs/.
cp configs/alerts.busy-lan.yaml configs/alerts.yaml # or alerts.example.yaml
CERBERUS_ALERTS_CONFIG=./configs/alerts.yaml sudo ./build/cerberus
See docs/how-to-alerts.md and docs/configuration.md.
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_ONLINEis enabled (seedocs/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
- Redis backend for distributed deployments
- REST API for external integrations
- Web dashboard for visualization
- Anomaly detection using ML
- IPv6 support
- Expand L7 payload capture to 128-256 bytes for better SNI/HTTP header extraction
- Add proper DNS response parsing
- Add HTTP Host header extraction
- Implement TLS version detection
- Support for identifying encrypted DNS (DoH/DoT)
- Track DNS response codes and query types
- Correlate DNS queries with subsequent connections
- Export to Prometheus/Grafana
- Custom alerting rules
- GeoIP location tracking
- Outbound alert notifications (webhook / Slack / Teams / syslog)
- Accurate IEEE OUI lookup (MA-L/MA-M/MA-S, stale-cache prefer, virtualization OUIs)
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
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
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
cerberus
command
|
|
|
internal
|
|
|
notify
Package notify delivers outbound alert notifications (webhook, Slack, Teams, syslog).
|
Package notify delivers outbound alert notifications (webhook, Slack, Teams, syslog). |
|
version
Package version exposes build metadata populated via -ldflags -X at build time.
|
Package version exposes build metadata populated via -ldflags -X at build time. |
Click to show internal directories.
Click to hide internal directories.