VishvaNarkar/Mini-IDRS
GitHub: VishvaNarkar/Mini-IDRS
一个基于 Python 构建的教育型入侵检测与响应实验室系统，通过 Scapy 流量分析、插件化检测引擎和双层自动拦截机制，演示实时网络安全防护的完整工作流。
Stars: 2 | Forks: 0
# 迷你入侵检测与响应系统 (IDRS)
**一个基于 Python 构建、模块化的 IDS/IPS 实验室系统，专为 VMware Workstation Pro 设计。**
## 项目概述
Mini-IDRS 是一个教育性质的网络安全项目，具备以下功能：
- 使用 **Scapy** 捕获实时网络流量
- 使用**基于插件的引擎**检测攻击（每个检测器都是一个独立的模块）
- 通过**双层拦截**自动响应：
- Linux 防火墙 VM — `nftables FORWARD` DROP 规则（通过防火墙 REST API）
- 受害者 VM — `iptables INPUT` DROP 规则（通过 Paramiko SSH）
- 暴露 **REST API** (FastAPI) 以进行编程控制
- 提供直接从 IDS API (FastAPI) 提供服务或独立运行的**自定义 SOC 仪表盘** (HTML/CSS/JS)，具有实时 WebSockets 和 Apache ECharts 可视化功能。
- 将拦截的 IP 持久化到 `runtime/blocked.json` — 状态在监控器重启后依然保留
- 支持 **PCAP 重放**，无需实时攻击即可测试新的检测逻辑
## 核心功能
| 功能 | 详情 |
|---------|--------|
| **实时检测** | Scapy 数据包分析，每种攻击类型对应一个插件 |
| **模块化插件** | 只需在 `plugins/` 目录中放入文件即可添加检测器 |
| **FirewallManager 抽象** | 无需修改 IDS 逻辑即可切换 nftables → iptables → pfSense |
| **REST API 控制平面** | 版本化 (`/api/v1/`)，经过身份验证 (`X-API-Key`) |
| **仪表盘 → 仅与 IDS API 通信** | 仪表盘对防火墙/SSH 零了解 |
| **持久化** | `blocked.json` 在重启后保留；接口已准备好支持 SQLite |
| **动态阈值** | 通过仪表盘滑块实时更新 SYN/SSH 阈值 |
| **PCAP 重放** | 通过完整 pipeline 重放捕获的内容（`--dry-run` 模式） |
| **APScheduler** | 后台任务：健康检查、白名单重载、统计、清理 |
| **Docker 支持** | `docker compose up` 启动监控器 + IDS API（托管仪表盘） |
| **无需 GNS3/Cisco** | 纯 VMware 环境 — 一台 Linux 防火墙 VM 即可取代整个模拟路由器 |
## 架构
```
[Kali Attacker VM] ──┐
[Ubuntu Victim VM] ─┼── VMnet2 (Host-Only, 192.168.10.0/24)
[Ubuntu Monitor VM] ─┘ │
▼
┌──────────────────────────┐
│ Linux Firewall VM │
│ ens34: 192.168.10.1/24 │ ← dnsmasq DHCP
│ ens33: DHCP (VMnet8) │ ← NAT / internet
│ nftables FORWARD chain │ ← drops attacker traffic
│ Firewall API :8080 │ ← internal-only, API-key auth
└──────────────────────────┘
│
VMnet8 (NAT) → Internet
```
**控制流：**
```
Dashboard → IDS API → FirewallManager → Firewall API → nftables
IDS Monitor → detects → EventPipeline → FirewallManager + VictimBlocker
```
有关完整的图表和组件映射，请参见 [docs/architecture.md](docs/architecture.md)。
## 项目结构
```
Mini-IDRS/
├── core/ IDS engine modules
├── plugins/ Detection plugins (one per attack type)
├── ids_api/ IDS REST API (Monitor VM)
├── firewall_api/ Firewall REST API (Linux Firewall VM)
├── tools/ PCAP replay tool
├── docs/ Architecture, API, development, deployment guides
├── runtime/ Generated files (logs, blocked.json, pcaps) — gitignored
├── config.yaml.example Non-secret config template
├── .env.example Secrets template
├── idrs_monitor.py Entry point
├── dashboard/ Pure HTML/CSS/JS SOC Dashboard frontend
├── requirements.txt
├── docker-compose.yml
└── GATEWAY_CONFIG.md Linux Firewall VM setup guide
```
## 前置条件
- **VMware Workstation Pro**（无需 GNS3）
- **4 台 VM**：Linux 防火墙 (Ubuntu)、监控器 (Ubuntu)、受害者 (Ubuntu)、攻击者 (Kali)
- 监控器和 Linux 防火墙 VM 上需安装 **Python 3.11+**
- 监控器 VM 上需具备 Root/sudo 权限（用于 Scapy 原始套接字嗅探）
## 快速开始
### 1. Linux 防火墙 VM
请按照 [GATEWAY_CONFIG.md](GATEWAY_CONFIG.md) 进行操作 — 设置 nftables、dnsmasq 和防火墙 API 服务。
### 2. 监控器 VM
```
git clone https://github.com/VishvaNarkar/Mini-IDRS.git
cd Mini-IDRS
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# 配置
cp config.yaml.example config.yaml # Edit IPs
cp .env.example .env # Edit secrets (API keys, SSH creds)
# 创建运行时目录 + 初始白名单
mkdir -p runtime/logs runtime/pcaps runtime/cache
echo "192.168.10.1" > runtime/whitelist.txt # Firewall VM
echo "192.168.10.12" >> runtime/whitelist.txt # Monitor (this host)
```
### 3. 受害者 VM
```
sudo apt install openssh-server -y
sudo visudo # Add: victim ALL=(ALL) NOPASSWD: /sbin/iptables
```
### 4. 运行（在监控器 VM 上打开三个终端）
```
# Terminal 1 — IDS 监控
sudo venv/bin/python idrs_monitor.py -i ens33
# Terminal 2 — IDS API（在 http://localhost:5000/dashboard/index.html 提供 dashboard 服务）
uvicorn ids_api.server:app --host 0.0.0.0 --port 5000
# Terminal 3 — 独立 Dashboard Web 服务器（可选备选方案）
cd dashboard && python -m http.server 8080
# 在浏览器中打开 http://192.168.10.12:8080
```
或使用 Docker：
```
docker compose up -d
# Dashboard 可通过以下地址访问：http://192.168.10.12:5000/dashboard/index.html
```
## 检测能力
| 攻击 | 方法 | 严重程度 | 默认阈值 |
|--------|--------|----------|------------------|
| **XMAS 扫描** | TCP FIN+PSH+URG 标志 | 低 | 立即（任意数据包） |
| **SYN Flood** | 滑动窗口 SYN 计数 | 严重 | 5 秒内 25 个 SYN |
| **SSH 暴力破解** | 端口 22 上的 TCP 握手跟踪 | 高 | 60 秒内 8 次握手 |
可通过仪表盘实时调整阈值 — 无需重启。
## 攻击模拟（仅限 Kali VM）
```
nmap -sX 192.168.10.14 # XMAS scan
sudo hping3 -S 192.168.10.14 -p 22 --flood # SYN flood
hydra -l root -P wordlist.txt ssh://192.168.10.14 # SSH brute-force
```
**验证拦截：**
```
# Firewall VM
sudo nft list chain inet filter FORWARD
# Victim VM
sudo iptables -L INPUT -n -v
# IDS API
curl -H "X-API-Key: your-key" http://192.168.10.12:5000/api/v1/blocks
```
## PCAP 重放
无需实时攻击即可测试新的检测器：
```
# 捕获
sudo tcpdump -i ens33 -w runtime/pcaps/session.pcap
# 使用 dry-run 重放（不进行阻断）
python tools/replay.py --pcap runtime/pcaps/session.pcap --dry-run
# 完整 pipeline 重放
python tools/replay.py --pcap runtime/pcaps/session.pcap
```
## 文档
| 文件 | 内容 |
|------|----------|
| [docs/architecture.md](docs/architecture.md) | 系统设计、图表、组件映射 |
| [docs/api.md](docs/api.md) | 完整的 API 参考（包含两个 API） |
| [docs/development.md](docs/development.md) | 添加插件和防火墙后端 |
| [docs/deployment.md](docs/deployment.md) | 逐步的实验室设置指南 |
| [GATEWAY_CONFIG.md](GATEWAY_CONFIG.md) | Linux 防火墙 VM 配置 |
## 安全提示
- 凭据应放在 `.env` 中 — 永远不要放在 `config.yaml` 或源代码中
- 生成强 API 密钥：`python3 -c "import secrets; print(secrets.token_hex(32))"`
- 防火墙 API 仅绑定到内部接口 (`192.168.10.1:8080`)
- 请勿用于生产环境 — 这是一个实验室/教育系统
## 未来改进
- SQLite 数据库（替换 `BlockStore` 后端 — 接口已准备就绪）
- 基于 TTL 的拦截过期机制（`_cleanup_blocks` 任务已计划）
- 通过 Unix socket 而非 HTTP 使用 nftables（以实现更严格的安全性）
- 威胁情报集成 (AbuseIPDB)
- 基于 ML 的异常检测插件
- 额外的检测器：UDP flood、ICMP flood、ARP 欺骗、端口扫描
## 使用的库
`scapy` · `paramiko` · `fastapi` · `uvicorn` · `pyyaml` · `python-dotenv` · `requests` · `apscheduler` · `psutil` · `websockets`
## 许可证
MIT 许可证 — 详见 `LICENSE`。
## 作者
**Vishva Narkar** — 学生
**Himesh Nayak** — 学生
*iM.Sc. IT 架构与网络安全 — 古吉拉特大学*
## 致谢
感谢 Scapy、Paramiko、FastAPI 和 Apache ECharts 背后的开源社区。
标签：AV绕过, DNS 反向解析, FastAPI, iptables, Netmiko, Scapy, 入侵检测系统, 安全数据湖, 网络安全, 自动化防御, 请求拦截, 逆向工具, 隐私保护