track.cpp File Reference

!track command More...

#include "pch.h"

Functions
VOID	CommandTrackHelp ()
	help of the !track command
VOID	CommandTrack (vector< CommandToken > CommandTokens, string Command)
	handler of !track command
VOID	CommandTrackHandleReceivedInstructions (UCHAR *BufferToDisassemble, UINT32 BuffLength, BOOLEAN Isx86_64, UINT64 RipAddress)
	Handle received 'call' or 'ret'.
VOID	CommandTrackHandleReceivedCallInstructions (const CHAR *NameOfFunctionFromSymbols, UINT64 ComputedAbsoluteAddress)
	Handle received 'call'.
VOID	CommandTrackHandleReceivedRetInstructions (UINT64 CurrentRip)
	Handle received 'ret'.

Variables
BOOLEAN	g_IsSerialConnectedToRemoteDebuggee
	Shows if the debugger was connected to remote debuggee over (A remote guest).
BOOLEAN	g_IsInstrumentingInstructions
	Shows whether the user is running 't', 'p', or 'i' command.
ACTIVE_DEBUGGING_PROCESS	g_ActiveProcessDebuggingState
	State of active debugging thread.
BOOLEAN	g_AddressConversion
	Whether converting addresses to object names or not.
UINT32	NumberOfCallsIdentation = 0
BOOLEAN	IsCallInstructionVisited = FALSE
BOOLEAN	ShowRegs = FALSE
volatile BOOLEAN	RequestShowingRegs = FALSE

Detailed Description

!track command

Author

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

Version

0.3

Date

2023-05-05

Copyright

This project is released under the GNU Public License v3.

Function Documentation

CommandTrack()

VOID CommandTrack	(	vector< CommandToken >	CommandTokens,
		string	Command )

handler of !track command

Parameters

CommandTokens
Command

Returns

VOID

{
    UINT32 StepCount;
    string SymbolServer;
 
    //
    // Validate the commands
    //
    if (CommandTokens.size() >= 4)
    {
        ShowMessages("incorrect use of the '%s'\n\n",
                     GetCaseSensitiveStringFromCommandToken(CommandTokens.at(0)).c_str());
        CommandTrackHelp();
        return;
    }
 
    //
    // Check if we're in VMI mode
    //
    if (g_ActiveProcessDebuggingState.IsActive)
    {
        ShowMessages("the tracking mechanism is only supported in Debugger Mode\n");
        return;
    }
 
    //
    // Show recommendation
    //
    if (!CommandSettingsGetValueFromConfigFile("SymbolServer", SymbolServer))
    {
        ShowMessages("it is recommended to configure the symbol path '.sympath' and load "
                     "symbols before using the '!track' command command to obtain results with function "
                     "names\n");
    }
 
    //
    // Reset the details of indentation and regs
    //
    NumberOfCallsIdentation  = 0;
    IsCallInstructionVisited = FALSE;
    ShowRegs                 = FALSE;
    RequestShowingRegs       = FALSE;
 
    //
    // Set default of stepping (tracking)
    //
    StepCount = DEBUGGER_REMOTE_TRACKING_DEFAULT_COUNT_OF_STEPPING;
 
    //
    // Check parameters
    //
    for (auto Section : CommandTokens)
    {
        if (CompareLowerCaseStrings(Section, "!track") || CompareLowerCaseStrings(Section, "track"))
        {
            continue;
        }
 
        //
        // check if the second param is a number
        //
        if (ConvertTokenToUInt32(Section, &StepCount))
        {
            continue;
        }
        else if (CompareLowerCaseStrings(Section, "tree"))
        {
            //
            // Default
            //
            ShowRegs = FALSE;
        }
        else if (CompareLowerCaseStrings(Section, "reg"))
        {
            ShowRegs = TRUE;
        }
        else
        {
            ShowMessages("err, couldn't resolve error at '%s'\n\n",
                         GetCaseSensitiveStringFromCommandToken(Section).c_str());
            return;
        }
    }
 
    //
    // Check if the remote serial debuggee or user debugger are paused or not
    //
    if (g_IsSerialConnectedToRemoteDebuggee)
    {
        //
        // Indicate that we're instrumenting
        //
        g_IsInstrumentingInstructions = TRUE;
 
        for (SIZE_T i = 0; i < StepCount; i++)
        {
            //
            // For logging purpose
            //
            // ShowMessages("percentage : %f %% (%x)\n", 100.0 * (i /
            //   (float)StepCount), i);
            //
 
            //
            // It's stepping over serial connection in kernel debugger
            //
            SteppingInstrumentationStepInForTracking();
 
            if (ShowRegs && RequestShowingRegs)
            {
                RequestShowingRegs = FALSE;
 
                //
                // Show registers
                //
                HyperDbgRegisterShowAll();
 
                ShowMessages("\n");
            }
 
            //
            // Check if user pressed CTRL+C
            //
            if (!g_IsInstrumentingInstructions)
            {
                break;
            }
        }
 
        //
        // We're not instrumenting instructions anymore
        //
        g_IsInstrumentingInstructions = FALSE;
    }
    else
    {
        ShowMessages("err, tracking is not valid in the current context, you "
                     "should connect to a debuggee\n");
    }
}

CommandTrackHandleReceivedCallInstructions()

VOID CommandTrackHandleReceivedCallInstructions	(	const CHAR *	NameOfFunctionFromSymbols,
		UINT64	ComputedAbsoluteAddress )

Handle received 'call'.

Parameters

NameOfFunctionFromSymbols
ComputedAbsoluteAddress

Returns

VOID

{
    //
    // One 'call' instruction is visited
    //
    IsCallInstructionVisited = TRUE;
 
    CHAR Utf8String1[] = "\xE2\x94\x82\x20\x20";
 
    for (SIZE_T i = 0; i < NumberOfCallsIdentation; i++)
    {
        PlatformWriteConsole(Utf8String1, sizeof(Utf8String1) - 1);
    }
 
    //
    // Write the UTF-8 encoded character sequence to the console
    //
    // CHAR Utf8String[] = "\xE2\x94\x9C\xE2\x94\x80\xE2\x94\x80";
    CHAR Utf8String[] = "\xE2\x94\x8C\xE2\x94\x80\xE2\x94\x80";
    PlatformWriteConsole(Utf8String, sizeof(Utf8String) - 1);
 
    if (NameOfFunctionFromSymbols != NULL)
    {
        ShowMessages(" %s (%s)\n", NameOfFunctionFromSymbols, SeparateTo64BitValue(ComputedAbsoluteAddress).c_str());
    }
    else
    {
        ShowMessages(" %s\n", SeparateTo64BitValue(ComputedAbsoluteAddress).c_str());
    }
 
    if (ShowRegs)
    {
        RequestShowingRegs = TRUE;
    }
 
    NumberOfCallsIdentation++;
}

CommandTrackHandleReceivedInstructions()

VOID CommandTrackHandleReceivedInstructions	(	UCHAR *	BufferToDisassemble,
		UINT32	BuffLength,
		BOOLEAN	Isx86_64,
		UINT64	RipAddress )

Handle received 'call' or 'ret'.

Parameters

BufferToDisassemble
BuffLength
Isx86_64
RipAddress

Returns

VOID

{
    BOOLEAN IsRet = FALSE;
 
    //
    // By calling this function, it acts as a callback that in case of the 'call' and the 'ret' instructions
    // the callbacks will be called
    //
    HyperDbgCheckWhetherTheCurrentInstructionIsCallOrRet(BufferToDisassemble, RipAddress, BuffLength, Isx86_64, &IsRet);
}

CommandTrackHandleReceivedRetInstructions()

VOID CommandTrackHandleReceivedRetInstructions

(

UINT64

CurrentRip

)

Handle received 'ret'.

Parameters

CurrentRip

Returns

VOID

{
    UINT64  UsedBaseAddress = NULL;
    BOOLEAN IsNameShowed    = FALSE;
 
    if (IsCallInstructionVisited)
    {
        if (NumberOfCallsIdentation != 0)
        {
            NumberOfCallsIdentation--;
        }
    }
 
    CHAR Utf8String1[] = "\xE2\x94\x82\x20\x20";
 
    for (SIZE_T i = 0; i < NumberOfCallsIdentation; i++)
    {
        PlatformWriteConsole(Utf8String1, sizeof(Utf8String1) - 1);
    }
 
    //
    // Write the UTF-8 encoded character sequence to the console
    //
    CHAR Utf8String[] = "\xE2\x94\x94\xE2\x94\x80\xE2\x94\x80\x20";
    PlatformWriteConsole(Utf8String, sizeof(Utf8String) - 1);
 
    //
    // Apply addressconversion of settings here
    //
    if (g_AddressConversion)
    {
        //
        // Showing function names here
        //
        if (SymbolShowFunctionNameBasedOnAddress(CurrentRip, &UsedBaseAddress))
        {
            //
            // The symbol address is showed
            //
            IsNameShowed = TRUE;
            ShowMessages(" (%s)\n", SeparateTo64BitValue(CurrentRip).c_str());
        }
    }
 
    if (!IsNameShowed)
    {
        ShowMessages("%s \n", SeparateTo64BitValue(CurrentRip).c_str());
    }
}

CommandTrackHelp()

VOID CommandTrackHelp

(

)

help of the !track command

Returns

VOID

{
    ShowMessages(
        "!track : tracks instructions from user-mode to kernel-mode or kernel-mode to user-mode "
        "to create call tree. Please note that it's highly recommended to configure symbols before "
        "using this command as it maps addresses to corresponding function names.\n\n");
 
    ShowMessages("syntax : \t!track [tree] [Count (hex)]\n");
    ShowMessages("syntax : \t!track [reg] [Count (hex)]\n");
 
    ShowMessages("\n");
    ShowMessages("\t\te.g : !track tree 10000\n");
    ShowMessages("\t\te.g : !track reg 10000\n");
}

Variable Documentation

g_ActiveProcessDebuggingState

ACTIVE_DEBUGGING_PROCESS g_ActiveProcessDebuggingState

extern

State of active debugging thread.

{0};

g_AddressConversion

BOOLEAN g_AddressConversion

extern

Whether converting addresses to object names or not.

it is enabled by default

g_IsInstrumentingInstructions

BOOLEAN g_IsInstrumentingInstructions

extern

Shows whether the user is running 't', 'p', or 'i' command.

g_IsSerialConnectedToRemoteDebuggee

BOOLEAN g_IsSerialConnectedToRemoteDebuggee

extern

Shows if the debugger was connected to remote debuggee over (A remote guest).

IsCallInstructionVisited

BOOLEAN IsCallInstructionVisited = FALSE

NumberOfCallsIdentation

UINT32 NumberOfCallsIdentation = 0

RequestShowingRegs

volatile BOOLEAN RequestShowingRegs = FALSE

ShowRegs

BOOLEAN ShowRegs = FALSE