How to create an action?
This document helps you to create an action for events
Actions are an essential part of the events.
Each event consists of zero or multiple actions. An event with zero actions is treated as a disabled event.
There are three types of actions in HyperDbg as described here.
You can have multiple "Custom Codes", "Script", and "Break".
This document is a brief of how to create actions for an event.
Pre-Allocated Buffers
There are many limitations when your script is running in vmx-root. To address these limitations, HyperDbg employs pre-allocated buffers.
Pre-allocated buffers are a buffer that HyperDbg previously allocated from the non-paged pool resource of the system as it is dedicated to being used within the events.
You can use these buffers safely from vmx-root to save your temporary variables or needed data. Keep in mind that there is only one pre-allocated buffer for an event, so if you want to access it from different cores, you should consider using spinlock functions to avoid concurrency.
Break
Break to the debugger, works exactly like classic debuggers like Windbg.
If you simply use the command without any extra parameters, it will be treated like classic debuggers, and HyperDbg gives the system control to the debugger.
Script
Custom vmx-root mode compatible script engine is another feature for HyperDbg.
You can use scripts within events by specifying your script within script { and } in the event's command.
Note that when the event is triggered, you can modify memory and registers, and when each event is triggered, it has its own set of registers, context, and memory layout. You should keep in mind that each event might be triggered simultaneously within different cores.
A pointer to the pre-allocated buffer for the target event is available in the $buffer pseudo-register.
There are different examples of using the script engine effectively within events here.
Custom Codes
Run custom code lets you run your custom assembly codes whenever a special event is triggered; this option is fast and powerful as you can customize the HyperDbg based on your needs.
Accessing random memory in custom code and condition code is considered "unsafe". You have some limitations on accessing memory on some special events.
Run custom code without a safe buffer
Each command in HyperDbg that are tagged as "event" in the document follows the same structure described here. At the time you execute a command, you can add a code { xx xx xx xx } where xx is the assembly (hex) of what you want to be executed in the case of that event.
Starting from v0.10, HyperDbg supports direct assembly code in the code sections. You can add asm code { asm1; asm2; asm3; asm4} where you can add any assembly code to be executed in the case of that event.
Generally, the assembly code in the code block will be called in the following form.
As it called in the fastcall calling convention, PreAllocatedBufferAddress will be on rcx, Regs will be on rdx and Context is on r8.
PreAllocatedBufferAddress is the address of a non-paged safe buffer, which is passed to the function on rcx. (more about it later).
Regs, for general-purpose registers, we pass a pointer to the following structure as the second argument on rdx.
The Context is a special variable that shows an essential parameter of the event. This value is different for each event. You should check the documentation of that command for more information about the Context. For example, Context for !syscall command is the syscall-number or for the !epthook2 command is the physical address of where the hidden hook triggered. Context is passed to the custom code as the third argument on r8 .
PreAllocatedBufferAddress (rcx) is always NULL in Run custom code without a safe buffer, and it's used in Run custom code with a safe buffer.
As an example, we want to find the TAG (ExAllocatePoolWithTag). If the tag is a special value, then we want to change it to a new value.
As you know, ExAllocatePoolWithTag in Windows is defined as:
Based on the x64 calling convention, the parameters are passed as rcx, rdx, r8, r9, and stack and Tag is on r8.
As you know, if you want to change a register in the target OS, you have to find the register in Regs and change it from there. Based on _GUEST_REGS, r8 is on 0x40 from the top of this structure.
Take a look at the following assembly code. It first checks whether the Tag (r8) is HDBG, and if it's HDBG, then we change it to HDB2.
When we convert the above code to assembly, then we have the following code :
Imagine, the ExAllocatePoolWithTag is located at fffff800`4ed6f010. We can hook and change the Tag using the following command.
Run custom code using assembler
Instead of using hexadecimal codes, you can directly use HyperDbg's assembler. The following command is the same as the above command but uses HyperDbg's internal assembler.
Run custom code with a safe buffer
The difference between "Run custom code without a safe buffer" and "Run custom code without a safe buffer" is that you have an extra parameter, called buffer xx where xx is the hex length of the buffer.
The PreAllocatedBufferAddress is just one buffer. You have to know how many cores you have. If there are two or more cores that might use the buffer simultaneously, you have to use a special location (offset from the top of the buffer) for each core to avoid race conditions and unintended behavior.
You can use the buffer which is available in rcx.
Last updated
