Contains implementations for the GLUE_IFACE APIs exposed by Introcore. More...

#include "introapi.h"
#include "debugger.h"
#include "decoder.h"
#include "deployer.h"
#include "gpacache.h"
#include "guests.h"
#include "kernvm.h"
#include "ptfilter.h"
#include "update_exceptions.h"
#include "vecore.h"

Functions
static void	IntApiLeave (BOOLEAN Async)
	Handles API exists. More...

static void	IntApiEnter (DWORD CpuNumber)
	Common API handler. More...

INTSTATUS	IntNewGuestNotification (void *GuestHandle, QWORD Options, PBYTE UpdateBuffer, DWORD BufferLength)
	Handles a new guest. It is essentially the Introcore entry point. More...

INTSTATUS	IntDisableIntro (void *GuestHandle, QWORD Flags)
	Disables and unloads the introspection engine. More...

INTSTATUS	IntNotifyGuestPowerStateChange (void *GuestHandle, IG_GUEST_POWER_STATE PowerState)
	Handles guest power state transitions. More...

INTSTATUS	IntAddRemoveProtectedProcessUtf8 (void GuestHandle, const CHAR FullPath, DWORD ProtectionMask, BOOLEAN Add, QWORD Context)
	Toggles protection options for a process. More...

INTSTATUS	IntAddRemoveProtectedProcessUtf16 (void GuestHandle, const WCHAR FullPath, DWORD ProtectionMask, BOOLEAN Add, QWORD Context)
	Toggles protection options for a process. More...

INTSTATUS	IntRemoveAllProtectedProcesses (void *GuestHandle)
	Removes the protection policies for all processes. More...

INTSTATUS	IntInjectProcessAgentInGuest (void GuestHandle, DWORD AgentTag, PBYTE AgentContent, DWORD AgentSize, const CHAR Name, const CHAR *Args)
	Requests a process agent injection inside the guest. More...

INTSTATUS	IntInjectFileAgentInGuest (void GuestHandle, PBYTE AgentContent, DWORD AgentSize, const CHAR Name)
	Drops a file on the guest hard disk. More...

INTSTATUS	IntGetCurrentInstructionLength (void GuestHandle, DWORD CpuNumber, BYTE Length)
	Returns the length of the instruction at which the current guest RIP points. More...

INTSTATUS	IntGetCurrentInstructionMnemonic (void GuestHandle, DWORD CpuNumber, CHAR Mnemonic)
	Returns the mnemonic of the instruction at which the current guest RIP points. More...

INTSTATUS	IntIterateVaSpace (void *GuestHandle, QWORD Cr3, PFUNC_VirtualAddressSpaceCallback Callback)
	Iterates over the guest virtual address space. More...

INTSTATUS	IntGetGuestInfo (void GuestHandle, GUEST_INFO GuestInfo)
	Get a description of the introspected guest. More...

INTSTATUS	IntModifyDynamicOptions (void *GuestHandle, QWORD NewOptions)
	Modifies the introcore options. More...

INTSTATUS	IntFlushGpaCache (void *GuestHandle)
	Flushed the introcore GPA cache. More...

INTSTATUS	IntGetCurrentIntroOptions (void GuestHandle, QWORD IntroOptions)
	Get the currently used introcore options. More...

INTSTATUS	IntUpdateSupport (void *GuestHandle, PBYTE Buffer, DWORD Length)
	Loads a new CAMI version. More...

INTSTATUS	IntGetSupportVersion (void GuestHandle, DWORD MajorVersion, DWORD MinorVersion, DWORD BuildNumber)
	Get the current version of CAMI. More...

INTSTATUS	IntProcessDebugCommand (void GuestHandle, DWORD CpuNumber, DWORD Argc, CHAR Argv[])
	Executes a debugger command. More...

INTSTATUS	IntGetExceptionsVersion (void GuestHandle, WORD MajorVersion, WORD MinorVersion, DWORD BuildNumber)
	Get the current exceptions version.See PFUNC_IntGetExceptionsVersion for details. More...

INTSTATUS	IntUpdateExceptions (void *GuestHandle, PBYTE Buffer, DWORD Length, DWORD Flags)
	Loads a new exceptions version.See PFUNC_IntUpdateExceptions for details. More...

INTSTATUS	IntAddExceptionFromAlert (void GuestHandle, const void Event, INTRO_EVENT_TYPE Type, BOOLEAN Exception, QWORD Context)
	Adds an exception for an alert reported by introcore.See PFUNC_IntAddExceptionFromAlert for details. More...

INTSTATUS	IntRemoveException (void *GuestHandle, QWORD Context)
	Removes a custom exception added with GLUE_IFACE.AddExceptionFromAlert.See PFUNC_IntRemoveException for details. More...

INTSTATUS	IntFlushAlertExceptions (void *GuestHandle)
	Removes all the custom exceptions added with GLUE_IFACE.AddExceptionFromAlert.See PFUNC_IntFlushAlertExceptions for details. More...

INTSTATUS	IntAbortEnableIntro (void *GuestHandle, BOOLEAN Abort)
	Abort the introcore loading process. More...

INTSTATUS	IntSetLogLevel (void *GuestHandle, IG_LOG_LEVEL LogLevel)
	Sets the log level. More...

INTSTATUS	IntGetVersionString (DWORD FullStringSize, DWORD VersionStringSize, CHAR FullString, CHAR VersionString)
	Get the version string information for the current guest. More...

Detailed Description

Contains implementations for the GLUE_IFACE APIs exposed by Introcore.

In general, the documentation for these functions is the same as the documentation for the PFUNC_ definitions in glueiface.h. If something is not explicitly documented here, the documentation from glueiface.h is sufficient.

Definition in file introapi.c.

Function Documentation

◆ IntAbortEnableIntro()

INTSTATUS IntAbortEnableIntro	(	void *	GuestHandle,
		BOOLEAN	Abort
	)

Abort the introcore loading process.

See PFUNC_IntSetIntroAbortStatus for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1545 of file introapi.c.

Referenced by IntInit().

◆ IntAddRemoveProtectedProcessUtf16()

INTSTATUS IntAddRemoveProtectedProcessUtf16	(	void *	GuestHandle,
		const WCHAR *	FullPath,
		DWORD	ProtectionMask,
		BOOLEAN	Add,
		QWORD	Context
	)

Toggles protection options for a process.

See PFUNC_IntAddRemoveProtectedProcessUtf16 for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 435 of file introapi.c.

Referenced by IntInit().

◆ IntAddRemoveProtectedProcessUtf8()

INTSTATUS IntAddRemoveProtectedProcessUtf8	(	void *	GuestHandle,
		const CHAR *	FullPath,
		DWORD	ProtectionMask,
		BOOLEAN	Add,
		QWORD	Context
	)

Toggles protection options for a process.

See PFUNC_IntAddRemoveProtectedProcessUtf8 for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 299 of file introapi.c.

Referenced by DbgProcAdd(), DbgProcRem(), and IntInit().

◆ IntApiEnter()

static void IntApiEnter ( DWORD CpuNumber )

static

Common API handler.

This establishes a consistent state for all APIs exposed by Introcore to the integrator that are not event callbacks.

Parameters

[in] CpuNumber The VCPU on which the API was called. If it is not called in the context of a VCPU this should be set to IG_CURRENT_VCPU and Introcore will assume that VCPU 0 is used. For Napoca, since we are always called in the context of a valid VCPU we get the current VCPU.

Definition at line 51 of file introapi.c.

Referenced by IntAddRemoveProtectedProcessUtf16(), IntAddRemoveProtectedProcessUtf8(), IntDisableIntro(), IntFlushGpaCache(), IntGetCurrentInstructionLength(), IntGetCurrentInstructionMnemonic(), IntGetGuestInfo(), IntGetVersionString(), IntInjectFileAgentInGuest(), IntInjectProcessAgentInGuest(), IntIterateVaSpace(), IntProcessDebugCommand(), IntRemoveAllProtectedProcesses(), and IntUpdateSupport().

◆ IntApiLeave()

static void IntApiLeave ( BOOLEAN Async )

static

Handles API exists.

This should be called before returning from an Introcore API that is exposed to the integrator that are not event callbacks.

Parameters

[in] Async True if the API is not called in the context of a VCPU.

Definition at line 27 of file introapi.c.

Referenced by IntGetCurrentInstructionLength(), IntGetCurrentInstructionMnemonic(), IntInjectFileAgentInGuest(), and IntInjectProcessAgentInGuest().

◆ IntDisableIntro()

INTSTATUS IntDisableIntro	(	void *	GuestHandle,
		QWORD	Flags
	)

Disables and unloads the introspection engine.

This is a wrapper over IntGuestDisableIntro which will ensure that the VCPUs are paused and that gLock is held.

See PFUNC_IntDisableIntro for details.

Parameters

[in]	GuestHandle	Integrator-specific guest identifier.
[in]	Flags	Flags controlling the disable operation. Can be 0 or IG_DISABLE_IGNORE_SAFENESS. If IG_DISABLE_IGNORE_SAFENESS is used, introcore will forcibly unload even it is not safe to do that at the moment. This may leave the guest in an unstable state.

Return values

INT_STATUS_SUCCESS	in case of success.
INT_STATUS_CANNOT_UNLOAD	if introcore can not unload.

Definition at line 176 of file introapi.c.

Referenced by IntInit(), and IntUninit().

◆ IntFlushGpaCache()

INTSTATUS IntFlushGpaCache ( void * GuestHandle )

Flushed the introcore GPA cache.

See PFUNC_IntFlushGpaCache for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1026 of file introapi.c.

Referenced by IntInit().

◆ IntGetCurrentInstructionLength()

INTSTATUS IntGetCurrentInstructionLength	(	void *	GuestHandle,
		DWORD	CpuNumber,
		BYTE *	Length
	)

Returns the length of the instruction at which the current guest RIP points.

See PFUNC_IntGetCurrentInstructionLength for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 729 of file introapi.c.

Referenced by IntInit().

◆ IntGetCurrentInstructionMnemonic()

INTSTATUS IntGetCurrentInstructionMnemonic	(	void *	GuestHandle,
		DWORD	CpuNumber,
		CHAR *	Mnemonic
	)

Returns the mnemonic of the instruction at which the current guest RIP points.

See PFUNC_IntGetCurrentInstructionMnemonic for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 806 of file introapi.c.

Referenced by IntInit().

◆ IntGetCurrentIntroOptions()

INTSTATUS IntGetCurrentIntroOptions	(	void *	GuestHandle,
		QWORD *	IntroOptions
	)

Get the currently used introcore options.

See PFUNC_IntGetCurrentIntroOptions for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1077 of file introapi.c.

Referenced by IntInit().

◆ IntGetGuestInfo()

INTSTATUS IntGetGuestInfo	(	void *	GuestHandle,
		GUEST_INFO *	GuestInfo
	)

Get a description of the introspected guest.

See PFUNC_IntGetGuestInfo for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 930 of file introapi.c.

Referenced by IntInit().

◆ IntGetSupportVersion()

INTSTATUS IntGetSupportVersion	(	void *	GuestHandle,
		DWORD *	MajorVersion,
		DWORD *	MinorVersion,
		DWORD *	BuildNumber
	)

Get the current version of CAMI.

See PFUNC_IntGetSupportVersion for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1212 of file introapi.c.

Referenced by IntInit().

◆ IntGetVersionString()

INTSTATUS IntGetVersionString	(	DWORD	FullStringSize,
		DWORD	VersionStringSize,
		CHAR *	FullString,
		CHAR *	VersionString
	)

Get the version string information for the current guest.

See PFUNC_IntGetVersionString for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1599 of file introapi.c.

Referenced by IntInit().

◆ IntInjectFileAgentInGuest()

INTSTATUS IntInjectFileAgentInGuest	(	void *	GuestHandle,
		PBYTE	AgentContent,
		DWORD	AgentSize,
		const CHAR *	Name
	)

Drops a file on the guest hard disk.

See PFUNC_IntInjectFileAgent for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 658 of file introapi.c.

Referenced by IntInit().

◆ IntInjectProcessAgentInGuest()

INTSTATUS IntInjectProcessAgentInGuest	(	void *	GuestHandle,
		DWORD	AgentTag,
		PBYTE	AgentContent,
		DWORD	AgentSize,
		const CHAR *	Name,
		const CHAR *	Args
	)

Requests a process agent injection inside the guest.

See PFUNC_IntInjectProcessAgent for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 585 of file introapi.c.

Referenced by IntInit().

◆ IntIterateVaSpace()

INTSTATUS IntIterateVaSpace	(	void *	GuestHandle,
		QWORD	Cr3,
		PFUNC_VirtualAddressSpaceCallback	Callback
	)

Iterates over the guest virtual address space.

See PFUNC_IntIterateVaSpace for details.

Returns: INT_STATUS_SUCCESS if successful, or an appropriate INTSTATUS error value.

Definition at line 881 of file introapi.c.

Referenced by IntInit().

◆ IntModifyDynamicOptions()

INTSTATUS IntModifyDynamicOptions	(	void *	GuestHandle,
		QWORD	NewOptions
	)

Modifies the introcore options.

See PFUNC_IntModifyDynamicOptions for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 980 of file introapi.c.

Referenced by IntInit().

◆ IntNewGuestNotification()

INTSTATUS IntNewGuestNotification	(	void *	GuestHandle,
		QWORD	Options,
		PBYTE	UpdateBuffer,
		DWORD	BufferLength
	)

Handles a new guest. It is essentially the Introcore entry point.

This is the place in which the process of guest introspection is started. This function loads the CAMI data base and prepares the guest hooking. Even if this function exits with a success status value, it does not mean that the guest is successfully introspected, as certain parts of the initialization are not synchronous. The guest must be considered as not identified until GLUE_IFACE.NotifyIntrospectionDetectedOs is called, and not protected until GLUE_IFACE.NotifyIntrospectionActivated is called. Errors can still be encountered while this process takes place, in which case GLUE_IFACE.NotifyIntrospectionErrorState will be used to report them.

See PFUNC_IntNotifyNewGuest for details.

Parameters

[in]	GuestHandle	Opaque value used to identify the guest. This is used when communicating between the introspection engine and the integrator and must not change during execution.
[in]	Options	Protection and activation flags. See Activation and protection flags
[in]	UpdateBuffer	The CAMI buffer to be used. If processing this buffer fails, this function will return one of the IntCamiSetUpdateBuffer error status values and will set the error state to intErrUpdateFileNotSupported. This buffer must remain valid until Introcore frees it with GLUE_IFACE.ReleaseBuffer.
[in]	BufferLength	The size of UpdateBuffer.

Return values

INT_STATUS_SUCCESS	in case of success.
INT_STATUS_INVALID_PARAMETER_1	if GuestHandle is NULL.
INT_STATUS_ALREADY_INITIALIZED_HINT	if a guest is already initialized.

Precondition: IntInit was called and it returned a success status value.

Definition at line 81 of file introapi.c.

Referenced by IntInit().

◆ IntNotifyGuestPowerStateChange()

INTSTATUS IntNotifyGuestPowerStateChange	(	void *	GuestHandle,
		IG_GUEST_POWER_STATE	PowerState
	)

Handles guest power state transitions.

If the guest is transitioning to the intGuestPowerStateSleep power state, gLock will be acquired, which will ensure that all events will be blocked until the guest resumes from sleep (intGuestPowerStateResume). This assumes that the resume event is always sent after the sleep event and that no consecutive sleep events are sent.

See PFUNC_IntNotifyGuestPowerStateChange for details.

Parameters

[in]	GuestHandle	Integrator-specific guest identifier. Ignored.
[in]	PowerState	The power state to which the guest is transitioning.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 231 of file introapi.c.

Referenced by IntInit().

◆ IntProcessDebugCommand()

INTSTATUS IntProcessDebugCommand	(	void *	GuestHandle,
		DWORD	CpuNumber,
		DWORD	Argc,
		CHAR *	Argv[]
	)

Executes a debugger command.

This function does not acquire gLock like all the other GLUE_IFACE APIs since a lot of the time, while debugging, we may already hold the lock, which will cause a dead lock. Since this offers only debugging functionalities this is not a problem.

See PFUNC_IntDebugProcessCommand.

Parameters

[in]	GuestHandle	Integrator-specific guest identifier.
[in]	CpuNumber	The current VCPU number.
[in]	Argc	The number of arguments.
[in]	Argv	An array of NULL terminated strings.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1260 of file introapi.c.

Referenced by IntInit().

◆ IntRemoveAllProtectedProcesses()

INTSTATUS IntRemoveAllProtectedProcesses ( void * GuestHandle )

Removes the protection policies for all processes.

See PFUNC_IntRemoveAllProtectedProcesses for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 522 of file introapi.c.

Referenced by DbgProcClear(), and IntInit().

◆ IntSetLogLevel()

INTSTATUS IntSetLogLevel	(	void *	GuestHandle,
		IG_LOG_LEVEL	LogLevel
	)

Sets the log level.

See PFUNC_IntSetLogLevel for details.

Return values

INT_STATUS_SUCCESS in case of success.

Definition at line 1571 of file introapi.c.

Referenced by IntInit().

◆ IntUpdateSupport()

INTSTATUS IntUpdateSupport	(	void *	GuestHandle,
		PBYTE	Buffer,
		DWORD	Length
	)

Loads a new CAMI version.

See PFUNC_IntUpdateSupport for details.

Return values

INT_STATUS_SUCCESS in case of success.

Remarks: After a successful call, the previously loaded CAMI settings are removed.

Definition at line 1128 of file introapi.c.

Referenced by IntInit().

Functions

Detailed Description

Function Documentation

◆ IntAbortEnableIntro()

◆ IntAddRemoveProtectedProcessUtf16()

◆ IntAddRemoveProtectedProcessUtf8()

◆ IntApiEnter()

◆ IntApiLeave()

◆ IntDisableIntro()

◆ IntFlushGpaCache()

◆ IntGetCurrentInstructionLength()

◆ IntGetCurrentInstructionMnemonic()

◆ IntGetCurrentIntroOptions()

◆ IntGetGuestInfo()

◆ IntGetSupportVersion()

◆ IntGetVersionString()

◆ IntInjectFileAgentInGuest()

◆ IntInjectProcessAgentInGuest()

◆ IntIterateVaSpace()

◆ IntModifyDynamicOptions()

◆ IntNewGuestNotification()

◆ IntNotifyGuestPowerStateChange()

◆ IntProcessDebugCommand()

◆ IntRemoveAllProtectedProcesses()

◆ IntSetLogLevel()

◆ IntUpdateSupport()