The-Bugger/Net-Guard
GitHub: The-Bugger/Net-Guard
NetGuard 是一个完全离线运行的实时可解释入侵检测与防御系统，通过捕获网络流量自动检测多类攻击、生成纯文本告警并通过 iptables 自动封禁。
Stars: 3 | Forks: 0
# NetGuard — 可解释的入侵检测与防御系统
[](https://python.org)
[](#testing)
[](LICENSE)
[](https://flask.palletsprojects.com)
[](https://sqlalchemy.org)
[](https://github.com/The-Bugger)
NetGuard 是一个实时的、可解释的入侵检测与防御系统 (IDPS)，它
捕获实时的网络流量，检测八大类攻击，为每个警报生成通俗易懂的纯文本
说明，并通过 iptables 自动封禁攻击者 —— 所有这些都可以通过
实时的 SOC 风格仪表盘进行查看。
由 **[The Bugger](https://github.com/The-Bugger)** 为 2026 年 MVIC Build Nepal 黑客松构建。
完全离线运行在单台 Linux 机器上。无需云服务、专有硬件或代理。
## 目录
1. [功能](#features)
2. [快速开始](#quick-start)
3. [架构](#architecture)
4. [目录结构](#directory-structure)
5. [前置条件](#prerequisites)
6. [安装说明](#installation)
7. [配置](#configuration)
8. [环境变量](#environment-variables)
9. [运行 NetGuard](#running-netguard)
10. [API 参考](#api-reference)
11. [检测规则](#detection-rules)
12. [服务层](#service-layer)
13. [数据库 Schema](#database-schema)
14. [测试](#testing)
15. [演示攻击脚本](#demo-attack-scripts)
16. [技术栈](#technology-stack)
17. [评委模式](#judges-mode)
## 功能
| 功能 | 详情 |
|---------|--------|
| 实时数据包捕获 | 基于 Scapy；支持任何操作系统接口上的 TCP、UDP、ICMP、ARP |
| 8 项检测规则 | SYN Flood、端口扫描、SQL 注入、暴力破解、ARP 欺骗、ICMP Flood、慢速 HTTP、DNS 隧道 |
| 可解释警报 | 通俗易懂的纯文本说明、严重性、0–100 的置信度、可操作的建议 |
| 自动封禁 | 检测到后几秒内应用 iptables DROP 规则 |
| 自动过期 | 后台线程每 5 秒移除过期的封禁 |
| 白名单 | 受信任的 IP 免受封禁；内存集合查找复杂度为 O(1) |
| API key 认证 | 在所有进行修改操作的 endpoint 上强制执行 `X-API-Key` header 校验；采用常数时间比较 |
| 速率限制 | 每个客户端 IP 每 60 秒 120 次请求，带有 `Retry-After` header |
| 安全 header | CSP、HSTS、X-Frame-Options、X-Content-Type-Options、Referrer-Policy |
| REST API | 28+ 个 endpoint —— 监控、检测、封禁、白名单、统计、日志、分析、导出、AI 助手 |
| 实时仪表盘 | WebSocket KPI、流量图表、严重性图表、威胁时间轴、分析、AI 聊天 |
| SQLite 持久化 | 通过 SQLAlchemy ORM 记录事件、封禁、白名单、设置和日志 |
| 678 项测试 | 单元测试 + 基于属性的测试 + 集成测试 |
| 轮转日志文件 | system.log、detections.log、errors.log —— 每个最大 10 MB，5 个备份 |
| 导出 | 支持 JSON、CSV、Markdown 和 PDF（可选）的检测导出 |
| 分析 | 包含攻击细分的每小时 / 每天 / 每周检测图表 |
| AI 助手 | 针对每个事件的 Markdown 报告和聊天面板（stub / Gemini / OpenAI） |
| 演示模式 | 使用 RFC 5737 TEST-NET IP 持续生成合成攻击 |
## 快速开始
```
pip install -r requirements.txt
python -c "from database.init_db import initialize_db; initialize_db()"
sudo python backend/main.py
```
打开 **http://localhost:5000**。添加 `?judges=1` 可进入演示模式。
## 架构
### 系统概述
```
graph TB
NIC["Network Interface (eth0 / wlan0)"]
CE["CaptureEngine\nsniffer.py\nPacket_Capture_Thread"]
PD["PacketDecoder\npacket_decoder.py"]
PQ["packet_queue\nqueue.Queue maxsize=10000"]
DE["DetectionEngine\ndetection_service.py\nDetection_Thread"]
R1["SynFloodRule"]
R2["PortScanRule"]
R3["SqlInjectionRule"]
R4["BruteForceRule"]
R5["ArpSpoofRule"]
R6["IcmpFloodRule"]
R7["SlowHttpRule"]
R8["DnsTunnelRule"]
EE["ExplainabilityEngine\nexplain_service.py"]
PE["PreventionEngine\nprevention_service.py"]
LE["LoggingEngine\nlog_service.py\nLogging_Thread"]
ET["ExpiryThread\nexpiry_service.py"]
DB[(SQLite\nnetguard.db)]
API["Flask REST API\n+ Flask-SocketIO"]
DASH["Frontend Dashboard\nVanilla JS + Chart.js"]
NIC -->|raw packets| CE
CE -->|decode| PD
PD -->|Packet objects| PQ
PQ -->|consume| DE
DE --> R1 & R2 & R3 & R4 & R5 & R6 & R7 & R8
DE -->|ThreatEvent| EE
EE -->|Explanation| PE
EE -->|Explanation| LE
PE -->|iptables -I| NIC
LE -->|INSERT| DB
ET -->|poll 5s| DB
ET -->|iptables -D| NIC
DE -->|SocketIO emit| API
PE -->|SocketIO emit| API
API <-->|HTTP + WS| DASH
DB <-->|SQLAlchemy| API
```
### 线程模型
| 线程 | 模块 | 角色 |
|--------|--------|------|
| `Packet_Capture_Thread` | `detection/capture/sniffer.py` | Scapy `sniff()` → 解码数据包 → 放入 `packet_queue` |
| `Detection_Thread` | `backend/services/detection_service.py` | 消费 `packet_queue` → 运行全部 8 项规则 → 通过回调触发 `ThreatEvent` |
| `Logging_Thread` | `backend/services/log_service.py` | 消费 `event_queue` → 持久化到 SQLite 和日志文件 |
| `Expiry_Thread` | `backend/services/expiry_service.py` | 每 5 秒轮询数据库 → 移除过期的 iptables 规则 |
| `API_Thread` | Flask + eventlet | 提供 HTTP REST + WebSocket 服务 |
## 目录结构
```
NetGuard/
├── backend/
│ ├── api/
│ │ ├── __init__.py # Flask app factory + SocketIO init
│ │ └── dependencies.py # Service registry (populated by main.py)
│ ├── middleware/
│ │ ├── auth.py # X-API-Key authentication hook
│ │ ├── rate_limiter.py # Sliding-window rate limiter
│ │ └── security_headers.py # CSP / HSTS / Permissions-Policy headers
│ ├── repositories/
│ │ ├── event_repository.py
│ │ ├── block_repository.py
│ │ ├── whitelist_repository.py
│ │ ├── log_repository.py
│ │ └── settings_repository.py
│ ├── routes/
│ │ ├── health_routes.py # GET /health, GET /status
│ │ ├── monitor_routes.py # POST /monitor/start|stop, GET /interfaces
│ │ ├── detection_routes.py # GET /detections, GET /detections/{id}, POST /detect
│ │ ├── block_routes.py # POST /block|/unblock, GET /blocked
│ │ ├── whitelist_routes.py # GET|POST /whitelist, DELETE /whitelist/{ip}
│ │ ├── dashboard_routes.py # GET /dashboard, GET /dashboard/live
│ │ ├── stats_routes.py # GET /statistics, GET /statistics/rules
│ │ ├── evidence_routes.py # GET /evidence/{id}
│ │ ├── logs_routes.py # GET /logs
│ │ ├── settings_routes.py # GET|PUT /settings
│ │ ├── analytics_routes.py # GET /analytics
│ │ ├── export_routes.py # GET /export
│ │ ├── timeline_routes.py # GET /timeline/{event_id}
│ │ ├── ai_assistant_routes.py # POST /ai-assistant
│ │ ├── advisor_routes.py # GET /advisor
│ │ ├── lan_devices_routes.py # GET /lan-devices, POST /lan-devices/refresh
│ │ └── reset_routes.py # POST /reset (dev only)
│ ├── services/
│ │ ├── config_service.py # ConfigurationManager — loads/validates config.yaml
│ │ ├── detection_service.py # DetectionEngine — packet→rule→event pipeline
│ │ ├── explain_service.py # ExplainabilityEngine — ThreatEvent→Explanation
│ │ ├── ai_explain_service.py # AIExplainService — Gemini/OpenAI/stub enrichment
│ │ ├── prevention_service.py # PreventionEngine — iptables block/unblock
│ │ ├── expiry_service.py # ExpiryThread — auto-removes expired blocks
│ │ ├── whitelist_service.py # WhitelistManager — O(1) in-memory lookup
│ │ ├── monitor_service.py # MonitorService — start/stop/interface management
│ │ ├── log_service.py # LoggingEngine — async DB + file logging
│ │ ├── stats_service.py # StatsService — aggregation for dashboard
│ │ ├── lan_scan_service.py # LanScanService — ARP-based LAN device discovery
│ │ └── security_advisor.py # SecurityAdvisor — health score and advice
│ ├── utils/
│ │ ├── validators.py # IP + numeric range validation
│ │ └── response.py # Standard JSON envelope helpers
│ └── main.py # Application entry point + startup sequence
├── database/
│ ├── schema.py # SQLAlchemy ORM models (6 tables)
│ └── init_db.py # initialize_db() — creates tables + seeds defaults
├── detection/
│ ├── capture/
│ │ └── sniffer.py # CaptureEngine — Scapy sniff() wrapper
│ ├── parsers/
│ │ └── packet_decoder.py # PacketDecoder — raw Scapy → normalized Packet
│ └── rules/
│ ├── base_rule.py # BaseRule ABC + ThreatEvent + Explanation dataclasses
│ ├── syn_flood.py # SynFloodRule (SYN_FLOOD_001)
│ ├── port_scan.py # PortScanRule (PORT_SCAN_001)
│ ├── sql_injection.py # SqlInjectionRule (SQL_INJECT_001)
│ ├── brute_force.py # BruteForceRule (BRUTE_FORCE_001)
│ ├── arp_spoof.py # ArpSpoofRule (ARP_SPOOF_001)
│ ├── icmp_flood.py # IcmpFloodRule (ICMP_FLOOD_001)
│ ├── slow_http.py # SlowHttpRule (SLOW_HTTP_001)
│ └── dns_tunnel.py # DnsTunnelRule (DNS_TUNNEL_001)
├── frontend/
│ ├── css/dark-theme.css
│ ├── js/ # socket.js, api.js, dashboard.js, charts.js, shell.js, …
│ ├── index.html # Main dashboard (KPIs, charts, threat timeline)
│ ├── blocked.html # Active blocks management
│ ├── whitelist.html # Whitelist management
│ ├── threats.html # Full threat list with filters
│ ├── logs.html # Log viewer
│ ├── rules.html # Detection rule configuration
│ ├── settings.html # System settings form
│ ├── analytics.html # Charts and attack distribution
│ ├── timeline.html # Per-event incident timeline
│ ├── about.html / architecture.html
│ └── 404.html / 500.html
├── config/
│ └── config.yaml # Runtime configuration (thresholds, interface, etc.)
├── demo/
│ ├── attack_syn.sh # hping3 SYN flood demo
│ ├── attack_scan.sh # nmap port scan demo
│ ├── attack_sql.sh # curl SQL injection demo
│ ├── attack_bruteforce.sh # hydra brute force demo
│ └── attack_arp.sh # arpspoof ARP spoofing demo
├── docs/
│ ├── API.md # Full REST API reference
│ ├── ARCHITECTURE.md # Detailed architecture with Mermaid diagrams
│ ├── DATABASE.md # Database schema reference
│ ├── DEPLOYMENT.md # Production deployment guide
│ ├── TROUBLESHOOTING.md # Common problems and solutions
│ └── ROADMAP.md # Feature roadmap
├── logs/ # Rotating log files (auto-created)
├── scripts/
│ └── setup.sh # One-shot setup script
├── tests/ # 678+ unit + property-based + integration tests
├── .env # Environment variables (not committed)
├── .env.example # Environment variable documentation
├── requirements.txt # Pinned Python dependencies
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contributor guide
├── SECURITY.md # Security policy and threat model
├── INSTALL.md # Installation guide
└── DEPLOYMENT.md # Proxy trust model and deployment notes
```
## 前置条件
- **Python 3.11+**（已在 3.11、3.12、3.14 上测试）
- **Linux**（基于 iptables 的封禁所必需；检测和 API 在 Windows/macOS 上以 mock 模式工作）
- **Root / sudo**（Scapy 原始套接字捕获和 iptables 所必需）
- **iptables**（大多数 Linux 发行版上已预装）
### 可选工具（仅限演示脚本）
| 工具 | 脚本 | 安装 |
|------|--------|---------|
| `hping3` | `demo/attack_syn.sh` | `sudo apt install hping3` |
| `nmap` | `demo/attack_scan.sh` | `sudo apt install nmap` |
| `hydra` | `demo/attack_bruteforce.sh` | `sudo apt install hydra` |
| `arpspoof` | `demo/attack_arp.sh` | `sudo apt install dsniff` |
| `curl` | `demo/attack_sql.sh` | 通常已预装 |
## 安装说明
```
# 克隆 repository
git clone https://github.com/The-Bugger/Net-Guard.git
cd Net-Guard
# 创建 virtual environment
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# 自动化设置（Linux，需要 sudo）
sudo bash scripts/setup.sh
# ── 或者手动安装 ────────────────────────────────────────────────────
pip install -r requirements.txt
python -c "from database.init_db import initialize_db; initialize_db()"
# 复制并编辑环境变量
cp .env.example .env
# 编辑 .env — 至少设置 SECRET_KEY，可选设置 NETGUARD_API_KEY
```
有关针对特定平台的完整安装说明，请参阅 [INSTALL.md](INSTALL.md)。
## 配置
所有运行时设置都位于 **`config/config.yaml`** 中。编辑此文件即可调整
阈值，而无需改动源代码。通过
`PUT /api/v1/settings` 提交的更改将立即生效，无需重启。
```
# config/config.yaml
network_interface: "" # Interface to capture on (e.g. eth0, wlan0)
syn_flood_threshold: 150 # SYN packets per source IP to trigger detection
syn_flood_window: 3 # Sliding window in seconds
port_scan_threshold: 20 # Unique ports per source IP to trigger detection
port_scan_window: 10
brute_force_threshold: 10 # Auth failures per source IP to trigger detection
brute_force_window: 60
icmp_flood_threshold: 100 # ICMP echo requests per source IP to trigger detection
icmp_flood_window: 3
slow_http_threshold: 10 # Concurrent slow connections to trigger detection
slow_http_window: 10
block_duration: 120 # Auto-block duration in seconds
dashboard_refresh_interval: 1 # Dashboard polling interval in seconds
rules_enabled:
syn_flood: true
port_scan: true
sql_injection: true
brute_force: true
arp_spoof: true
icmp_flood: true
slow_http: true
dns_tunnel: true
debug: false
```
## 环境变量
有关每个变量的完整文档，请参阅 [`.env.example`](.env.example)。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SECRET_KEY` | `change-me-before-production` | Flask session 密钥 —— **在生产环境中必须设置**，否则应用拒绝启动 |
| `DATABASE_URL` | `sqlite:///database/netguard.db` | SQLAlchemy 数据库 URL |
| `LOG_LEVEL` | `INFO` | Python 日志级别 (`DEBUG`、`INFO`、`WARNING`、`ERROR`) |
| `FLASK_HOST` | `0.0.0.0` | 绑定地址；在反向代理后使用 `127.0.0.1` |
| `FLASK_PORT` | `5000` | 监听端口 |
| `FLASK_ENV` | `development` | Flask 环境；生产环境请设置为 `production` |
| `ALLOWED_ORIGINS` | `*` | 逗号分隔的 CORS 源；在生产环境中应进行限制 |
| `NETGUARD_API_KEY` | _(未设置)_ | 修改操作的 endpoint 的 `X-API-Key` header 中所需的共享 API key；未设置时，应用以无认证的开发模式运行 |
| `TRUST_PROXY_HEADERS` | `false` | 为 `true` 时，速率限制器从 `X-Forwarded-For` 读取客户端 IP；仅在受信任的反向代理后启用 |
| `REQUIRE_AUTH_FOR_READS` | `false` | 为 `true` 时，也会在 `GET` endpoint 上强制校验 `X-API-Key`；SocketIO 路径始终豁免 |
| `AI_PROVIDER` | `stub` | AI 说明提供者：`stub`、`gemini` 或 `openai` |
| `GEMINI_API_KEY` | _(未设置)_ | 当 `AI_PROVIDER=gemini` 时必需 |
| `OPENAI_API_KEY` | _(未设置)_ | 当 `AI_PROVIDER=openai` 时必需 |
| `SOCKETIO_ASYNC_MODE` | _(auto)_ | 在 Python 3.14+ 上强制使用 `threading`（自动设置） |
## 运行 NetGuard
```
# packet capture + iptables 需要 root 权限
sudo python backend/main.py
# Dashboard: http://localhost:5000
# API base: http://localhost:5000/api/v1
```
### 启动序列 (`backend/main.py`)
1. Eventlet monkey-patch（必须是第一个导入项）
2. 通过 `ConfigurationManager` 加载 `config/config.yaml`
3. 通过 `setup_logging()` 配置轮转日志 handler
4. 初始化 SQLite 数据库 (`initialize_db()`)
5. 构建 repository（EventRepository、BlockRepository 等）
6. 构建服务（LoggingEngine、WhitelistManager、PreventionEngine 等）
7. 验证 iptables 权限 (`PreventionEngine.verify_privileges()`)
8. 在依赖容器中注册所有服务
9. 创建 Flask 应用 + 注册所有路由 blueprint
10. 启动 `LoggingEngine` 线程
11. 启动 `ExpiryThread`
12. 启动 `DetectionEngine` 线程
13. 启动实时统计 SocketIO 后台任务
14. `socketio.run()` —— 在配置的 host:port 上提供 HTTP + WebSocket 服务
## API 参考
所有 endpoint 均位于 `http://localhost:5000/api/v1` 下。
**响应包装** (每个响应)：
```
{ "success": true, "message": "OK", "data": { ... } }
{ "success": false, "error": "Description", "error_code": "VALIDATION_ERROR" }
```
**认证：** 当设置了 `NETGUARD_API_KEY` 时，所有的 `POST`、`PUT`、`DELETE` 和 `PATCH`
请求必须包含 `X-API-Key: ` header。默认情况下 `GET` 请求是开放的
（设置 `REQUIRE_AUTH_FOR_READS=true` 可对其进行保护）。SocketIO 路径始终豁免。
### 核心 Endpoint
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/health` | 存活检查 |
| `GET` | `/status` | 监控状态、线程状态、数据包/封禁计数 |
| `POST` | `/monitor/start` | 开始捕获：`{"interface":"eth0"}` |
| `POST` | `/monitor/stop` | 停止捕获 |
| `GET` | `/monitor/interfaces` | 列出可用网络接口 |
| `GET` | `/dashboard` | 完整快照：KPI + 近期事件 + 活动封禁 |
| `GET` | `/dashboard/live` | 轻量级：`packets_per_second`、`active_threats`、`alerts_today` |
| `GET` | `/detections` | 分页列表；按 `severity`、`attack_type`、`source_ip`、`date` 过滤 |
| `GET` | `/detections/` | 通过 UUID 查询单个检测 |
| `POST` | `/detect` | 手动提交检测事件 |
| `GET` | `/evidence/` | 获取某次检测的完整 `Explanation` 对象 |
| `POST` | `/block` | 封禁 IP：`{"ip":"10.0.0.1","reason":"manual","duration":120}` |
| `POST` | `/unblock` | 解封：`{"ip":"10.0.0.1"}` |
| `GET` | `/blocked` | 包含 `expires_in` 倒计时的所有活动封禁 |
| `GET` | `/whitelist` | 列出所有受信任的 IP |
| `POST` | `/whitelist` | 添加受信任的 IP：`{"ip":"192.168.1.1","description":"gateway"}` |
| `DELETE` | `/whitelist/` | 从白名单中移除 IP |
| `GET` | `/statistics` | 按攻击类型和严重性聚合统计 |
| `GET` | `/statistics/rules` | 各规则检测统计（所有 8 项规则） |
| `GET` | `/logs` | 分页系统日志；按 `severity`、`date`、`module` 过滤 |
| `GET` | `/settings` | 返回当前配置 |
| `PUT` | `/settings` | 更新阈值；超出范围 → 422 VALIDATION_ERROR |
| `GET` | `/timeline/` | 逐步显示的事件时间轴 |
| `GET` | `/analytics` | 小时//周图表数据，严重性和攻击分布 |
| `GET` | `/export` | 导出事件：`?format=json\|csv\|markdown\|pdf` |
| `GET` | `/lan-devices` | 最近一次 ARP 扫描发现的局域网设备 |
| `POST` | `/lan-devices/refresh` | 触发新的 ARP 扫描 |
| `GET` | `/advisor` | 安全建议和健康评分 |
| `POST` | `/ai-assistant` | 与 AI 安全助手聊天：`{"question":"..."}` |
### 演示 Endpoint
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/demo/start` | 开始持续生成合成攻击 |
| `POST` | `/demo/stop` | 停止演示发射循环 |
| `POST` | `/demo/trigger` | 触发一次合成事件：`{"attack_type":"SQL Injection"}` |
| `GET` | `/demo/status` | 当前演示 session 状态 |
包含请求/响应 schema 的完整 API 文档：[`docs/API.md`](docs/API.md)
### Socket.IO 事件
| 事件 | Payload | 描述 |
|-------|---------|-------------|
| `new_threat` | `{event_id, attack_type, source_ip, severity, confidence, timestamp, blocked}` | 检测到新威胁 |
| `ip_blocked` | `{ip, reason, expires_at}` | IP 被封禁 |
| `ip_unblocked` | `{ip}` | IP 被解封（手动或过期） |
| `live_stats` | `{packets_per_second, active_threats, alerts_today}` | 监控期间每秒发射 |
| `monitoring_status` | `{active: bool, interface: string}` | 监控已开始或停止 |
## 检测规则
| 规则 | 规则 ID | 攻击类型 | 阶段 |
|------|---------|-------------|-------|
| `SynFloodRule` | `SYN_FLOOD_001` | TCP SYN Flood | 基准 |
| `PortScanRule` | `PORT_SCAN_001` | 端口侦察 | 基准 |
| `SqlInjectionRule` | `SQL_INJECT_001` | SQL 注入 (HTTP) | 基准 |
| `BruteForceRule` | `BRUTE_FORCE_001` | 暴力破解登录 | 基准 |
| `ArpSpoofRule` | `ARP_SPOOF_001` | ARP 欺骗 / 中间人攻击 | 基准 |
| `IcmpFloodRule` | `ICMP_FLOOD_001` | ICMP Flood / Smurf 攻击 | v1.1 |
| `SlowHttpRule` | `SLOW_HTTP_001` | 慢速 HTTP / Slowloris | v1.1 |
| `DnsTunnelRule` | `DNS_TUNNEL_001` | DNS 隧道（启发式） | v1.1 |
所有规则均实现了 `BaseRule` 接口：`initialize / process_packet / evaluate / explain / cleanup`。
每条规则通过针对每个 `(source_ip, rule_name)` 的 10 秒冷却期触发，以防止警报风暴。
发生未捕获异常时，故障规则将在当前 session 中被禁用（而非全局禁用），并可通过 `reload_rules()` 恢复。
有关完整的 pipeline 详情，请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
## 服务层
| 服务 | 模块 | 职责 |
|---------|--------|----------------|
| `DetectionEngine` | `detection_service.py` | 多规则 pipeline；冷却控制；单规则异常隔离 |
| `ExplainabilityEngine` | `explain_service.py` | `ThreatEvent → Explanation`；攻击类型模板；<50 毫秒 |
| `AIExplainService` | `ai_explain_service.py` | 结合 MITRE ATT&CK 上下文的 Gemini/OpenAI/stub 丰富化 |
| `PreventionEngine` | `prevention_service.py` | iptables 封禁/解封；私有 IP 防护；权限检查 |
| `ExpiryThread` | `expiry_service.py` | 每 5 秒自动移除过期的封禁 |
| `WhitelistManager` | `whitelist_service.py` | 由 SQLite 支持的 O(1) 内存集合；线程安全的 RLock |
| `LoggingEngine` | `log_service.py` | 异步日志线程；三个轮转文件；敏感 key 脱敏 |
| `ConfigurationManager` | `config_service.py` | 带有内置默认值的 YAML 配置；范围验证；线程安全 |
| `MonitorService` | `monitor_service.py` | 通过 psutil 进行接口验证；启动/停止协调 |
| `StatsService` | `stats_service.py` | 滚动 PPS 计数器；仪表盘统计聚合；健康评分 |
| `LanScanService` | `lan_scan_service.py` | 带有缓存的基于 ARP 的局域网设备发现 |
| `SecurityAdvisor` | `security_advisor.py` | 基于健康评分和攻击类型的上下文建议 |
## 数据库 Schema
`database/schema.py` 中的六个 SQLAlchemy ORM 表：
| 表 | 用途 |
|-------|---------|
| `events` | 包含证据、说明和建议的每个被检测到的威胁事件 |
| `blocked_ips` | 具有过期时间戳的活动及历史防火墙封禁 |
| `whitelist` | 免受自动封禁的受信任 IP |
| `detection_rules` | 带有阈值和启用状态的可配置规则 |
| `settings` | 键值对配置存储（映射 `config.yaml`） |
| `system_logs` | 用于仪表盘日志查看器的操作日志条目 |
有关完整的列级文档，请参阅 [`docs/DATABASE.md`](docs/DATABASE.md)。
## 测试
```
# 运行全部 678 个带有 coverage 的测试
pytest --cov=backend --cov=detection --cov=database --cov-report=term-missing
# 仅 Unit tests（快速，无网络）
pytest tests/ -k "not integration"
# 仅 Property-based tests
pytest tests/ -k "hypothesis"
```
测试套件包括单元、基于属性的 以及完整的 API 集成测试。
所有路由 blueprint 均已通过 mock 服务进行了覆盖测试。
## 演示攻击脚本
在 NetGuard 运行期间，从第二个终端运行：
```
sudo bash demo/attack_syn.sh # SYN flood (requires hping3)
bash demo/attack_scan.sh # Port scan (requires nmap)
bash demo/attack_sql.sh # SQL inject (requires curl)
bash demo/attack_bruteforce.sh # Brute force (requires hydra)
sudo bash demo/attack_arp.sh # ARP spoof (requires dsniff)
```
## 技术栈
| 组件 | 技术 | 版本 |
|-----------|------------|---------|
| REST API | Flask | 3.0.3 |
| WebSocket | Flask-SocketIO + eventlet | 5.3.6 + 0.36.1 |
| 数据包捕获 | Scapy | 2.5.0 |
| 数据库 ORM | SQLAlchemy | 2.0.51 |
| 数据库 | SQLite | (标准库) |
| 配置 | PyYAML | 6.0.2 |
| 环境 | python-dotenv | 1.0.1 |
| 系统信息 | psutil | 6.1.0 |
| 测试 | pytest + Hypothesis | 8.3.3 + 6.115.6 |
| 前端 | 原生 JS ES6 + Chart.js + Socket.IO 客户端 | — |
## 评委模式
将 **`?judges=1`** 添加到任何 URL 即可激活演示模式：
- 仪表盘顶部会出现一个紫色/青色的横幅。
- 演示模式自动启动，生成实时的合成攻击流量。
- **"Next Feature →"** 按钮可循环切换演示脚本：演示模式 → AI 说明 → 分析 → 导出 → 时间轴。
## 许可证
MIT 许可证 —— 详见 [LICENSE](LICENSE)
© 2026 [The Bugger](https://github.com/The-Bugger)
## 贡献
有关开发环境设置、编码规范和 PR 流程，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
有关威胁模型和漏洞报告政策，请参阅 [SECURITY.md](SECURITY.md)。
标签：CISA项目, Flask, iptables, Scapy, 入侵检测与防御系统, 安全运营中心, 插件系统, 网络映射, 网络流量分析, 网络测绘, 逆向工具, 配置错误