huanghfzhufeng/malware-analysis-tool
GitHub: huanghfzhufeng/malware-analysis-tool
基于PyQt5的一体化恶意软件分析平台，集成静态分析、动态沙箱执行、图神经网络分类与威胁情报查询，帮助安全研究人员高效完成恶意样本的多维度分析。
Stars: 0 | Forks: 0
# 🛡️ 恶意软件分析工具 (Malware Analysis Tool)
基于 PyQt5 的桌面端恶意软件分析平台，集成静态分析、动态沙箱、图神经网络分类与威胁情报查询。
## ⚠️ 安全使用守则（请先阅读）
### 各模块风险等级
| 模块 | 是否会执行样本 | 在主机上跑 |
|------|--------------|-----------|
| 静态分析（YARA / PE / AST / 熵） | ❌ 否，只读字节流 | 🟢 安全 |
| GNN 分析（CFG 提取 + 分类） | ❌ 否 | 🟢 安全 |
| 威胁情报（VirusTotal / MITRE） | ❌ 否，只发 hash | 🟢 安全 |
| **动态分析**（Frida spawn 真实进程） | ✅ **是，会真跑** | 🔴 **必须在 VM 里** |
### 内置安全防线
1. **样本运行守卫**：`lynx_sample.py` / `病毒样本.py` 顶部会检查 `MALWARE_SANDBOX_OK=yes` 环境变量，未设置则 `sys.exit(1)`，防止误双击 / 误 import / 误命令行启动。
2. **路径校验**：动态分析器对 Frida `spawn` 目标做 `realpath` 解析，拒绝 shell 元字符与系统关键路径（`Windows\System32`、`/proc`、`/sys`）。
3. **凭据隔离**：API key 仅从环境变量 `VIRUSTOTAL_API_KEY` 读取，已移除明文文件回退。
4. **不再 import 即跑**：移除了 `lynx_sample.py` 末尾"被 import 时自动执行 reconnaissance"的分支。
### 跑动态分析前的检查清单
- [ ] 当前是隔离 VM（Hyper-V / VMware / VirtualBox），**不是物理主机**
- [ ] VM 网络已切到 Internal/Private 或断网
- [ ] 已从干净的 baseline 快照恢复
- [ ] 接受"分析完直接还原快照"，不会带任何产物回主机
- [ ] 已经 `export MALWARE_SANDBOX_OK=yes`（或 PowerShell 的 `$env:MALWARE_SANDBOX_OK = 'yes'`）
任意一项 ❌ → **不要跑**。
## ✨ 主要特性
### 🔍 静态分析
- YARA 规则匹配（`rules/` 目录递归加载）
- PE 文件解析（pefile）：DOS/NT 头、节信息、导入/导出表
- ELF 文件支持（lief）
- PDF 检测（PyPDF2）：JavaScript 与可疑元数据
- Python AST：可疑导入、调用、字符串常量
- Shannon 熵计算
### 🚀 动态分析
- Frida 实时 API hook 与进程行为监控
- 多沙箱后端：本地 / Cuckoo Sandbox / QEMU（通过 `SANDBOX_BACKEND` 切换）
- 反检测的 stealth Frida 脚本
- 路径校验、超时控制、自动进程清理
- 精细化错误分类（`ErrorType` enum + 结构化 `AnalysisResult`）
### 🧠 图神经网络分析
- 控制流图（CFG）提取
- PyTorch Geometric 二分类模型（节点特征维度 16）
- GNNExplainer 可解释性输出
- CogDL 模型扩展（GAT / GCN 等可选）
### 🌐 威胁情报
- VirusTotal v3 API（hash 查询，超时 5s，缓存 12 小时）
- MITRE ATT&CK 技术匹配（缓存 7 天）
- 限流 / 超时自动回退到模拟数据，不阻塞 UI
### 🎨 用户界面
- 现代化主题与响应式布局
- 静态 / 动态 / GNN 多 Tab 可视化
- 内存与系统资源监控线程
## 🚀 快速开始
### 环境要求
- Python 3.10+（CI 使用 3.10）
- Windows 10/11（主要支持）
- 8GB+ RAM
- 动态分析需要管理员权限 + 隔离 VM
### 安装依赖
pip install -r requirements.txt
# 如果 PyTorch / torch-geometric 安装失败，参考 CogDL_安装指南.md 中的分阶段安装步骤
### 配置环境变量
复制 `.env.example` 为 `.env` 并填入：
# 可选：VirusTotal API key（不设则使用模拟数据）
VIRUSTOTAL_API_KEY=your_key_here
# 可选：沙箱后端
SANDBOX_BACKEND=local # local | cuckoo | qemu
CUCKOO_API_URL=http://localhost:8090
CUCKOO_API_TOKEN=
### 运行
python main.py
# 或以管理员权限（动态分析需要）
.\run_as_admin.ps1
## 📁 项目结构
.
├── main.py # 应用入口
├── gui.py # 主窗口与 UI 编排（1176 行）
├── settings.py # 配置常量与环境变量读取
├── security.py # Shannon 熵计算
│
├── static.py # 静态分析（YARA/PE/ELF/PDF/AST）
├── dynamic_improved.py # 动态分析（Frida + 沙箱后端）
├── gnn.py # GNN 分类器
├── gnn_utils.py # GNN 辅助函数
├── gnn_improvements.py # 真实 CFG 提取（angr）+ GNNExplainer
├── real_feature_extractor.py # AST/PE 特征提取
├── cogdl_integration.py # CogDL 模型适配层
├── threat_intel.py # VirusTotal + MITRE ATT&CK
├── vis.py # matplotlib + networkx 可视化
├── modern_theme.py # PyQt5 主题与样式
│
├── lynx_sample.py # ⚠️ APT 行为模拟样本（含真实持久化）
├── 病毒样本.py # ⚠️ 勒索软件行为模拟（含真实破坏操作）
├── malicious_like_sample.py # 安全的"恶意行为"测试样本（自清理）
├── lynx_ransom.txt # 勒索文本占位
│
├── rules/ # YARA 规则目录
├── config/ # 配置文件目录
├── cache/ # 威胁情报查询缓存（已 gitignore）
├── tests/ # pytest 测试套件
├── .github/workflows/ # GitHub Actions CI
│
├── requirements.txt
├── pytest.ini
├── .env.example # 环境变量模板
├── .gitignore
└── CogDL_安装指南.md # CogDL 分阶段安装指南
## 📊 使用指南
GUI 启动后顶部按钮区从左到右：
1. **📁 选择文件** → 输入或浏览待分析路径
2. **🔍 静态分析** → YARA/PE/AST/熵 → 输出报告与可视化
3. **🚀 动态分析** → Frida hook → 实时 API 调用流（**必须在 VM 中运行**）
4. **🧠 GNN 分析** → CFG 提取 → 分类 + 可解释性
5. **🌐 威胁情报** → VT hash 查询 + MITRE 技术匹配
结果分布在 4 个 Tab：日志、静态、动态、GNN。每个 Tab 包含图表 + 文本报告。
## 🧪 测试
# 收集并运行所有测试
pytest tests/
# 仅运行不需要重型依赖的测试
pytest tests/ -q --tb=short
测试套件包含 21 用例（4 个文件，5-6 个用例每个），分布在 `tests/test_dynamic.py` / `test_gnn.py` / `test_api_calls.py` / `test_static.py`。需要重型依赖（PyTorch Geometric / Frida）的用例会通过 `pytest.mark.skipif` 自动跳过。
CI 在 `ubuntu-latest` 上跑轻量子集（不装 torch-scatter / frida），结果通常是 **9 passed, 12 skipped**。
## 🛠️ 故障排除
| 问题 | 处理 |
|------|------|
| `frida` 相关错误 | 以管理员权限运行；`pip install -U frida frida-tools` |
| `ModuleNotFoundError: torch_geometric` | 参考 `CogDL_安装指南.md` 分阶段装：先 torch，再 torch-scatter/sparse/cluster，最后 torch-geometric |
| `yara.SyntaxError` | 检查 `rules/*.yar` 语法；YARA ≥ 4.2 |
| GUI 字体异常（中文显示为方块） | 安装 SimHei / Microsoft YaHei，或修改 `settings.py` 中的字体列表 |
| 内存占用过高 | 调整 `gui.py` 中 `PerformanceMonitor.memory_threshold`；关闭可视化 Tab |
| 守卫拦截："拒绝运行" | 当且仅当在隔离 VM 里时，`export MALWARE_SANDBOX_OK=yes` |
## 🔒 运维补充
- **凭据**：`.env` 已 gitignore；切勿提交 `config/virustotal_api_key.txt`（旧版兼容文件，已废弃）
- **YARA 规则**：来自外部源时建议先校验 hash 再放入 `rules/`
- **日志**：`analysis.log` 含样本指纹与 API 细节，分享前脱敏
- **依赖更新**：`pip list --outdated` + 关注 frida、yara-python、PyTorch 系列的安全公告
- **MITRE 缓存**：`cache/mitre_*.json` 默认每 7 天失效自动刷新
## 🤝 贡献
git clone https://github.com/huanghfzhufeng/malware-analysis-tool
cd malware-analysis-tool
pip install -r requirements.txt
pytest tests/
python main.py
提交 PR 前请确保：
1. `pytest tests/` 全绿（或仅有合理 skip）
2. 不要引入新的 bare `except:` 子句（除 `lynx_sample.py` 内的故意行为模拟外）
3. 不要把任何 API key、凭据、`.env` 提交到仓库
## 📄 许可证
MIT License — 详见 `LICENSE`（如未提供请与维护者联系）。
## 🙏 致谢
PyQt5 · Frida · PyTorch / PyTorch Geometric · YARA · NetworkX · CogDL · VirusTotal · MITRE ATT&CK
**⚠️ 免责声明**：仅用于安全研究与教育，使用者自行承担风险。请勿用于任何非法用途。
标签：API接口, API查询, Ask搜索, CFG, Cloudflare, DAST, DNS 反向解析, Docker支持, ELF文件解析, Frida, GNN, Hook, lief, Malware Analysis, meg, MITRE ATT&CK, PDF检测, pefile, PE文件解析, PyQt5, Python, Sandbox, VirusTotal, YARA, 二进制分析, 云安全监控, 云安全运维, 云资产可视化, 信息安全, 凭据扫描, 动态注入, 图神经网络, 威胁情报, 开发者工具, 恶意样本分析, 恶意软件分析, 控制流图, 无后门, 无线安全, 桌面应用, 桌面端安全平台, 沙箱, 沙箱逃逸防护, 特权检测, 网络安全, 自动化分析, 虚拟机隔离, 跨站脚本, 逆向工具, 隐私保护, 静态分析