zrougamed/cerberus
GitHub: zrougamed/cerberus
基于 eBPF 的高性能实时网络流量监控工具，提供设备发现、第七层协议深度分析和异常行为检测能力。
Stars: 67 | Forks: 8
# Cerberus
**网络卫士 - 实时流量监控与设备发现**
Cerberus 是一款基于 eBPF (Extended Berkeley Packet Filter) 构建的高性能网络监控工具，可提供网络流量的实时可见性、设备发现以及第七层（Layer 7）协议分析功能。
## 功能
- **实时流量捕获**：使用 eBPF 在内核层面监控 ARP、TCP、UDP、ICMP、DNS、HTTP 和 TLS 流量
- **第七层协议检测**：对 DNS 查询、HTTP 请求和 TLS 握手进行深度包检测
- **设备发现**：自动检测加入网络的新设备
- **流量分类**：通过智能模式识别对网络协议进行识别和分类
- **厂商识别**：使用 IEEE OUI 数据库查询设备制造商
- **模式追踪**：使用 LRU 缓存追踪唯一的通信模式
- **统计仪表盘**：实时网络统计和设备行为分析
- **智能去重**：仅对新的流量模式（首次出现）发出警报
- **持久化存储**：用于历史数据的本地数据库，并提供 Redis 迁移路径
- **控制室 (Web UI)**：采用哈希路由的仪表盘，包含摘要、设备、规则警报、异常和原始 JSON 视图
- **行为异常与滥用特征信号**：轻量级机器学习窗口会高亮 SYN 密集、大流量和非常规端口模式（与扫描/泛洪行为一致）；规则警报会标记 DNS/TCP/目标扩散行为；有关范围和限制请参阅 **[`docs/threat-and-anomaly-patterns.md`](docs/threat-and-anomaly-patterns.md)**（这并非完整的 IDS；也没有专用的反向隧道分类器）
完整的系统行为、数据流和 UI 分解位于 **[`docs/`](docs/README.md)**。关于如何触发警报（规则与异常）的分步指南位于 **[`docs/how-to-alerts.md`](docs/how-to-alerts.md)**。
### Web UI 线框图 (控制室)
仪表盘是一个单页外壳：**顶部栏**显示产品标题和主题切换开关；**选项卡**用于切换哈希路由；**主区域**显示活动页面（所有面板会在短间隔内刷新）。
```
┌──────────────────────────────────────────────────────────────────────────┐
│ 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/ (full device JSON) │
│ #/alerts (table) #/anomalies (full anomaly UI) │
│ #/raw/ (pretty-printed API JSON) │
└──────────────────────────────────────────────────────────────────────────┘
```
有关每个屏幕的布局、路由以及为每个视图提供数据的 REST 端点，请参阅 **[`docs/web-ui.md`](docs/web-ui.md)**。
## 为什么选择 Cerberus？
**基于纯 Go + eBPF 构建** - Cerberus 使用 [cilium/ebpf](https://github.com/cilium/ebpf) 而不是基于 CGO 的替代方案，从而实现：
- **零 CGO 依赖** - 没有 libbpf 版本冲突，可在任何地方运行
- **二进制文件体积减小 95%** - 19.5MB 相比 447MB 的 Docker 镜像
- **构建速度提升 64%** - 31秒 相比 87秒的编译时间
- **经过生产验证** - 同一库为 Cilium、Falco 和 Tetragon 提供支持
*Cerberus 具有高度的可移植性、可维护性，并在大规模应用中久经考验。*
## 架构
```
flowchart TD
subgraph UserSpace["User Space"]
direction TB
Monitor["Monitor
Traffic Analysis & Classification"] L7["Layer 7 Inspector
DNS/HTTP/TLS Analysis"] Cache["LRU Cache
Device & Pattern Tracking"] DB["BuntDB
Persistent Storage"] OUI["OUI Database
Vendor Lookup"] Services["Service Database
Port Mapping"] Monitor --> L7 L7 --> Cache Monitor --> Cache Cache --> DB Monitor --> OUI Monitor --> Services end RingBuffer["Ring Buffer
(Kernel ↔ User Communication)"] subgraph KernelSpace["Kernel Space"] direction TB eBPF["eBPF TC Classifier
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
(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 ``` ## 前提条件 - Linux 内核 5.10+（需支持 eBPF） - Go 1.24+ - Clang/LLVM - Root/sudo 权限（用于 eBPF 和 TC 挂载点） ### 系统要求 ``` # Ubuntu/Debian sudo apt-get install -y \ clang \ llvm \ libbpf-dev \ linux-headers-$(uname -r) \ make \ gcc # 验证内核支持 uname -r # Should be 5.10+ grep CONFIG_BPF_SYSCALL /boot/config-$(uname -r) # Should output =y ``` ## 快速入门 ### 安装 ``` # Clone 仓库 git clone https://github.com/zrougamed/cerberus.git cd cerberus # 安装 Go 依赖 go mod download # 构建 make # 运行 sudo ./build/cerberus ``` ### 使用方法 ``` # 基本用法 sudo ./build/cerberus ``` ## 输出示例 ### 新设备检测 ``` 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 ``` ### 流量模式 ``` [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) ``` ### 统计摘要 ``` ╔════════════════════════════════════════════════════════════════╗ ║ NETWORK STATISTICS SUMMARY ║ ╠════════════════════════════════════════════════════════════════╣ ║ Total Devices: 15 ║ ║ Total Packets: 45821 ║ ║ - ARP: 1245 ║ ║ - TCP: 38456 ║ ║ - UDP: 6120 ║ ║ - ICMP: 245 ║ ║ - DNS: 892 ║ ║ - HTTP: 156 ║ ║ - TLS: 1834 ║ ╚════════════════════════════════════════════════════════════════╝ ``` ### 设备统计 ``` ┌─ 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] └─ ``` ## 流量分类 ### 支持的协议 **ARP 流量：** - `ARP_REQUEST` - 标准 ARP 请求 - `ARP_REPLY` - ARP 响应 - `ARP_PROBE` - 地址冲突检测（源地址为 0.0.0.0） - `ARP_ANNOUNCE` - 免费ARP公告 - `ARP_SCAN` - 网络扫描行为 **TCP 流量：** - `TCP_SYN` - 连接发起 - `TCP_SYNACK` - 连接确认 - `TCP_ACK` - 数据确认 - `TCP_FIN` - 连接终止 - `TCP_RST` - 连接重置 - `TCP_HTTP` - 端口 80 流量 - `TCP_HTTPS` - 端口 443 流量 - `TCP_SSH` - 端口 22 流量 - `TCP_CUSTOM` - 其他 TCP 服务 **UDP 流量：** - `UDP_DNS` - 端口 53（DNS 查询） - `UDP_DHCP` - 端口 67/68（DHCP） - `UDP_NTP` - 端口 123（时间同步） - `UDP_SNMP` - 端口 161/162（网络管理） - `UDP_CUSTOM` - 其他 UDP 服务 **ICMP 流量：** - `ICMP_ECHO_REQUEST` - Ping 请求（类型 8） - `ICMP_ECHO_REPLY` - Ping 回复（类型 0） - `ICMP_DEST_UNREACHABLE` - 目标不可达（类型 3） - `ICMP_TIME_EXCEEDED` - TTL 超时（类型 11） - `ICMP_REDIRECT` - 重定向消息（类型 5） - `ICMP_CUSTOM` - 其他 ICMP 类型 **DNS 流量：** - `DNS_QUERY` - DNS 查询请求 - `DNS_RESPONSE` - DNS 查询响应 - 从数据包中提取查询的域名 **HTTP 流量：** - `HTTP_GET` - HTTP GET 请求 - `HTTP_POST` - HTTP POST 请求 - `HTTP_REQUEST` - 其他 HTTP 方法 - 提取请求方法和路径 **TLS 流量：** - `TLS_CLIENT_HELLO` - TLS 握手发起 - `TLS_SERVER_HELLO` - TLS 握手响应 - `TLS_HANDSHAKE` - 通用 TLS 握手 - 检测加密连接 ## 第七层协议检测 Cerberus 执行深度包检测以提取应用层信息： ### DNS 检测 - 从 QNAME 字段解析 DNS 查询名称 - 支持基于标签的域名格式 - 追踪每个设备查询的域名 - 示例：`[DNS] 192.168.1.100 → 8.8.8.8:53 (DNS) [example.com]` ### HTTP 检测 - 识别 HTTP 方法（GET、POST、HEAD、PUT、DELETE） - 从 HTTP 请求中提取请求路径 - 追踪每个设备访问的 HTTP 主机 - 示例：`[HTTP] 192.168.1.100 → 93.184.216.34:80 (HTTP) [GET /api/v1/users]` ### TLS 检测 - 检测 TLS 握手记录（0x16） - 识别 Client Hello 和 Server Hello 消息 - 追踪每个设备的 TLS 连接 - 示例：`[TLS] 192.168.1.100 → 142.250.185.46:443 (TLS) [TLS]` ### 数据包结构 eBPF 程序为每个事件捕获 208 字节的数据： ``` 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 ``` ## 配置 ### GeoIP 位置追踪 Cerberus 支持在提供 MaxMind GeoLite2 City 数据库时，对公网 IP 进行可选的 GeoIP 信息补充： ``` CERBERUS_GEOIP_DB=/path/to/GeoLite2-City.mmdb sudo ./build/cerberus ``` ### 网络接口 默认情况下，Cerberus 会监控所有物理网络接口。如需自定义： ``` // In main.go // Modify the interface selection logic to target specific interfaces ``` ### 缓存大小 ``` // Adjust LRU cache size (default: 1000 devices) monitor, err := monitor.NewNetworkMonitor(1000, "network.db") ``` ### 统计间隔 ``` // Change statistics printing interval (default: 60 seconds) statsTicker := time.NewTicker(60 * time.Second) ``` ## 项目结构 ``` 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 ``` ## 开发 ### 从源码构建 ``` # 构建 eBPF 程序 make bpf # 构建 Go 二进制文件 make build # Clean 构建产物 make clean ``` ### 测试 ``` sudo ./build/cerberus ``` ### 测试第七层检测 ``` # 测试 DNS 流量 nslookup google.com dig example.com # 测试 HTTP 流量 curl http://example.com # 测试 TLS 流量 curl https://google.com # 测试 ICMP 流量 ping 8.8.8.8 ``` ### 调试 ``` # 检查 TC hooks sudo tc filter show dev enp3s0 ingress # 列出已加载的 BPF 程序 sudo bpftool prog show # 检查 BPF maps sudo bpftool map show # 查看 ringbuffer 事件 sudo bpftool map dump name events ``` ## 常见问题 ### "Operation not permitted" (操作不允许) ``` # 确保使用 sudo 运行 sudo ./build/cerberus ``` ### "Interface not found" (未找到接口) ``` # 列出可用接口 ip link show # 如果需要，更新代码中的接口名称 ``` ### "TC hook already exists" (TC 挂载点已存在) ``` # Clean up 现有 hooks make cleanup # 或手动： sudo tc qdisc del dev eth0 ingress ``` ### 未检测到流量 ``` # 验证接口是否有流量 sudo tcpdump -i eth0 -c 10 # 生成测试流量 ping google.com curl https://zrouga.email ``` ### 短包警告 ``` # 如果您看到 "Short packet: X bytes (expected 208)" # 这表明 eBPF 和 Go 代码之间存在不匹配 # 确保两者使用相同的结构体大小 (208 bytes) ``` ## 安全注意事项 - eBPF 和 TC 操作需要 root 权限 - 捕获网络元数据和用于 L7 检测的前 128 字节载荷 - 不捕获或存储完整的数据包载荷 - 本地数据库存储在 `network.db` 中 - 默认情况下无外部网络连接；如果启用 `CERBERUS_DB_ONLINE`，可选择下载 IEEE/IANA 数据库（参见 `docs/system-overview.md`） - L7 检测仅限于协议识别和元数据提取 ## 已知限制 1. **TLS SNI 提取**：完整的 SNI 解析可能需要更深入的握手解析。当前实现捕获了更多的握手上下文并检测 TLS 版本。 2. **HTTP Host 头**：Host 提取取决于捕获的载荷中是否存在 header 字节，目前尚未解析绝对形式的 URI。 3. **DNS 响应解析**：从观察到的载荷窗口解析响应码和应答域名；完整的 RR-set 解析可能需要更深入的数据包捕获。 4. **加密流量**：无法检测加密载荷（TLS/HTTPS 内容）。 ## 路线图 - [ ] 用于分布式部署的 Redis 后端 - [x] 用于外部集成的 REST API - [x] 用于可视化的 Web 仪表盘 - [x] 使用机器学习的异常检测 - [x] IPv6 支持 - [x] 将 L7 载荷捕获扩展到 128-256 字节，以更好地提取 SNI/HTTP 头 - [x] 添加完善的 DNS 响应解析 - [x] 添加 HTTP Host 头提取 - [x] 实现 TLS 版本检测 - [x] 支持识别加密 DNS (DoH/DoT) - [x] 追踪 DNS 响应码和查询类型 - [x] 将 DNS 查询与后续连接相关联 - [x] 导出到 Prometheus/Grafana - [x] 自定义警报规则 - [x] GeoIP 位置追踪 ## 性能 - 使用 eBPF 环形缓冲区进行**零拷贝数据包处理** - 用于高效设备追踪的 **LRU 缓存** - 每 30 秒执行一次**批量数据库写入** - 借助内核级过滤实现**极低的 CPU 开销** - 通过可配置的缓存大小实现**内存高效** 有关在高链路吞吐量下 **Docker** 资源使用情况的示例（低 CPU/RSS，容器 NET I/O 通常为零，因为流量未被代理）记录在 **[`docs/deployment-and-performance.md`](docs/deployment-and-performance.md)** 中。 ## 兼容性 - **Go 版本**：1.24+ - **内核**：5.10+ 且支持 eBPF - **依赖项**：无外部运行时依赖 - **数据库**：向下兼容现有的 network.db 文件 ## 许可证 MIT 许可证 - 详情请参阅 LICENSE 文件 ## 贡献 欢迎贡献代码！请随时提交 Pull Request。 1. Fork 本仓库 2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交您的更改 (`git commit -m 'Add some amazing feature'`) 4. 推送到该分支 (`git push origin feature/amazing-feature`) 5. 发起一个 Pull Request ## 联系方式 [Mohamed Zrouga](https://zrouga.email) ## 致谢 - 基于 [Cilium ePF](https://github.com/cilium/ebpf) 构建 - 使用 [BuntDB](https://github.com/tidwall/buntdb) 进行存储 - 使用 [golang-lru](https://github.com/hashicorp/golang-lru) 进行缓存 - 受网络监控工具启发 ## 支持的发行版 Cerberus 已在以下 Linux 发行版上成功构建和测试： | 发行版 | 状态 | |--------------|--------| | Ubuntu 22.04 | 通过 | | Ubuntu 24.04 | 通过 | | Debian 12 | 通过 | | Arch Linux | 通过 | **使用 ❤️ 和 eBPF 构建**
Traffic Analysis & Classification"] L7["Layer 7 Inspector
DNS/HTTP/TLS Analysis"] Cache["LRU Cache
Device & Pattern Tracking"] DB["BuntDB
Persistent Storage"] OUI["OUI Database
Vendor Lookup"] Services["Service Database
Port Mapping"] Monitor --> L7 L7 --> Cache Monitor --> Cache Cache --> DB Monitor --> OUI Monitor --> Services end RingBuffer["Ring Buffer
(Kernel ↔ User Communication)"] subgraph KernelSpace["Kernel Space"] direction TB eBPF["eBPF TC Classifier
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
(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 ``` ## 前提条件 - Linux 内核 5.10+（需支持 eBPF） - Go 1.24+ - Clang/LLVM - Root/sudo 权限（用于 eBPF 和 TC 挂载点） ### 系统要求 ``` # Ubuntu/Debian sudo apt-get install -y \ clang \ llvm \ libbpf-dev \ linux-headers-$(uname -r) \ make \ gcc # 验证内核支持 uname -r # Should be 5.10+ grep CONFIG_BPF_SYSCALL /boot/config-$(uname -r) # Should output =y ``` ## 快速入门 ### 安装 ``` # Clone 仓库 git clone https://github.com/zrougamed/cerberus.git cd cerberus # 安装 Go 依赖 go mod download # 构建 make # 运行 sudo ./build/cerberus ``` ### 使用方法 ``` # 基本用法 sudo ./build/cerberus ``` ## 输出示例 ### 新设备检测 ``` 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 ``` ### 流量模式 ``` [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) ``` ### 统计摘要 ``` ╔════════════════════════════════════════════════════════════════╗ ║ NETWORK STATISTICS SUMMARY ║ ╠════════════════════════════════════════════════════════════════╣ ║ Total Devices: 15 ║ ║ Total Packets: 45821 ║ ║ - ARP: 1245 ║ ║ - TCP: 38456 ║ ║ - UDP: 6120 ║ ║ - ICMP: 245 ║ ║ - DNS: 892 ║ ║ - HTTP: 156 ║ ║ - TLS: 1834 ║ ╚════════════════════════════════════════════════════════════════╝ ``` ### 设备统计 ``` ┌─ 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] └─ ``` ## 流量分类 ### 支持的协议 **ARP 流量：** - `ARP_REQUEST` - 标准 ARP 请求 - `ARP_REPLY` - ARP 响应 - `ARP_PROBE` - 地址冲突检测（源地址为 0.0.0.0） - `ARP_ANNOUNCE` - 免费ARP公告 - `ARP_SCAN` - 网络扫描行为 **TCP 流量：** - `TCP_SYN` - 连接发起 - `TCP_SYNACK` - 连接确认 - `TCP_ACK` - 数据确认 - `TCP_FIN` - 连接终止 - `TCP_RST` - 连接重置 - `TCP_HTTP` - 端口 80 流量 - `TCP_HTTPS` - 端口 443 流量 - `TCP_SSH` - 端口 22 流量 - `TCP_CUSTOM` - 其他 TCP 服务 **UDP 流量：** - `UDP_DNS` - 端口 53（DNS 查询） - `UDP_DHCP` - 端口 67/68（DHCP） - `UDP_NTP` - 端口 123（时间同步） - `UDP_SNMP` - 端口 161/162（网络管理） - `UDP_CUSTOM` - 其他 UDP 服务 **ICMP 流量：** - `ICMP_ECHO_REQUEST` - Ping 请求（类型 8） - `ICMP_ECHO_REPLY` - Ping 回复（类型 0） - `ICMP_DEST_UNREACHABLE` - 目标不可达（类型 3） - `ICMP_TIME_EXCEEDED` - TTL 超时（类型 11） - `ICMP_REDIRECT` - 重定向消息（类型 5） - `ICMP_CUSTOM` - 其他 ICMP 类型 **DNS 流量：** - `DNS_QUERY` - DNS 查询请求 - `DNS_RESPONSE` - DNS 查询响应 - 从数据包中提取查询的域名 **HTTP 流量：** - `HTTP_GET` - HTTP GET 请求 - `HTTP_POST` - HTTP POST 请求 - `HTTP_REQUEST` - 其他 HTTP 方法 - 提取请求方法和路径 **TLS 流量：** - `TLS_CLIENT_HELLO` - TLS 握手发起 - `TLS_SERVER_HELLO` - TLS 握手响应 - `TLS_HANDSHAKE` - 通用 TLS 握手 - 检测加密连接 ## 第七层协议检测 Cerberus 执行深度包检测以提取应用层信息： ### DNS 检测 - 从 QNAME 字段解析 DNS 查询名称 - 支持基于标签的域名格式 - 追踪每个设备查询的域名 - 示例：`[DNS] 192.168.1.100 → 8.8.8.8:53 (DNS) [example.com]` ### HTTP 检测 - 识别 HTTP 方法（GET、POST、HEAD、PUT、DELETE） - 从 HTTP 请求中提取请求路径 - 追踪每个设备访问的 HTTP 主机 - 示例：`[HTTP] 192.168.1.100 → 93.184.216.34:80 (HTTP) [GET /api/v1/users]` ### TLS 检测 - 检测 TLS 握手记录（0x16） - 识别 Client Hello 和 Server Hello 消息 - 追踪每个设备的 TLS 连接 - 示例：`[TLS] 192.168.1.100 → 142.250.185.46:443 (TLS) [TLS]` ### 数据包结构 eBPF 程序为每个事件捕获 208 字节的数据： ``` 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 ``` ## 配置 ### GeoIP 位置追踪 Cerberus 支持在提供 MaxMind GeoLite2 City 数据库时，对公网 IP 进行可选的 GeoIP 信息补充： ``` CERBERUS_GEOIP_DB=/path/to/GeoLite2-City.mmdb sudo ./build/cerberus ``` ### 网络接口 默认情况下，Cerberus 会监控所有物理网络接口。如需自定义： ``` // In main.go // Modify the interface selection logic to target specific interfaces ``` ### 缓存大小 ``` // Adjust LRU cache size (default: 1000 devices) monitor, err := monitor.NewNetworkMonitor(1000, "network.db") ``` ### 统计间隔 ``` // Change statistics printing interval (default: 60 seconds) statsTicker := time.NewTicker(60 * time.Second) ``` ## 项目结构 ``` 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 ``` ## 开发 ### 从源码构建 ``` # 构建 eBPF 程序 make bpf # 构建 Go 二进制文件 make build # Clean 构建产物 make clean ``` ### 测试 ``` sudo ./build/cerberus ``` ### 测试第七层检测 ``` # 测试 DNS 流量 nslookup google.com dig example.com # 测试 HTTP 流量 curl http://example.com # 测试 TLS 流量 curl https://google.com # 测试 ICMP 流量 ping 8.8.8.8 ``` ### 调试 ``` # 检查 TC hooks sudo tc filter show dev enp3s0 ingress # 列出已加载的 BPF 程序 sudo bpftool prog show # 检查 BPF maps sudo bpftool map show # 查看 ringbuffer 事件 sudo bpftool map dump name events ``` ## 常见问题 ### "Operation not permitted" (操作不允许) ``` # 确保使用 sudo 运行 sudo ./build/cerberus ``` ### "Interface not found" (未找到接口) ``` # 列出可用接口 ip link show # 如果需要，更新代码中的接口名称 ``` ### "TC hook already exists" (TC 挂载点已存在) ``` # Clean up 现有 hooks make cleanup # 或手动： sudo tc qdisc del dev eth0 ingress ``` ### 未检测到流量 ``` # 验证接口是否有流量 sudo tcpdump -i eth0 -c 10 # 生成测试流量 ping google.com curl https://zrouga.email ``` ### 短包警告 ``` # 如果您看到 "Short packet: X bytes (expected 208)" # 这表明 eBPF 和 Go 代码之间存在不匹配 # 确保两者使用相同的结构体大小 (208 bytes) ``` ## 安全注意事项 - eBPF 和 TC 操作需要 root 权限 - 捕获网络元数据和用于 L7 检测的前 128 字节载荷 - 不捕获或存储完整的数据包载荷 - 本地数据库存储在 `network.db` 中 - 默认情况下无外部网络连接；如果启用 `CERBERUS_DB_ONLINE`，可选择下载 IEEE/IANA 数据库（参见 `docs/system-overview.md`） - L7 检测仅限于协议识别和元数据提取 ## 已知限制 1. **TLS SNI 提取**：完整的 SNI 解析可能需要更深入的握手解析。当前实现捕获了更多的握手上下文并检测 TLS 版本。 2. **HTTP Host 头**：Host 提取取决于捕获的载荷中是否存在 header 字节，目前尚未解析绝对形式的 URI。 3. **DNS 响应解析**：从观察到的载荷窗口解析响应码和应答域名；完整的 RR-set 解析可能需要更深入的数据包捕获。 4. **加密流量**：无法检测加密载荷（TLS/HTTPS 内容）。 ## 路线图 - [ ] 用于分布式部署的 Redis 后端 - [x] 用于外部集成的 REST API - [x] 用于可视化的 Web 仪表盘 - [x] 使用机器学习的异常检测 - [x] IPv6 支持 - [x] 将 L7 载荷捕获扩展到 128-256 字节，以更好地提取 SNI/HTTP 头 - [x] 添加完善的 DNS 响应解析 - [x] 添加 HTTP Host 头提取 - [x] 实现 TLS 版本检测 - [x] 支持识别加密 DNS (DoH/DoT) - [x] 追踪 DNS 响应码和查询类型 - [x] 将 DNS 查询与后续连接相关联 - [x] 导出到 Prometheus/Grafana - [x] 自定义警报规则 - [x] GeoIP 位置追踪 ## 性能 - 使用 eBPF 环形缓冲区进行**零拷贝数据包处理** - 用于高效设备追踪的 **LRU 缓存** - 每 30 秒执行一次**批量数据库写入** - 借助内核级过滤实现**极低的 CPU 开销** - 通过可配置的缓存大小实现**内存高效** 有关在高链路吞吐量下 **Docker** 资源使用情况的示例（低 CPU/RSS，容器 NET I/O 通常为零，因为流量未被代理）记录在 **[`docs/deployment-and-performance.md`](docs/deployment-and-performance.md)** 中。 ## 兼容性 - **Go 版本**：1.24+ - **内核**：5.10+ 且支持 eBPF - **依赖项**：无外部运行时依赖 - **数据库**：向下兼容现有的 network.db 文件 ## 许可证 MIT 许可证 - 详情请参阅 LICENSE 文件 ## 贡献 欢迎贡献代码！请随时提交 Pull Request。 1. Fork 本仓库 2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交您的更改 (`git commit -m 'Add some amazing feature'`) 4. 推送到该分支 (`git push origin feature/amazing-feature`) 5. 发起一个 Pull Request ## 联系方式 [Mohamed Zrouga](https://zrouga.email) ## 致谢 - 基于 [Cilium ePF](https://github.com/cilium/ebpf) 构建 - 使用 [BuntDB](https://github.com/tidwall/buntdb) 进行存储 - 使用 [golang-lru](https://github.com/hashicorp/golang-lru) 进行缓存 - 受网络监控工具启发 ## 支持的发行版 Cerberus 已在以下 Linux 发行版上成功构建和测试： | 发行版 | 状态 | |--------------|--------| | Ubuntu 22.04 | 通过 | | Ubuntu 24.04 | 通过 | | Debian 12 | 通过 | | Arch Linux | 通过 | **使用 ❤️ 和 eBPF 构建**
标签：ARP监控, DNS分析, Docker镜像, EVTX分析, Go语言, HTTP分析, Linux网络工具, LRU缓存, MAC地址厂商识别, OUI查询, Redis, TCP监控, TLS握手分析, Web控制台, 内核态监控, 协议分析, 实时流量监控, 日志审计, 权限提升, 流量分类, 深度包检测, 程序破解, 网络安全, 网络安全分析, 网络安全审计, 网络测绘, 自定义请求头, 设备发现, 防御绕过, 隐私保护