shuvendu9207/NetShield
GitHub: shuvendu9207/NetShield
NetShield 是一个基于机器学习的网络入侵检测系统，通过对离线 PCAP 文件和实时网络流量进行流级特征提取与分类，自动识别六类常见网络攻击并生成安全警报。
Stars: 0 | Forks: 0
# NetShield：基于 AI 的网络入侵检测系统 (NIDS)
NetShield 是一个生产级、由 AI 驱动的网络入侵检测系统 (NIDS)，旨在分析网络流量并实时对网络威胁进行分类。结合了底层的数据包捕获技术、流追踪和机器学习分类器，NetShield 能够自动解析原始网络流量（PCAP 文件或实时网络适配器），执行特征提取，对流进行分类，针对恶意流量发出警报，并将所有历史日志记录到 PostgreSQL 数据库中。
## 1. 项目概述
在现代安全运营中，传统的基于特征的检测系统（如 Snort 或 Suricata）难以捕捉零日攻击或多态威胁。NetShield 通过使用基于网络流量特征训练的监督机器学习模型（Random Forest 和 XGBoost）弥补了这一空白。
### 核心目标：
* **零前端足迹**：纯后端 API 系统，带有交互式的 Swagger 文档。
* **双监控模式**：无缝支持离线 PCAP 文件取证上传和实时网络嗅探。
* **有状态的流追踪**：将 TCP/UDP 数据包重构为双向流。
* **确定性安全警报**：使用可配置的置信度和严重性阈值，将良性流量警报与已验证的威胁区分开来。
* **Docker 就绪**：预配置的多容器技术栈，具有自动关联的 FastAPI 和 PostgreSQL 服务。
## 2. 系统架构
NetShield 采用高度模块化、解耦的架构构建，包含 6 个核心子系统：
```
graph TD
A[Network Input: PCAP or Live Adapter] --> B[Packet Capture & Parser]
B --> C[Feature Extraction & Flow Tracker]
C --> D[ML Inference Engine: XGBoost/RF]
D --> E[Alert Engine: Threshold Rules]
D --> F[Database Layer: PostgreSQL]
E --> F
F --> G[FastAPI REST API Layer]
```
### 核心子系统：
1. **数据包解析器 (`src/packet_capture`)**：
使用 Scapy 的流式处理功能 (`PcapReader`) 解析数据包层属性，而无需将大型 PCAP 文件完全加载到内存中。实时监控会在后台执行线程中运行 Scapy 的嗅探循环。
2. **特征提取 (`src/feature_extraction`)**：
为通过 5 元组键 `(Src IP, Src Port, Dst IP, Dst Port, Protocol)` 定义的双向网络连接维护状态。当数据包到达时，流统计信息（例如持续时间、字节数、数据包/秒、TTL 平均值、TCP 标志组合）将实时更新。
3. **ML 推理引擎 (`src/inference`)**：
加载序列化的模型权重 (`model.pkl`)、缩放器和标签编码器。它将原始的 11 个网络流特征转换为标准化输入，并返回预测概率。
4. **警报引擎 (`src/alerts`)**：
监控预测结果。如果预测结果非 Benign 且其概率超过 $90\%$，则会触发高严重性警报。
5. **数据库集成 (`src/database`)**：
提供 `DetectionHistory` 和 `Alert` 表的 SQLAlchemy ORM 映射，在本地支持 SQLite 以便快速测试，并在生产 Docker 环境中支持 PostgreSQL。
6. **API 接口 (`src/api`)**：
FastAPI 路由层，暴露清晰的 HTTP endpoint，处理生命周期初始化、验证 schema 和数据库依赖。
## 3. 数据集与特征工程
NetShield 的分类器在 **CIC-IDS2017** 数据集上训练，该数据集包含良性流量以及常见的特定家族网络攻击。
### 分类标签：
* **Benign**：标准的非恶意网络流量。
* **DDoS**：分布式拒绝服务攻击。
* **PortScan**：主机发现和漏洞扫描尝试。
* **Bot**：Botnet Command and Control 通道通信。
* **BruteForce**：自动凭证破解 (SSH/FTP)。
* **WebAttack**：SQL 注入、跨站脚本 (XSS) 和暴力目录遍历。
### 提取的特征 Schema（11 个特征）：
在训练、PCAP 上传解析和实时网络捕获中，保证使用完全相同的特征提取 schema：
| 特征名称 | 描述 | 层来源 |
|---|---|---|
| **Protocol** | 传输层协议 ID（例如，TCP=6, UDP=17） | IP 层 |
| **Source Port** | 源连接端口 | TCP/UDP 层 |
| **Destination Port** | 目标连接端口 | TCP/UDP 层 |
| **Packet Length** | 流中所有数据包的平均大小 | IP/Ether 层 |
| **TTL** | 数据包的平均生存时间 | IP 层 |
| **TCP Flags** | 所有观察到的 TCP 控制标志的按位 OR 累积 | TCP 层 |
| **Flow Duration** | 第一个和最后一个数据包之间的时间差（以微秒为单位） | 系统/数据包时间 |
| **Packets Per Second** | 发送的总数据包数除以流持续时间 | 计算得出 |
| **Bytes Per Second** | 发送的总字节数除以流持续时间 | 计算得出 |
| **Forward Packets** | 源 $\rightarrow$ 目标方向传输的数据包计数 | 计算得出 |
| **Backward Packets** | 目标 $\rightarrow$ 源方向传输的数据包计数 | 计算得出 |
## 4. 本地安装指南
### 前置条件
* Python 3.10+
* 系统数据包捕获驱动程序：
* **Windows**：安装 [Npcap](https://npcap.com/)（确保勾选“Install Npcap in WinPcap API-compatible Mode”）。
* **Linux**：安装 libpcap：`sudo apt-get install libpcap-dev`
* **macOS**：安装 libpcap：`brew install libpcap`
### 本地开发设置：
1. 克隆项目并导航到项目目录：
cd NetShield
2. 创建并激活 Python 虚拟环境：
python -m venv venv
# 在 Windows (PowerShell) 上：
venv\Scripts\Activate.ps1
# 在 Linux/macOS 上：
source venv/bin/activate
3. 安装依赖项：
pip install -r requirements.txt
4. 复制环境模板：
copy .env.example .env
5. *（可选）* 如果您想重新生成模型，请运行模型训练 pipeline：
python -m src.training.train
6. 启动本地开发服务器（默认使用 SQLite）：
uvicorn src.api.app:app --reload --host 127.0.0.1 --port 8000
## 5. Docker 部署设置
NetShield 已完全使用 Docker 和 Docker Compose 进行容器化，编译了所有依赖项并挂载了一个独立的 PostgreSQL 数据库。
### 启动环境：
```
docker compose up --build
```
这将启动：
* `netshield_db`：暴露端口 `5432` 并具有卷持久性的 PostgreSQL 服务。
* `netshield_web`：暴露端口 `8000` 的 FastAPI 服务（取决于 `netshield_db` 的健康检查）。
### 在 Docker 内部嗅探主机适配器（仅限 Linux）：
默认情况下，Docker 容器在隔离的虚拟网络上运行。要在容器内对主机的实际网络接口运行实时嗅探，请取消注释 `docker-compose.yml` 中的网络配置选项：
```
# network_mode: "host"
# cap_add:
# - NET_ADMIN
```
## 6. API 文档与 Swagger 使用
当服务器运行时，可以通过以下地址访问交互式的 OpenAPI Swagger 页面：
**[http://localhost:8000/docs](http://localhost:8000/docs)**
### REST API endpoint 概述：
#### 1. 系统健康状态
* **方法**：`GET`
* **路由**：`/`
* **响应**：
{
"status": "healthy",
"service": "NetShield NIDS API",
"model_loaded": true
}
#### 2. PCAP 流量分析与分类
* **方法**：`POST`
* **路由**：`/predict`
* **Payload**：Form-Data（`file`：`.pcap` 或 `.pcapng` 格式）
* **响应**：
{
"message": "PCAP processed successfully.",
"total_flows": 1,
"predictions": [
{
"src_ip": "192.168.1.50",
"dst_ip": "10.0.0.99",
"src_port": 54321,
"dst_port": 80,
"protocol": 6,
"attack_type": "Benign",
"confidence": 99.96
}
]
}
#### 3. 获取存储的检测结果
* **方法**：`GET`
* **路由**：`/detections`
* **参数**：`limit`（默认值：100），`offset`（默认值：0）
#### 4. 获取安全警报
* **方法**：`GET`
* **路由**：`/alerts`
* **参数**：`limit`（默认值：100），`offset`（默认值：0）
#### 5. 列出接口
* **方法**：`GET`
* **路由**：`/monitor/interfaces`
#### 6. 开始实时嗅探
* **方法**：`POST`
* **路由**：`/monitor/start`
* **参数**：`interface`（查询字符串）
#### 7. 停止实时嗅探
* **方法**：`POST`
* **路由**：`/monitor/stop`
* **参数**：`interface`（查询字符串）
#### API 交互示例 (PowerShell)
## 7. 自动化测试套件
NetShield 附带了一整套使用 `pytest` 的单元测试和集成测试，以确保在部署更新时数据库连接、API 路由和机器学习组件能够继续正常工作。
要运行测试：
```
pytest -v
```
测试范围涵盖：
1. **conftest.py**：使用 `StaticPool` 创建内存中 SQLite 实例的共享测试上下文。
2. **test_alerts.py**：验证警报引擎的警报阈值规则。
3. **test_api.py**：测试 API endpoint 路由和请求验证 schema。
4. **test_database.py**：检查 ORM 模型、字段定义和数据库操作。
5. **test_feature_extraction.py**：确认 Scapy 数据包解码和流统计信息。
6. **test_inference.py**：验证模型工件加载和模型预测。
## 8. 未来改进与生产路线图
* **分布式嗅探**：在目标主机上部署轻量级的数据包捕获代理（例如，基于 Scapy/eBPF），将原始流指标转发到集中的 NetShield 预测微服务。
* **无监督异常检测**：添加 Autoencoder 模型，以检测不适合已知 CIC-IDS2017 监督标签的全新零日威胁模式。
* **通知集成**：扩展警报引擎，将高置信度的检测结果推送到消息 webhook（Slack/Teams）或 syslog 管理器 (SIEM)。
* **IP 封禁操作**：添加主动响应集成，动态编写 iptables/firewall 规则，以丢弃来自被标记为多个恶意警报的 IP 地址的流量。
标签：Apex, AV绕过, FastAPI, PCAP, PostgreSQL, 入侵检测系统, 安全数据湖, 安全规则引擎, 机器学习, 测试用例, 版权保护, 网络安全, 网络流量分析, 请求拦截, 逆向工具, 防御绕过, 隐私保护