script-engine.h File Reference

General script-engine functions and wrappers. More...

Go to the source code of this file.

Functions
UINT64	ScriptEngineConvertNameToAddressWrapper (const char *FunctionOrVariableName, PBOOLEAN WasFound)
	ScriptEngineConvertNameToAddress wrapper.
UINT32	ScriptEngineLoadFileSymbolWrapper (UINT64 BaseAddress, const char *PdbFileName, const char *CustomModuleName)
	ScriptEngineLoadFileSymbol wrapper.
VOID	ScriptEngineSetTextMessageCallbackWrapper (PVOID Handler)
	ScriptEngineSetTextMessageCallback wrapper.
UINT32	ScriptEngineUnloadAllSymbolsWrapper ()
	ScriptEngineUnloadAllSymbols wrapper.
UINT32	ScriptEngineUnloadModuleSymbolWrapper (char *ModuleName)
	ScriptEngineUnloadModuleSymbol wrapper.
UINT32	ScriptEngineSearchSymbolForMaskWrapper (const char *SearchMask)
	ScriptEngineSearchSymbolForMask wrapper.
BOOLEAN	ScriptEngineGetFieldOffsetWrapper (CHAR *TypeName, CHAR *FieldName, UINT32 *FieldOffset)
	ScriptEngineGetFieldOffset wrapper.
BOOLEAN	ScriptEngineGetDataTypeSizeWrapper (CHAR *TypeName, UINT64 *TypeSize)
	ScriptEngineGetDataTypeSize wrapper.
BOOLEAN	ScriptEngineCreateSymbolTableForDisassemblerWrapper (void *CallbackFunction)
	ScriptEngineCreateSymbolTableForDisassembler wrapper.
BOOLEAN	ScriptEngineConvertFileToPdbPathWrapper (const char *LocalFilePath, char *ResultPath)
	ScriptEngineConvertFileToPdbPath wrapper.
BOOLEAN	ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetailsWrapper (const char *LocalFilePath, char *PdbFilePath, char *GuidAndAgeDetails, BOOLEAN Is32BitModule)
	ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetails wrapper.
BOOLEAN	ScriptEngineSymbolInitLoadWrapper (PMODULE_SYMBOL_DETAIL BufferToStoreDetails, UINT32 StoredLength, BOOLEAN DownloadIfAvailable, const char *SymbolPath, BOOLEAN IsSilentLoad)
	ScriptEngineSymbolInitLoad wrapper.
BOOLEAN	ScriptEngineShowDataBasedOnSymbolTypesWrapper (const char *TypeName, UINT64 Address, BOOLEAN IsStruct, PVOID BufferAddress, const char *AdditionalParameters)
	ScriptEngineShowDataBasedOnSymbolTypes wrapper.
VOID	ScriptEngineSymbolAbortLoadingWrapper ()
	SymbolAbortLoading wrapper.
VOID	ScriptEngineWrapperTestParser (const string &Expr)
	test parser
BOOLEAN	ScriptAutomaticStatementsTestWrapper (const string &Expr, UINT64 ExpectationValue, BOOLEAN ExceptError)
	massive tests for script engine statements
PVOID	ScriptEngineParseWrapper (char *Expr, BOOLEAN ShowErrorMessageIfAny)
	ScriptEngineParse wrapper.
VOID	PrintSymbolBufferWrapper (PVOID SymbolBuffer)
	PrintSymbolBuffer wrapper.
UINT64	ScriptEngineWrapperGetHead (PVOID SymbolBuffer)
	wrapper for getting head
UINT32	ScriptEngineWrapperGetSize (PVOID SymbolBuffer)
	wrapper for getting size
UINT32	ScriptEngineWrapperGetPointer (PVOID SymbolBuffer)
	wrapper for getting pointer
VOID	ScriptEngineWrapperRemoveSymbolBuffer (PVOID SymbolBuffer)
	wrapper for removing symbol buffer
BOOLEAN	ScriptEngineFuncNumberOfOperands (UINT64 FuncType, UINT32 *NumberOfGetOperands, UINT32 *NumberOfSetOperands)
	wrapper for getting operand count
UINT64	ScriptEngineEvalUInt64StyleExpressionWrapper (const string &Expr, PBOOLEAN HasError)
	In the local debugging (VMI mode) environment, this function computes the expressions.
UINT64	ScriptEngineEvalSingleExpression (string Expr, PBOOLEAN HasError)
	Get the value from the evaluation of single expression from local debuggee and remote debuggee.

Detailed Description

General script-engine functions and wrappers.

Author

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

Version

0.1

Date

2021-09-23

Copyright

This project is released under the GNU Public License v3.

Function Documentation

PrintSymbolBufferWrapper()

VOID PrintSymbolBufferWrapper

(

PVOID

SymbolBuffer

)

PrintSymbolBuffer wrapper.

Print symbol buffer wrapper

Parameters

SymbolBuffer

Returns

PVOID

{
    PrintSymbolBuffer(SymbolBuffer);
}

ScriptAutomaticStatementsTestWrapper()

BOOLEAN ScriptAutomaticStatementsTestWrapper	(	const string &	Expr,
		UINT64	ExpectationValue,
		BOOLEAN	ExceptError )

massive tests for script engine statements

Parameters

Expr	The expression to test
ExpectationValue	What value this statements expects (not used if ExceptError is TRUE)
ExceptError	True if the statement expects an error

Returns

BOOLEAN whether the test was successful or not

{
    //
    // Set the global variable indicator of test_statement to 0
    //
    g_CurrentExprEvalResult = 0;
 
    //
    // Call the test parser
    //
    ScriptEngineWrapperTestParser(Expr);
 
    //
    // Check the global variable to see the results
    //
    if (g_CurrentExprEvalResultHasError && ExceptError)
    {
        return TRUE;
    }
    else if (ExpectationValue == g_CurrentExprEvalResult)
    {
        return TRUE;
    }
 
    return FALSE;
}

ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetailsWrapper()

BOOLEAN ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetailsWrapper	(	const char *	LocalFilePath,
		char *	PdbFilePath,
		char *	GuidAndAgeDetails,
		BOOLEAN	Is32BitModule )

ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetails wrapper.

Parameters

LocalFilePath
PdbFilePath
GuidAndAgeDetails
Is32BitModule

Returns

BOOLEAN

{
    return ScriptEngineConvertFileToPdbFileAndGuidAndAgeDetails(LocalFilePath, PdbFilePath, GuidAndAgeDetails, Is32BitModule);
}

ScriptEngineConvertFileToPdbPathWrapper()

BOOLEAN ScriptEngineConvertFileToPdbPathWrapper	(	const char *	LocalFilePath,
		char *	ResultPath )

ScriptEngineConvertFileToPdbPath wrapper.

Parameters

LocalFilePath
ResultPath

Returns

BOOLEAN

{
    return ScriptEngineConvertFileToPdbPath(LocalFilePath, ResultPath);
}

ScriptEngineConvertNameToAddressWrapper()

UINT64 ScriptEngineConvertNameToAddressWrapper	(	const char *	FunctionOrVariableName,
		PBOOLEAN	WasFound )

ScriptEngineConvertNameToAddress wrapper.

Parameters

FunctionName
WasFound

Returns

UINT64

{
    return ScriptEngineConvertNameToAddress(FunctionOrVariableName, WasFound);
}

ScriptEngineCreateSymbolTableForDisassemblerWrapper()

BOOLEAN ScriptEngineCreateSymbolTableForDisassemblerWrapper

(

void *

CallbackFunction

)

ScriptEngineCreateSymbolTableForDisassembler wrapper.

Parameters

CallbackFunction

Returns

BOOLEAN

{
    return ScriptEngineCreateSymbolTableForDisassembler(CallbackFunction);
}

ScriptEngineEvalSingleExpression()

UINT64 ScriptEngineEvalSingleExpression	(	string	Expr,
		PBOOLEAN	HasError )

Get the value from the evaluation of single expression from local debuggee and remote debuggee.

Parameters

Expr
HasError

Returns

UINT64

{
    PVOID  CodeBuffer;
    UINT64 BufferAddress;
    UINT32 BufferLength;
    UINT32 Pointer;
    UINT64 Result = NULL;
 
    //
    // Prepend and append 'formats(' and ')'
    //
    Expr.insert(0, "formats(");
    Expr.append(");");
 
    //
    // Run script engine handler
    //
    CodeBuffer = ScriptEngineParseWrapper((char *)Expr.c_str(), FALSE);
 
    if (CodeBuffer == NULL)
    {
        //
        // return to show that this item contains an script
        //
        *HasError = TRUE;
        return NULL;
    }
 
    //
    // Print symbols (test)
    //
    // PrintSymbolBufferWrapper(CodeBuffer);
 
    //
    // Set the buffer and length
    //
    BufferAddress = ScriptEngineWrapperGetHead(CodeBuffer);
    BufferLength  = ScriptEngineWrapperGetSize(CodeBuffer);
    Pointer       = ScriptEngineWrapperGetPointer(CodeBuffer);
 
    //
    // Check if it's connected over remote debuggee (in the Debugger Mode)
    //
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // Send over serial
        //
 
        //
        // Send it to the remote debuggee
        //
        KdSendScriptPacketToDebuggee(BufferAddress, BufferLength, Pointer, TRUE);
 
        //
        // Check whether there was an error in evaluation or not
        //
        if (g_ErrorStateOfResultOfEvaluatedExpression == DEBUGGER_OPERATION_WAS_SUCCESSFUL)
        {
            //
            // Everything was fine, return the result of the evaluated
            // expression and null the global holders
            //
            Result                                    = g_ResultOfEvaluatedExpression;
            g_ErrorStateOfResultOfEvaluatedExpression = NULL;
            g_ResultOfEvaluatedExpression             = NULL;
            *HasError                                 = FALSE;
        }
        else
        {
            //
            // There was an error evaluating the expression from the kernel (debuggee)
            //
            g_ErrorStateOfResultOfEvaluatedExpression = NULL;
            g_ResultOfEvaluatedExpression             = NULL;
 
            *HasError = TRUE;
            Result    = NULL;
        }
    }
    else
    {
        //
        // It's in vmi-mode,
        // execute it locally with regs set to ZERO
        //
        Result = ScriptEngineEvalUInt64StyleExpressionWrapper(Expr, HasError);
    }
 
    //
    // Remove the buffer of script engine interpreted code
    //
    ScriptEngineWrapperRemoveSymbolBuffer(CodeBuffer);
 
    return Result;
}

ScriptEngineEvalUInt64StyleExpressionWrapper()

UINT64 ScriptEngineEvalUInt64StyleExpressionWrapper	(	const string &	Expr,
		PBOOLEAN	HasError )

In the local debugging (VMI mode) environment, this function computes the expressions.

for example, if the user u ExAllocatePoolWithTag+0x10 this will evaluate the expr

Parameters

Expr
HasError

Returns

UINT64

{
    //
    // In VMI-mode we'll form all registers as zero
    //
    GUEST_REGS GuestRegs = {0};
 
    ScriptEngineEvalWrapper(&GuestRegs, Expr);
 
    //
    // Set the results and return the value
    //
    *HasError = g_CurrentExprEvalResultHasError;
    return g_CurrentExprEvalResult;
}

ScriptEngineFuncNumberOfOperands()

BOOLEAN ScriptEngineFuncNumberOfOperands	(	UINT64	FuncType,
		UINT32 *	NumberOfGetOperands,
		UINT32 *	NumberOfSetOperands )

wrapper for getting operand count

Parameters

FuncType
NumberOfGetOperands
NumberOfSetOperands

Returns

BOOLEAN

{
    return FuncGetNumberOfOperands(FuncType, NumberOfGetOperands, NumberOfSetOperands);
}

ScriptEngineGetDataTypeSizeWrapper()

BOOLEAN ScriptEngineGetDataTypeSizeWrapper	(	CHAR *	TypeName,
		UINT64 *	TypeSize )

ScriptEngineGetDataTypeSize wrapper.

Parameters

TypeName
TypeSize

Returns

BOOLEAN

{
    return ScriptEngineGetDataTypeSize(TypeName, TypeSize);
}

ScriptEngineGetFieldOffsetWrapper()

BOOLEAN ScriptEngineGetFieldOffsetWrapper	(	CHAR *	TypeName,
		CHAR *	FieldName,
		UINT32 *	FieldOffset )

ScriptEngineGetFieldOffset wrapper.

Parameters

TypeName
FieldName
FieldOffset

Returns

BOOLEAN

{
    return ScriptEngineGetFieldOffset(TypeName, FieldName, FieldOffset);
}

ScriptEngineLoadFileSymbolWrapper()

UINT32 ScriptEngineLoadFileSymbolWrapper	(	UINT64	BaseAddress,
		const char *	PdbFileName,
		const char *	CustomModuleName )

ScriptEngineLoadFileSymbol wrapper.

Parameters

BaseAddress
FileName

Returns

UINT32

{
    return ScriptEngineLoadFileSymbol(BaseAddress, PdbFileName, CustomModuleName);
}

ScriptEngineParseWrapper()

PVOID ScriptEngineParseWrapper	(	char *	Expr,
		BOOLEAN	ShowErrorMessageIfAny )

ScriptEngineParse wrapper.

Parameters

Expr
ShowErrorMessageIfAny

Returns

PVOID

{
    PSYMBOL_BUFFER SymbolBuffer;
    SymbolBuffer = (PSYMBOL_BUFFER)ScriptEngineParse(Expr);
 
    //
    // Check if there is an error or not
    //
    if (SymbolBuffer->Message == NULL)
    {
        return SymbolBuffer;
    }
    else
    {
        //
        // Show error message and free the buffer
        //
        if (ShowErrorMessageIfAny)
        {
            ShowMessages("%s\n", SymbolBuffer->Message);
        }
        ScriptEngineWrapperRemoveSymbolBuffer(SymbolBuffer);
        return NULL;
    }
}

ScriptEngineSearchSymbolForMaskWrapper()

UINT32 ScriptEngineSearchSymbolForMaskWrapper

(

const char *

SearchMask

)

ScriptEngineSearchSymbolForMask wrapper.

Parameters

SearchMask

Returns

UINT32

{
    return ScriptEngineSearchSymbolForMask(SearchMask);
}

ScriptEngineSetTextMessageCallbackWrapper()

VOID ScriptEngineSetTextMessageCallbackWrapper

(

PVOID

Handler

)

ScriptEngineSetTextMessageCallback wrapper.

Parameters

Handler

Returns

VOID

{
    return ScriptEngineSetTextMessageCallback(Handler);
}

ScriptEngineShowDataBasedOnSymbolTypesWrapper()

BOOLEAN ScriptEngineShowDataBasedOnSymbolTypesWrapper	(	const char *	TypeName,
		UINT64	Address,
		BOOLEAN	IsStruct,
		PVOID	BufferAddress,
		const char *	AdditionalParameters )

ScriptEngineShowDataBasedOnSymbolTypes wrapper.

Parameters

TypeName
Address
IsStruct
BufferAddress
AdditionalParameters

Returns

BOOLEAN

{
    return ScriptEngineShowDataBasedOnSymbolTypes(TypeName, Address, IsStruct, BufferAddress, AdditionalParameters);
}

ScriptEngineSymbolAbortLoadingWrapper()

VOID ScriptEngineSymbolAbortLoadingWrapper

(

)

SymbolAbortLoading wrapper.

Returns

VOID

{
    return ScriptEngineSymbolAbortLoading();
}

ScriptEngineSymbolInitLoadWrapper()

BOOLEAN ScriptEngineSymbolInitLoadWrapper	(	PMODULE_SYMBOL_DETAIL	BufferToStoreDetails,
		UINT32	StoredLength,
		BOOLEAN	DownloadIfAvailable,
		const char *	SymbolPath,
		BOOLEAN	IsSilentLoad )

ScriptEngineSymbolInitLoad wrapper.

Parameters

ScriptEngineSymbolInitLoad
StoredLength
DownloadIfAvailable
SymbolPath
IsSilentLoad

Returns

BOOLEAN

{
    return ScriptEngineSymbolInitLoad(BufferToStoreDetails, StoredLength, DownloadIfAvailable, SymbolPath, IsSilentLoad);
}

ScriptEngineUnloadAllSymbolsWrapper()

UINT32 ScriptEngineUnloadAllSymbolsWrapper

(

)

ScriptEngineUnloadAllSymbols wrapper.

Returns

UINT32

{
    return ScriptEngineUnloadAllSymbols();
}

ScriptEngineUnloadModuleSymbolWrapper()

UINT32 ScriptEngineUnloadModuleSymbolWrapper

(

char *

ModuleName

)

ScriptEngineUnloadModuleSymbol wrapper.

Parameters

ModuleName

Returns

UINT32

{
    return ScriptEngineUnloadModuleSymbol(ModuleName);
}

ScriptEngineWrapperGetHead()

UINT64 ScriptEngineWrapperGetHead

(

PVOID

SymbolBuffer

)

wrapper for getting head

Parameters

SymbolBuffer

Returns

UINT64

{
    return (UINT64)((PSYMBOL_BUFFER)SymbolBuffer)->Head;
}

ScriptEngineWrapperGetPointer()

UINT32 ScriptEngineWrapperGetPointer

(

PVOID

SymbolBuffer

)

wrapper for getting pointer

Parameters

SymbolBuffer

Returns

UINT32

{
    return (UINT32)((PSYMBOL_BUFFER)SymbolBuffer)->Pointer;
}

ScriptEngineWrapperGetSize()

UINT32 ScriptEngineWrapperGetSize

(

PVOID

SymbolBuffer

)

wrapper for getting size

Parameters

SymbolBuffer

Returns

UINT32

{
    UINT32 Size =
        (UINT32)((PSYMBOL_BUFFER)SymbolBuffer)->Pointer * sizeof(SYMBOL);
    return Size;
}

ScriptEngineWrapperRemoveSymbolBuffer()

VOID ScriptEngineWrapperRemoveSymbolBuffer

(

PVOID

SymbolBuffer

)

wrapper for removing symbol buffer

Parameters

SymbolBuffer

Returns

UINT32

{
    RemoveSymbolBuffer((PSYMBOL_BUFFER)SymbolBuffer);
}

ScriptEngineWrapperTestParser()

VOID ScriptEngineWrapperTestParser

(

const string &

Expr

)

test parser

Parameters

Expr

Returns

VOID

{
    ALLOCATED_MEMORY_FOR_SCRIPT_ENGINE_CASTING AllocationsForCastings = {0};
 
    typedef struct _TEST_STRUCT
    {
        UINT64 Var1;
        UINT64 Var2;
        UINT64 Var3;
        UINT64 Var4;
    } TEST_STRUCT, *PTEST_STRUCT;
 
    PTEST_STRUCT TestStruct = (PTEST_STRUCT)malloc(sizeof(TEST_STRUCT));
 
    if (TestStruct == NULL)
    {
        return;
    }
 
    RtlZeroMemory(TestStruct, sizeof(TEST_STRUCT));
 
    TestStruct->Var1 = 0x41414141;
    TestStruct->Var3 = 0x4242424242424242;
 
    GUEST_REGS GuestRegs = {0};
 
    char    test[] = "Hello world !";
    wchar_t testw[] =
        L"A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 "
        L"9 a b c d e f g h i j k l m n o p q r s t u v w x y z";
 
    char * RspReg = (char *)malloc(0x100);
 
    if (RspReg == NULL)
    {
        ShowMessages("err, unable to allocate stack for script engine tests");
        free(TestStruct);
        return;
    }
 
    memcpy(RspReg, testw, sizeof(testw));
 
    GuestRegs.rax = 0x1;
    GuestRegs.rcx = (UINT64)AllocateStructForCasting(&AllocationsForCastings); // TestStruct
    GuestRegs.rdx = 0x3;
    GuestRegs.rbx = 0x4;
    GuestRegs.rsp = (UINT64)RspReg + 0x50;
    GuestRegs.rbp = 0x6;
    GuestRegs.rsi = 0x7;
    GuestRegs.rdi = 0x8;
    GuestRegs.r8  = 0x9;
    GuestRegs.r9  = 0xa;
    GuestRegs.r10 = 0xb;
    GuestRegs.r11 = 0xc;
    GuestRegs.r12 = 0xd;
    GuestRegs.r13 = 0xe;
    GuestRegs.r14 = (UINT64)testw;
    GuestRegs.r15 = (UINT64)test;
 
    ScriptEngineEvalWrapper(&GuestRegs, Expr);
 
    free(RspReg);
    free(TestStruct);
    free(AllocationsForCastings.Buff1);
    free(AllocationsForCastings.Buff2);
    free(AllocationsForCastings.Buff3);
    free(AllocationsForCastings.Buff4);
    free(AllocationsForCastings.Buff5);
    free(AllocationsForCastings.Buff6);
}