x64dbg 插件开发指南:深入解析 PLUG_CB_UNLOADDLL DLL 卸载事件回调
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(); // ⑦ 更新内存映射视图
}
从这段实现可以清晰看到文档所述时序的源码依据:
- 插件回调最先执行:
plugincbcall(CB_UNLOADDLL, &callbackInfo)位于函数最前面,早于后续任何模块清理逻辑; - 断点清理在后:x64dbg 会枚举并移除与被卸载模块相关的断点(
cbRemoveModuleBreakpoints),随后在日志窗口打印DLL Unloaded: <base> <modname>; - 暂停判定在后:若用户在事件设置中开启了
DllUnload(或系统 DLL 的DllUnloadSystem),调试器才在此处暂停; - 从模块列表移除在最后:
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 同样遵守:
callbackInfo指针永不为 NULL:但结构体内的成员可能为 NULL,使用前应做判空;- 指针仅在回调函数作用域内有效:
UnloadDll指向的内存由调试循环管理,不能保存指针到回调之外使用,如需保留数据应在回调内及时拷贝; - 避免在回调内执行耗时操作:回调运行在调试循环的关键路径上(从上面的源码可以看到,回调返回后调试器还要继续完成断点清理、事件判定、模块移除等工作),耗时操作会阻塞调试器,建议将重活放到独立线程;
- 回调不影响调试器默认行为:该回调是"通知型"接口,插件无法通过修改返回结构阻止 DLL 卸载或改变 x64dbg 的模块清理流程;
- 事件开关依赖用户设置:是否因卸载而暂停由
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 卸载并执行自定义逻辑。