Getting Started
Using HyperDbg
Tips & Tricks
Contribution
Customize build
Description about customizing HyperDbg builds
You have different options to build HyperDbg in the way you want.
Configurations
Before building, you can change the following options in the Configuration.h file.
By default, HyperDbg sends the current time of the system with each message packet from kernel-mode to user-mode, if you set
ShowSystemTimeOnDebugMessages to FALSE then it no longer sends date and time along with each message (These messages along with time are used in internal logging functions, and it's not exposed to the script engine).1
/**
2
* @brief Configures whether to show the current system time in the output of
3
* debug messages or not (only available on usermode tracing messages)
4
*
5
*/
6
#define ShowSystemTimeOnDebugMessages TRUE
Copied!
If you want to use WPP Tracing instead of HyperDbg's message tracing, then set
UseWPPTracing to TRUE. After that, you no longer see any message in HyperDbg, and instead, you can see the messages in a WPP Tracing compatible app.1
/**
2
* @brief Use WPP Tracing instead of all logging functions
3
*
4
*/
5
#define UseWPPTracing FALSE
Copied!
If you set this option to
TRUE then it uses DbgPrint instead of HyperDbg's message tracing or WPP Tracing. Keep in mind that DbgPrint is not usable in most events as it's not vmx-root compatible.1
/**
2
* @brief Configures whether to use DbgPrint or use the custom usermode message
3
* tracking
4
*
5
*/
6
#define UseDbgPrintInsteadOfUsermodeMessageTracking FALSE
Copied!
Shows debug messages in both the user-mode app and debugger. It works only if you set
UseDbgPrintInsteadOfUsermodeMessageTracking to FALSEThis option is not usable in the current version of HyperDbg.
1
/**
2
* @brief Show debug messages in both usermode app and debugger,
3
* it works only if you set UseDbgPrintInsteadOfUsermodeMessageTracking to FALSE
4
*
5
*/
6
​
7
//
8
// Should be FALSE, I realized that if we enable this flag, we end up in a
9
// situation that DbgPrint halts the system because it is executing in
10
// Dispatch-level in a DPC routine, I left it to FALSE for future attention
11
//
12
#define ShowMessagesOnDebugger FALSE
Copied!
This is one of the important options for HyperDng. By default, HyperDbg accumulates messages in a separate buffer, and it won't send them immediately to the user-mode buffers.
If you need to see messages immediately after each one message, then set this option to
TRUE. However, it kills the performance as sending buffers to the user-mode involves various and heavy functions.If you set this option to
FALSE (default), then HyperDbg accumulates (~5 or more) messages, and when the buffer is full, it sends the buffer to the user-mode CLI or GUI.1
/**
2
* @brief Use immediate messaging (means that it sends each message when they
3
* recieved and do not accumulate them) it works only if you set
4
* UseDbgPrintInsteadOfUsermodeMessageTracking to FALSE
5
*/
6
#define UseImmediateMessaging TRUE
Copied!
The following option shows whether immediate messaging is active for each event or is not active. It means that if you set this option to
TRUE then it's like to add imm yes to each event command, and if you set this option to FALSE then it's like to add imm no to each command.You can still change a special event's behavior by specifying
imm yes and imm no.1
/**
2
* @brief Use immediate messaging (means that it sends each message when they
3
* recieved and do not accumulate them) its the default value on events,
4
* a user can change this behavior by selecting 'imm yes' or 'imm no' in the
5
* case of events
6
*/
7
#define UseImmediateMessagingByDefaultOnEvents TRUE
Copied!
The following option enables or disables debug-mode which determines whether the debuggee should send its pre-initialize logs to the debugger or not and also enters debugger in debugging section to break the debugger in the case of errors.
1
/**
2
* @brief Shows whether to show or not show the drivers debugging infomation
3
* and also enters debugger in debugging section to break the debugger in the
4
* case of errors
5
*/
6
#define DebugMode FALSE
Copied!
Definitions
Before building, you can change the following options in the Definition.h file.
The following option shows the maximum amount of packets that HyperDbg uses as storage for unread messages. For example, if you have a high rate of producing messages, you can increase the value. If the maximum capacity is full of unread messages, then HyperDbg overrides old messages, and you'll lose earlier messages.
1
/* Default buffer size */
2
#define MaximumPacketsCapacity 1000 // number of packets
Copied!
The following option shows the capacity of each packet in HyperDbg message tracing. If you have long messages or buffers, then you can increase this value.
1
#define PacketChunkSize \
2
1000 // NOTE : REMEMBER TO CHANGE IT IN USER-MODE APP TOO
Copied!
DbgPrint has a size limitation. This option changes the default limitation of DbgPrint.
This option is not usable in the current version of HyperDbg.
1
#define DbgPrintLimitation 512
Copied!
The following option indicates the start seed for creating the event's
Tag value.1
#define DebuggerEventTagStartSeed 0x1000000
Copied!
1
#define MaximumSearchResults 0x1000
Copied!
The following option changes the default TCP port used to listen and connect to a remote system.
1
#define DEFAULT_PORT "50000"
Copied!
Determines how many sources a debugger can have for a single event.
1
#define DebuggerOutputSourceMaximumRemoteSourceForSingleEvent 0x5
Copied!
The seeds that user-mode codes use as the starter of their output source tag.
1
#define DebuggerOutputSourceTagStartSeed 0x1
Copied!
The following option changes the maximum number of breakpoints ('bp' command) that the user can put into the entire system before continuing the debuggee. If you continue the debuggee and send an IOCTL, HyperDbg will reset this number.
1
#define MAXIMUM_BREAKPOINTS_WITHOUT_CONTINUE 50
Copied!
The following option changes the speed at which HyperDbg reads kernel messages in user-mode. It's the wait time before requesting any new request to read messages in milliseconds.
1
/**
2
* @brief The speed delay for showing messages from kernel-mode
3
* to user-mode in VMI-mode, using a lower value causes the
4
* HyperDbg to show messages faster but you should keep in mind,
5
* not to eat all of the CPU
6
*/
7
#define DefaultSpeedOfReadingKernelMessages 30
Copied!
​
Last modified 3mo ago
Copy link
Edit on GitHub