quarkslab/qbindiff
GitHub: quarkslab/qbindiff
QBinDiff 是一个基于机器学习的二进制差异分析工具，旨在解决传统比对在复杂场景下灵活性不足的问题。
Stars: 225 | Forks: 13
# QBinDiff
QBinDiff is an experimental binary diffing tool based on machine learning technics, namely Belief propagation.
Examples:
- For Quokka exports: qbindiff -e1 file1.bin -e2 file2.bin file1.quokka file2.quokka
- For BinExport exports, changing the output path: qbindiff -o my_diff.bindiff file1.BinExport file2.BinExport
╭─ Output parameters ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
--output -o Output file path. (FILE) [default: qbindiff_results.csv]
--format -ff Output file format. (bindiff|csv) [default: csv]
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─ Primary file options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
--primary-loader -l1 Enforce loader type. (binexport|quokka|ida)
--primary-executable -e1 Path to the raw executable (required for quokka exports). (PATH)
--primary-arch -a1 Enforce disassembling architecture. Format is like 'CS_ARCH_X86:CS_MODE_64'. (TEXT)
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─ Secondary file options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
--secondary-loader -l2 Enforce loader type. (binexport|quokka|ida)
--secondary-executable -e2 Path to the raw executable (required for quokka exports). (PATH)
--secondary-arch -a2 Enforce disassembling architecture. Format is like 'CS_ARCH_X86:CS_MODE_64'. (TEXT)
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─ Global options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
--verbose -v Activate debugging messages. (-v|-vv|-vvv)
--quiet -q Do not display progress bars and final statistics.
--help -h Show this message and exit.
--version Show the version and exit.
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─ Diffing parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
--feature -f Features to use for the binary analysis, it can be specified multiple times. ()
Features may be weighted by a positive value (default 1.0) and/or compared with a
specific distance (by default the option -d is used) like this ::.
For a list of all the features available see --list-features.
--list-features List all the available features.
--normalize -n Normalize the Call Graph (can potentially lead to a partial matching).
--distance -d Available distances: (canberra|euclidean|cosine|haussmann) [default: haussmann]
--tradeoff -t Tradeoff between function content (near 1.0) and call-graph information (near 0.0). (FLOAT) [default: 0.8]
--sparsity-ratio -s Ratio of least probable matches to ignore. Between 0.0 (nothing is ignored) to 1.0 (only perfect matches are considered) (FLOAT) [default: 0.6]
--sparse-row -sr Whether to build the sparse similarity matrix considering its entirety or processing it row per row.
--epsilon -e Relaxation parameter to enforce convergence. (FLOAT) [default: 0.9]
--maxiter -i Maximum number of iteration for belief propagation. (INTEGER) [default: 1000]
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─ Passes parameters ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ --pass-feature-hash Anchor matches when function have the same feature hash.
│ --pass-user-defined Anchor matches using user defined matches. Format is like 'primary-addr1:secondary-addr2,...'. (TEXT)
│ --pass-flirt-hash Anchor matches using FLIRT/FunctionID like signatures.
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
```
### Quokka 示例
Quokka 导出器需要可执行文件路径，因此应同时使用 ``-e1`` 和 ``-e2``。
```
$ qbindiff -e1 primary.exe -e2 secondary.exe primary.exe.Quokka secondary.exe.Quokka
```
请注意所有参数均采用默认值，但可以配置所使用的不同特征及参数。
```
$ qbindiff -e1 primary.exe \
-e2 secondary.exe \
-f bnb \ # basic block number
-f cc:3.0 \ # cyclomatic complexity feature
-f cst:5.0 \ # feature based on constants
--maxiter 100 \ # maximum number of iterations
primary.exe.Quokka \
secondary.exe.Quokka
```
### BinExport 示例
生成 ``.BinDiff`` 格式差异文件的最简单示例如下：
```
$ qbindiff primary.BinExport secondary.BinExport -ff bindiff -o out.BinDiff
```
后端使用 Binexport，并依赖 Capstone 进行指令反汇编及部分特征提取。
因此对于某些架构，特别是 ARM/Thumb 模式，应提供确切的反汇编模式，使用 Capstone 的 [架构标识符](https://github.com/capstone-engine/capstone/blob/f81eb3affaa04a66411af12cf75522cb9649cf83/bindings/python/capstone/__init__.py#L207) 和 [模式标识符](https://github.com/capstone-engine/capstone/blob/f81eb3affaa04a66411af12cf75522cb9649cf83/bindings/python/capstone/__init__.py#L231)。例如，要对两个 binexport 文件进行差异分析并指定精确架构，可以执行：
```
$ qbindiff primary.BinExport secondary.BinExport -a1 CS_ARCH_ARM:CS_MODE_THUMB -a2 CS_ARCH_ARM:CS_MODE_THUMB
```
## 库用法
QBinDiff 的优势在于可以作为 Python 库使用。以下代码片段展示了如何加载两个 binexport 文件并使用助记符特征进行比较：
```
from qbindiff import QBinDiff, Program
from qbindiff.features import MnemonicTyped
from pathlib import Path
p1 = Program("primary.BinExport")
p2 = Program("secondary.BinExport")
differ = QBinDiff(p1, p2)
differ.register_feature_extractor(MnemonicTyped, 1.0)
# 如果需要，请添加其他功能
differ.process()
mapping = differ.compute_matching()
output = {(match.primary.addr, match.secondary.addr) for match in mapping}
```
## 引用本工作
如果您在工作中使用了 QBinDiff，请考虑引用以下文献：
```
@inproceedings{CAIDQBinDiff,
author = "Cohen, Roxane and David, Robin and Mori, Riccardo and Yger, Florian and Rossi, Fabrice",
title = "Improving binary diffing through similarity and matching intricacies",
booktitle = "Proc. of the 6th Conference on Artificial Intelligence for Defense",
year = 2024,
}
```
```
@misc{SSTICQBinDiff,
title = "QBinDiff: A modular differ to enhance binary diffing and graph alignment",
author = "Cohen, Roxane and David, Robin and Mori, Riccardo and Yger, Florian and Rossi, Fabrice",
howpublished = "\url{https://www.sstic.org/2024/presentation/qbindiff_a_modular_differ/}",
year = 2024,
}
```
标签：Apex, APX难问题, BinExport, IDA Pro, Quokka, UML, Wayback Machine, 二次规划, 二进制比对, 云安全监控, 云资产清单, 优化算法, 反汇编, 固件分析, 图对齐, 实验性工具, 嵌入式安全, 机器学习, 社交网络分析, 程序匹配, 网络对齐, 软件比对, 逆向工具, 逆向工程, 静态分析