Wereluna/CodeAlpha_Network-Intrusion-Detection-System-using-Suricate-Snort-and-Python
GitHub: Wereluna/CodeAlpha_Network-Intrusion-Detection-System-using-Suricate-Snort-and-Python
一个基于 Python Scapy 的轻量级网络入侵检测系统，通过自定义规则引擎实时嗅探并识别常见网络攻击，提供可视化 Web 仪表板和自动化报告。
Stars: 0 | Forks: 0
# 🛡️ NIDS — Python 网络入侵检测系统
这是一个生产级别的、基于 Scapy 的网络入侵检测系统 (NIDS)，它可以嗅探实时网络流量，使用自定义的 Snort 风格规则引擎检测常见攻击模式，记录所有事件，并在实时 Web 仪表板上可视化结果。
作为 CodeAlpha 网络安全实习项目 — 任务 4 构建。
## ✨ 功能
- 使用 Scapy **捕获实时数据包**（源/目的 IP、协议、端口、TCP 标志、大小、时间戳、负载）
- **自定义检测规则引擎**（无需安装 Snort/Suricata）：
- 端口扫描检测
- Ping 扫描检测
- ICMP 泛洪检测
- SYN 泛洪检测
- 可疑 TCP 标志（NULL 扫描、XMAS 扫描）
- 畸形数据包检测
- 异常大数据包检测
- 黑名单/白名单 IP 匹配
- **彩色控制台告警**（Colorama + Rich）
- **结构化日志记录**：`alerts.log`、`network.log`、`attack_history.csv`
- **会话结束报告**：JSON + TXT 摘要
- **实时 Web 仪表板**（Flask + Chart.js）：饼图、柱状图、时间轴、实时告警信息流
- **模块化、文档齐全、符合 PEP8 标准的代码库**，包含异常处理和集中式配置文件
## 🏗️ 架构
```
┌─────────────────────┐
│ Live Network │
│ Traffic (NIC) │
└──────────┬───────────┘
│ raw packets
┌──────────▼───────────┐
│ packet_capture.py │ (Scapy sniff)
└──────────┬───────────┘
│ Packet object
┌──────────▼───────────┐
│ detection_engine.py │ rule engine
│ - port scan │
│ - ping sweep │
│ - flood detection │
│ - flag/malformed chk │
│ - blacklist check │
└──────────┬───────────┘
│ alert(type, severity, ips...)
┌──────────▼───────────┐
│ alert_manager.py │
└──┬──────┬─────────┬──┘
│ │ │
console alert alerts.log attack_history.csv
│
┌──────────▼───────────┐
│ dashboard/app.py │ Flask + Chart.js
└───────────────────────┘
```
### 流程图 (Mermaid)
```
flowchart TD
A[Start Capture] --> B[Sniff Packet - Scapy]
B --> C{Has IP Layer?}
C -- No --> B
C -- Yes --> D[Extract IP/Port/Protocol/Flags/Size]
D --> E[Log to network.log]
E --> F{Source IP Whitelisted?}
F -- Yes --> B
F -- No --> G[Run Detection Rules]
G --> H{Rule Triggered?}
H -- No --> B
H -- Yes --> I[Raise Alert]
I --> J[Console Alert - Colorama]
I --> K[Write alerts.log]
I --> L[Append attack_history.csv]
L --> M[Dashboard reads CSV]
B --> N{Stop Requested?}
N -- No --> B
N -- Yes --> O[Generate Session Report]
O --> P[End]
```
## 📂 文件夹结构
```
NIDS-Project/
├── README.md
├── requirements.txt
├── LICENSE
├── .gitignore
├── src/
│ ├── config.py # thresholds, paths, IP lists
│ ├── packet_capture.py # Scapy sniff wrapper
│ ├── detection_engine.py # rule engine (all detectors)
│ ├── alert_manager.py # alert formatting, logging, CSV
│ ├── logger_setup.py # logging configuration
│ ├── report_generator.py # JSON/TXT session reports
│ └── main.py # CLI entry point
├── rules/
│ └── rules.json # human-readable Snort-style rule docs
├── dashboard/
│ ├── app.py # Flask backend
│ └── templates/dashboard.html
├── logs/ # generated at runtime (gitignored)
├── sample_logs/ # example output for grading/demo
├── screenshots/ # place demo screenshots here
├── report/
│ └── NIDS_Project_Report.docx # full 35+ page academic project report
├── presentation/
│ └── NIDS_Presentation.pptx # 22-slide project presentation
└── docs/ # architecture notes
```
## ⚙️ 安装
```
git clone https://github.com//NIDS-Project.git
cd NIDS-Project
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
**仅限 Windows：** 安装 [Npcap](https://npcap.com/)（WinPcap 兼容模式），以便 Scapy 能够捕获数据包。
## ▶️ 用法
### 1. 运行 IDS（需要 root/管理员权限）
```
sudo python3 -m src.main
sudo python3 -m src.main --interface eth0 --filter "tcp or icmp"
sudo python3 -m src.main --count 500
```
按 `Ctrl+C` 停止捕获 — 会话报告将自动写入 `logs/session_report.json` 和 `logs/session_report.txt`。
### 2. 运行实时仪表板（在单独的终端中，无需 root 权限）
```
python3 dashboard/app.py
```
然后在浏览器中打开 **http://127.0.0.1:5000** 。它会读取 `logs/attack_history.csv` 并每 3 秒自动刷新一次，因此无论嗅探器是在本地运行还是您在查看过去会话的日志，它都能正常工作。
### 3. 生成测试流量以触发检测
从另一台机器/终端发起（需获得许可 — 仅限在您自己的实验网络中进行测试）：
```
nmap -sS # triggers Port Scan alert
ping -c 60 # can trigger ICMP Flood if run in a tight loop
nmap -sN # triggers NULL scan alert
```
## 🧪 示例输出
查看 `sample_logs/` 获取示例 `alerts.log`、`network.log`、`attack_history.csv` 以及由模拟测试运行（端口扫描、ICMP 泛洪、NULL 扫描、黑名单 IP）生成的会话报告。
## 🔭 后续改进
- 基于机器学习的异常检测（基于流量特征的 Isolation Forest / Random Forest）
- 邮件 / Telegram 告警集成
- 基于 GeoIP 的来源归属分析
- 可选的 Suricata/Snort 后端，用于大规模的基于特征的检测
- 云部署（容器化嗅探器 + 托管仪表板）
- 通过防火墙规则自动（模拟）阻断 IP
## ⚠️ 法律/道德声明
本工具仅供**教育用途和授权测试使用**（您自己的实验室、家庭网络，或您拥有明确书面授权可以监控的环境）。请勿在没有所有权或未经授权的情况下对网络运行此工具 — 在大多数司法管辖区，未经授权的数据包捕获和入侵测试是非法的。
## 📜 许可证
MIT 许可证 — 详见 [LICENSE](LICENSE)。
## 👤 作者
Luna — B.Tech CSE，诺伊达工程与技术学院 (NIET)
CodeAlpha 网络安全实习 — 任务 4
## 🙏 致谢
使用 Scapy、Flask、Chart.js、Rich 和 Colorama 构建。感谢 CodeAlpha 提供的项目机会。
标签：Flask, Scapy, 插件系统, 网络安全, 网络流量分析, 逆向工具, 配置错误, 隐私保护