x64dbg 插件开发指南:深入解析 PLUG_CB_CREATETHREAD 线程创建回调

原创2026-09-19 19:59:491,455 阅读
文章标签:开发工具调试器逆向工程桌面应用网络安全

x64dbg 插件开发指南:深入解析 PLUG_CB_CREATETHREAD 线程创建回调

PLUG_CB_CREATETHREAD 是 x64dbg 插件 SDK 中用于感知被调试进程新线程创建的核心回调,它在调试器主循环内部、线程信息登记完成之后被同步触发。本文基于 插件回调结构索引 中的官方定义,并结合仓库源码(src/dbg/_plugins.h、src/dbg/debugger.cpp)展开讲解,帮助你掌握该回调的触发时机、结构体字段含义、注册方式以及底层调用链,从而在自己的插件中准确捕获线程创建事件并安全地读取线程信息。

回调概述与触发时机

按照官方文档的定义,PLUG_CB_CREATETHREAD 在以下时序点被调用:

Called after thread creation (in the debug loop), after adding the thread to the internal thread list, before breaking the debugger on thread creation and after setting breakpoints on the thread entry.

即它发生在调试循环(debug loop)处理 CREATE_THREAD_DEBUG_EVENT 的过程中,具体满足四个前置条件:

  1. 线程已在系统层面完成创建(调试器收到了 CREATE_THREAD_DEBUG_EVENT 事件);
  2. 新线程已被加入调试器的内部线程列表(ThreadCreate 已完成);
  3. 调试器尚未因线程创建事件而主动断下(break);
  4. 调试器已经在新线程入口处设置好事件断点(如果用户开启了相关选项)。

简言之,当你的回调被调用时,新线程的一切内部登记工作都已就绪,你可以安全地查询线程 ID、入口地址等数据,而无需担心读到未初始化的状态。

回调信息结构体 PLUG_CB_CREATETHREAD

该回调通过 void* callbackInfo 传入的信息结构体定义如下(完整定义见 src/dbg/_plugins.h):

typedef struct
{
    CREATE_THREAD_DEBUG_INFO* CreateThread;
    DWORD dwThreadId;
} PLUG_CB_CREATETHREAD;

各字段含义:

字段 类型 说明
CreateThread CREATE_THREAD_DEBUG_INFO* Windows 调试事件自带的线程创建信息指针,指向 DEBUG_EVENT 中的 u.CreateThread 成员
dwThreadId DWORD 该线程在调试器内部登记时使用的线程 ID,可用于后续查询线程句柄等操作

其中 CREATE_THREAD_DEBUG_INFO 是 Windows SDK 的标准结构,包含以下成员:

  • hThread:新线程的内核句柄(调试器视角);
  • lpStartAddress:线程入口函数的起始地址(即该线程将从哪里开始执行);
  • lpThreadLocalBase:线程环境块(TEB/TIB)的基地址。

从源码实现看,dwThreadId 取自 GetDebugData()->dwThreadId(当前调试事件的线程 ID),并非直接由 CreateThread 结构派生,因此建议始终优先使用 dwThreadId 字段来标识线程。

注册回调:CBTYPE 与 _plugin_registercallback

所有回调结构体都通过 _plugin_registercallback 函数注册,用法参见 registercallback 文档:

void _plugin_registercallback(
    int pluginHandle, //插件句柄(由 _plugin_register 提供)
    CBTYPE cbType,    //事件类型
    CBPLUGIN cbPlugin //回调函数指针
);

线程创建事件对应的 CBTYPE 枚举值为 CB_CREATETHREAD,在 src/dbg/_plugins.h 中定义,注释明确标注其对应 PLUG_CB_CREATETHREAD。回调函数的类型定义统一为:

void CBPLUGIN(
    CBTYPE bType,        //事件类型(同一函数注册多个事件时可用来区分)
    void* callbackInfo   //指向对应信息结构体的指针,此处为 PLUG_CB_CREATETHREAD*
);

注册代码示例:

static void CBPLUGIN myThreadCallback(CBTYPE bType, void* callbackInfo)
{
    if(bType == CB_CREATETHREAD)
    {
        PLUG_CB_CREATETHREAD* info = (PLUG_CB_CREATETHREAD*)callbackInfo;
        // 在这里处理线程创建事件
    }
}

// 在插件初始化时注册
_plugin_registercallback(pluginHandle, CB_CREATETHREAD, myThreadCallback);

注意事项(来自 回调结构索引 的通用约定,适用于本回调):

  • callbackInfo 指针永远不会为 NULL,但结构体内部的成员可能为 NULL,使用时需判空;
  • 结构体指针只在回调函数作用域内有效,不得保存并在回调外使用;
  • 回调在调试器内部线程上同步执行,应避免执行耗时操作,如确有需要请在独立线程中处理;
  • 同一插件对同一事件只能注册一个回调。

源码级调用链:cbCreateThread 的完整执行流程

CB_CREATETHREAD 的触发点在 src/dbg/debugger.cpp 的 cbCreateThread 函数中,它是调试循环处理 CREATE_THREAD_DEBUG_EVENT 事件时的核心函数。其完整执行顺序如下:

1. 断点预期(BreakIn)检查

if(bBreakInExpected && breakInThreadStartAddress != 0 &&
        (duint)CreateThread->lpStartAddress == breakInThreadStartAddress)
    dwBreakInThreadId = GetDebugData()->dwThreadId;

如果调试器正处于"预期在某地址断下"的状态,且新线程的入口地址与预期地址匹配,则记录该线程 ID 作为断点落点线程。

2. 更新内部线程列表

ThreadCreate(CreateThread); //update thread list
DWORD dwThreadId = GetDebugData()->dwThreadId;
hActiveThread = ThreadGetHandle(dwThreadId);

ThreadCreate 将新线程登记进调试器的内部线程列表(这正是文档所说 "after adding the thread to the internal thread list");随后通过 ThreadGetHandle 获取该线程的调试句柄并切换为活动线程。这一步完成后,线程信息才可供查询。

3. 填充结构体并广播回调

PLUG_CB_CREATETHREAD callbackInfo;
callbackInfo.CreateThread = CreateThread;
callbackInfo.dwThreadId = dwThreadId;
plugincbcall(CB_CREATETHREAD, &callbackInfo);

调试器在此处填充结构体并通过 plugincbcall 向所有注册了 CB_CREATETHREAD 的插件同步分发事件。这就是你的插件回调被调用的确切位置——此时线程已登记完毕,但调试器尚未因线程事件断下。

4. 回调之后的后续处理

回调返回后,调试器继续完成剩余工作,这部分可以帮助你理解回调所处的上下文:

  • 输出日志:通过 dprintf 打印线程 ID、入口地址(lpStartAddress 的符号名)与入口参数(x64 下取自 RDX,x86 下取自 EBX,见 ArchValue(UE_EBX, UE_RDX));
  • 若用户开启了 Events 设置项中的 ThreadEntry,则通过 cmddirectexec 在入口地址处动态设置断点(单步断点 + 自定义日志),这正是文档所说 "after setting breakpoints on the thread entry" 的由来;
  • 若开启了 Events 设置项中的 ThreadStart,则调用 DebugUpdateGuiSetStateAsync 更新 GUI 并进入暂停等待(lock(WAITID_RUN)),即文档所说 "before breaking the debugger on thread creation";
  • 否则,将线程栈以"伪页"形式插入内存映射,避免缓存未命中(对应 issue #1475 的修复)。

可见,你的回调恰好运行在"信息就绪"与"调试器断下/设断点"之间的窗口期,这是读取线程入口地址、参数并做出反应的理想时机。

实战示例:捕获线程入口地址

综合以上知识,下面给出一个完整可用的插件回调示例,它在每次线程创建时打印线程 ID 与入口符号名:

#include "pluginsdk.h"
#include <stdio.h>

static void CBPLUGIN cbCreateThread(CBTYPE bType, void* callbackInfo)
{
    if(bType != CB_CREATETHREAD)
        return;

    PLUG_CB_CREATETHREAD* info = (PLUG_CB_CREATETHREAD*)callbackInfo;
    if(!info->CreateThread)
        return;

    duint entry = (duint)info->CreateThread->lpStartAddress;
    char symbol[MAX_SYMBOL_SIZE] = "";
    if(DbgGetSymbolAt(entry, symbol, MAX_SYMBOL_SIZE))
        dprintf("[MyPlugin] Thread %X created, entry: %s\n", info->dwThreadId, symbol);
    else
        dprintf("[MyPlugin] Thread %X created, entry: %p\n", info->dwThreadId, entry);
}

PLUG_EXPORT bool pluginit(PLUG_INITSTRUCT* initStatus)
{
    initStatus->pluginVersion = 1;
    initStatus->sdkVersion = PLUG_SDKVERSION;
    strcpy_s(initStatus->pluginName, "MyThreadMonitor");
    return true;
}

PLUG_EXPORT bool plugsetup(PLUG_SETUPSTRUCT* setupStruct)
{
    _plugin_registercallback(setupStruct->pluginHandle, CB_CREATETHREAD, cbCreateThread);
    return true;
}

此示例中 plugsetup 在插件装载阶段注册回调;dprintf 输出到 x64dbg 日志窗口,便于即时验证。

使用注意事项与最佳实践

结合官方约定与源码行为,使用 PLUG_CB_CREATETHREAD 时应注意:

  1. 不要跨作用域保存指针:callbackInfo 及其内部的 CreateThread 指针仅在回调执行期间有效,如需保留信息应自行拷贝(例如将 lpStartAddress、dwThreadId 复制到自己的结构中);
  2. 区分两种 ID:dwThreadId 是触发事件时调试器登记的线程 ID;CreateThread->hThread 是系统句柄。按需选择,不要混用;
  3. 回调内勿做耗时操作:回调在调试主循环内同步执行,阻塞会拖慢整个调试器,复杂处理请移交独立线程;
  4. 入口地址是最常用数据:lpStartAddress 对分析线程行为(如反调试线程、多线程加壳逻辑)非常关键,可结合 DbgGetSymbolAt 或 SymGetSymbolicName 解析符号;
  5. 结合线程栈信息:从源码看,回调之后调试器还会读取 TIB(ThreadGetTib)并登记线程栈内存页,若插件需要内存映射数据,建议在回调中自行通过相关 API 查询,不要假设栈页已存在。

与相邻回调的关系

在 x64dbg 的回调体系中,PLUG_CB_CREATETHREAD 与几个相邻事件形成完整的线程生命周期观测链,可参见 回调结构索引:

  • PLUG_CB_CREATEPROCESS(CB_CREATEPROCESS):进程创建时触发,先于任何线程回调;
  • PLUG_CB_CREATETHREAD(CB_CREATETHREAD):每个新线程创建时触发(包括主线程);
  • PLUG_CB_EXITTHREAD(CB_EXITTHREAD):线程退出时触发;
  • PLUG_CB_EXITPROCESS(CB_EXITPROCESS):进程退出时触发,此时不会再收到线程退出事件(主线程退出即进程退出)。

若希望不遗漏任何调试事件(包括线程创建),还可以注册 CB_DEBUGEVENT 类型的全量事件回调,它会在每个调试事件到来时被调用;而 PLUG_CB_CREATETHREAD 的优势在于已经过调试器内部处理、线程信息完备且无需自行解析事件数据。

小结

PLUG_CB_CREATETHREAD 是 x64dbg 插件捕获线程创建事件的标准入口:它在调试器完成线程登记、尚未断下之前被同步触发,结构体同时携带 Windows 原生 CREATE_THREAD_DEBUG_INFO 数据与调试器内部线程 ID。配合 src/dbg/debugger.cpp 的 cbCreateThread 源码,你可以精确理解回调的执行上下文,并据此设计出安全、高效的多线程监控插件。

登录后查看全文
x64dbg