eBPF-LLM NetSentinel

🛡️ Intelligent network threat detection and blocking system based on eBPF XDP, with AI-powered threat analysis supporting multiple LLM backends.

🌟 Highlights

• Real-time Monitoring: eBPF kprobe monitors ALL outbound TCP connections
• Kernel-level Blocking: XDP drops malicious packets BEFORE they reach the TCP/IP stack
• AI-Powered Analysis: Three LLM backend options (Cloud, Local, Offline)
• Human-in-the-Loop: Critical threats require manual approval before blocking
• Beautiful Dashboard: Streamlit-based web UI with real-time updates

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              USER SPACE                                     │
│                                                                             │
│   ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────────┐  │
│   │   Dashboard     │     │  llm_analyzer   │     │   unified_ebpf      │  │
│   │  (Streamlit)    │────▶│     .py         │◀────│       .py           │  │
│   │                 │     │                 │     │                     │  │
│   │  • View events  │     │ • AI analysis   │     │ • Load eBPF progs   │  │
│   │  • Ban/Unban IP │     │ • Threat detect │     │ • Process events    │  │
│   │  • HITL review  │     │ • 3 LLM options │     │ • Execute bans      │  │
│   └─────────────────┘     └─────────────────┘     └──────────┬──────────┘  │
│            │                       │                         │              │
│            └───────────────────────┼─────────────────────────┘              │
│                          JSON Files (IPC)                                   │
├─────────────────────────────────────┼───────────────────────────────────────┤
│                              KERNEL SPACE                                   │
│                                     │                                       │
│   ┌─────────────────┐     ┌────────▼────────┐                              │
│   │   kprobe        │     │      XDP        │                              │
│   │ tcp_v4_connect  │     │   IP Filter     │                              │
│   │                 │     │                 │                              │
│   │ Monitors ALL    │     │ Drops banned    │                              │
│   │ TCP connects    │     │ IPs at NIC      │                              │
│   └─────────────────┘     └─────────────────┘                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

✨ Features

Feature	Description
🔍 eBPF kprobe	Monitor all outbound TCP connections with process info
🚫 eBPF XDP	High-speed IP blocking at NIC driver level (fastest possible)
🤖 Multi-LLM Support	Zhipu AI (cloud), Ollama (local), HuggingFace (offline)
📊 Streamlit Dashboard	Real-time visualization and one-click management
👤 Human-in-the-Loop	HIGH/CRITICAL threats require manual confirmation
⚙️ Hot-Reload Config	Change LLM settings without restarting
📝 Whitelist System	Exclude trusted IPs, processes, and ports

---

📦 Installation

1. System Dependencies

# Ubuntu/Debian
sudo apt update
sudo apt install python3-bcc linux-headers-$(uname -r)

# Fedora
sudo dnf install python3-bcc kernel-devel

2. Python Dependencies

pip install -r requirements.txt

3. Configure LLM (Optional)

# Copy example config
cp .env.example .env

# Edit with your API key
nano .env

---

🚀 Quick Start

Option 1: Monitor Only (No LLM)

# 1. Find your network interface name (e.g., eth0, enp3s0, wlan0)
ip link show

# 2. Start monitoring (REPLACE 'eth0' with your actual interface name!)
sudo python3 -u unified_ebpf.py -i eth0

Option 2: Full Pipeline (With AI Analysis)

# Terminal 1: Start eBPF + LLM pipeline
# ⚠️ IMPORTANT: Replace 'eth0' with your interface name
sudo sh -c "python3 -u unified_ebpf.py -i eth0 | python3 -u llm_analyzer.py"

# Terminal 2: Start Dashboard
streamlit run dashboard.py

Then open http://localhost:8501 in your browser.

Option 3: Using Different LLM Backends

# Use Zhipu AI (Cloud - default, requires API key)
# Remember to replace 'eth0' with your interface!
sudo sh -c "python3 -u unified_ebpf.py -i eth0 | python3 -u llm_analyzer.py --backend zhipuai"

# Use Ollama (Local - requires Ollama installed)
sudo sh -c "python3 -u unified_ebpf.py -i eth0 | python3 -u llm_analyzer.py --backend ollama"

# Use HuggingFace (Offline - downloads model automatically)
sudo sh -c "python3 -u unified_ebpf.py -i eth0 | python3 -u llm_analyzer.py --backend huggingface"

---

🤖 LLM Backend Comparison

Backend	Pros	Cons	Best For
Zhipu AI	Best accuracy, easy setup	Requires internet, API cost	Production use
Ollama	Good privacy, no API key	Requires Ollama install	Privacy-conscious users
HuggingFace	Fully offline, customizable	High GPU memory needed	Air-gapped environments

Zhipu AI Setup (Default)

# Set API key in .env file
ZHIPUAI_API_KEY=your_api_key_here

Ollama Setup

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull qwen3:8b

# Run with Ollama backend
python3 llm_analyzer.py --backend ollama

HuggingFace Setup

# Install dependencies
pip install transformers torch accelerate

# Run with HuggingFace backend (auto-downloads model)
python3 llm_analyzer.py --backend huggingface --hf-model Qwen/Qwen2.5-1.5B-Instruct

# With 4-bit quantization (saves GPU memory)
pip install bitsandbytes
python3 llm_analyzer.py --backend huggingface --hf-quantize 4bit

---

🚫 IP Ban Operations

Via Dashboard

1. Go to http://localhost:8501
2. Enter IP in sidebar → Click "🚫 Ban IP"

Via Command Line

# Ban an IP
echo '[{"action": "ban", "ip": "1.2.3.4", "reason": "Malicious scan"}]' > records/ban_commands.json

# Unban an IP
echo '[{"action": "unban", "ip": "1.2.3.4"}]' > records/ban_commands.json

Verify Ban Effect

# Before ban
ping 8.8.8.8  # ✅ Normal response

# After ban
ping 8.8.8.8  # ❌ 100% packet loss (XDP dropped)

---

📁 Project Structure

LLMWebPacketFilter/
├── unified_ebpf.py      # Core: eBPF kprobe + XDP blocking
├── llm_analyzer.py      # AI: Multi-backend threat analysis
├── dashboard.py         # UI: Streamlit web interface
├── user_whitelist.py    # Lib: User-defined whitelist management
├── test_connections.py  # Test: Generate network events
├── test_unit.py         # Test: Unit tests
├── requirements.txt     # Deps: Python packages
├── .env.example         # Config: Environment template
├── filter_config.json   # Config: Whitelist rules
└── records/             # Data: Runtime JSON files
    ├── banned_ips.json
    ├── ban_commands.json
    ├── pending_threats.json
    ├── dashboard_logs.json
    └── llm_config.json

---

⚙️ Command Line Options

unified_ebpf.py

sudo python3 unified_ebpf.py --help

Options:
  -i, --interface   Network interface (default: eth0)
  --no-xdp          Disable XDP blocking (monitor only)
  --ban IP          Ban IP at startup (repeatable)

llm_analyzer.py

python3 llm_analyzer.py --help

Options:
  --backend         LLM backend: zhipuai, ollama, huggingface
  --hf-model        HuggingFace model name or path
  --hf-device       Device: auto, cuda, cpu
  --hf-quantize     Quantization: none, 4bit, 8bit
  --clear           Clear all data files on start

---

📊 Threat Classification

Level	Emoji	Description	Action
CRITICAL	🔴	Port scan, nmap, malware	→ HITL Review
HIGH	🟠	Suspicious ports (23, 445, 3389)	→ HITL Review
MEDIUM	🟡	Unusual but not malicious	Logged
INFO	🟢	Normal connections	Logged

---

🛡️ System Requirements

Component	Minimum	Recommended
Linux Kernel	5.4+	5.15+
Python	3.8+	3.10+
RAM	2GB	8GB (for HuggingFace)
GPU	None	NVIDIA (for HuggingFace)

Required packages:

• BCC (BPF Compiler Collection)
• Root privileges (for eBPF)

---

📝 Testing

Run Unit Tests

python3 test_unit.py

Generate Test Traffic

# Start monitoring first, then in another terminal:
python3 test_connections.py --all

Test Specific Scenarios

python3 test_connections.py normal  # INFO level events
python3 test_connections.py high    # HIGH level events (suspicious ports)
python3 test_connections.py scan    # CRITICAL level (port scan simulation)

---

🔧 Troubleshooting

"Permission denied" error

# eBPF requires root
sudo python3 unified_ebpf.py -i eth0

"Interface not found" error

# 1. List available interfaces
ip link show

# 2. Use correct interface name (REPLACE 'eth0' with yours, e.g., 'wlan0', 'enp3s0')
sudo python3 unified_ebpf.py -i enp0s3

LLM not responding

# Check API key is set
cat .env | grep API_KEY

# Test Ollama connection
curl http://localhost:11434/api/tags

Dashboard not updating

# Install autorefresh extension
pip install streamlit-autorefresh

---

📄 License

MIT License - see LICENSE file.

---

---

📚 Authors

This project is a joint research effort by three exchange students from Hong Kong University of Science and Technology (HKUST) at École Polytechnique Fédérale de Lausanne (EPFL) during the Fall 2025-26 semester.

CS-477 Advanced Operating Systems Research Project

Author	Affiliation	Role
Fangzhou Liang	HKUST / EPFL	Co-Author (Equal Contribution)
Hongrui Li	HKUST / EPFL	Co-Author (Equal Contribution)
Zongmin Zhang	HKUST / EPFL	Co-Author (Equal Contribution)

---

🔗 Citation

If you use eBPF-LLM NetSentinel in your research or project, please cite it as:

@misc{eBPF-LLM-NetSentinel,
  author = {Liang, Fangzhou and Li, Hongrui and Zhang, Zongmin},
  title = {eBPF-LLM NetSentinel: Intelligent Network Threat Detection System},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/NagatoBigSeven/eBPF-LLM-NetSentinel}},
  note = {HKUST/EPFL CS-477 Advanced Operating Systems Research Project}
}

🙏 Acknowledgments

• BCC - eBPF toolkit
• Streamlit - Dashboard framework
• Zhipu AI - GLM-4 API
• Ollama - Local LLM runtime
• HuggingFace - Model hub