Exposes the types, constants and functions needed to block Windows module loads (used to block double agent attacks). More...

#include "winpe.h"

Macros
#define	WINMODBLOCK_INVALID_VALUE 0xFFFFFFFF
	DllHandle, Reason and Reserved can be equal to WINMODBLOCK_INVALID_VALUE when something that is not the entry point of the module (e.g. DllMain) is called. More...

Typedefs
typedef enum _WIN_MOD_BLOCK_FLAG	WIN_MOD_BLOCK_FLAG
	Used to provided blocking options. More...

typedef INTSTATUS(*	PFUNC_IntWinModBlockCallback) (WIN_PROCESS_MODULE Module, void BlockObject, QWORD DllHandle, QWORD Reason, QWORD Reserved, QWORD RetAddress, INTRO_ACTION *Action)
	This callbacks provided detection logic for Windows module loads. More...

typedef INTSTATUS(*	PFUNC_IntWinModBlockHeadersCallback) (WIN_PROCESS_MODULE Module, BYTE Headers)
	This callback type will be called for the suspicious module headers when they are swapped in. More...

typedef INTSTATUS(*	PFUNC_IntWinModBlockCleanup) (WIN_PROCESS_MODULE Module, const void BlockObject)
	This callback type will be invoked when IntWinModBlockRemoveBlockObject is called for cleanup purposes. More...

Enumerations
enum	_WIN_MOD_BLOCK_FLAG { winModBlockFlagUnloadAfterExec = 0x00000001u, winModBlockFlagDoNotUnload = 0x00000002u, winModBlockFlagKillOnError = 0x00000004u }
	Used to provided blocking options. More...

Functions
INTSTATUS	IntWinModBlockBlockModuleLoad (WIN_PROCESS_MODULE Module, WIN_MOD_BLOCK_FLAG Flags, PFUNC_IntWinModBlockCallback Callback, PFUNC_IntWinModBlockHeadersCallback HeadersCallback, PFUNC_IntWinModBlockCleanup CleanupCallback, void *BlockObject)
	This function is invoked when a suspicious dll is loaded in order to analyze and block the dll load if required. More...

INTSTATUS	IntWinModBlockRegisterCallbackForReason (void *BlockObject, DWORD Reason, PFUNC_IntWinModBlockCallback Callback)
	Registers a callback that is invoked when the blocked module's DllMain function is called with a given reason parameter. More...

INTSTATUS	IntWinModBlockRemoveBlockObject (void *BlockObject)
	This function is used in order to destroy a WIN_MOD_BLOCK_OBJECT structure. More...

Detailed Description

Exposes the types, constants and functions needed to block Windows module loads (used to block double agent attacks).

Definition in file winummoduleblock.h.

Macro Definition Documentation

◆ WINMODBLOCK_INVALID_VALUE

#define WINMODBLOCK_INVALID_VALUE 0xFFFFFFFF

DllHandle, Reason and Reserved can be equal to WINMODBLOCK_INVALID_VALUE when something that is not the entry point of the module (e.g. DllMain) is called.

Definition at line 21 of file winummoduleblock.h.

Referenced by IntWinDagentHandleSuspModExecution(), IntWinModBlockHandleExecution(), and IntWinModBlockRegisterCallbackForReason().

Typedef Documentation

◆ PFUNC_IntWinModBlockCallback

typedef INTSTATUS(* PFUNC_IntWinModBlockCallback) (WIN_PROCESS_MODULE *Module, void *BlockObject, QWORD DllHandle, QWORD Reason, QWORD Reserved, QWORD RetAddress, INTRO_ACTION *Action)

This callbacks provided detection logic for Windows module loads.

This callback type can be called for the following reasons: 1) At every execution of a suspicious DLL which should be blocked, being mandatory registered through IntWinModBlockBlockModuleLoad. 2) On certain DllMain reasons, as requested by the user, callbacks which are being registered by calls to IntWinModBlockRegisterCallbackForReason.

For the case 1) - DllHandle, Reason and Reserved can be equal to WINMODBLOCK_INVALID_VALUE when something that is not the entry point of the module (e.g. DllMain) is called. It is good practice for the callback to verify for DllHandle, Reason and Reserved being equal to WINMODBLOCK_INVALID_VALUE, especially when the callback does something regarding those parameters (e.g. verify reason or do something with the Reserved parameter).

Definition at line 52 of file winummoduleblock.h.

◆ PFUNC_IntWinModBlockCleanup

typedef INTSTATUS(* PFUNC_IntWinModBlockCleanup) (WIN_PROCESS_MODULE *Module, const void *BlockObject)

This callback type will be invoked when IntWinModBlockRemoveBlockObject is called for cleanup purposes.

It is strongly recommended that at least the block object is kept inside the module to be nullified when this is called.

Definition at line 81 of file winummoduleblock.h.

◆ PFUNC_IntWinModBlockHeadersCallback

typedef INTSTATUS(* PFUNC_IntWinModBlockHeadersCallback) (WIN_PROCESS_MODULE *Module, BYTE *Headers)

This callback type will be called for the suspicious module headers when they are swapped in.

It is used for getting auxiliary information on the module (e.g. on double agent it is needed for deciding a good address for putting the verifier structures needed for init).

Definition at line 69 of file winummoduleblock.h.

◆ WIN_MOD_BLOCK_FLAG

typedef enum _WIN_MOD_BLOCK_FLAG WIN_MOD_BLOCK_FLAG

Used to provided blocking options.

Enumeration Type Documentation

◆ _WIN_MOD_BLOCK_FLAG

enum _WIN_MOD_BLOCK_FLAG

Used to provided blocking options.

Enumerator
winModBlockFlagUnloadAfterExec	Force the module to unload by returning FALSE.
winModBlockFlagDoNotUnload	Do not unload the module.
winModBlockFlagKillOnError	Kill the process by injecting a #PF on CR2 0 if something

Definition at line 27 of file winummoduleblock.h.

Function Documentation

◆ IntWinModBlockBlockModuleLoad()

INTSTATUS IntWinModBlockBlockModuleLoad	(	WIN_PROCESS_MODULE *	Module,
		WIN_MOD_BLOCK_FLAG	Flags,
		PFUNC_IntWinModBlockCallback	Callback,
		PFUNC_IntWinModBlockHeadersCallback	HeadersCallback,
		PFUNC_IntWinModBlockCleanup	CleanupCallback,
		void **	BlockObject
	)

This function is invoked when a suspicious dll is loaded in order to analyze and block the dll load if required.

This function reads the module headers, hooks the executable sections and invokes the provided Callback in order to obtain a required action. Depending on the provided Flags, this function could block the module load or kill the process if an error occurred while blocking the load.

Parameters

[in]	Module	The WIN_PROCESS_MODULE structure of the module in question.
[in]	Flags	The flags that will indicate what kind of action should be taken if the module is deemed unsafe.
[in]	Callback	The callback that will provided the detection logic.
[in]	HeadersCallback	This callback is invoked when the module headers have been successfully read.
[in]	CleanupCallback	This callback is invoked before destroying the WIN_MOD_BLOCK_OBJECT associated with this module.
[in,out]	BlockObject	The WIN_MOD_BLOCK_OBJECT associated with the given module.

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INVALID_INTERNAL_STATE	WIN_PROCESS_MODULE::StaticScan must NOT be TRUE.
INT_STATUS_INSUFFICIENT_RESOURCES	A memory allocation failed.

Definition at line 454 of file winummoduleblock.c.

Referenced by IntWinDagentCheckSuspiciousDllLoad().

◆ IntWinModBlockRegisterCallbackForReason()

INTSTATUS IntWinModBlockRegisterCallbackForReason	(	void *	BlockObject,
		DWORD	Reason,
		PFUNC_IntWinModBlockCallback	Callback
	)

Registers a callback that is invoked when the blocked module's DllMain function is called with a given reason parameter.

There can be any number of callbacks for any reason. Take into account that the reason equal to 0xFFFFFFFF (WINMODBLOCK_INVALID_VALUE) is reserved and an error will be returned if one tries to call this function for that specific reason.

Parameters

[in]	BlockObject	The WIN_MOD_BLOCK_OBJECT associated with the given module.
[in]	Reason	The DllMain provided reason.
[in]	Callback	A callback which is invoked at every execution inside the suspicious DLL of DllMain when the reason parameter in DllMain equals to the given Reason parameter. See PFUNC_IntWinModBlockCallback in callbacks section for more details. If the returned Action by the registered callback is introGuestAllowed, the block object will be removed. Please note that even if the maximum priority of action is taken (e.g. introGuestRetry has more priority), if the main callback (registered through IntWinModBlockBlockModuleLoad) returns introGuestAllowed, then no other callback registered through IntWinModBlockRegisterCallbackForReason gets called and the block object is removed!

Return values

INT_STATUS_SUCCESS	On success.
INT_STATUS_INSUFFICIENT_RESOURCES	A memory allocation failed.

Definition at line 558 of file winummoduleblock.c.

Referenced by IntWinDagentCheckSuspiciousDllLoad().

◆ IntWinModBlockRemoveBlockObject()

INTSTATUS IntWinModBlockRemoveBlockObject ( void * BlockObject )

This function is used in order to destroy a WIN_MOD_BLOCK_OBJECT structure.

This functions invokes the cleanup callback provided when to IntWinModBlockBlockModuleLoad after which all the structures used by the the WIN_MOD_BLOCK_OBJECT are safely destroyed.

Parameters

[in] BlockObject The WIN_MOD_BLOCK_OBJECT structure to be destroyed.

Return values

INT_STATUS_SUCCESS On success.

Definition at line 664 of file winummoduleblock.c.

Referenced by IntWinDagentCheckSuspiciousDllLoad(), IntWinModBlockHandleExecution(), and IntWinModUnHookModule().

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ WINMODBLOCK_INVALID_VALUE

Typedef Documentation

◆ PFUNC_IntWinModBlockCallback

◆ PFUNC_IntWinModBlockCleanup

◆ PFUNC_IntWinModBlockHeadersCallback

◆ WIN_MOD_BLOCK_FLAG

Enumeration Type Documentation

◆ _WIN_MOD_BLOCK_FLAG

Function Documentation

◆ IntWinModBlockBlockModuleLoad()

◆ IntWinModBlockRegisterCallbackForReason()

◆ IntWinModBlockRemoveBlockObject()