duyhoang05/Windows-malware-api-call-analysis

# Windows 恶意软件 API 调用分析器 基于运行时 API 调用序列的 Windows 程序动态分析工具。该系统使用 Frida 对进程进行插桩，使用 Python 收集和分析事件，使用基于规则的引擎检测可疑行为，并利用 Random Forest 作为辅助分类信号。 这是一个用于恶意软件分析研究与实践的学术项目。该工具不能替代 antivirus、EDR 或专业的 sandbox。 ## 主要功能 - 使用 Frida 启动并监控 Windows 可执行文件。 - Hook 属于 memory、file、registry、process/thread、library、network 和反分析组的 API。 - 监控由 target 创建的子进程。 - 将运行时事件记录为 CSV 和 JSONL。 - 将 API 聚合为 behavior 和 behavior group。 - 检测 behavior chain、可疑指标和 IOC。 - 将 endpoint 与 C2 指标及本地可信域进行比对。 - 计算 risk score 并对风险等级进行分类。 - 将部分行为映射到 MITRE ATT&CK。 - 使用 Random Forest 结合 threshold 和 reliability gating 预测 API profile。 - 生成 text、enhanced text 和 HTML 报告。 - 提供包含 Start、Stop 和 Force Stop 功能的 GUI。 ## 架构 ``` Target EXE -> Frida spawn/attach -> hook.js thu thập Windows API calls -> main.py ghi logs/api_log.csv và api_log.jsonl -> analyzer.py phân tích rule, IOC, MITRE và risk score -> ml/predict_ml.py bổ sung tín hiệu Random Forest -> report.txt, report_enhanced.txt, report.html và GUI ``` `main.py` 是核心协调模块。`hook.js` 负责插桩。`analyzer.py` 处理基于规则的分析。`ml/` 目录包含 Machine Learning 的特征向量化、训练和预测部分。 ## 环境要求 - Windows 10 或 Windows 11。 - Python 3.10 及以上版本。 - 具备让 Frida 启动/附加到 target process 的适当权限。 - 建议在隔离的虚拟机中运行不受信任的样本。 ## 安装 在项目目录下打开 PowerShell 或 Command Prompt： ``` py -m pip install -r requirements.txt ``` 主要依赖包括 Frida、scikit-learn、pandas、joblib 和 NumPy。Tkinter 通常会随 Windows 上的 Python 一起安装。 检查 Frida： ``` py -c "import frida; print(frida.__version__)" ``` ## 使用 GUI 直接运行： ``` py gui.py ``` 或者运行： ``` RUN_ANALYZER.bat ``` 使用流程： 1. 选择需要分析的 `.exe` 文件。 2. 设置监控 timeout。 3. 开启或关闭 Machine Learning。 4. 点击 Start Analysis。 5. 在控制台中监控 API events。 6. 使用 Stop 请求软停止，系统仍会生成报告。 7. 如果分析器或 target 未按时停止，请使用 Force Stop。 ## 使用 CLI 基础语法： ``` py main.py -t ``` 示例： ``` py main.py samples\sample.exe -t 30 ``` 关闭 Machine Learning： ``` py main.py samples\sample.exe -t 30 --no-ml ``` 较长的 timeout 有助于观察延迟触发的 payload，但也会导致日志体积变大。简短的 trace 或极少的 API 并不足以断定样本是良性的。 ## 分析流程 1. `main.py` 清理旧日志并准备输出目录。 2. Frida 以暂停状态启动 target。 3. Python 附加到进程并加载 `hook.js`。 4. `hook.js` 查找 API 的运行时地址并附加 `Interceptor.attach()`。 5. target 恢复执行；hook events 被发送回 Python。 6. events 被记录到 CSV 和 JSONL 中。 7. 当 timeout 结束或收到 Stop 指令时，系统会 detach 并清理已监控的进程。 8. `analyzer.py` 执行基于规则的分析。 9. 如果开启 ML，`ml/predict_ml.py` 会生成特征向量并加载 model。 10. 系统生成各项输出报告。 ## 基于规则的分析 分析器不会基于单个 API 得出结论。像 `VirtualAlloc`、`LoadLibraryW` 或 `GetProcAddress` 这样的常见 API 可能会同时出现在 goodware 和 malware 中。 系统会将 API 映射为 behavior，然后检查行为链和上下文。例如： ``` OpenProcess -> VirtualAllocEx -> WriteProcessMemory -> CreateRemoteThread ``` 上述行为链可能与 Process Injection 有关。主要检测组包括： - Process Injection、Native Process Injection 和 APC Injection。 - 类 Process Hollowing 行为。 - Downloader 和 WinHTTP downloader 行为。 - Registry 和服务持久化。 - 类 Ransomware 文件活动。 - Dynamic API Resolution。 - 反分析和 sandbox evasion。 - C2 endpoint、可疑域名和公网 IP 连接。 Risk score 是基于 behavior chain 和可疑指标的启发式分数。它并不是 malware 的概率。如果没有高可靠性的证据，分析器会限制得分，以减少由常见运行时 API 引起的 false positive。 目前的结论等级： - `LOW`：无明显可疑的行为链或指标。 - `SUSPICIOUS`：存在行为链或指标，但总证据有限。 - `MEDIUM`：score 达到 40 且有足够的上下文支持。 - `HIGH`：score 达到 80 且有强烈的类 malware 证据。 - `INCONCLUSIVE`：trace 过短或 coverage 不足以得出结论。 ## 机器学习 ML 模块使用 Random Forest 评估 API profile。ML 不会取代基于规则的引擎，也不是最终的结论。 输入的数据集包含 API ID 序列和 `malware` 标签。在训练过程中： 1. API ID 被映射为 API 名称。 2. 每个样本被转换为 API 频率向量。 3. 对数据集进行 undersampling 以减少类别不平衡。 4. 数据被划分为 train、validation 和 test 集。 5. 在 train 集上训练 Random Forest。 6. 使用 validation 集根据 false-positive rate 目标选择 threshold。 7. 使用 test 集进行最终评估。 8. Model、特征列表、threshold 和 metadata 会被打包保存。 训练 model： ``` py ml\train_ml_kaggle.py --csv dataset\dynamic_api_call_sequence_per_malware_100_0_306.csv --model models\api_rf_model.pkl --malware-ratio 3 ``` Model 保存在： ``` models/api_rf_model.pkl ``` 预测结果包括 probability、threshold、reliability、recognized calls、active features、anchor calls 和 warnings。当 reliability 为 `LOW` 时，分析人员应优先考虑基于规则的证据和 IOC。 ## 输出数据 ### `logs/` - `api_log.csv`：表格形式的 API events，供分析器和 ML 使用。 - `api_log.jsonl`：按行存储的完整 JSON 格式 events。 - `stop_requested.flag`：来自 GUI 的 Stop 信号。 - `spawned_pids.txt`：用于清理和 Force Stop 的 PID。 ### `reports/` - `report.txt`：主要的详细报告。 - `report_enhanced.txt`：扩展展示的文本版本。 - `report.html`：HTML dashboard 和图表。 `report.txt` 包括 Executive Summary、API sequence、top APIs、behaviors、chains、indicators、IOC、MITRE mapping、evidence、risk score、ML 分析和分析人员结论。 ### `models/` - `api_rf_model.pkl`：Random Forest model package。 ## 项目结构 ``` malware_api_analyzer/ |-- main.py CLI và orchestration |-- gui.py Giao diện Tkinter |-- hook.js Frida API hooks |-- analyzer.py Rule-based analysis và report chính |-- rules.py API sequences và trọng số rule |-- html_report.py Sinh HTML report |-- enhanced_report.py Sinh enhanced text report |-- report_formatting.py Helper định dạng report |-- chartjs.min.js Chart.js dùng cho HTML report |-- RUN_ANALYZER.bat Launcher cho GUI |-- requirements.txt Python dependencies |-- ml/ | |-- train_ml_kaggle.py Huấn luyện Random Forest | |-- predict_ml.py Dự đoán từ Frida CSV | |-- ml_features.py Chuyển log/sequence thành vector | `-- api_mapping.py API ID mapping và feature set |-- reputation/ | |-- c2_indicators.txt C2 indicator cục bộ | `-- trusted_domains.txt Trusted domain cục bộ |-- dataset/ Dataset huấn luyện |-- models/ Model package |-- samples/ Mẫu kiểm thử cục bộ |-- logs/ Runtime logs `-- reports/ Báo cáo được sinh ``` ## 故障排除 ### `ModuleNotFoundError: No module named 'frida'` ``` py -m pip install frida frida-tools ``` ### Frida 无法附加到 target - 以适当的权限运行终端。 - 检查 target 是否过快退出。 - 检查 Python/Frida 和 target 的架构是否匹配。 - 尝试增加 timeout，或者确保运行 target 时提供了正确的输入参数。 ### Model 不存在或无法加载 - 检查 `models/api_rf_model.pkl`。 - 使用当前正在运行的 scikit-learn 版本重新训练 model。 - 不要从不受信任的来源加载 model package，因为 `joblib/pickle` 在 deserialize 时可能会执行代码。 ### Stop 没有立即响应 首次点击 Stop 以请求软停止。如果进程仍在运行，请点击 Force Stop。GUI 将使用 PID 跟踪和 `taskkill` 来清理进程树。 ### 多次运行结果不一致 动态分析取决于 timeout、子进程、网络、权限、触发器和环境状态。一次运行不能代表样本的全部行为。 ## 安全使用 - 仅在被允许的环境内分析样本。 - 切勿在个人计算机或生产网络上运行真实的 malware。 - 使用隔离的虚拟机，并在运行前创建快照。 - 当不需要真实的互联网连接时，请关闭或模拟网络。 - 切勿将凭据、个人文件或重要数据放入分析机中。 - 将日志、报告和输出文件视为不受信任的数据。 ## 局限性 - Frida 是用户态插桩，可能会被检测或规避。 - Direct syscall 可能不会经过已 hook 的 API。 - Hook 列表和规则无法覆盖所有的 malware 技术。 - 较短的 timeout 可能会漏掉延迟激活的 payload。 - ML 依赖于数据集，并且可能会对合法的 installer 或 loader 产生 false positive。 - 目前的 IOC reputation 是本地列表，不能替代 threat intelligence service。 ## 使用目的 本项目是为学习、信息安全研究以及在授权环境下的恶意软件分析而构建的。使用者需承担责任，确保运行样本的行为符合相关法律规定及所涉及系统的策略。 ## 技术栈 - Python - Frida - scikit-learn - pandas、NumPy 和 joblib - Tkinter - Chart.js - 规则层面的 MITRE ATT&CK mapping

标签：Apex, ATT&CK映射, DAST, Docker支持, Frida, 恶意软件分析, 数据可视化, 机器学习, 行为检测, 逆向工具, 速率限制处理