9ith4b/binary-tracer

# binary-tracer `binary-tracer`（工具名：MalwarePinAnalyzer）是一个基于 Intel Pin 的 Windows 动态二进制分析工具。它面向恶意程序、加壳程序和 VMProtect 保护代码的受控研究， 能够采集 API、函数调用、内存、进程、反分析与局部指令执行证据，并离线生成 JSON、 JSONL 和文本报告。 ## 主要能力 - 自动发现样本实际调用的命名 Windows API； - 使用 JSON 配置批量指定需要提取关键参数的 API； - API 调用时间线和按线程组织的 API 调用树； - 可选全量动态函数调用树，支持主 EXE 和多个显式样本 DLL； - x64 与 x86/WOW64 共用一套 C++ 源码和二进制协议； - 模块、线程、进程和子进程生命周期； - 本地/远程内存分配、保护、写入、执行和私有内存 Dump； - Section/View、Native API 与 syscall 观察； - 文件、注册表、网络、进程、互斥体、服务、计划任务和 IOC 汇总； - 进程注入与 Process Hollowing 候选证据链； - 反调试、时间、CPUID/RDTSC、异常、PEB/TEB、环境与自校验观察； - 有界 VMP ROI 指令 Trace、dispatcher/handler slice、VIP/VSP/rolling-key 候选； - handler replay、内置语义验证和可选 Triton 后端。 工具坚持保留证据语义：`observed`、`neutralized`、`forced` 和 `inferred` 不会混为 一谈。注入、Hollowing、解包和 VMP 寄存器角色均属于候选结论，而不是自动恶意判定。 ## 支持范围 | 项目 | 当前支持 | |---|---| | 宿主系统 | Windows 10/11 x64 | | 目标程序 | 原生 x64、WOW64 x86 | | Pin | Intel Pin 4.3.99850，JIT 模式 | | 编译器 | Visual Studio 2026 18.7.3，ClangCL，C++17 | | SDK | Windows SDK 10.0.26100.0 | | 日志协议 | binary protocol v1，小端、固定宽度字段 | | 离线分析 | Python 3.10+ | 原生 32 位 Windows 的构建产物和验收入口已经具备，但仍需要在真实原生 x86 系统 完成最终运行确认。 ## 仓库结构 pintool/ Intel Pin C++ 采集器 analyzer/ Python 解码、关联和报告模块 rules/ 运行配置、API 参数配置示例与 JSON Schema tests/ 离线测试和无恶意 x64/x86 Pin 集成样本 deployment/ 一键入口、中文手册和原生 x86 验收脚本 scripts/ 发布包构建脚本 docs/ 分阶段设计与实施文档 `x64/`、`x86/`、`dist/`、`output/`、日志、Dump 和测试二进制是生成内容，不提交到 仓库。 ## 构建 仓库应位于 Intel Pin 源码树的 `source\tools\MyPinTool`，或使用等价的 Pin include/ library 路径配置。Intel Pin 本身不包含在仓库中。 & 'D:\Microsoft Visual Studio\18\Professional\MSBuild\Current\Bin\MSBuild.exe' ` '.\MalwarePinAnalyzer-clang.vcxproj' /t:Build ` /p:Configuration=Release /p:Platform=x64 /nologo & 'D:\Microsoft Visual Studio\18\Professional\MSBuild\Current\Bin\MSBuild.exe' ` '.\MalwarePinAnalyzer-clang.vcxproj' /t:Build ` /p:Configuration=Release /p:Platform=Win32 /nologo 输出： - `x64\Release\MalwarePinAnalyzer.dll` - `x86\Release\MalwarePinAnalyzer.dll` 生成可复制部署包： .\scripts\package_release.ps1 -Version 1.1.0 完整工具链配置见 [`toolchain.md`](toolchain.md)。 ## 快速开始 进入生成的 `dist\MalwarePinAnalyzer-1.1.0` 目录： .\mpa.ps1 run -PinRoot E:\pin -Target C:\samples\sample.exe 入口会自动识别目标架构、选择 `pin.exe` 或 `pin32.exe`、采集二进制事件、校验日志， 然后生成完整报告套件。 目标需要参数时： .\mpa.ps1 run -PinRoot E:\pin -Target C:\samples\sample.exe ` -TargetArguments '--config','C:\samples\sample.dat','--quiet' 跟随本次运行创建的子进程： .\mpa.ps1 run -PinRoot E:\pin -Target C:\samples\dropper.exe -FollowChild 单实例程序可能把请求交给已经存在、未被 Pin 注入的旧进程，然后立即退出。此时应先 关闭旧实例，或使用目标程序提供的独立实例参数。`-FollowChild` 只能跟踪本次创建的 新子进程，不能接管早已存在的进程。 ## 自动 API 发现与参数配置 默认 `-ApiTracking auto` 会记录从样本作用域进入的命名 API，无需维护完整硬编码 列表。首先查看 `reports\api-inventory.json`，了解程序实际调用了哪些 API。 需要提取 `CreateFileW` 路径等关键参数时，使用配置文件： .\mpa.ps1 run -PinRoot E:\pin -Target C:\samples\sample.exe ` -ApiConfig .\rules\api-capture.example.json 示例： { "schema_version": 1, "captures": [ {"api": "CreateFileW", "parameters": ["lpFileName"]}, {"api": "CreateProcessW", "parameters": ["lpApplicationName", "lpCommandLine"]}, {"api": "CopyFileW", "parameters": ["lpExistingFileName", "lpNewFileName"]} ] } 支持 `uint32`、`uint64`、`pointer`、`handle`、`bool`、`ansi_string`、 `utf16_string` 和有界 `buffer`。字符串与 Buffer 使用 `PIN_SafeCopy` 读取，并受到 硬上限约束。Schema 和完整示例位于 [`rules/`](rules/)。 ## 分析预设 | 预设 | 用途 | 主要行为 | |---|---|---| | `quick` | 快速初筛 | 减少高频指令观察，优先速度 | | `standard` | 首次分析 | 默认 API、行为、内存和受支持 Buffer 采集 | | `deep` | 深度分析 | 全量函数树、深度写入、私有执行 Dump、全部 syscall | | `vmp` | VMProtect 局部研究 | 有界 ROI 指令、寄存器、内存和分支状态 | .\mpa.ps1 run -PinRoot E:\pin -Target C:\samples\sample.exe -Preset deep ## 结果 一次标准运行会生成： analysis-results\sample-时间戳\ ├─ run-summary.json ├─ raw\events.bin ├─ dumps\ └─ reports\ ├─ README.md ├─ analysis-summary.json ├─ api-inventory.json ├─ api-timeline.json ├─ api-call-tree.json ├─ api-call-tree.txt ├─ full-call-tree.json ├─ behavior-report.json ├─ ioc-report.json ├─ memory-timeline.json ├─ injection-report.json ├─ hollowing-report.json ├─ anti-analysis-report.json ├─ vmp-trace.json ├─ vmp-analysis.json └─ events.jsonl 推荐先阅读每次运行生成的 `reports\README.md` 和 `api-inventory.json`，再进入行为、 调用树、IOC、内存或 VMP 报告。 ## 测试 离线测试： python -m unittest discover -s tests -p "test_*.py" -v Pin 集成测试会运行仓库提供的无恶意 x64/x86 测试程序。测试不会使用真实恶意样本。 当前项目记录的完整验收为 169/169：98 项离线测试、36 项 x64 Pin 测试和 35 项 x86/WOW64 Pin 测试；另有 4 项可选 Triton 测试在未安装后端时跳过。 ## 文档 - [中文完整使用说明](deployment/USER_GUIDE.zh-CN.md) - [工具链、构建与高级命令](toolchain.md) - [项目阶段与验收进度](PROJECT_PROGRESS.md) - [原始实施计划](VMP%20恶意程序动态分析工具代码实施计划.md) ## 已知边界 - 工具不是自动 VMProtect 去虚拟化器；VMP 结果是局部动态证据和候选分析； - Windows JIT 模式不能依赖事后附加来补救已经运行的旧单实例进程； - `neutralize` 和 `force` 只修改明确批准的反调试事实； - 原始日志应作为证据保留，离线推断不能替代人工复核； - 未知样本必须在合法授权和隔离环境中运行。

标签：AI合规, C++, DAST, Intel Pin, 云资产清单, 代码保护分析, 动态二进制分析, 恶意软件分析, 数据擦除, 逆向工具, 逆向工程