x64dbg 插件开发指南:深入解析 PLUG_CB_UNLOADDLL DLL 卸载事件回调

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

x64dbg 插件开发指南:深入解析 PLUG_CB_UNLOADDLL DLL 卸载事件回调

导读

本文围绕 x64dbg 插件 SDK 中的 PLUG_CB_UNLOADDLL 回调结构展开,详细说明 DLL 卸载事件在调试循环中的触发时机、数据结构定义、底层调用链,以及插件开发者如何在 DLL 被卸载时获得通知并做出响应。读完本文,你将掌握 x64dbg 插件 SDK 中模块卸载事件回调的完整用法:从回调注册、结构体解读,到基于 src/dbg/debugger.cpp 源码理解回调前后的调试器内部动作,能够独立编写出监听 DLL 卸载事件的实用插件。

回调结构定义

PLUG_CB_UNLOADDLL 是 x64dbg 插件 SDK 定义的事件回调结构之一,用于在调试会话中 DLL 被卸载时向插件传递相关信息。其完整定义(见 src/dbg/_plugins.h)如下:

typedef struct
{
    UNLOAD_DLL_DEBUG_INFO* UnloadDll;
} PLUG_CB_UNLOADDLL;

该结构与官方插件文档 docs/developers/plugins/Callbacks/plugcbunloaddll.rst 中描述的一致:

struct PLUG_CB_UNLOADDLL
{
    UNLOAD_DLL_DEBUG_INFO* UnloadDll;
};

结构体只有一个成员:

成员 类型 说明
UnloadDll UNLOAD_DLL_DEBUG_INFO* 指向 Windows 调试事件结构 UNLOAD_DLL_DEBUG_INFO 的指针

底层成员:UNLOAD_DLL_DEBUG_INFO

UNLOAD_DLL_DEBUG_INFO 是 Windows SDK 定义的标准调试事件结构,当调试器收到 LOAD_DLL_DEBUG_EVENT(即 UNLOAD_DLL_DEBUG_EVENT)时由操作系统填充。该结构仅包含一个成员:

typedef struct _UNLOAD_DLL_DEBUG_INFO {
    LPVOID lpBaseOfDll;  // 被卸载 DLL 的基地址
} UNLOAD_DLL_DEBUG_INFO;

在插件回调中,可以通过 info->UnloadDll->lpBaseOfDll 拿到被卸载 DLL 的基地址。结合 x64dbg 的模块 API,可以进一步解析该地址对应的模块名、路径等信息(例如通过 ModNameFromAddr 或模块 API 将基地址转换为模块名,供日志或条件判断使用)。

触发时机:调试循环中的卸载流程

根据官方文档 plugcbunloaddll.rst 的说明,该回调在以下时机被触发:

  • 在**调试循环(debug loop)**中被调用;
  • 发生在将该 DLL 从内部模块列表移除之前;
  • 发生在因 DLL 卸载而暂停(break on DLL unloading)之前。

也就是说,插件在 PLUG_CB_UNLOADDLL 回调里看到的模块信息仍然是"有效"的——此时 x64dbg 尚未执行模块卸载的内部清理工作,插件仍可基于 lpBaseOfDll 读取模块相关数据。

源码层面的完整调用链

回调的触发点在 src/dbg/debugger.cpp 的 cbUnloadDll 函数中。该函数通过 SetCustomHandler(UE_CH_UNLOADDLL, (TITANCALLBACKARG)cbUnloadDll)(见 src/dbg/debugger.cpp)注册为 TitanEngine 的 DLL 卸载事件处理器。核心流程如下:

static void cbUnloadDll(UNLOAD_DLL_DEBUG_INFO* UnloadDll)
{
    hActiveThread = ThreadGetHandle(GetDebugData()->dwThreadId);
    PLUG_CB_UNLOADDLL callbackInfo;
    callbackInfo.UnloadDll = UnloadDll;
    plugincbcall(CB_UNLOADDLL, &callbackInfo);   // ① 通知所有插件

    void* base = UnloadDll->lpBaseOfDll;        // ② 取出 DLL 基地址
    char modname[MAX_MODULE_SIZE] = "???";
    if(ModNameFromAddr((duint)base, modname, true))
        BpEnumAll(cbRemoveModuleBreakpoints, modname, duint(base)); // ③ 移除与该模块相关的断点
    int party = ModGetParty(duint(base));
    DebugUpdateBreakpointsViewAsync();
    dprintf(QT_TRANSLATE_NOOP("DBG", "DLL Unloaded: %p %s\n"), base, modname); // ④ 日志输出

    // ⑤ 根据事件设置决定是否暂停
    auto dllUnloadSetting = party == mod_system ? "DllUnloadSystem" : "DllUnload";
    if(dbghandledllbreakpoint(modname, false))
    {
        cbGenericBreakpoint(BPDLL, modname);
    }
    else if(settingboolget("Events", dllUnloadSetting, false))
    {
        // ... 暂停调试,等待用户操作 ...
    }

    ModUnload((duint)base);   // ⑥ 从内部模块列表移除

    MemUpdateMapAsync();      // ⑦ 更新内存映射视图
}

从这段实现可以清晰看到文档所述时序的源码依据:

  1. 插件回调最先执行:plugincbcall(CB_UNLOADDLL, &callbackInfo) 位于函数最前面,早于后续任何模块清理逻辑;
  2. 断点清理在后:x64dbg 会枚举并移除与被卸载模块相关的断点(cbRemoveModuleBreakpoints),随后在日志窗口打印 DLL Unloaded: <base> <modname>;
  3. 暂停判定在后:若用户在事件设置中开启了 DllUnload(或系统 DLL 的 DllUnloadSystem),调试器才在此处暂停;
  4. 从模块列表移除在最后:ModUnload((duint)base) 将模块从内部模块列表移除,并异步更新内存映射视图。

因此,插件若需要在 DLL 卸载时读取模块的最后状态、或需要在 x64dbg 自身清理前采取行动,PLUG_CB_UNLOADDLL 回调正是最合适的介入点。

与 PLUG_CB_LOADDLL 的时序对比

模块加载与卸载事件是对称的。对照 docs/developers/plugins/Callbacks/plugcbloaddll.rst 与 src/dbg/_plugins.h,二者差异如下:

回调 触发时机 结构成员
PLUG_CB_LOADDLL DLL 加载后、已加入内部模块列表之后、设置 DLL 入口断点之后 LOAD_DLL_DEBUG_INFO* LoadDll、IMAGEHLP_MODULE64* modInfo、const char* modname
PLUG_CB_UNLOADDLL DLL 卸载时、从内部模块列表移除之前、暂停于 DLL 卸载之前 UNLOAD_DLL_DEBUG_INFO* UnloadDll

需要特别注意的是,PLUG_CB_LOADDLL 额外提供了 modInfo(模块信息)与 modname(模块名)两个便捷成员,而 PLUG_CB_UNLOADDLL 只有原始调试事件指针 UnloadDll,插件需要自行从 lpBaseOfDll 解析模块信息。

如何注册并接收该回调

方式一:使用 _plugin_registercallback

在 pluginit 中通过 _plugin_registercallback 注册(API 原型见 docs/developers/plugins/API/registercallback.rst,声明见 src/dbg/_plugins.h):

#include "_plugins.h"

static void CBUNLOADDLL(CBTYPE cbType, PLUG_CB_UNLOADDLL* info)
{
    // cbType 为 CB_UNLOADDLL,info->UnloadDll 指向卸载事件信息
    duint base = (duint)info->UnloadDll->lpBaseOfDll;
    dprintf("Plugin: DLL unloaded at %p\n", base);
}

extern "C" __declspec(dllexport) bool pluginit(PLUG_INITSTRUCT* initStruct)
{
    initStruct->pluginVersion = 1;
    initStruct->sdkVersion = PLUG_SDKVERSION;
    strncpy_s(initStruct->pluginName, "MyUnloadWatcher", _TRUNCATE);

    _plugin_registercallback(initStruct->pluginHandle, CB_UNLOADDLL, CBUNLOADDLL);
    return true;
}

extern "C" __declspec(dllexport) bool plugstop()
{
    // 建议在插件卸载时注销回调
    _plugin_unregistercallback(-1, CB_UNLOADDLL);
    return true;
}

CBTYPE 枚举中对应的事件类型为 CB_UNLOADDLL(见 src/dbg/_plugins.h),其注释明确标注对应 PLUG_CB_UNLOADDLL。回调函数类型为:

typedef void (*CBPLUGIN)(CBTYPE cbType, void* callbackInfo);

注意 _plugin_registercallback 的说明:每个事件每个插件只能注册一个回调,不允许对同一事件注册多个回调函数。

方式二:导出同名回调

根据 docs/developers/plugins/basics.md 的说明,除显式调用注册函数外,插件还可以直接导出一个名为 CBUNLOADDLL 的 CDECL 导出函数,x64dbg 会自动将其注册为 CB_UNLOADDLL 事件的回调(导出名中不要使用下划线):

extern "C" __declspec(dllexport) void CBUNLOADDLL(CBTYPE cbType, PLUG_CB_UNLOADDLL* info)
{
    // 自动注册的卸载事件回调
}

另外,如果插件导出名为 CBALLEVENTS 的函数,则会收到所有事件的回调(在注册其他具名导出之前完成绑定),此时可通过 cbType 参数区分具体事件类型。

使用同一个函数处理多个事件

回调函数签名中的 cbType 参数正是为"多事件复用"设计的。例如可以注册同一个函数处理 CB_LOADDLL 与 CB_UNLOADDLL,再通过 cbType 分支:

static void CBLOADUNLOAD(CBTYPE cbType, void* callbackInfo)
{
    if(cbType == CB_LOADDLL)
    {
        auto* info = (PLUG_CB_LOADDLL*)callbackInfo;
        dprintf("Loaded: %s\n", info->modname);
    }
    else if(cbType == CB_UNLOADDLL)
    {
        auto* info = (PLUG_CB_UNLOADDLL*)callbackInfo;
        dprintf("Unloaded: %p\n", info->UnloadDll->lpBaseOfDll);
    }
}

使用注意事项

x64dbg 插件回调(docs/developers/plugins/Callbacks/index.rst)有一组适用于所有事件的通用约定,PLUG_CB_UNLOADDLL 同样遵守:

  1. callbackInfo 指针永不为 NULL:但结构体内的成员可能为 NULL,使用前应做判空;
  2. 指针仅在回调函数作用域内有效:UnloadDll 指向的内存由调试循环管理,不能保存指针到回调之外使用,如需保留数据应在回调内及时拷贝;
  3. 避免在回调内执行耗时操作:回调运行在调试循环的关键路径上(从上面的源码可以看到,回调返回后调试器还要继续完成断点清理、事件判定、模块移除等工作),耗时操作会阻塞调试器,建议将重活放到独立线程;
  4. 回调不影响调试器默认行为:该回调是"通知型"接口,插件无法通过修改返回结构阻止 DLL 卸载或改变 x64dbg 的模块清理流程;
  5. 事件开关依赖用户设置:是否因卸载而暂停由 Events 配置中的 DllUnload / DllUnloadSystem 决定,但 PLUG_CB_UNLOADDLL 回调本身在每次 DLL 卸载时都会触发,与暂停设置无关。

典型应用场景

结合回调触发时机(模块移除之前)与调试器内部动作,PLUG_CB_UNLOADDLL 适合实现以下功能:

  • 卸载监控/审计:记录目标进程加载、卸载的 DLL 基地址序列,用于脱壳、反调试对抗分析中的模块活动追踪;
  • 模块状态快照:在模块从列表移除前捕获其导出表、节区权限等最后状态;
  • 条件卸载日志:结合 ModNameFromAddr 判断卸载模块是否为关注目标(如被注入的 payload DLL),命中时输出详细日志甚至触发后续脚本动作;
  • 资源清理:插件自身维护与模块关联的数据(如符号缓存、分析结果)时,在卸载回调中同步清理,避免内存泄漏或悬挂引用。

小结

PLUG_CB_UNLOADDLL 是 x64dbg 插件 SDK 中感知"模块生命周期"的关键回调之一。通过 src/dbg/_plugins.h 中的结构定义与 src/dbg/debugger.cpp 的 cbUnloadDll 实现,可以确认:回调在 DLL 从内部模块列表移除之前、暂停判定之前触发,且是 cbUnloadDll 函数中最早执行的动作。插件开发者既可通过 _plugin_registercallback 显式注册,也可通过导出 CBUNLOADDLL 符号自动绑定,从而在正确的时机观察 DLL 卸载并执行自定义逻辑。

登录后查看全文
x64dbg