[原创] QBDI 源码阅读笔记-Android安全-看雪安全社区

## 前言
用的 Ubuntu 编译的 Linux 版本, android 版本也编译了, 不过为了方便调试还是用的 Linux, 两者编译有些许不同, 原理和代码一样.

长文预警! 长文预警! 长文预警!

感觉前后文联系很强, 写的比较细, 几乎是每个地方都刨根问底, 如果跳着看, 注意回看前文, 有些前面写了, 我就没在后面重复.

建议一个屏幕打开源码, 一个屏幕读文章. 这样可以自己亲身体会一下.

作者也是小白, 难免疏忽, 如有错误还请您指出.

## 项目地址
61bK9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6Y4K9i4c8Z5N6h3u0Q4x3X3g2U0L8$3#2Q4x3V1k6c8b7V1c8u0i4K6u0r3f1f1u0p5d9b7`.`.

## 文档
- 首页: 7cbK9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3
- c api: f0eK9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3j5i4m8A6i4K6g2X3j5#2)9J5k6h3S2@1L8h3H3`.

## 原理概述
QBDI 实现了一个自己的 ir, 然后将要插桩的二进制指令与插桩代码统一翻译成自己的 ir, 然后借助 llvm 的组件转成对应架构二进制指令, 天才的构思. 接下来让我们一点点揭开它神秘的面纱.

## 阅读源码

### 从官方示例出发
- 编译: 614K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3j5$3!0E0M7r3W2D9j5i4c8A6L8$3&6Q4x3X3g2Z5N6r3#2D9
 ```bash
 mkdir build
 cd build
 ../cmake/config/config-linux-X86_64.sh
 # cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
 # ln -s compile_commands.json ..
 # 要安装到系统目录, 这样头文件可以直接导入
 sudo ninja install
 ```
- c 语言示例: de3K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3k6$3g2@1i4K6g2X3M7%4c8S2M7Y4c8W2k6q4)9J5k6r3y4Q4x3X3g2Z5N6r3#2D9i4K6t1K6k6Y4g2D9L8q4)9J5k6r3g2^5j5h3#2H3L8r3f1`.
 ```bash
 # 编译 examples/ 程序
 cd build
 # 编译 debug 版可以配合 gdb 调试
 cmake -DQBDI_EXAMPLES=ON -DCMAKE_BUILD_TYPE=Debug -DQBDI_LOG_DEBUG=ON .. 
 ninja
 ```
- 使用官方模板: d56K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3k6$3g2@1i4K6g2X3M7%4c8S2M7Y4c8W2k6q4)9J5k6q4q4n7c8p5W2b7M7X3g2D9L8$3q4V1i4K6u0W2K9s2c8E0L8q4)9J5x3$3N6W2N6q4)9J5k6s2y4@1j5i4u0@1k6h3c8Q4x3X3c8H3M7X3g2D9L8$3q4V1i4K6u0V1j5H3`.`.
 ```bash
 mkdir QBDIPreload && cd QBDIPreload
 # build/package/qbdi-preload-template 脚本中的命令, 要在编译时执行 sudo ninja install 才能复制过来
 cp /usr/local/share/qbdipreloadX86_64/qbdi_preload_template/* .
 mkdir build && cd build
 cmake ..
 make
 ```

跑一下 build/examples/ 中的可执行程序, 看看效果
 ![](upload/attach/202507/1025255_GJFXB3BZ7JS6VRV.webp)
可以正常跑, 好了现在开始阅读 example 目录下的代码, 首先看下 CMakeLists.txt, `examples/CMakeLists.txt`:
```cmake
add_executable(mnemonicFilter mnemonicFilter.cpp)
target_link_libraries(mnemonicFilter QBDI)
set_target_properties(mnemonicFilter PROPERTIES CXX_STANDARD 11
                                                CXX_STANDARD_REQUIRED ON)
add_signature(mnemonicFilter)

add_executable(modules_c modules.c)
target_link_libraries(modules_c QBDI)
add_signature(modules_c)

add_executable(modules_cpp modules.cpp)
target_link_libraries(modules_cpp QBDI)
set_target_properties(modules_cpp PROPERTIES CXX_STANDARD 11
                                             CXX_STANDARD_REQUIRED ON)
add_signature(modules_cpp)

add_executable(thedude_c thedude.c)
target_link_libraries(thedude_c QBDI)
add_signature(thedude_c)

add_executable(thedude_cpp thedude.cpp)
target_link_libraries(thedude_cpp QBDI)
set_target_properties(thedude_cpp PROPERTIES CXX_STANDARD 11
                                             CXX_STANDARD_REQUIRED ON)
add_signature(thedude_cpp)

add_executable(cryptolock_cpp cryptolock.cpp)
target_link_libraries(cryptolock_cpp QBDI)
set_target_properties(cryptolock_cpp PROPERTIES CXX_STANDARD 11
                                                CXX_STANDARD_REQUIRED ON)
add_signature(cryptolock_cpp)

add_executable(cryptolock_c cryptolock.c)
target_link_libraries(cryptolock_c QBDI)
add_signature(cryptolock_c)

add_subdirectory(c)
add_subdirectory(cpp)
```
添加了 `mnemonicFilter` `modules_c` `modules_cpp` `thedude_c` `thedude_cpp` `cryptolock_cpp` `cryptolock_c` 可执行文件, 然后再看 `examples/c/CMakeLists.txt`:
```cmake
add_executable(fibonacci_c fibonacci.c)
target_link_libraries(fibonacci_c QBDI)
add_signature(fibonacci_c)

if(QBDI_TOOLS_QBDIPRELOAD)
 add_library(tracer_preload_c SHARED tracer_preload.c)
 target_link_libraries(tracer_preload_c QBDIPreload QBDI_static)
endif()
```
创建 `fibonacci_c` 可执行文件和 `tracer_preload_c` 共享库. 斐波那契数列真是老演员了, 我们从这里开始看起, 上边的 <a href="elink@482K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3k6$3g2@1i4K6g2X3M7%4c8S2M7Y4c8W2k6q4)9J5k6r3y4Q4x3X3g2Z5N6r3#2D9i4K6t1K6k6Y4g2D9L8q4)9J5k6r3g2^5j5h3#2H3L8r3f1`.">c 语言示例</a>同样讲解的这个代码, 我觉得官方文档写的真好, 我无论怎么讲都显得冗余, 但为了完整性, 我还是简单概括下:
- 目标程序:
 ```c
 // 斐波那契数列
 int fibonacci(int n) {
 if(n <= 2)
 return 1;
 return fibonacci(n-1) + fibonacci(n-2);
 }
 ```
- 初始化: 
 ```c
 #include "QBDI.h"

// 初始化虚拟机
    VMInstanceRef vm;
    qbdi_initVM(&vm, NULL, NULL, 0);

// 虚拟机状态的指针
    GPRState *state;
    state = qbdi_getGPRState(vm);
    assert(state != NULL);

// 请求一个虚拟堆栈, 虚拟机不使用你进程中的常规堆栈, QBDI 需要自己的堆栈
    uint8_t *fakestack;
    static const uint32_t STACK_SIZE = 0x100000; // 1MB
    bool res = qbdi_allocateVirtualStack(state, STACK_SIZE, &fakestack);
    assert(res == true);
    ```
- 回调:
    ```c
    // 获取当前指令的地址和反汇编, 并将其打印出来,

// 回调函数遵循 InstCallback 的函数签名
    VMAction showInstruction(VMInstanceRef vm, GPRState *gprState,
                            FPRState *fprState, void *data) {
    // 获取指令的分析信息, 包括指令地址和反汇编代码
    const InstAnalysis *instAnalysis = qbdi_getInstAnalysis(
        vm, QBDI_ANALYSIS_INSTRUCTION | QBDI_ANALYSIS_DISASSEMBLY);

// 打印指令的地址和反汇编代码
    printf("0x%" PRIRWORD ": %s\n", instAnalysis->address,
            instAnalysis->disassembly);

return QBDI_CONTINUE;
    }
    // 通过传参控制回调是在指令前(QBDI_PREINST)或指令后(QBDI_POSTINST)被调用. 
    uint32_t cid = qbdi_addCodeCB(vm, QBDI_PREINST, showInstruction, NULL, 0);
    assert(cid != QBDI_INVALID_EVENTID);

// 计算递归调用次数

// QBDI 回调函数都允许用户传递一个自定义参数 data, 其类型为 void *
    VMAction countIteration(VMInstanceRef vm, GPRState *gprState,
                            FPRState *fprState, void *data) {
    (*((int *)data))++;

return QBDI_CONTINUE;
 }
 int iterationCount = 0;
 // qbdi_addMnemonicCB 可以用于注册一个回调函数, 该回调函数仅在遇到特定指令时被调用
 qbdi_addMnemonicCB(vm, "CALL*", QBDI_PREINST, countIteration, &iterationCount, 0);
 ```
 关于类似 `qbdi_addCodeCB` 与 `qbdi_addMnemonicCB` 这样的函数可以查阅 <a href="elink@405K9s2c8@1M7s2y4Q4x3@1q4Q4x3V1k6Q4x3V1k6I4j5X3c8A6i4K6u0W2M7X3g2S2k6s2c8Z5k6h3c8G2j5%4y4Q4x3X3g2A6L8#2)9J5c8X3g2F1i4K6u0r3L8r3q4@1k6i4y4@1i4K6u0r3j5i4m8A6i4K6g2X3j5#2)9J5k6h3S2@1L8h3H3`.">c api 文档</a>
- 生效:
 ```c
 // QBDI 的插桩代码需要一个生效的地址范围, 如果超出此范围, QBDI 不再处理, 即插桩代码不再发生作用. 
 bool res = qbdi_addInstrumentedModuleFromAddr(vm, (rword)&fibonacci);
 assert(res == true);

// qbdi_call() 函数最终运行插桩, 用 retvalue 接收返回值, 并通过 QBDI 调用目标函数, 1 是参数个数, n 是要传入参数 
    rword retvalue;
    res = qbdi_call(vm, &retvalue, (rword)fibonacci, 1, n);
    assert(res == true);
    ```
    控制插桩代码生效地址范围的函数有多个
      ![](upload/attach/202507/1025255_SQ2VYBZ4FBABUCU.webp)

### 跟入示例中调用的实现

#### 首先跟入 `qbdi_initVM` 函数, 看一下头文件 `include/QBDI/VM_C.h` 中的注释:
```cpp
/*! 创建并初始化一个虚拟机实例. 
 *
 * @param[out] instance 创建的虚拟机实例. 
 * @param[in]  cpu      一个 C 字符串, 指定要使用的 CPU 模型名称. 
 *                      如果为 NULL, 则使用默认架构的 CPU 模型
 *                      （更多细节请参考 LLVM 文档）. 
 * @param[in]  mattrs   一个以 NULL 结尾的 C 字符串数组, 指定 CPU 模型的属性. 
 *                      如果为 NULL, 则不指定额外的特性. 
 * @param[in]  opts     要在虚拟机中启用的选项. 
 */
QBDI_EXPORT void qbdi_initVM(VMInstanceRef *instance, const char *cpu,
                             const char **mattrs, Options opts);
```
进入 `src/Engine/VM_C.cpp` 中查看代码:
```cpp
#define QBDI_REQUIRE_ACTION(req, ac)           \
  if (!(req)) {                                \
    QBDI_ERROR("Assertion Failed : {}", #req); \
    ac;                                        \
  }

void qbdi_initVM(VMInstanceRef *instance, const char *cpu, const char **mattrs,
                 Options opts) {
  QBDI_REQUIRE_ACTION(instance, return);

*instance = nullptr;
 std::string cpuStr = "";
 std::vector<std::string> mattrsStr;

if (cpu != nullptr) {
    cpuStr += cpu;
  }

if (mattrs != nullptr) {
    for (unsigned i = 0; mattrs[i] != nullptr; i++) {
      mattrsStr.emplace_back(mattrs[i]);
    }
  }

*instance = static_cast<VMInstanceRef>(new VM(cpuStr, mattrsStr, opts));
}
```
可以看到代码很简单, 就是处理参数, 返回了一个 VM 类的实例, 跟进去 VM 类看一下, 来到了 `include/QBDI/VM.h` 下, 整个文件都是这个类的定义, 支持了很多的方法, 因为太长所以只截了几张图:
 ![](upload/attach/202507/1025255_U5V34KHQR4J2MDJ.webp)
 ![](upload/attach/202507/1025255_NPJP3BU8YS3R24H.webp)

我们看一下它的构造函数:
```cpp
VM::VM(const std::string &cpu, const std::vector<std::string> &mattrs,
 Options opts)
 : memoryLoggingLevel(0), memCBID(0),
 memReadGateCBID(VMError::INVALID_EVENTID),
 memWriteGateCBID(VMError::INVALID_EVENTID) {
#if defined(_QBDI_ASAN_ENABLED_)
 opts |= Options::OPT_DISABLE_FPR;
#endif
 engine = std::make_unique<Engine>(cpu, mattrs, opts, this);
 memCBInfos = std::make_unique<std::vector<std::pair<uint32_t, MemCBInfo>>>();
 instrCBInfos = std::make_unique<
 std::vector<std::pair<uint32_t, std::unique_ptr<InstrCBInfo>>>>();
}
```
将参数传入到了 `Engine` 类中, 我们同样找一下 `Engine` 类初始化函数:
```cpp
Engine::Engine(const std::string &_cpu, const std::vector<std::string> &_mattrs,
 Options opts, VMInstanceRef vminstance)
 : vminstance(vminstance), instrRulesCounter(0), vmCallbacksCounter(0),
 curCPUMode(CPUMode::DEFAULT), options(opts), eventMask(VMEvent::NO_EVENT),
 running(false) {

llvmCPUs = std::make_unique<LLVMCPUs>(_cpu, _mattrs, opts);
 blockManager = std::make_unique<ExecBlockManager>(*llvmCPUs, vminstance);
 execBroker = blockManager->getExecBroker();

// Get Patch rules Assembly for this architecture
 patchRuleAssembly = std::make_unique<PatchRuleAssembly>(options);

gprState = std::make_unique<GPRState>();
 fprState = std::make_unique<FPRState>();
 curGPRState = gprState.get();
 curFPRState = fprState.get();

initGPRState();
  initFPRState();

curExecBlock = nullptr;
}
```
可以看到, 很复杂, 初始化了很多类, 我们暂时不分析, 继续往下看.

#### 回到 `examples/c/fibonacci.c` 示例, 我们往下看 `qbdi_getGPRState` 函数:
```cpp
GPRState *qbdi_getGPRState(VMInstanceRef instance) {
 QBDI_REQUIRE_ACTION(instance, return nullptr);
 return static_cast<VM *>(instance)->getGPRState();
}

GPRState *VM::getGPRState() const { return engine->getGPRState(); }
```
可以看到是在调用 `VM` 类中的 `getGPRState` 方法, 再跟入 `engine->getGPRState` 来到 `src/Engine/Engine.cpp` 中:
```cpp
GPRState *Engine::getGPRState() const { return curGPRState; }
```
返回了 `Engine` 类 中的 `curGPRState` 属性, 让我们跟踪一下 `curGPRState`:
```cpp
GPRState *curGPRState;

/*! X86_64 General Purpose Register context.
 */ // SPHINX_X86_64_GPRSTATE_BEGIN
typedef struct QBDI_ALIGNED(8) {
  rword rax;
  rword rbx;
  rword rcx;
  rword rdx;
  rword rsi;
  rword rdi;
  rword r8;
  rword r9;
  rword r10;
  rword r11;
  rword r12;
  rword r13;
  rword r14;
  rword r15;
  rword rbp;
  rword rsp;
  rword rip;
  rword eflags;
  // Only backup and restore with OPT_ENABLE_FS_GS
  rword fs;
  rword gs;
} GPRState;
// SPHINX_X86_64_GPRSTATE_END
```
在 `include/QBDI/arch/X86_64/State.h` 中找到了 `GPRState` 结构体的定义:
 ![](upload/attach/202507/1025255_AU5ACKWVG9XDSE9.webp)
可以看到在 `include/QBDI/arch/` 下同样有其他架构的一些支持, 根据我们编译时运行的脚本 `GPRState` 等有不同的实现.

在 `src/Engine/Engine.cpp` 与 `src/Engine/Engine.h` 中实现了 `Engine` 类, 而 `VM` 类中的 engine 属性就是 `Engine` 类的实例. 我们不着急分析这些类, 而是分析这个斐波那契示例实现的过程, 慢慢的就明白这些类扮演了什么样的角色.

#### 回到示例往下看 `qbdi_allocateVirtualStack`:
```cpp
bool qbdi_allocateVirtualStack(GPRState *ctx, uint32_t stackSize,
                               uint8_t **stack) {
  return allocateVirtualStack(ctx, stackSize, stack);
}

bool allocateVirtualStack(GPRState *ctx, uint32_t stackSize, uint8_t **stack) {
 (*stack) = static_cast<uint8_t *>(alignedAlloc(stackSize, 16));
 if (*stack == nullptr) {
 return false;
 }

QBDI_GPR_SET(ctx, REG_SP, reinterpret_cast<QBDI::rword>(*stack) + stackSize);
 QBDI_GPR_SET(ctx, REG_BP, QBDI_GPR_GET(ctx, REG_SP));

return true;
}

// 分配对齐的内存
void *alignedAlloc(size_t size, size_t align) {
  void *allocated = nullptr;  // 初始化分配的内存指针为 nullptr
  // 对齐大小必须是 2 的幂
  if ((align == 0) || ((align & (align - 1)) != 0)) {
    return nullptr;  // 如果对齐大小不是 2 的幂, 返回 nullptr
  }
#if defined(QBDI_PLATFORM_LINUX) || defined(QBDI_PLATFORM_ANDROID) || \
    defined(QBDI_PLATFORM_OSX)
  // 在 Linux、Android 和 macOS 上使用 posix_memalign 分配对齐内存
  int ret = posix_memalign(&allocated, align, size);  // 尝试分配对齐内存
  if (ret != 0) {
    return nullptr;  // 如果分配失败, 返回 nullptr
  }
#elif defined(QBDI_PLATFORM_WINDOWS)
  // 在 Windows 上使用 _aligned_malloc 分配对齐内存
  allocated = _aligned_malloc(size, align);  // 尝试分配对齐内存
#endif
  return allocated;  // 返回分配的内存指针
}

#ifdef __cplusplus
#define QBDI_GPR_GET(state, i) (reinterpret_cast<const QBDI::rword *>(state)[i])
#define QBDI_GPR_SET(state, i, v) \
 (reinterpret_cast<QBDI::rword *>(state)[i] = v)
#else
#define QBDI_GPR_GET(state, i) (((rword *)state)[i])
#define QBDI_GPR_SET(state, i, v) (((rword *)state)[i] = v)
#endif
```
我按执行顺序从上往下贴的, 可以看到这段是为虚拟栈分配了内存空间, 并且再内存大小上做了对齐处理, 然后将虚拟寄存器中的栈指针, 帧指针赋值. (虚拟栈存在堆上, 虚拟寄存器存在寄存器中)

#### 回到示例往下看, `qbdi_addCodeCB`, 首先看一下头文件中的参数说明, 在 `include/QBDI/VM_C.h` 中:
```cpp
/*! 注册特定指令事件的回调事件.

* @param[in] instance  虚拟机实例. 
 * @param[in] pos       事件回调的相对位置
 *                      （QBDI_PREINST / QBDI_POSTINST）. 
 * @param[in] cbk       回调函数的指针. 
 * @param[in] data      传递给回调函数的用户自定义数据. 
 * @param[in] priority  回调的优先级.

* @return 注册的插桩的 ID（如果失败则返回 QBDI_INVALID_EVENTID）. 
 */
QBDI_EXPORT uint32_t qbdi_addCodeCB(VMInstanceRef instance, InstPosition pos,
 InstCallback cbk, void *data, int priority);
```
然后来到 `src/Engine/VM_C.cpp` 文件来看实现:
```cpp
uint32_t qbdi_addCodeCB(VMInstanceRef instance, InstPosition pos,
 InstCallback cbk, void *data, int priority) {
 QBDI_REQUIRE_ACTION(instance, return VMError::INVALID_EVENTID);
 return static_cast<VM *>(instance)->addCodeCB(pos, cbk, data, priority);
}
```
与上边的 `qbdi_getGPRState` 类似, 还是调用 VM 类中的方法, 我们接着往下看, 跟入 `addCodeCB` 方法:
```cpp
uint32_t VM::addCodeCB(InstPosition pos, InstCallback cbk, void *data,
 int priority) {
 QBDI_REQUIRE_ACTION(cbk != nullptr, return VMError::INVALID_EVENTID);
 return engine->addInstrRule(InstrRuleBasicCBK::unique(
 True::unique(), cbk, data, pos, true, priority,
 (pos == PREINST) ? RelocTagPreInstStdCBK : RelocTagPostInstStdCBK));
}
```
一点点看, 首先是 `True::unique()`, 跟进去:
```cpp
// helper to create a object as a unique_ptr
template <typename T, typename U>
class AutoUnique : public T {
public:
 template <typename... Args>
 AutoUnique(Args &&...args) : T(std::forward<Args>(args)...) {}

template <typename... Args>
 inline static std::unique_ptr<T> unique(Args &&...args) {
 return std::make_unique(std::forward<Args>(args)...);
 };
};
```
发现就是一个模板工具类, 用来快速创建 `unique_ptr` 只能指针(这个指针的使用与 rust 中的所有权转移类似, 一个 std::unique_ptr 对象在任何时刻只能拥有一个指向动态分配对象的指针. 它不允许拷贝构造或赋值, 但可以通过 std::move 将所有权从一个 std::unique_ptr 转移到另一个), 现在我们疑惑的是 `AutoUnique` 这个模板类在 `True::unique` 调用时 `typename T, typename U` 是什么, 为此我们还要跟入 `True` 类一探究竟:
```cpp
class True : public AutoClone<PatchCondition, True> {
public:
 /*! Return true.
 */
 True() {}

bool test(const Patch &patch, const LLVMCPU &llvmcpu) const override {
 return true;
 }
};
```
在跟入 `AutoClone<PatchCondition, True>`:
```cpp
// helper to clone object, when the copy is possible
template <typename T, typename U>
class AutoClone : public AutoUnique<T, U> {
public:
 template <typename... Args>
 AutoClone(Args &&...args) : AutoUnique<T, U>(std::forward<Args>(args)...) {}

inline std::unique_ptr<T> clone() const override {
 return std::make_unique(*static_cast<const U *>(this));
 };
};
```
看到这, 我们可以知道 T 类型是 `PatchCondition`, U 类型是 `True`, 而 `AutoClone` `AutoUnique` 模板类相当于插入继承链, 本来是 `True` 类继承 `PatchCondition` 类变为了 `True` 继承 `AutoClone` 继承 `AutoUnique` 继承 `PatchCondition`. 而 `True::unique(address)` 创建的也就是一个类型为 `True` 的智能指针, 而翻回头来 `InstrRuleBasicCBK::unique` 也是类似的实现:
```cpp
class InstrRuleBasicCBK : public AutoUnique<InstrRule, InstrRuleBasicCBK> {

PatchConditionUniquePtr condition;
  PatchGeneratorUniquePtrVec patchGen;
  InstPosition position;
  bool breakToHost;
  RelocatableInstTag tag;
  InstCallback cbk;
  void *data;

public:
  /*! 创建新的插桩规则, 包含条件判断、生成器列表、插桩位置和主机中断请求. 
   *
   * @param[in] condition    用于判断该PatchRule是否适用的PatchCondition条件
   * @param[in] cbk          待执行的回调函数
   * @param[in] data         传递给回调函数的数据指针
   * @param[in] position     枚举值, 指示插桩应位于指令之前还是之后
   * @param[in] breakToHost  布尔值, 决定该插桩是否应以主机中断结束（例如在回调场景）
   * @param[in] priority     回调函数的优先级
   * @param[in] tag          回调函数的标签
   */
  InstrRuleBasicCBK(PatchConditionUniquePtr &&condition, InstCallback cbk,
                    void *data, InstPosition position, bool breakToHost,
                    int priority = PRIORITY_DEFAULT,
                    RelocatableInstTag tag = RelocTagInvalid);

~InstrRuleBasicCBK() override;

std::unique_ptr<InstrRule> clone() const override;

inline InstPosition getPosition() const { return position; }

RangeSet<rword> affectedRange() const override;

/*! 通过评估当前上下文中的规则条件, 确定本规则是否适用. 
   *
   * @param[in] patch    包含当前上下文的补丁对象
   * @param[in] llvmcpu  LLVMCPU对象
   *
   * @return 若插桩条件在当前补丁上评估为真, 则返回true
   */
  bool canBeApplied(const Patch &patch, const LLVMCPU &llvmcpu) const;

bool changeDataPtr(void *data) override;

inline bool tryInstrument(Patch &patch,
 const LLVMCPU &llvmcpu) const override {
 if (canBeApplied(patch, llvmcpu)) {
 instrument(patch, patchGen, breakToHost, position, priority, tag);
 return true;
 }
 return false;
 }
};
```
好了现在我们可以回过头来跟入 `engine->addInstrRule` 函数了:
```cpp
uint32_t Engine::addInstrRule(std::unique_ptr<InstrRule> &&rule) {
 uint32_t id = instrRulesCounter++;
 QBDI_REQUIRE_ACTION(id < EVENTID_VM_MASK, return VMError::INVALID_EVENTID);

this->clearCache(rule->affectedRange());

auto v = std::make_pair(id, std::move(rule));

return id;
}
```
把插桩规则的个数 `instrRulesCounter` 作为 id 返回, 并规定了最大个数 `id < EVENTID_VM_MASK`, 再看 `this->clearCache(rule->affectedRange())`, 先跟入 `rule->affectedRange`(如果跳转错误, 也可以搜索 `InstrRuleBasicCBK::affectedRange`):
```cpp
RangeSet<rword> InstrRuleBasicCBK::affectedRange() const {
 return condition->affectedRange();
}
```
`InstrRuleBasicCBK` 的 condition 属性就是 `True::unique()`, 而 `True` 类继承自 `PatchCondition`, 在跟入 `condition->affectedRange`, 就到了 `PatchCondition` 类中:
```cpp
class PatchCondition {
public:
 using UniquePtr = std::unique_ptr<PatchCondition>;
 using UniquePtrVec = std::vector<std::unique_ptr<PatchCondition>>;

virtual UniquePtr clone() const = 0;

virtual bool test(const Patch &patch, const LLVMCPU &llvmcpu) const = 0;

virtual RangeSet<rword> affectedRange() const {
 RangeSet<rword> r;
 r.add(Range<rword>(0, (rword)-1));
 return r;
 }

virtual ~PatchCondition() = default;
};
```
`Range` 与 `RangeSet` 太长了, 说下作用, 不在贴出代码, 感兴趣可以到 `include/QBDI/Range.h` 中自行查看:
- `Range`: 用于表示和区间范围的类, 它提供了对范围的各种操作, 例如检查范围是否包含某个值、是否与另一个范围重叠、计算范围的大小、获取范围的交集等
- `RangeSet`: 用于管理一组范围(Range)的容器类, 它提供了对范围集合的各种操作, 例如添加、删除、交集、并集等.

回到 `Engine::addInstrRule` 函数中来看剩余这部分:
```cpp
auto v = std::make_pair(id, std::move(rule));

// insert rule in instrRules and keep the priority order
auto it = std::upper_bound(instrRules.begin(), instrRules.end(), v,
 [](const decltype(instrRules)::value_type &a,
 const decltype(instrRules)::value_type &b) {
 return a.second->getPriority() >
 b.second->getPriority();
 });
instrRules.insert(it, std::move(v));
```
`std::make_pair` 创建了一个 `std::pair` 对象, 将 id 和 rule 组合在一起. `std::upper_bound` 是一个标准库函数, 用于在有序范围内找到第一个不满足给定条件的元素. 而 `instrRules` 是`std::vector<std::pair<uint32_t, std::unique_ptr<InstrRule>>>` 类型, 所以这段代码就是将 `rule` 插入到 `instrRules` 中第一个优先级小于或等于 `rule` 的优先级的位置. 使得 `instrRules` 中的规则始终按照优先级从高到低.

总结一下 `qbdi_addCodeCB` 函数就是创建插桩规则然后按输入的优先级存起来. 其中插桩规则保存了回调函数, 插桩位置, 用户参数...具体可以看 `InstrRuleBasicCBK` 类的构造函数.

#### 回到示例中, 类比 `qbdi_addCodeCB` 看一下 `qbdi_addMnemonicCB` 函数:
```cpp
uint32_t qbdi_addMnemonicCB(VMInstanceRef instance, const char *mnemonic,
 InstPosition pos, InstCallback cbk, void *data,
 int priority) {
 QBDI_REQUIRE_ACTION(instance, return VMError::INVALID_EVENTID);
 return static_cast<VM *>(instance)->addMnemonicCB(mnemonic, pos, cbk, data,
 priority);
}
```
二话不说跟进 `addMnemonicCB`:
```cpp
uint32_t VM::addMnemonicCB(const char *mnemonic, InstPosition pos,
 InstCallback cbk, void *data, int priority) {
 QBDI_REQUIRE_ACTION(mnemonic != nullptr, return VMError::INVALID_EVENTID);
 QBDI_REQUIRE_ACTION(cbk != nullptr, return VMError::INVALID_EVENTID);
 return engine->addInstrRule(InstrRuleBasicCBK::unique(
 MnemonicIs::unique(mnemonic), cbk, data, pos, true, priority,
 (pos == PREINST) ? RelocTagPreInstStdCBK : RelocTagPostInstStdCBK));
}
```
可以看到和 `qbdi_addCodeCB` 函数实现唯一的差别就是 `True::unique()` 变为了 `MnemonicIs::unique(mnemonic)`. `mnemonic` 就是咱们传进来的出发回调的特定指令, 在斐波那契这个示例中就是 `"CALL*"`. 而 `MnemonicIs` 类与 `True` 类似:
```cpp
class MnemonicIs : public AutoClone<PatchCondition, MnemonicIs> {
 std::string mnemonic;

public:
  /*! Return true if the mnemonic of the current instruction is equal to
   * Mnemonic.
   *
   * @param[in] mnemonic   A null terminated instruction mnemonic (using LLVM
   * style)
   */
  MnemonicIs(const char *mnemonic) : mnemonic(mnemonic) {}

bool test(const Patch &patch, const LLVMCPU &llvmcpu) const override;
};
```
看到这结合上面不难猜测 `True` 和 `MnemonicIs` 类都是用来判断回调条件的, 而这个 `test` 虚函数就是判断的统一调用. 所以我们在来看看 `MnemonicIs::test`:
```cpp
bool MnemonicIs::test(const Patch &patch, const LLVMCPU &llvmcpu) const {
  return QBDI::String::startsWith(
      mnemonic.c_str(), llvmcpu.getInstOpcodeName(patch.metadata.inst));
}

bool startsWith(const char *prefix, const char *str) {
  // 确保prefix和str都不是nullptr
  QBDI_REQUIRE_ACTION(prefix != nullptr, return false);
  QBDI_REQUIRE_ACTION(str != nullptr, return false);

// 遍历prefix和str, 逐字符比较
 while (*prefix && *str) {
 // 通配符匹配: 如果prefix中的当前字符是'*', 则跳过直到str中的字符与prefix中的下一个字符匹配
 if (*prefix == '*') {
 // 如果prefix的下一个字符（忽略大小写）与str的当前字符匹配, 则移动prefix和str的指针
 if (toupper(*(prefix + 1)) == toupper(*str++)) {
 prefix++;
 }
 // 继续检查下一个字符
 continue;
 }
 // 比较当前字符（忽略大小写）
 if (toupper(*prefix++) != toupper(*str++)) {
 // 如果字符不匹配, 返回false
 return false;
 }
 }
 // 检查prefix是否还有未匹配的字符（除了通配符'*'之外）
 if (*prefix && *(prefix + 1)) {
 // 如果prefix还有未匹配的字符, 则返回false
 return false;
 }
 // 检查str的下一个字符是否是数字、下划线或字符串结束符
 // 如果不是, 则返回false
 if (!((*str >= '0' && *str <= '9') || *str == '_' || !*str)) {
 return false;
 }
 // 如果所有检查都通过, 则返回true
 return true;
}
```
我们先来看看第一个参数的类型 `Patch` 类, 跟入来到了 `src/Patch/Patch.h` 中, 代码不长, 将头文件注释:
```cpp
namespace llvm {
class MCInst;
}

namespace QBDI {
class LLVMCPU;
class RelocatableInst;

// 指令补丁结构
struct InstrPatch {
 InstPosition position;
 int priority;
 std::vector<std::unique_ptr<RelocatableInst>> insts;
};

// 指令补丁的类
class Patch {
private:
 std::vector<InstrPatch> instsPatchs;

public:
 InstMetadata metadata;
 std::vector<std::unique_ptr<RelocatableInst>> insts;
 // 由 PatchRule 生成的标志
 std::vector<std::pair<unsigned int, int>> patchGenFlags;
 int patchGenFlagsOffset = 0;
 // 用于在 ExecBlockManager 中注册的指令回调
 std::vector<std::unique_ptr<InstCbLambda>> userInstCB;
 // 指令使用的寄存器
 std::array<RegisterUsage, NUM_GPR> regUsage;
 std::map<RegLLVM, RegisterUsage> regUsageExtra;
 // 本补丁使用的临时寄存器
 std::set<RegLLVM> tempReg;
 const LLVMCPU *llvmcpu;
 bool finalize = false;

using Vec = std::vector<Patch>;

Patch(const llvm::MCInst &inst, rword address, uint32_t instSize,
        const LLVMCPU &llvmcpu);

Patch(Patch &&);
  Patch &operator=(Patch &&);

~Patch();

void setModifyPC(bool modifyPC);

// 在指令列表的末尾追加一个可重定位指令
 void append(std::unique_ptr<RelocatableInst> &&r);
 // 在指令列表的末尾追加多个可重定位指令
 void append(std::vector<std::unique_ptr<RelocatableInst>> v);

// 在指令列表的开头插入一个可重定位指令
 void prepend(std::unique_ptr<RelocatableInst> &&r);
 // 在指令列表的开头插入多个可重定位指令
 void prepend(std::vector<std::unique_ptr<RelocatableInst>> v);

// 在指定位置插入多个可重定位指令
 void insertAt(unsigned position,
 std::vector<std::unique_ptr<RelocatableInst>> v);

void addInstsPatch(InstPosition position, int priority,
 std::vector<std::unique_ptr<RelocatableInst>> v);

void finalizeInstsPatch();
};

} // namespace QBDI
```
在跟进 `llvmcpu.getInstOpcodeName` 看一眼:
```cpp
const char *LLVMCPU::getInstOpcodeName(const llvm::MCInst &inst) const {
  return getInstOpcodeName(inst.getOpcode());
}

const char *LLVMCPU::getInstOpcodeName(unsigned opcode) const {
 /* llvm::StringRef can return a no null terminate pointer
 * However, in the case of opcode name, that seems to be always the case
 * see <ARM|AArch64|X86>InstrNameData
 */
 return MCII->getName(opcode).data();
}
```
看样子是在返回反汇编指令, 行, 这里先打住, 乱猜也是浪费时间, 接下往下看.

#### 回到示例, 跟进 `qbdi_addInstrumentedModuleFromAddr` 函数:
```cpp
bool qbdi_addInstrumentedModuleFromAddr(VMInstanceRef instance, rword addr) {
 QBDI_REQUIRE_ACTION(instance, return false);
 return static_cast<VM *>(instance)->addInstrumentedModuleFromAddr(addr);
}

bool VM::addInstrumentedModuleFromAddr(rword addr) {
  return engine->addInstrumentedModuleFromAddr(addr);
}

bool Engine::addInstrumentedModuleFromAddr(rword addr) {
 return execBroker->addInstrumentedModuleFromAddr(addr);
}
```
从上到下一步步跟入, execBroker 是 `Engine` 类的一个属性 `ExecBroker *execBroker`, 也是 `ExecBroker` 类的实例, 我们继续跟入 `execBroker->addInstrumentedModuleFromAddr` 函数:
```cpp
bool ExecBroker::addInstrumentedModuleFromAddr(rword addr) {
 // 遍历当前进程的内存映射
 for (const MemoryMap &m : getCurrentProcessMaps()) {
 // 检查当前内存映射是否包含指定地址
 if (m.range.contains(addr)) {
 // 如果内存映射有名称（即是一个已知的模块）
 if (not m.name.empty()) {
 // 尝试将该模块添加到已监控的模块列表中
 return addInstrumentedModule(m.name);
 } else if (m.permission & QBDI::PF_EXEC) {
 // 如果内存映射没有名称, 但具有执行权限
 // 则将该内存范围添加到已监控的范围中
 addInstrumentedRange(m.range);
 return true;
 } else {
 // 如果内存映射没有名称且没有执行权限, 则返回false
 return false;
 }
 }
 }
 // 如果没有找到包含指定地址的内存映射, 返回false
 return false;
}
```
看函数的名字就很容易知道在做什么, 写出注释. 首先先看看 `getCurrentProcessMaps` 函数, 来到了 `src/Utility/Memory_linux.cpp` 中, 还是会根据你编译的架构确定函数实现, 在同级目录下同样有其他架构的实现:
 ![](upload/attach/202507/1025255_KJV33ME6GU7QGN3.webp)
闲话少说来看看 `getCurrentProcessMaps` 函数的实现:
```cpp
QBDI_EXPORT std::vector<MemoryMap>
getCurrentProcessMaps(bool full_path = false);

std::vector<MemoryMap> getCurrentProcessMaps(bool full_path) {
 return getRemoteProcessMaps(getpid(), full_path);
}

// 获取指定进程的内存映射
std::vector<MemoryMap> getRemoteProcessMaps(QBDI::rword pid, bool full_path) {
 static const int BUFFER_SIZE = 256; // 定义缓冲区大小
 char line[BUFFER_SIZE] = {0}; // 用于存储读取的每一行数据
 FILE *mapfile = nullptr; // 文件指针, 用于打开 /proc/[pid]/maps 文件
 std::vector<MemoryMap> maps; // 用于存储解析后的内存映射信息

// 构造 /proc/[pid]/maps 文件的路径
  snprintf(line, BUFFER_SIZE, "/proc/%llu/maps", (unsigned long long)pid);
  // 打开文件
  mapfile = fopen(line, "r");
  // 打印调试信息
  QBDI_DEBUG("Querying memory maps from {}", line);
  // 确保文件打开成功
  QBDI_REQUIRE_ACTION(mapfile != nullptr, return maps);

// 处理 /proc/[pid]/maps 文件中的每一行
  while (fgets(line, BUFFER_SIZE, mapfile) != nullptr) {
    char *ptr = nullptr; // 用于指向当前解析的位置
    MemoryMap m; // 创建一个 MemoryMap 对象, 用于存储当前行的解析结果

// 去掉行尾的换行符
    if ((ptr = strchr(line, '\n')) != nullptr) {
      *ptr = '\0';
    }
    ptr = line; // 从行首开始解析
    QBDI_DEBUG("Parsing line: {}", line);

// 解析内存范围
    m.range.setStart(strtoul(ptr, &ptr, 16)); // 解析起始地址
    ptr++; // 跳过 '-'
    m.range.setEnd(strtoul(ptr, &ptr, 16)); // 解析结束地址