binary-tracer（工具名：MalwarePinAnalyzer）是一个基于 Intel Pin 的 Windows
动态二进制分析工具。它面向恶意程序、加壳程序和 VMProtect 保护代码的受控研究，
能够采集 API、函数调用、内存、进程、反分析与局部指令执行证据，并离线生成 JSON、
JSONL 和文本报告。
本项目用于防御、安全研究和授权分析。请只在隔离虚拟机中运行未知程序，并做好 快照、网络隔离和样本处置。Intel Pin 和任何测试目标均不随仓库分发。
- 自动发现样本实际调用的命名 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.dllx86\Release\MalwarePinAnalyzer.dll
生成可复制部署包：
.\scripts\package_release.ps1 -Version 1.1.0完整工具链配置见 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 只能跟踪本次创建的
新子进程，不能接管早已存在的进程。
默认 -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/。
| 预设 | 用途 | 主要行为 |
|---|---|---|
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" -vPin 集成测试会运行仓库提供的无恶意 x64/x86 测试程序。测试不会使用真实恶意样本。 当前项目记录的完整验收为 169/169：98 项离线测试、36 项 x64 Pin 测试和 35 项 x86/WOW64 Pin 测试；另有 4 项可选 Triton 测试在未安装后端时跳过。
- 工具不是自动 VMProtect 去虚拟化器；VMP 结果是局部动态证据和候选分析；
- Windows JIT 模式不能依赖事后附加来补救已经运行的旧单实例进程；
neutralize和force只修改明确批准的反调试事实；- 原始日志应作为证据保留，离线推断不能替代人工复核；
- 未知样本必须在合法授权和隔离环境中运行。