MAMDOUHjr/threat-hunting-dashboard
GitHub: MAMDOUHjr/threat-hunting-dashboard
一款基于 Python 的桌面应用，通过 SSH 连接 Linux 虚拟机集群并运行 8 项自动化威胁狩猎检查，实现集中化安全日志分析与报告导出。
Stars: 0 | Forks: 0
# 🛡️ 威胁狩猎仪表板
一款生产级的 Python 桌面应用程序，用于通过 SSH 监控 Linux 虚拟机，收集安全日志，运行自动化威胁狩猎检查，并导出详细的调查结果报告。
## 📸 概览
该仪表板通过 SSH（基于密钥的身份验证）连接到 Linux 虚拟机，提取关键日志文件，并运行与实际 SOC 工作流程对齐的 8 项自动化威胁狩猎检查。结果将显示在深色主题的 GUI 中，并可导出为 TXT 或 JSON 格式。
## ✨ 功能
| 功能 | 详情 |
|---|---|
| 🖥️ GUI | 深色主题的 CustomTkinter 桌面应用程序 |
| 🔐 SSH | 通过 Fabric 3 + Paramiko 进行基于密钥的身份验证 |
| 🔍 检查 | 8 项内置威胁狩猎规则（与 MITRE 对齐） |
| 📄 报告 | 可读的 TXT + 机器可读的 JSON 导出 |
| ⚡ 并发 | 多线程的“Hunt All” — GUI 保持完全响应 |
| 📋 日志 | 应用程序日志位于 `logs/application.log` |
| 🐧 发行版支持 | 适用于 Debian/Kali/Ubuntu 以及 RHEL/CentOS |
## 📁 项目结构
```
threat_hunting_dashboard/
├── main.py # Entry point
├── requirements.txt # Python dependencies
├── config/
│ └── vms.json # VM fleet definitions (IPs, credentials)
├── gui/
│ ├── app.py # Main application window
│ ├── vm_card.py # Per-VM card widget
│ └── report_panel.py # Report viewer + export panel
├── transport/
│ └── ssh.py # SSH / Fabric wrapper (key-based auth)
├── hunting/
│ ├── models.py # Dataclasses: VMConfig, Finding, HuntReport
│ ├── checks.py # 8 threat-hunting check functions
│ └── engine.py # Hunt orchestrator + VM config loader
├── reports/
│ └── exports.py # TXT and JSON report export
└── logs/ # Application logs (auto-created at runtime)
```
## 🔧 要求
- **Python** 3.12+
- 对目标 Linux 虚拟机的 **基于 SSH 密钥的访问权限**
- 每台虚拟机上的 SSH 用户必须能够读取 `/var/log/` 文件（root 用户，或属于 `adm` 组的用户）
### Python 依赖项
```
customtkinter>=5.2.2
fabric>=3.2.2
paramiko>=3.4.0
Pillow>=10.2.0
```
## 🚀 安装说明
### 步骤 1 — 克隆代码库
```
git clone https://github.com/YOUR_USERNAME/threat-hunting-dashboard.git
cd threat-hunting-dashboard
```
### 步骤 2 — 创建虚拟环境
```
python3 -m venv .venv
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate # Windows
```
### 步骤 3 — 安装依赖项
```
pip install -r requirements.txt
```
## ⚙️ 配置
编辑 `config/vms.json` 来定义你的虚拟机集群：
```
[
{
"name": "kali-lab",
"host": "192.168.56.101",
"port": 22,
"username": "analyst",
"key_path": "~/.ssh/id_rsa",
"key_passphrase": null
}
]
```
| 字段 | 必填 | 描述 |
|---|---|---|
| `name` | ✓ | 仪表板中的显示标签 |
| `host` | ✓ | IP 地址或主机名 |
| `port` | 可选 | SSH 端口（默认：`22`） |
| `username` | 可选 | SSH 登录用户（默认：`root`） |
| `key_path` | 可选 | SSH 私钥路径（默认：`~/.ssh/id_rsa`） |
| `key_passphrase` | 可选 | 私钥的密码短语（`null` = 无） |
## 🔑 SSH 密钥设置
该仪表板使用**基于密钥的 SSH 身份验证**（无密码）。以下是设置方法：
### 在运行仪表板的机器上：
```
# 生成一个 SSH key pair（如果已有可跳过）
ssh-keygen -t rsa -b 4096 -C "threat-hunting-dashboard"
# 将 public key 复制到目标 VM
ssh-copy-id -i ~/.ssh/id_rsa.pub username@VM_IP
```
### 首先手动测试连接：
```
ssh -i ~/.ssh/id_rsa username@VM_IP
```
有关完整的 SSH 密钥设置指南，请参阅 [`SSH_KEY_SETUP_GUIDE.md`](SSH_KEY_SETUP_GUIDE.md)。
## ▶️ 运行应用程序
```
python main.py
```
## 🖱️ 使用说明
### 1. 测试连通性
- 在虚拟机卡片上点击 **[Test]** 以验证对该虚拟机的 SSH 访问。
- 点击 **[Test All]** 同时测试所有虚拟机。
### 2. 运行威胁狩猎
- 在虚拟机卡片上点击 **[Hunt]** 以收集日志并运行所有 8 项检查。
- 点击 **[Hunt All]** 在整个集群中运行并发狩猎。
- 结果将显示在右侧的 **Report Viewer** 面板中。
### 3. 导出报告
狩猎完成后：
- **[Export TXT]** → 保存为 `reports/report__.txt`
- **[Export JSON]** → 保存为 `reports/report__.json`
## 🔍 威胁狩猎检查
| # | 检查项目 | 严重程度 | 日志来源 |
|---|---|---|---|
| 1 | SSH 暴力破解检测 | 🔴 高 | `/var/log/auth.log` · `/var/log/secure` |
| 2 | 失败后的成功登录 | 🚨 严重 | `/var/log/auth.log` · `/var/log/secure` |
| 3 | Sudo 滥用 / 提权失败 | 🟠 中 | `/var/log/auth.log` · `/var/log/secure` |
| 4 | 新建用户 / 组 | 🔴 高 | `/var/log/auth.log` · `/var/log/secure` |
| 5 | 可疑的非工作时间 Cron 任务 | 🟠 中 | `/var/log/cron` |
| 6 | 软件包安装活动 | 🟡 低 | `/var/log/dpkg.log` · `/var/log/yum.log` |
| 7 | Audit 日志中的提权行为 | 🔴 高 | `/var/log/audit/audit.log` |
| 8 | 可疑的 Bash History 命令 | 🔴 高 | `~/.bash_history` |
## 📋 收集的日志文件
引擎从每台虚拟机上的以下路径收集（会妥善跳过缺失的文件）：
**Debian / Kali / Ubuntu:**
- `/var/log/auth.log`
- `/var/log/syslog`
- `/var/log/dpkg.log`
- `/var/log/kern.log`
**RHEL / CentOS / Fedora:**
- `/var/log/secure`
- `/var/log/messages`
- `/var/log/yum.log` · `/var/log/dnf.log`
**通用:**
- `/var/log/cron`
- `/var/log/audit/audit.log`
- `~/.bash_history`
## 📄 示例报告输出
```
============================================================
VM: kali-lab
Host: 192.168.56.101:22
Generated: 2026-06-03 14:00:00
============================================================
[CRITICAL]
Successful Login After Multiple Failures
----------------------------------------
Description:
IP 185.220.101.42 had 17 failed login attempts followed by a
successful authentication — possible account compromise.
Evidence:
IP address: 185.220.101.42 | Failure count: 17
Source: /var/log/auth.log
[HIGH]
SSH Brute Force Detected
----------------------------------------
Description:
Repeated SSH authentication failures detected from 185.220.101.42.
Evidence:
Failed password from 185.220.101.42 (17 times)
============================================================
SUMMARY
============================================================
Total Findings : 2
CRITICAL : 1
HIGH : 1
MEDIUM : 0
LOW : 0
Duration : 4.2s
============================================================
```
## 🏗️ 架构
```
main.py
└── gui/app.py ← Main window, spawns threads
├── gui/vm_card.py ← Per-VM widget (Test / Hunt buttons)
└── gui/report_panel.py ← Results display + export
└── hunting/engine.py ← Orchestrates one full hunt
├── transport/ssh.py ← SSH connection + log collection
└── hunting/checks.py ← 8 pure check functions
└── hunting/models.py ← Dataclasses
```
**设计原则：**
- **传输层**（`transport/ssh.py`）与 GUI 完全解耦 — 可独立用于脚本化/自动化狩猎。
- **检查函数**（`hunting/checks.py`）是纯函数：`dict[str, str] → list[Finding]` — 易于进行单元测试和扩展。
- **基于队列的结果传递**确保 GUI 线程永远不会被网络 I/O 阻塞。
- 全面采用的 **Dataclasses** 在所有层之间提供了清晰、类型化的数据契约。
## 🛠️ 故障排除
| 问题 | 解决方案 |
|---|---|
| `SSHError: SSH key not found` | 检查 `vms.json` 中的 `key_path`；确认该文件存在 |
| `Authentication failed` | 确认用户名无误，并且你的公钥已添加到虚拟机的 `~/.ssh/authorized_keys` 中 |
| `Network error connecting` | 确认虚拟机正在运行且可访问；检查防火墙/iptables 规则 |
| `No findings returned` | 用户可能没有日志文件的读取权限；尝试使用 root 或属于 `adm` 组的用户 |
| `customtkinter not found` | 在你的虚拟环境中运行 `pip install -r requirements.txt` |
| `Permission denied on log file` | 在目标虚拟机上运行 `sudo chmod o+r /var/log/auth.log` |
## 📜 许可证
本项目仅用于教育和实验室用途。欢迎自由 fork、扩展和在此基础上进行开发。
## 👥 团队
本项目是我们 NTI 网络安全培训期间合作完成的。
## | 姓名 | GitHub |
|---|---|
| Amr | [@MAMDOUHjr](https://github.com/MAMDOUHjr) |
| Gouda | [@7amada8088](https://github.com/7amada8088) |
| Youssef | [@YoussefMansour74](https://github.com/YoussefMansour74) |
| Saad | [@Sa3dHazem]( https://github.com/Sa3dHazem) |
| Badr | [@MohamedBadr9]( https://github.com/MohamedBadr9) |
标签：Linux监控, MIT 许可证, PB级数据处理, Python桌面应用, SSH自动化, Web报告查看器, 安全运维, 逆向工具