# eBPF-LLM-NetSentinel

**Repository Path**: colornix/eBPF-LLM-NetSentinel

## Basic Information

- **Project Name**: eBPF-LLM-NetSentinel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# eBPF-LLM NetSentinel

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

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-brightgreen.svg)](https://python.org)
[![Linux](https://img.shields.io/badge/platform-Linux-orange.svg)](https://kernel.org)

## 🌟 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

```bash
# 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

```bash
pip install -r requirements.txt
```

### 3. Configure LLM (Optional)

```bash
# Copy example config
cp .env.example .env

# Edit with your API key
nano .env
```

---

## 🚀 Quick Start

### Option 1: Monitor Only (No LLM)

```bash
# 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)

```bash
# 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

```bash
# 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)
```bash
# Set API key in .env file
ZHIPUAI_API_KEY=your_api_key_here
```

### Ollama Setup
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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
```bash
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
```bash
python3 test_unit.py
```

### Generate Test Traffic
```bash
# Start monitoring first, then in another terminal:
python3 test_connections.py --all
```

### Test Specific Scenarios
```bash
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
```bash
# eBPF requires root
sudo python3 unified_ebpf.py -i eth0
```

### "Interface not found" error
```bash
# 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
```bash
# Check API key is set
cat .env | grep API_KEY

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

### Dashboard not updating
```bash
# Install autorefresh extension
pip install streamlit-autorefresh
```

---

## 📄 License

MIT License - see [LICENSE](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:

```bibtex
@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](https://github.com/iovisor/bcc) - eBPF toolkit
- [Streamlit](https://streamlit.io/) - Dashboard framework
- [Zhipu AI](https://open.bigmodel.cn/) - GLM-4 API
- [Ollama](https://ollama.com/) - Local LLM runtime
- [HuggingFace](https://huggingface.co/) - Model hub