From 3cbf328fee0645314bed2aa9db3e3cd2eb8bfd64 Mon Sep 17 00:00:00 2001 From: sina Date: Sat, 25 Apr 2026 18:02:48 +0200 Subject: [PATCH] Restructure of the hypertrace project --- CHANGELOG.md | 1 + CREDITS.md | 3 +- .../hyperkd/code/debugger/core/Debugger.c | 2 +- .../code/debugger/events/Termination.c | 2 +- .../hyperkd/code/debugger/kernel-level/Kd.c | 2 +- hyperdbg/hyperkd/code/driver/Ioctl.c | 2 +- hyperdbg/hyperkd/code/driver/Loader.c | 2 +- .../code/{Tracing.c => api/LbrApi.c} | 40 +++---- hyperdbg/hypertrace/code/api/PtApi.c | 21 ++++ .../code/{ => broadcast}/Broadcast.c | 0 .../code/{ => broadcast}/DpcRoutines.c | 0 .../hypertrace/code/{ => common}/UnloadDll.c | 0 hyperdbg/hypertrace/code/{ => lbr}/Lbr.c | 35 +++--- hyperdbg/hypertrace/code/pt/Pt.c | 21 ++++ .../header/{Tracing.h => api/LbrApi.h} | 15 +-- hyperdbg/hypertrace/header/api/PtApi.h | 18 +++ .../header/{ => broadcast}/Broadcast.h | 0 .../hypertrace/header/{ => broadcast}/Dpc.h | 0 .../header/{ => broadcast}/DpcRoutines.h | 0 .../header/{ => common}/UnloadDll.h | 0 .../header/{ => globals}/GlobalVariables.h | 6 + hyperdbg/hypertrace/header/{ => lbr}/Lbr.h | 53 +++++---- hyperdbg/hypertrace/header/pch.h | 42 ++++--- hyperdbg/hypertrace/header/pt/Pt.h | 31 +++++ hyperdbg/hypertrace/hypertrace.vcxproj | 30 ++--- .../hypertrace/hypertrace.vcxproj.filters | 107 ++++++++++++------ .../SDK/imports/kernel/HyperDbgHyperTrace.h | 24 ++-- hyperdbg/script-eval/code/Functions.c | 4 +- 28 files changed, 295 insertions(+), 166 deletions(-) rename hyperdbg/hypertrace/code/{Tracing.c => api/LbrApi.c} (88%) create mode 100644 hyperdbg/hypertrace/code/api/PtApi.c rename hyperdbg/hypertrace/code/{ => broadcast}/Broadcast.c (100%) rename hyperdbg/hypertrace/code/{ => broadcast}/DpcRoutines.c (100%) rename hyperdbg/hypertrace/code/{ => common}/UnloadDll.c (100%) rename hyperdbg/hypertrace/code/{ => lbr}/Lbr.c (89%) create mode 100644 hyperdbg/hypertrace/code/pt/Pt.c rename hyperdbg/hypertrace/header/{Tracing.h => api/LbrApi.h} (51%) create mode 100644 hyperdbg/hypertrace/header/api/PtApi.h rename hyperdbg/hypertrace/header/{ => broadcast}/Broadcast.h (100%) rename hyperdbg/hypertrace/header/{ => broadcast}/Dpc.h (100%) rename hyperdbg/hypertrace/header/{ => broadcast}/DpcRoutines.h (100%) rename hyperdbg/hypertrace/header/{ => common}/UnloadDll.h (100%) rename hyperdbg/hypertrace/header/{ => globals}/GlobalVariables.h (92%) rename hyperdbg/hypertrace/header/{ => lbr}/Lbr.h (72%) create mode 100644 hyperdbg/hypertrace/header/pt/Pt.h diff --git a/CHANGELOG.md b/CHANGELOG.md index f55fc80d..bba4deea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,7 @@ New release of the HyperDbg Debugger. - Fix the problem of the '!epthook' not finding the PML1 entry ([link](https://docs.hyperdbg.org/commands/extension-commands/epthook)) - Fix the problem of getting the PML1 entry of the target address on Intel Core Ultra processors (#567) ([link](https://github.com/HyperDbg/HyperDbg/issues/567)) - Fix the '.clang-format' formatting error +- Restructure of the hypertrace project ## [0.18.0.0] - 2026-02-16 New release of the HyperDbg Debugger. diff --git a/CREDITS.md b/CREDITS.md index 87577baa..0d39ff7b 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -26,4 +26,5 @@ Just so you know – the attributions listed on this credits page are acknowledg - Björn Ruytenberg ([@0Xiphorus](https://twitter.com/0Xiphorus)) - Marcis Zarins ([@CokeTree3](https://github.com/CokeTree3)) for his works on enhancing HyperEvade project - Artem Shishkin ([@honorary_bot](https://twitter.com/honorary_bot)) for always answering our hypervisor questions -- unrustled.jimmies for helping us debug and fix issues, and his contributions in HyperDbg \ No newline at end of file +- unrustled.jimmies for helping us debug and fix issues, and his contributions in HyperDbg +- Hari Mishal ([@harimishal1](https://github.com/harimishal1)) for his works on the hypertrace project for supporting Last Branch Record (LBR) \ No newline at end of file diff --git a/hyperdbg/hyperkd/code/debugger/core/Debugger.c b/hyperdbg/hyperkd/code/debugger/core/Debugger.c index dae95e97..922691f9 100644 --- a/hyperdbg/hyperkd/code/debugger/core/Debugger.c +++ b/hyperdbg/hyperkd/code/debugger/core/Debugger.c @@ -277,7 +277,7 @@ DebuggerUninitialize() // // Uninitialize the HyperTrace (if it was initialized) // - HyperTraceUninit(); + HyperTraceLbrUninit(); // // Uninitialize kernel debugger diff --git a/hyperdbg/hyperkd/code/debugger/events/Termination.c b/hyperdbg/hyperkd/code/debugger/events/Termination.c index 122b455d..b6f59de4 100644 --- a/hyperdbg/hyperkd/code/debugger/events/Termination.c +++ b/hyperdbg/hyperkd/code/debugger/events/Termination.c @@ -1609,7 +1609,7 @@ TerminateQueryDebuggerResourceSaveAndLoadDebugControls(UINT32 // // Query the hypertrace project about this controls since there might be using this load and save controls // - if (HyperTraceQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(CoreId)) + if (HyperTraceLbrQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(CoreId)) { // // We should ignore it since LBR feature of hypertrace is still using it diff --git a/hyperdbg/hyperkd/code/debugger/kernel-level/Kd.c b/hyperdbg/hyperkd/code/debugger/kernel-level/Kd.c index acc93528..cf759122 100644 --- a/hyperdbg/hyperkd/code/debugger/kernel-level/Kd.c +++ b/hyperdbg/hyperkd/code/debugger/kernel-level/Kd.c @@ -2909,7 +2909,7 @@ KdDispatchAndPerformCommandsFromDebugger(PROCESSOR_DEBUGGING_STATE * DbgState) // // Perform the HyperTrace operations (it's in vmx-root) // - HyperTracePerformOperation(HyperTraceOperationPacket, TRUE); + HyperTraceLbrPerformOperation(HyperTraceOperationPacket, TRUE); // // Send the result of the HyperTrace back to the debuggee diff --git a/hyperdbg/hyperkd/code/driver/Ioctl.c b/hyperdbg/hyperkd/code/driver/Ioctl.c index d352309d..eed36c98 100644 --- a/hyperdbg/hyperkd/code/driver/Ioctl.c +++ b/hyperdbg/hyperkd/code/driver/Ioctl.c @@ -1286,7 +1286,7 @@ DrvDispatchIoControl(PDEVICE_OBJECT DeviceObject, PIRP Irp) // // Perform the HyperTrace operation // - HyperTracePerformOperation(HyperTraceOperationRequest, TRUE); + HyperTraceLbrPerformOperation(HyperTraceOperationRequest, TRUE); Irp->IoStatus.Information = SIZEOF_HYPERTRACE_OPERATION_PACKETS; Status = STATUS_SUCCESS; diff --git a/hyperdbg/hyperkd/code/driver/Loader.c b/hyperdbg/hyperkd/code/driver/Loader.c index bc11cc52..48d06e8f 100644 --- a/hyperdbg/hyperkd/code/driver/Loader.c +++ b/hyperdbg/hyperkd/code/driver/Loader.c @@ -63,7 +63,7 @@ LoaderInitHyperTrace(BOOLEAN InitForHypervisorEnvironment) // // Initialize hypertrace module // - if (HyperTraceInitCallback(&HyperTraceCallbacks, InitForHypervisorEnvironment)) + if (HyperTraceLbrInitCallback(&HyperTraceCallbacks, InitForHypervisorEnvironment)) { LogDebugInfo("HyperDbg's hypertrace loaded successfully"); return TRUE; diff --git a/hyperdbg/hypertrace/code/Tracing.c b/hyperdbg/hypertrace/code/api/LbrApi.c similarity index 88% rename from hyperdbg/hypertrace/code/Tracing.c rename to hyperdbg/hypertrace/code/api/LbrApi.c index bd2a9e2d..26862452 100644 --- a/hyperdbg/hypertrace/code/Tracing.c +++ b/hyperdbg/hypertrace/code/api/LbrApi.c @@ -1,8 +1,8 @@ /** - * @file Tracing.c + * @file LbrApi.c * @author Hari Mishal (harimishal6@gmail.com) * @author Sina Karvandi (sina@hyperdbg.org) - * @brief Tracing routines for HyperTrace module + * @brief Tracing routines for HyperTrace module (Intel Last Branch Record) * @details * @version 0.18 * @date 2025-12-02 @@ -20,7 +20,7 @@ * @return BOOLEAN */ VOID -HyperTraceExamplePerformLbrTrace(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) +HyperTraceLbrExamplePerformTrace(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) { if (LbrStartLbr(ApplyFromVmxRootMode, ApplyByVmcall)) { @@ -53,7 +53,7 @@ HyperTraceExamplePerformLbrTrace(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVm * @return BOOLEAN */ BOOLEAN -HyperTraceStartLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) +HyperTraceLbrStart(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) { return LbrStartLbr(ApplyFromVmxRootMode, ApplyByVmcall); } @@ -66,7 +66,7 @@ HyperTraceStartLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) * @return VOID */ VOID -HyperTraceStopLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) +HyperTraceLbrStop(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) { LbrStopLbr(ApplyFromVmxRootMode, ApplyByVmcall); } @@ -82,8 +82,8 @@ HyperTraceStopLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) * @return BOOLEAN */ BOOLEAN -HyperTraceInitCallback(HYPERTRACE_CALLBACKS * HypertraceCallbacks, - BOOLEAN InitForHypervisorEnvironment) +HyperTraceLbrInitCallback(HYPERTRACE_CALLBACKS * HypertraceCallbacks, + BOOLEAN InitForHypervisorEnvironment) { UINT32 ProcessorsCount = 0; @@ -150,7 +150,7 @@ HyperTraceInitCallback(HYPERTRACE_CALLBACKS * HypertraceCallbacks, * @return BOOLEAN */ BOOLEAN -HyperTraceQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(UINT32 CoreId) +HyperTraceLbrQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(UINT32 CoreId) { UNREFERENCED_PARAMETER(CoreId); // Right now there is no core specifc controls for LBR @@ -166,7 +166,7 @@ HyperTraceQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(UINT32 CoreId) * @return BOOLEAN */ BOOLEAN -HyperTraceEnableLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, +HyperTraceLbrEnable(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, BOOLEAN ApplyFromVmxRootMode) { UNREFERENCED_PARAMETER(ApplyFromVmxRootMode); @@ -225,7 +225,7 @@ HyperTraceEnableLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, * @return BOOLEAN */ BOOLEAN -HyperTraceDisableLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, +HyperTraceLbrDisable(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, BOOLEAN ApplyFromVmxRootMode) { UNREFERENCED_PARAMETER(ApplyFromVmxRootMode); @@ -273,7 +273,7 @@ HyperTraceDisableLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, * @return BOOLEAN */ BOOLEAN -HyperTraceSaveLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, +HyperTraceLbrSave(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, BOOLEAN ApplyFromVmxRootMode) { UNREFERENCED_PARAMETER(ApplyFromVmxRootMode); @@ -318,7 +318,7 @@ HyperTraceSaveLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, * @return BOOLEAN */ BOOLEAN -HyperTraceDumpLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, +HyperTraceLbrDump(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, BOOLEAN ApplyFromVmxRootMode) { UNREFERENCED_PARAMETER(ApplyFromVmxRootMode); @@ -360,12 +360,12 @@ HyperTraceDumpLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, * @return VOID */ VOID -HyperTraceUninit() +HyperTraceLbrUninit() { // // Disable LBR tracing if it is still enabled // - HyperTraceDisableLbr(NULL, FALSE); + HyperTraceLbrDisable(NULL, FALSE); // // Set callbacks to not initialized @@ -391,8 +391,8 @@ HyperTraceUninit() * @return BOOLEAN */ BOOLEAN -HyperTracePerformOperation(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, - BOOLEAN ApplyFromVmxRootMode) +HyperTraceLbrPerformOperation(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, + BOOLEAN ApplyFromVmxRootMode) { BOOLEAN Status = TRUE; @@ -414,7 +414,7 @@ HyperTracePerformOperation(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationReq LogInfo("HyperTrace: Enabling LBR tracing...\n"); - HyperTraceEnableLbr(HyperTraceOperationRequest, ApplyFromVmxRootMode); + HyperTraceLbrEnable(HyperTraceOperationRequest, ApplyFromVmxRootMode); break; @@ -422,7 +422,7 @@ HyperTracePerformOperation(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationReq LogInfo("HyperTrace: Disabling LBR tracing...\n"); - HyperTraceDisableLbr(HyperTraceOperationRequest, ApplyFromVmxRootMode); + HyperTraceLbrDisable(HyperTraceOperationRequest, ApplyFromVmxRootMode); break; @@ -430,7 +430,7 @@ HyperTracePerformOperation(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationReq LogInfo("HyperTrace: Saving LBR tracing...\n"); - HyperTraceSaveLbr(HyperTraceOperationRequest, ApplyFromVmxRootMode); + HyperTraceLbrSave(HyperTraceOperationRequest, ApplyFromVmxRootMode); break; @@ -438,7 +438,7 @@ HyperTracePerformOperation(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationReq LogInfo("HyperTrace: Showing LBR tracing...\n"); - HyperTraceDumpLbr(HyperTraceOperationRequest, ApplyFromVmxRootMode); + HyperTraceLbrDump(HyperTraceOperationRequest, ApplyFromVmxRootMode); break; diff --git a/hyperdbg/hypertrace/code/api/PtApi.c b/hyperdbg/hypertrace/code/api/PtApi.c new file mode 100644 index 00000000..3b031415 --- /dev/null +++ b/hyperdbg/hypertrace/code/api/PtApi.c @@ -0,0 +1,21 @@ +/** + * @file PtApi.c + * @author + * @brief Tracing routines for HyperTrace module (Intel Processor Trace) + * @details + * @version 0.19 + * @date 2026-04-25 + * + * @copyright This project is released under the GNU Public License v3. + */ +#include "pch.h" + +/** + * @brief Example of performing PT trace + * + * @return BOOLEAN + */ +VOID +HyperTracePtExample() +{ +} diff --git a/hyperdbg/hypertrace/code/Broadcast.c b/hyperdbg/hypertrace/code/broadcast/Broadcast.c similarity index 100% rename from hyperdbg/hypertrace/code/Broadcast.c rename to hyperdbg/hypertrace/code/broadcast/Broadcast.c diff --git a/hyperdbg/hypertrace/code/DpcRoutines.c b/hyperdbg/hypertrace/code/broadcast/DpcRoutines.c similarity index 100% rename from hyperdbg/hypertrace/code/DpcRoutines.c rename to hyperdbg/hypertrace/code/broadcast/DpcRoutines.c diff --git a/hyperdbg/hypertrace/code/UnloadDll.c b/hyperdbg/hypertrace/code/common/UnloadDll.c similarity index 100% rename from hyperdbg/hypertrace/code/UnloadDll.c rename to hyperdbg/hypertrace/code/common/UnloadDll.c diff --git a/hyperdbg/hypertrace/code/Lbr.c b/hyperdbg/hypertrace/code/lbr/Lbr.c similarity index 89% rename from hyperdbg/hypertrace/code/Lbr.c rename to hyperdbg/hypertrace/code/lbr/Lbr.c index c7bef9dc..6d956b93 100644 --- a/hyperdbg/hypertrace/code/Lbr.c +++ b/hyperdbg/hypertrace/code/lbr/Lbr.c @@ -1,7 +1,7 @@ /** * @file Lbr.c * @author Hari Mishal (harimishal6@gmail.com) - * @brief Message logging and tracing implementation + * @brief Last Branch Record (LBR) tracing implementation for HyperTrace module * @details Modified from LIBIHT project (Thomasaon Zhao et al) with Windows style updates. * @version 0.18 * @date 2025-12-02 @@ -14,8 +14,6 @@ // Global Definitions // ////////////////////////////////////////////////// -ULONGLONG LbrCapacity = 0; - // // Typical Intel LBR capacities based on CPU model // This is a subset; you can expand this as needed @@ -89,18 +87,15 @@ LbrFlushLbr() { ULONG i; ULONGLONG DbgCtlMsr; - KIRQL OldIrql; - - xlock_core(&OldIrql); // // Disable LBR // LogInfo("Flush LBR on cpu core: %d\n", xcoreid()); - xrdmsr(MSR_IA32_DEBUGCTLMSR, &DbgCtlMsr); - DbgCtlMsr &= ~DEBUGCTLMSR_LBR; - xwrmsr(MSR_IA32_DEBUGCTLMSR, DbgCtlMsr); + xrdmsr(IA32_DEBUGCTL, &DbgCtlMsr); + DbgCtlMsr &= ~IA32_DEBUGCTL_LBR_FLAG; + xwrmsr(IA32_DEBUGCTL, DbgCtlMsr); // // Flush LBR registers @@ -113,8 +108,6 @@ LbrFlushLbr() xwrmsr(MSR_LBR_NHM_FROM + i, 0); xwrmsr(MSR_LBR_NHM_TO + i, 0); } - - xrelease_core(&OldIrql); } /** @@ -162,8 +155,8 @@ LbrStartLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) DbgCtlMsr = g_Callbacks.VmFuncGetDebugctl(); } - DbgCtlMsr |= DEBUGCTLMSR_LBR; // Bit 0 = 1 - DbgCtlMsr &= ~(1ULL << 11); // Bit 11 = 0 + DbgCtlMsr |= IA32_DEBUGCTL_LBR_FLAG; // Bit 0 = 1 + DbgCtlMsr &= ~(1ULL << 11); // Bit 11 = 0 if (ApplyByVmcall) { @@ -180,10 +173,10 @@ LbrStartLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) // Enable LBR and CLEAR 'Freeze LBRs on PMI' (Bit 11) // If Bit 11 is set, the LBR stops as soon as a single interrupt happens // - xrdmsr(MSR_IA32_DEBUGCTLMSR, &DbgCtlMsr); - DbgCtlMsr |= DEBUGCTLMSR_LBR; // Bit 0 = 1 - DbgCtlMsr &= ~(1ULL << 11); // Bit 11 = 0 - xwrmsr(MSR_IA32_DEBUGCTLMSR, DbgCtlMsr); + xrdmsr(IA32_DEBUGCTL, &DbgCtlMsr); + DbgCtlMsr |= IA32_DEBUGCTL_LBR_FLAG; // Bit 0 = 1 + DbgCtlMsr &= ~(1ULL << 11); // Bit 11 = 0 + xwrmsr(IA32_DEBUGCTL, DbgCtlMsr); } return TRUE; @@ -251,7 +244,7 @@ LbrStopLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) DbgCtlMsr = g_Callbacks.VmFuncGetDebugctl(); } - DbgCtlMsr &= ~DEBUGCTLMSR_LBR; + DbgCtlMsr &= ~IA32_DEBUGCTL_LBR_FLAG; if (ApplyByVmcall) { @@ -264,9 +257,9 @@ LbrStopLbr(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall) } else { - xrdmsr(MSR_IA32_DEBUGCTLMSR, &DbgCtlMsr); - DbgCtlMsr &= ~DEBUGCTLMSR_LBR; - xwrmsr(MSR_IA32_DEBUGCTLMSR, DbgCtlMsr); + xrdmsr(IA32_DEBUGCTL, &DbgCtlMsr); + DbgCtlMsr &= ~IA32_DEBUGCTL_LBR_FLAG; + xwrmsr(IA32_DEBUGCTL, DbgCtlMsr); } // diff --git a/hyperdbg/hypertrace/code/pt/Pt.c b/hyperdbg/hypertrace/code/pt/Pt.c new file mode 100644 index 00000000..cf2edaaf --- /dev/null +++ b/hyperdbg/hypertrace/code/pt/Pt.c @@ -0,0 +1,21 @@ +/** + * @file Pt.c + * @author + * @brief Processor Trace (PT) tracing implementation for HyperTrace module + * @details + * @version 0.19 + * @date 2026-04-25 + * + * @copyright This project is released under the GNU Public License v3. + */ +#include "pch.h" + +/** + * @brief Processor Trace (PT) test function + * + * @return VOID + */ +VOID +PtTest() +{ +} diff --git a/hyperdbg/hypertrace/header/Tracing.h b/hyperdbg/hypertrace/header/api/LbrApi.h similarity index 51% rename from hyperdbg/hypertrace/header/Tracing.h rename to hyperdbg/hypertrace/header/api/LbrApi.h index 3b5ca89e..da3af5f0 100644 --- a/hyperdbg/hypertrace/header/Tracing.h +++ b/hyperdbg/hypertrace/header/api/LbrApi.h @@ -1,8 +1,8 @@ /** - * @file Tracing.h + * @file LbrApi.h * @author Hari Mishal (harimishal6@gmail.com) - * @brief Message logging and tracing implementation - * @details Modified from LIBIHT project (Thomasaon Zhao et al) with Windows style updates. + * @brief Header for LBR tracing routines for HyperTrace module (Intel Last Branch Record) + * @details * @version 0.18 * @date 2025-12-02 * @@ -11,11 +11,8 @@ #pragma once ////////////////////////////////////////////////// -// Globals // +// Functions // ////////////////////////////////////////////////// -/** - * @brief List of callbacks - * - */ -HYPERTRACE_CALLBACKS g_Callbacks; +VOID +HyperTraceLbrExamplePerformTrace(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall); diff --git a/hyperdbg/hypertrace/header/api/PtApi.h b/hyperdbg/hypertrace/header/api/PtApi.h new file mode 100644 index 00000000..8ba8c25b --- /dev/null +++ b/hyperdbg/hypertrace/header/api/PtApi.h @@ -0,0 +1,18 @@ +/** + * @file PtApi.h + * @author + * @brief Header for PT tracing routines for HyperTrace module (Intel Processor Trace) + * @details + * @version 0.19 + * @date 2026-04-25 + * + * @copyright This project is released under the GNU Public License v3. + */ +#pragma once + +////////////////////////////////////////////////// +// Globals // +////////////////////////////////////////////////// + +VOID +HyperTracePtExample(); diff --git a/hyperdbg/hypertrace/header/Broadcast.h b/hyperdbg/hypertrace/header/broadcast/Broadcast.h similarity index 100% rename from hyperdbg/hypertrace/header/Broadcast.h rename to hyperdbg/hypertrace/header/broadcast/Broadcast.h diff --git a/hyperdbg/hypertrace/header/Dpc.h b/hyperdbg/hypertrace/header/broadcast/Dpc.h similarity index 100% rename from hyperdbg/hypertrace/header/Dpc.h rename to hyperdbg/hypertrace/header/broadcast/Dpc.h diff --git a/hyperdbg/hypertrace/header/DpcRoutines.h b/hyperdbg/hypertrace/header/broadcast/DpcRoutines.h similarity index 100% rename from hyperdbg/hypertrace/header/DpcRoutines.h rename to hyperdbg/hypertrace/header/broadcast/DpcRoutines.h diff --git a/hyperdbg/hypertrace/header/UnloadDll.h b/hyperdbg/hypertrace/header/common/UnloadDll.h similarity index 100% rename from hyperdbg/hypertrace/header/UnloadDll.h rename to hyperdbg/hypertrace/header/common/UnloadDll.h diff --git a/hyperdbg/hypertrace/header/GlobalVariables.h b/hyperdbg/hypertrace/header/globals/GlobalVariables.h similarity index 92% rename from hyperdbg/hypertrace/header/GlobalVariables.h rename to hyperdbg/hypertrace/header/globals/GlobalVariables.h index 0ff4d3a8..3cbcb430 100644 --- a/hyperdbg/hypertrace/header/GlobalVariables.h +++ b/hyperdbg/hypertrace/header/globals/GlobalVariables.h @@ -16,6 +16,12 @@ // Global Variables // ////////////////////////////////////////////////// +/** + * @brief List of callbacks + * + */ +HYPERTRACE_CALLBACKS g_Callbacks; + /** * @brief The flag indicating whether the hypertrace module callbacks is initialized or not * diff --git a/hyperdbg/hypertrace/header/Lbr.h b/hyperdbg/hypertrace/header/lbr/Lbr.h similarity index 72% rename from hyperdbg/hypertrace/header/Lbr.h rename to hyperdbg/hypertrace/header/lbr/Lbr.h index 71ec907b..7154d793 100644 --- a/hyperdbg/hypertrace/header/Lbr.h +++ b/hyperdbg/hypertrace/header/lbr/Lbr.h @@ -14,14 +14,11 @@ // Constants // ////////////////////////////////////////////////// -// Intel MSR Constants -#define MSR_IA32_DEBUGCTLMSR 0x000001D9 -#define DEBUGCTLMSR_LBR (1ULL << 0) -#define MSR_LBR_SELECT 0x000001C8 -#define MSR_LBR_TOS 0x000001C9 -#define MSR_LBR_NHM_FROM 0x00000680 -#define MSR_LBR_NHM_TO 0x000006C0 -#define LBR_SELECT 0x00000000 +#define MSR_LBR_SELECT 0x000001C8 +#define MSR_LBR_TOS 0x000001C9 +#define MSR_LBR_NHM_FROM 0x00000680 +#define MSR_LBR_NHM_TO 0x000006C0 +#define LBR_SELECT 0x00000000 /** * @brief Maximum LBR capacity that is supported by processors @@ -33,6 +30,10 @@ // Structures // ////////////////////////////////////////////////// +/** + * @brief The structure to hold a single LBR entry (from and to addresses) + * + */ typedef struct _LBR_BRANCH_ENTRY { ULONGLONG From; @@ -40,6 +41,10 @@ typedef struct _LBR_BRANCH_ENTRY } LBR_BRANCH_ENTRY, PLBR_BRANCH_ENTRY; +/** + * @brief The structure to hold the LBR stack for a single processor core, including the branch entries and the TOS index + * + */ typedef struct _LBR_STACK_ENTRY { LBR_BRANCH_ENTRY BranchEntry[MAXIMUM_LBR_CAPACITY]; @@ -60,22 +65,6 @@ typedef struct _LBR_STACK_ENTRY #define xcoreid() KeGetCurrentProcessorNumber() #define xgetcurrent_pid() (ULONG)(ULONG_PTR) PsGetCurrentProcessId() -// List Handling -#define xlist_next(ptr) (ptr)->Flink -#define xlist_add(entry, head) InsertTailList(&(head), &(entry)) -#define xlist_del(entry) RemoveEntryList(&(entry)) - -// Spinlock & IRQL (Using Windows Native to fix VCR001) -#define xacquire_lock(Lock, Irql) KeAcquireSpinLock((PKSPIN_LOCK)(Lock), (Irql)) -#define xrelease_lock(Lock, Irql) KeReleaseSpinLock((PKSPIN_LOCK)(Lock), *(Irql)) - -#define xlock_core(irql) KeRaiseIrql(DISPATCH_LEVEL, irql) -#define xrelease_core(irql) KeLowerIrql(*(irql)) - -// Buffer Copy -#define xcopy_from_user(dest, src, sz) (RtlCopyMemory(dest, src, sz), 0) -#define xcopy_to_user(dest, src, sz) (RtlCopyMemory(dest, src, sz), 0) - // CPUID (Fixed C6001: initialized cpuInfo) #define xcpuid(code, a, b, c, d) \ { \ @@ -91,16 +80,30 @@ typedef struct _LBR_STACK_ENTRY // Global Variables // ////////////////////////////////////////////////// +/** + * @brief The structure to hold the mapping of CPU model to its LBR capacity + * + */ typedef struct _CPU_LBR_MAP { ULONG Model; ULONG LbrCapacity; } CPU_LBR_MAP, *PCPU_LBR_MAP; +/** + * @brief The global variable to hold the mapping of CPU model to its LBR capacity + * + */ extern CPU_LBR_MAP CPU_LBR_MAPS[]; +/** + * @brief The global variable to hold the LBR capacity of the current CPU + * + */ +ULONGLONG LbrCapacity; + ////////////////////////////////////////////////// -// Prototypes // +// Functions // ////////////////////////////////////////////////// BOOLEAN diff --git a/hyperdbg/hypertrace/header/pch.h b/hyperdbg/hypertrace/header/pch.h index 9dba8f90..2767c8fb 100644 --- a/hyperdbg/hypertrace/header/pch.h +++ b/hyperdbg/hypertrace/header/pch.h @@ -42,18 +42,6 @@ // #include "ia32-doc/out/ia32.h" -// -// DPC and broadcasting function headers -// -#include "Dpc.h" -#include "DpcRoutines.h" -#include "Broadcast.h" - -// -// Unload function (to be called when the driver is unloaded) -// -#include "UnloadDll.h" - // // SDK headers // @@ -64,6 +52,23 @@ // #include "config/Configuration.h" +// +// Platform independent headers +// +#include "platform/kernel/header/PlatformMem.h" + +// +// DPC and broadcasting function headers +// +#include "broadcast/Dpc.h" +#include "broadcast/DpcRoutines.h" +#include "broadcast/Broadcast.h" + +// +// Unload function (to be called when the driver is unloaded) +// +#include "common/UnloadDll.h" + // // Hyperlog headers // @@ -81,15 +86,16 @@ #include "SDK/modules/HyperTrace.h" // -// Definition of tracing types and structures +// Definition of tracing types and structures (Last Branch Record) // -#include "Tracing.h" -#include "Lbr.h" +#include "api/LbrApi.h" +#include "lbr/Lbr.h" // -// Platform independent headers +// Definition of tracing types and structures (Processor Trace) // -#include "platform/kernel/header/PlatformMem.h" +#include "api/PtApi.h" +#include "pt/Pt.h" // // Export functions @@ -99,4 +105,4 @@ // // Global variables // -#include "GlobalVariables.h" +#include "globals/GlobalVariables.h" diff --git a/hyperdbg/hypertrace/header/pt/Pt.h b/hyperdbg/hypertrace/header/pt/Pt.h new file mode 100644 index 00000000..6a5f74a2 --- /dev/null +++ b/hyperdbg/hypertrace/header/pt/Pt.h @@ -0,0 +1,31 @@ +/** + * @file Pt.h + * @author + * @brief Header for Processor Trace (PT) tracing routines for HyperTrace module + * @details + * @version 0.19 + * @date 2026-04-25 + * + * @copyright This project is released under the GNU Public License v3. + */ +#pragma once + +////////////////////////////////////////////////// +// Constants // +////////////////////////////////////////////////// + +////////////////////////////////////////////////// +// Structures // +////////////////////////////////////////////////// + +////////////////////////////////////////////////// +// Platform Wrappers // +////////////////////////////////////////////////// + +////////////////////////////////////////////////// +// Global Variables // +////////////////////////////////////////////////// + +////////////////////////////////////////////////// +// Functions // +////////////////////////////////////////////////// diff --git a/hyperdbg/hypertrace/hypertrace.vcxproj b/hyperdbg/hypertrace/hypertrace.vcxproj index 7d9ec5e4..b6283379 100644 --- a/hyperdbg/hypertrace/hypertrace.vcxproj +++ b/hyperdbg/hypertrace/hypertrace.vcxproj @@ -101,27 +101,29 @@ - - - - - - + + + + + + + - - - - - - - + + + + + + + + - + diff --git a/hyperdbg/hypertrace/hypertrace.vcxproj.filters b/hyperdbg/hypertrace/hypertrace.vcxproj.filters index 79fc73b9..c1dfe379 100644 --- a/hyperdbg/hypertrace/hypertrace.vcxproj.filters +++ b/hyperdbg/hypertrace/hypertrace.vcxproj.filters @@ -21,46 +21,73 @@ {50dcf65c-eea2-4bf3-b57e-d6689999b39d} + + {09d5457a-bade-4a3f-a171-641110492d57} + + + {b8b32a09-61fb-433a-ad79-eb7cfc5f3437} + + + {32ea8333-847b-443d-8992-4140d54dc1d3} + + + {2271439b-db98-4351-9457-77225ccee301} + + + {d2eb3e6f-49d6-49c6-a255-a0158414ff54} + + + {df6eb164-34b2-4f2a-9530-b88443662fb7} + + + {cb4e742a-6e43-4798-af4a-72bcb11089c9} + + + {ab21116d-5f5b-4ef8-82bb-6585ac3dec95} + + + {57d56081-eede-41a3-b9f0-e7019d32c986} + + + {a59b8bf9-45ee-49c9-bbac-9b065f41f1a2} + + + {7d49a3f4-a2eb-48b1-8f41-220b9ccf30dc} + - - code - - - code - - - code - code\platform code\interface - - code + + code\api - - code + + code\api - - code + + code\broadcast + + + code\broadcast + + + code\common + + + code\lbr + + + code\pt - - header - - - header - header - - header - header\platform @@ -70,20 +97,32 @@ header\interface - - header + + header\api - - header + + header\broadcast - - header + + header\broadcast - - header + + header\broadcast - - header + + header\common + + + header\globals + + + header\lbr + + + header\pt + + + header\api \ No newline at end of file diff --git a/hyperdbg/include/SDK/imports/kernel/HyperDbgHyperTrace.h b/hyperdbg/include/SDK/imports/kernel/HyperDbgHyperTrace.h index 518be457..0ee687d6 100644 --- a/hyperdbg/include/SDK/imports/kernel/HyperDbgHyperTrace.h +++ b/hyperdbg/include/SDK/imports/kernel/HyperDbgHyperTrace.h @@ -16,16 +16,6 @@ # define IMPORT_EXPORT_HYPERTRACE __declspec(dllimport) #endif -////////////////////////////////////////////////// -// Example Functions // -////////////////////////////////////////////////// - -// -// Used for testing purposes -// -IMPORT_EXPORT_HYPERTRACE VOID -HyperTraceExamplePerformLbrTrace(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVmcall); - ////////////////////////////////////////////////// // HyperTrace Functions // ////////////////////////////////////////////////// @@ -34,32 +24,32 @@ HyperTraceExamplePerformLbrTrace(BOOLEAN ApplyFromVmxRootMode, BOOLEAN ApplyByVm // Initialize the hypertrace module with the provided callbacks // IMPORT_EXPORT_HYPERTRACE BOOLEAN -HyperTraceInitCallback(HYPERTRACE_CALLBACKS * HypertraceCallbacks, BOOLEAN InitForHypervisorEnvironment); +HyperTraceLbrInitCallback(HYPERTRACE_CALLBACKS * HypertraceCallbacks, BOOLEAN InitForHypervisorEnvironment); // // Uninitialize the HyperTrace module // IMPORT_EXPORT_HYPERTRACE VOID -HyperTraceUninit(); +HyperTraceLbrUninit(); // // Perform operations related to HyperTrace based on the request type and parameters // IMPORT_EXPORT_HYPERTRACE BOOLEAN -HyperTracePerformOperation(HYPERTRACE_OPERATION_PACKETS * LbrOperationRequest, - BOOLEAN ApplyFromVmxRootMode); +HyperTraceLbrPerformOperation(HYPERTRACE_OPERATION_PACKETS * LbrOperationRequest, + BOOLEAN ApplyFromVmxRootMode); ////////////////////////////////////////////////// // LBR Functions // ////////////////////////////////////////////////// IMPORT_EXPORT_HYPERTRACE BOOLEAN -HyperTraceSaveLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, +HyperTraceLbrSave(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, BOOLEAN ApplyFromVmxRootMode); IMPORT_EXPORT_HYPERTRACE BOOLEAN -HyperTraceDumpLbr(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, +HyperTraceLbrDump(HYPERTRACE_OPERATION_PACKETS * HyperTraceOperationRequest, BOOLEAN ApplyFromVmxRootMode); IMPORT_EXPORT_HYPERTRACE BOOLEAN -HyperTraceQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(UINT32 CoreId); +HyperTraceLbrQueryStateOfLbrSaveAndLoadVmExitAndEntryControls(UINT32 CoreId); diff --git a/hyperdbg/script-eval/code/Functions.c b/hyperdbg/script-eval/code/Functions.c index b0e09ca1..431be3df 100644 --- a/hyperdbg/script-eval/code/Functions.c +++ b/hyperdbg/script-eval/code/Functions.c @@ -2031,7 +2031,7 @@ ScriptEngineFunctionLbrSave() // // Depending if we are in VMX-root then a VMCALL is issued by default instead, otherwise the VMCALL is ignored // - return HyperTraceSaveLbr(NULL, VmFuncVmxGetCurrentExecutionMode()); + return HyperTraceLbrSave(NULL, VmFuncVmxGetCurrentExecutionMode()); #endif // SCRIPT_ENGINE_KERNEL_MODE } @@ -2054,7 +2054,7 @@ ScriptEngineFunctionLbrDump() // // Depending if we are in VMX-root then a VMCALL is issued by default instead, otherwise the VMCALL is ignored // - return HyperTraceDumpLbr(NULL, VmFuncVmxGetCurrentExecutionMode()); + return HyperTraceLbrDump(NULL, VmFuncVmxGetCurrentExecutionMode()); #endif // SCRIPT_ENGINE_KERNEL_MODE }