HyperDbgHyperEvade.h File Reference

Headers relating exported functions from hyperevade (transparency) module. More...

Go to the source code of this file.

Macros
#define	IMPORT_EXPORT_HYPEREVADE   __declspec(dllimport)

Functions
IMPORT_EXPORT_HYPEREVADE BOOLEAN	TransparentHideDebugger (HYPEREVADE_CALLBACKS *HyperevadeCallbacks, DEBUGGER_HIDE_AND_TRANSPARENT_DEBUGGER_MODE *TransparentModeRequest)
	Hide debugger on transparent-mode (activate transparent-mode).
IMPORT_EXPORT_HYPEREVADE BOOLEAN	TransparentUnhideDebugger ()
	Deactivate transparent-mode.
IMPORT_EXPORT_HYPEREVADE VOID	TransparentCheckAndModifyCpuid (PGUEST_REGS Regs, INT32 CpuInfo[])
	Handle Cpuid Vmexits when the Transparent mode is enabled.
IMPORT_EXPORT_HYPEREVADE VOID	TransparentCheckAndTrapFlagAfterVmexit ()
	Handle anti-debugging method of a trap flag after a VM exit.
IMPORT_EXPORT_HYPEREVADE BOOLEAN	TransparentCheckAndModifyMsrRead (PGUEST_REGS Regs, UINT32 TargetMsr)
	Handle RDMSR VM exits when the Transparent mode is enabled.
IMPORT_EXPORT_HYPEREVADE BOOLEAN	TransparentCheckAndModifyMsrWrite (PGUEST_REGS Regs, UINT32 TargetMsr)
	Handle WRMSR VM exits when the Transparent mode is enabled.
IMPORT_EXPORT_HYPEREVADE VOID	TransparentHandleSystemCallHook (GUEST_REGS *Regs)
	Handle The triggered hook on KiSystemCall64 system call handler when the Transparency mode is enabled.
IMPORT_EXPORT_HYPEREVADE VOID	TransparentCallbackHandleAfterSyscall (GUEST_REGS *Regs, UINT32 ProcessId, UINT32 ThreadId, UINT64 Context, SYSCALL_CALLBACK_CONTEXT_PARAMS *Params)
	Callback function to handle returns from the syscall.

Detailed Description

Headers relating exported functions from hyperevade (transparency) module.

Author

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Version

0.14

Date

2025-06-07

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

IMPORT_EXPORT_HYPEREVADE

#define IMPORT_EXPORT_HYPEREVADE   __declspec(dllimport)

Function Documentation

TransparentCallbackHandleAfterSyscall()

IMPORT_EXPORT_HYPEREVADE VOID TransparentCallbackHandleAfterSyscall	(	GUEST_REGS *	Regs,
		UINT32	ProcessId,
		UINT32	ThreadId,
		UINT64	Context,
		SYSCALL_CALLBACK_CONTEXT_PARAMS *	Params )

Callback function to handle returns from the syscall.

Parameters

Regs	The virtual processor's state of registers
ProcessId	The process id of the thread
ThreadId	The thread id of the thread
Context	The context of the caller
Params	The (optional) parameters of the caller

Returns

VOID

{
    //
    // Handle each defined system call separately, after the kernel execution has finished(at the SYSRET instruction)
    //
 
    //
    // Handle the memory buffer and return code modification after NtQuerySystemInformation system call
    //
    if (Context == g_SystemCallNumbersInformation.SysNtQuerySystemInformation)
    {
        TransparentCallbackHandleAfterNtQuerySystemInformationSyscall(Regs, Params);
    }
    //
    // Handle the memory buffer and return code modification after NtQueryAttributesFile system call
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryAttributesFile)
    {
        //
        // Check if the obtained buffer pointer is valid
        //
        if (g_Callbacks.CheckAccessValidityAndSafety(Params->OptionalParam1, sizeof(FILE_BASIC_INFORMATION)))
        {
            FILE_BASIC_INFORMATION Buf = {0};
            //
            // Copy over the data from the output buffer pointer
            //
            if (!g_Callbacks.MemoryMapperReadMemorySafeOnTargetProcess(Params->OptionalParam1, &Buf, sizeof(FILE_BASIC_INFORMATION)))
            {
                LogError("Err, Virtual memory read failed");
            }
            else
            {
                //
                // Modify the file attribute to INVALID_FILE_ATTRIBUTES and write it back to the pointer
                //
                Buf.FileAttributes = ((DWORD)-1);
 
                if (!g_Callbacks.MemoryMapperWriteMemorySafeOnTargetProcess(Params->OptionalParam1, &Buf, sizeof(FILE_BASIC_INFORMATION)))
                {
                    LogError("Err, Virtual memory write failed");
                }
            }
        }
        else
        {
            LogInfo("A call for the NtQueryAttributeFile system call for a marked file was made, but the output buffer was not captured");
        }
    }
 
    //
    // Handle the memory buffer and return code modification after NtOpenDirectoryObject system call.
    //
    // NOTE: No transparent mitigations of this call have been implemented
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtOpenDirectoryObject)
    {
        LogInfo("A NtOpenDirectoryObject system call was made for a known directory that reveals hypervisor presence. process: %x, thread: %x\n",
                ProcessId,
                ThreadId);
        LogInfo("No action to mitigate this was made as a handler for NtOpenDirectoryObject has not been implemented");
    }
    //
    // Handle the memory buffer modification after NtQueryInformationProcess system call
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryInformationProcess)
    {
        switch (Params->OptionalParam1)
        {
        case 0x07:
        {
            if (g_Callbacks.CheckAccessValidityAndSafety(Params->OptionalParam2, sizeof(DWORD_PTR)))
            {
                //
                // Zero out the return buffer to user-mode
                //
                DWORD_PTR NoDebugPort = 0x0;
 
                g_Callbacks.MemoryMapperWriteMemorySafeOnTargetProcess(Params->OptionalParam2, &NoDebugPort, sizeof(DWORD_PTR));
            }
            break;
        }
        case 0x1f:
        {
            //
            // Zero out the return buffer to user-mode
            //
            ULONG notDebugged = 0x0;
            g_Callbacks.MemoryMapperWriteMemorySafeOnTargetProcess(Params->OptionalParam2, &notDebugged, sizeof(ULONG));
            break;
        }
        case 0x1e:
        {
            if (g_Callbacks.CheckAccessValidityAndSafety(Params->OptionalParam2, (UINT32)Params->OptionalParam3))
            {
                LogInfo("Process %llx called the NtQueryInformationProcess system call with the ProcessDebugObject class, no transparent mitigations were performed", ProcessId);
            }
            break;
        }
        default:
        {
            break;
        }
        }
    }
    //
    // Handle the return code modification after NtSystemDebugControl system call
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtSystemDebugControl)
    {
        //
        // In the entry handler, the Syscall number was changed to corrupt this call, after the SYSRET, change the return code to STATUS_DEBUGGER_INACTIVE
        //
        Regs->rax = (UINT64)(UINT32)STATUS_DEBUGGER_INACTIVE;
    }
 
    //
    // Handle the return code modification after SysNtOpenFile system call
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtOpenFile)
    {
        //
        // In the entry handler, the Syscall number was changed to corrupt this call if the request was for a known hypervisor file
        // after the SYSRET, change the return code to STATUS_OBJECT_NAME_NOT_FOUND
        //
        Regs->rax = (UINT64)(UINT32)STATUS_OBJECT_NAME_NOT_FOUND;
    }
 
    //
    // Handle the return code modification after NtNtQueryValueKey system call
    //
    // NOTE: The transparent mitigation will replace all occurrences of a hypervisor vendor string in the registry
    // key data to a randomized real hardware vendor string, no matter the meaning of the key,
    // This can cause some keys to produce illogical data, for example,
    // a disk drive ID having a vendor string of ASUS even though (as far as I know) ASUS doesn't produce storage devices.
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryValueKey)
    {
        UINT64 RetVal;
 
        //
        // Call the handler of NtQueryValueKey syscall callback
        //
        RetVal = TransparentCallbackHandleAfterNtQueryValueKeySyscall(Params);
 
        //
        // If a custom(Specific to transparency) error code should be returned,
        // set it to %RAX
        // Else leave it to what the kernel already set it to
        //
        if (RetVal != 0)
        {
            Regs->rax = RetVal;
        }
    }
    //
    // Handle the memory buffer modification after NtOpenKey system call and its derivatives
    //
    else if (Context == g_SystemCallNumbersInformation.SysNtOpenKey || Context == g_SystemCallNumbersInformation.SysNtOpenKeyEx)
    {
        //
        // In the entry handler, the Syscall number was changed to corrupt this call if the request was for a known hypervisor registry key
        // after the SYSRET, change the return code to STATUS_OBJECT_NAME_NOT_FOUND
        //
        Regs->rax = (UINT64)(UINT32)STATUS_OBJECT_NAME_NOT_FOUND;
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtEnumerateKey)
    {
        UINT64 RetVal;
 
        //
        // Call the handler of NtEnumerateKey syscall callback
        //
        RetVal = TransparentCallbackHandleAfterNtEnumerateKeySyscall(Params);
 
        //
        // If a custom(Specific to transparency) error code should be returned,
        // set it to %RAX
        // Else leave it to what the kernel already set it to
        //
        if (RetVal != 0)
        {
            Regs->rax = RetVal;
        }
    }
    else
    {
        //
        // A SYSRET trap flag was inserted for a System call that does not have a transparency handler implemented
        //
        LogInfo("Transparent callback  for an unimplemented system call handle with the trap flag for process: %x, thread: %x, context: %llx RAX: %llx (p1: %llx, p2: %llx, p3: %llx, p4: %llx) \n",
                ProcessId,
                ThreadId,
                Context,
                Regs->rax,
                Params->OptionalParam1,
                Params->OptionalParam2,
                Params->OptionalParam3,
                Params->OptionalParam4);
    }
}

TransparentCheckAndModifyCpuid()

IMPORT_EXPORT_HYPEREVADE VOID TransparentCheckAndModifyCpuid	(	PGUEST_REGS	Regs,
		INT32	CpuInfo[] )

Handle Cpuid Vmexits when the Transparent mode is enabled.

Parameters

Regs	The virtual processor's state of registers
CpuInfo	The temporary logical processor registers

Returns

VOID

{
    if ((g_TransparentEvadeMask & TRANSPARENT_EVADE_MASK_CPUID) == 0)
    {
        return;
    }
 
    if (Regs->rax == CPUID_PROCESSOR_AND_PROCESSOR_FEATURE_IDENTIFIERS)
    {
        //
        // Unset the Hypervisor Present-bit in RCX, which Intel and AMD have both
        // reserved for this indication
        //
        CpuInfo[2] &= ~HYPERV_HYPERVISOR_PRESENT_BIT;
    }
    else if (Regs->rax == CPUID_HV_VENDOR_AND_MAX_FUNCTIONS || Regs->rax == HYPERV_CPUID_INTERFACE)
    {
        //
        // When transparent, all CPUID leaves in the 0x40000000+ range should contain no usable data
        //
        CpuInfo[0] = CpuInfo[1] = CpuInfo[2] = CpuInfo[3] = 0x40000000;
    }
}

TransparentCheckAndModifyMsrRead()

IMPORT_EXPORT_HYPEREVADE BOOLEAN TransparentCheckAndModifyMsrRead	(	PGUEST_REGS	Regs,
		UINT32	TargetMsr )

Handle RDMSR VM exits when the Transparent mode is enabled.

Parameters

Regs	The virtual processor's state of registers
TargetMsr	Target MSR in ECX register

Returns

BOOLEAN Whether the emulation should be further continued or not

{
    if ((g_TransparentEvadeMask & TRANSPARENT_EVADE_MASK_MSR) == 0)
    {
        UNREFERENCED_PARAMETER(Regs);
        UNREFERENCED_PARAMETER(TargetMsr);
 
        return FALSE;
    }
 
    //
    // The MSR range between 40000000H and 400000F0H is reserved and usually used by hypervisors
    // when the guest operating system is Windows to indicate the OS identifier
    //
    // Sina: Needs more investigation since injecting #GP on Nested-virtualization environments
    // will crash the VM on Meteor Lake processors since the OS expects to use synthetic timers
    // (HV_REGISTER_STIMER0_CONFIG and HV_REGISTER_STIMER0_COUNT) to receive interrupts
    // Ref: https://learn.microsoft.com/en-us/virtualization/hyper-v-on-windows/tlfs/timers
    //
    // if (TargetMsr >= RESERVED_MSR_RANGE_LOW && TargetMsr <= RESERVED_MSR_RANGE_HI)
    // {
    //     LogInfo("RDMSR attempts to write to a reserved MSR range. MSR: %x",
    //             TargetMsr);
    //
    //     g_Callbacks.EventInjectGeneralProtection();
    //     return TRUE; // Should not emulate further
    // }
    // else
    // {
    //     //
    //     // Not handled in the transparent-mode
    //     //
    //     return FALSE;
    // }
 
    UNREFERENCED_PARAMETER(Regs);
    UNREFERENCED_PARAMETER(TargetMsr);
 
    return FALSE;
}

TransparentCheckAndModifyMsrWrite()

IMPORT_EXPORT_HYPEREVADE BOOLEAN TransparentCheckAndModifyMsrWrite	(	PGUEST_REGS	Regs,
		UINT32	TargetMsr )

Handle WRMSR VM exits when the Transparent mode is enabled.

Parameters

Regs	The virtual processor's state of registers
TargetMsr	Target MSR in ECX register

Returns

BOOLEAN Whether the emulation should be further continued or not

{
    if ((g_TransparentEvadeMask & TRANSPARENT_EVADE_MASK_MSR) == 0)
    {
        UNREFERENCED_PARAMETER(Regs);
        UNREFERENCED_PARAMETER(TargetMsr);
 
        return FALSE;
    }
 
    // if (TargetMsr >= RESERVED_MSR_RANGE_LOW && TargetMsr <= RESERVED_MSR_RANGE_HI)
    // {
    //     //
    //     // The MSR range between 40000000H and 400000F0H is reserved and usually used by hypervisors
    //     // when the guest operating system is Windows to indicate the OS identifier
    //     //
    //
    //     LogInfo("WRMSR attempts to write to a reserved MSR range. MSR: %x, rax: %llx, rdx: %llx",
    //             TargetMsr,
    //             Regs->rax,
    //             Regs->rdx);
    //
    //     g_Callbacks.EventInjectGeneralProtection();
    //
    //     return TRUE; // Should not emulate further
    // }
    // else
    // {
    //     //
    //     // Not handled in the transparent-mode
    //     //
    //     return FALSE;
    // }
 
    UNREFERENCED_PARAMETER(Regs);
    UNREFERENCED_PARAMETER(TargetMsr);
 
    return FALSE;
}

TransparentCheckAndTrapFlagAfterVmexit()

IMPORT_EXPORT_HYPEREVADE VOID TransparentCheckAndTrapFlagAfterVmexit

(

)

Handle anti-debugging method of a trap flag after a VM exit.

Returns

VOID

{
    if ((g_TransparentEvadeMask & TRANSPARENT_EVADE_MASK_TRAP_FLAG) == 0)
    {
        return;
    }
 
    //
    // If RIP is incremented, then we emulate an instruction, and then
    // we need to handle the trap flag if it is set in a guest
    //
    g_Callbacks.HvHandleTrapFlag();
}

TransparentHandleSystemCallHook()

IMPORT_EXPORT_HYPEREVADE VOID TransparentHandleSystemCallHook

(

GUEST_REGS *

Regs

)

Handle The triggered hook on KiSystemCall64 system call handler when the Transparency mode is enabled.

Parameters

Regs	The virtual processor's state of registers

Returns

VOID

{
    //
    // If the transparent mode is not enabled, do nothing
    //
    if (!g_TransparentMode)
    {
        return;
    }
 
    PCHAR  CallingProcess = g_Callbacks.CommonGetProcessNameFromProcessControlBlock(PsGetCurrentProcess());
    UINT64 Context        = Regs->rax;
 
    //
    // Skip the transparent mitigations of system calls when the caller process
    // is a Windows process that should receive unmodified data
    //
    for (ULONG i = 0; i < (sizeof(TRANSPARENT_WIN_PROCESS_IGNORE) / sizeof(TRANSPARENT_WIN_PROCESS_IGNORE[0])); i++)
    {
        if (strstr(CallingProcess, TRANSPARENT_WIN_PROCESS_IGNORE[i]))
        {
            return;
        }
    }
 
    if (Context == g_SystemCallNumbersInformation.SysNtQuerySystemInformation ||
        Context == g_SystemCallNumbersInformation.SysNtQuerySystemInformationEx)
    {
        //
        // Handle the NtQuerySystemInformation System call
        //
 
        TransparentHandleNtQuerySystemInformationSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtSystemDebugControl)
    {
        //
        // Handle the NtSystemDebugControl System call
        //
        TransparentHandleNtSystemDebugControlSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryAttributesFile)
    {
        //
        // Handle the NtQueryAttributesFile System call
        //
        TransparentHandleNtQueryAttributesFileSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtOpenDirectoryObject)
    {
        //
        // Handle the NtOpenDirectoryObject System call
        //
        TransparentHandleNtOpenDirectoryObjectSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryDirectoryObject)
    {
        //
        // Handle the NtQueryDirectoryObject System call
        //
        // TransparentHandleNtQueryDirectoryObjectSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryInformationProcess)
    {
        //
        // Handle the NtQueryInformationProcess System call
        //
        TransparentHandleNtQueryInformationProcessSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryInformationThread)
    {
        //
        // Handle the NtQueryInformationThread System call
        //
        // TransparentHandleNtQueryInformationThreadSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtOpenFile)
    {
        //
        // Handle the NtOpenFile System call
        //
        TransparentHandleNtOpenFileSyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtOpenKeyEx || Context == g_SystemCallNumbersInformation.SysNtOpenKey)
    {
        //
        // Handle the NtOpenKey System call
        //
        TransparentHandleNtOpenKeySyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtQueryValueKey)
    {
        //
        // Handle the NtQueryValueKey System call
        //
        TransparentHandleNtQueryValueKeySyscall(Regs);
    }
    else if (Context == g_SystemCallNumbersInformation.SysNtEnumerateKey)
    {
        //
        // Handle the NtEnumerateKey System call
        //
        TransparentHandleNtEnumerateKeySyscall(Regs);
    }
    else
    {
        //
        // The syscall is not important to us
        //
    }
}

TransparentHideDebugger()

IMPORT_EXPORT_HYPEREVADE BOOLEAN TransparentHideDebugger	(	HYPEREVADE_CALLBACKS *	HyperevadeCallbacks,
		DEBUGGER_HIDE_AND_TRANSPARENT_DEBUGGER_MODE *	TransparentModeRequest )

Hide debugger on transparent-mode (activate transparent-mode).

Parameters

HyperevadeCallbacks	Pointer to the HyperEvade callbacks structure
TransparentModeRequest	Pointer to the transparent debugger mode request

Returns

BOOLEAN

{
    UINT32 EvadeMask = TransparentModeRequest->EvadeMask;
 
    if (EvadeMask == 0)
    {
        EvadeMask = TRANSPARENT_EVADE_MASK_DEFAULT;
    }
 
    if ((EvadeMask & ~TRANSPARENT_EVADE_MASK_ALL) != 0)
    {
        TransparentModeRequest->KernelStatus = DEBUGGER_ERROR_UNABLE_TO_HIDE_OR_UNHIDE_DEBUGGER;
        return FALSE;
    }
 
    //
    // Check if any of the required callbacks are NULL
    //
    for (UINT32 i = 0; i < sizeof(HYPEREVADE_CALLBACKS) / sizeof(UINT64); i++)
    {
        if (((PVOID *)HyperevadeCallbacks)[i] == NULL)
        {
            //
            // The callback has null entry, so we cannot proceed
            //
            TransparentModeRequest->KernelStatus = DEBUGGER_ERROR_UNABLE_TO_HIDE_OR_UNHIDE_DEBUGGER;
            return FALSE;
        }
    }
 
    //
    // Save the callbacks
    //
    RtlCopyMemory(&g_Callbacks, HyperevadeCallbacks, sizeof(HYPEREVADE_CALLBACKS));
 
    //
    // Check whether the transparent-mode was already initialized or not
    //
    if (!g_TransparentMode)
    {
        //
        // Store the system-call numbers information
        //
        RtlCopyBytes(&g_SystemCallNumbersInformation,
                     &TransparentModeRequest->SystemCallNumbersInformation,
                     sizeof(SYSTEM_CALL_NUMBERS_INFORMATION));
#if ActivateHyperEvadeProject == TRUE
        //
        // Choose a random genuine vendor string to replace hypervisor vendor data
        //
        g_TransparentGenuineVendorStringIndex = TransparentGetRand() %
                                                (sizeof(TRANSPARENT_LEGIT_VENDOR_STRINGS_WCHAR) / sizeof(TRANSPARENT_LEGIT_VENDOR_STRINGS_WCHAR[0]));
#endif
 
        //
        // Enable the transparent mode
        //
        g_TransparentMode                    = TRUE;
        g_TransparentEvadeMask               = EvadeMask;
        TransparentModeRequest->EvadeMask    = EvadeMask;
        TransparentModeRequest->KernelStatus = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
 
        //
        // Successfully enabled the transparent-mode
        //
        return TRUE;
    }
    else
    {
        TransparentModeRequest->KernelStatus = DEBUGGER_ERROR_DEBUGGER_ALREADY_HIDE;
        return FALSE;
    }
}

TransparentUnhideDebugger()

IMPORT_EXPORT_HYPEREVADE BOOLEAN TransparentUnhideDebugger

(

)

Deactivate transparent-mode.

Returns

BOOLEAN

{
    if (g_TransparentMode)
    {
        //
        // Disable the transparent-mode
        //
        g_TransparentMode      = FALSE;
        g_TransparentEvadeMask = 0;
 
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}