Bitdefender Hypervisor Memory Introspection
introapi.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2020 Bitdefender
3  * SPDX-License-Identifier: Apache-2.0
4  */
5 #ifndef _INTROAPI_H_
6 #define _INTROAPI_H_
7 
8 #include "glue.h"
9 
10 //
11 // Introspection API - exposed to the HV/other 3rd party integrators.
12 //
13 INTSTATUS
14 IntNewGuestNotification(
15  _In_ void *GuestHandle,
16  _In_ QWORD Options,
17  _In_reads_(BufferLength) PBYTE UpdateBuffer,
18  _In_ DWORD BufferLength
19  );
20 
21 INTSTATUS
22 IntDisableIntro(
23  _In_ void *GuestHandle,
24  _In_ QWORD Flags
25  );
26 
27 INTSTATUS
28 IntNotifyGuestPowerStateChange(
29  _In_ void *GuestHandle,
30  _In_ IG_GUEST_POWER_STATE PowerState
31  );
32 
33 INTSTATUS
34 IntInjectProcessAgentInGuest(
35  _In_ void *GuestHandle,
36  _In_ DWORD AgentTag,
37  _In_opt_ PBYTE AgentContent,
38  _In_opt_ DWORD AgentSize,
39  _In_z_ const CHAR *Name,
40  _In_opt_ const CHAR *Args
41  );
42 
43 INTSTATUS
44 IntInjectFileAgentInGuest(
45  _In_ void *GuestHandle,
46  _In_ PBYTE AgentContent,
47  _In_ DWORD AgentSize,
48  _In_z_ const CHAR *Name
49  );
50 
51 INTSTATUS
52 IntAddRemoveProtectedProcessUtf8(
53  _In_ void *GuestHandle,
54  _In_z_ const CHAR *FullPath,
55  _In_ DWORD ProtectionMask,
56  _In_ BOOLEAN Add,
57  _In_ QWORD Context
58  );
59 
60 INTSTATUS
61 IntAddRemoveProtectedProcessUtf16(
62  _In_ void *GuestHandle,
63  _In_z_ const WCHAR *FullPath,
64  _In_ DWORD ProtectionMask,
65  _In_ BOOLEAN Add,
66  _In_ QWORD Context
67  );
68 
69 INTSTATUS
70 IntRemoveAllProtectedProcesses(
71  _In_ void *GuestHandle
72  );
73 
74 INTSTATUS
75 IntGetCurrentInstructionLength(
76  _In_ void *GuestHandle,
77  _In_ DWORD CpuNumber,
78  _Out_ BYTE *Length
79  );
80 
81 INTSTATUS
82 IntGetCurrentInstructionMnemonic(
83  _In_ void *GuestHandle,
84  _In_ DWORD CpuNumber,
85  _Out_ CHAR *Mnemonic
86  );
87 
88 INTSTATUS
89 IntIterateVaSpace(
90  _In_ void *GuestHandle,
91  _In_ QWORD Cr3,
92  _In_ PFUNC_VirtualAddressSpaceCallback Callback
93  );
94 
95 INTSTATUS
96 IntGetGuestInfo(
97  _In_ void *GuestHandle,
98  _Out_ GUEST_INFO *GuestInfo
99  );
100 
101 INTSTATUS
102 IntModifyDynamicOptions(
103  _In_ void *GuestHandle,
104  _In_ QWORD NewOptions
105  );
106 
107 INTSTATUS
108 IntFlushGpaCache(
109  _In_ void *GuestHandle
110  );
111 
112 INTSTATUS
113 IntGetCurrentIntroOptions(
114  _In_ void *GuestHandle,
115  _Out_ QWORD *IntroOptions
116  );
117 
118 INTSTATUS
119 IntProcessDebugCommand(
120  _In_ void *GuestHandle,
121  _In_ DWORD CpuNumber,
122  _In_ DWORD Argc,
123  _In_ CHAR *Argv[]
124  );
125 
126 
127 //
128 // Exceptions related.
129 //
130 INTSTATUS
131 IntGetExceptionsVersion(
132  _In_ void *GuestHandle,
133  _Out_ WORD *MajorVersion,
134  _Out_ WORD *MinorVersion,
135  _Out_ DWORD *BuildNumber
136  );
137 
138 INTSTATUS
139 IntUpdateExceptions(
140  _In_ void *GuestHandle,
141  _In_reads_bytes_(Length) PBYTE Buffer,
142  _In_ DWORD Length,
143  _In_ DWORD Flags
144  );
145 
146 INTSTATUS
147 IntUpdateSupport(
148  _In_ void *GuestHandle,
149  _In_reads_bytes_(Length) PBYTE Buffer,
150  _In_ DWORD Length
151  );
152 
153 INTSTATUS
154 IntGetSupportVersion(
155  _In_ void *GuestHandle,
156  _Out_ DWORD *MajorVersion,
157  _Out_ DWORD *MinorVersion,
158  _Out_ DWORD *BuildNumber
159  );
160 
161 
162 INTSTATUS
163 IntAddExceptionFromAlert(
164  _In_ void *GuestHandle,
165  _In_ const void *Event,
166  _In_ INTRO_EVENT_TYPE Type,
167  _In_ BOOLEAN Exception,
168  _In_ QWORD Context
169  );
170 
171 INTSTATUS
172 IntFlushAlertExceptions(
173  _In_ void *GuestHandle
174  );
175 
176 INTSTATUS
177 IntRemoveException(
178  _In_ void *GuestHandle,
179  _In_opt_ QWORD Context
180  );
181 
182 INTSTATUS
183 IntAbortEnableIntro(
184  _In_ void *GuestHandle,
185  _In_ BOOLEAN Abort
186  );
187 
188 INTSTATUS
189 IntSetLogLevel(
190  _In_ void *GuestHandle,
191  _In_ IG_LOG_LEVEL LogLevel
192  );
193 
194 INTSTATUS
195 IntGetVersionString(
196  _In_ DWORD FullStringSize,
197  _In_ DWORD VersionStringSize,
198  _Out_ CHAR *FullString,
199  _Out_ CHAR *VersionString
200  );
201 
202 #endif // _INTROAPI_H_
_In_opt_
#define _In_opt_
Definition: intro_sal.h:16
_Out_
#define _Out_
Definition: intro_sal.h:22
BOOLEAN
_Bool BOOLEAN
Definition: intro_types.h:58
BYTE
uint8_t BYTE
Definition: intro_types.h:47
IntProcessDebugCommand
INTSTATUS IntProcessDebugCommand(void *GuestHandle, DWORD CpuNumber, DWORD Argc, CHAR *Argv[])
Executes a debugger command.
Definition: introapi.c:1260
_In_
#define _In_
Definition: intro_sal.h:21
IntIterateVaSpace
INTSTATUS IntIterateVaSpace(void *GuestHandle, QWORD Cr3, PFUNC_VirtualAddressSpaceCallback Callback)
Iterates over the guest virtual address space.
Definition: introapi.c:881
WORD
uint16_t WORD
Definition: intro_types.h:48
IntGetExceptionsVersion
INTSTATUS IntGetExceptionsVersion(void *GuestHandle, WORD *MajorVersion, WORD *MinorVersion, DWORD *BuildNumber)
Get the current exceptions version.See PFUNC_IntGetExceptionsVersion for details. ...
Definition: introapi.c:1303
PFUNC_VirtualAddressSpaceCallback
INTSTATUS(* PFUNC_VirtualAddressSpaceCallback)(QWORD Cr3, QWORD VirtualAddress, QWORD Entry, QWORD PageSize)
The type of callback invoked by PFUNC_IntIterateVaSpace while iterating the guest virtual address spa...
Definition: glueiface.h:1814
IntGetSupportVersion
INTSTATUS IntGetSupportVersion(void *GuestHandle, DWORD *MajorVersion, DWORD *MinorVersion, DWORD *BuildNumber)
Get the current version of CAMI.
Definition: introapi.c:1212
IG_GUEST_POWER_STATE
enum _IG_GUEST_POWER_STATE IG_GUEST_POWER_STATE
The guest power state.
IntGetGuestInfo
INTSTATUS IntGetGuestInfo(void *GuestHandle, GUEST_INFO *GuestInfo)
Get a description of the introspected guest.
Definition: introapi.c:930
_In_reads_
#define _In_reads_(expr)
Definition: intro_sal.h:27
IntAddExceptionFromAlert
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...
Definition: introapi.c:1402
INTSTATUS
int INTSTATUS
The status data type.
Definition: introstatus.h:24
IntDisableIntro
INTSTATUS IntDisableIntro(void *GuestHandle, QWORD Flags)
Disables and unloads the introspection engine.
Definition: introapi.c:176
IntUpdateSupport
INTSTATUS IntUpdateSupport(void *GuestHandle, PBYTE Buffer, DWORD Length)
Loads a new CAMI version.
Definition: introapi.c:1128
IntAddRemoveProtectedProcessUtf8
INTSTATUS IntAddRemoveProtectedProcessUtf8(void *GuestHandle, const CHAR *FullPath, DWORD ProtectionMask, BOOLEAN Add, QWORD Context)
Toggles protection options for a process.
Definition: introapi.c:299
IntSetLogLevel
INTSTATUS IntSetLogLevel(void *GuestHandle, IG_LOG_LEVEL LogLevel)
Sets the log level.
Definition: introapi.c:1571
IntNotifyGuestPowerStateChange
INTSTATUS IntNotifyGuestPowerStateChange(void *GuestHandle, IG_GUEST_POWER_STATE PowerState)
Handles guest power state transitions.
Definition: introapi.c:231
IntUpdateExceptions
INTSTATUS IntUpdateExceptions(void *GuestHandle, PBYTE Buffer, DWORD Length, DWORD Flags)
Loads a new exceptions version.See PFUNC_IntUpdateExceptions for details.
Definition: introapi.c:1352
IntRemoveException
INTSTATUS IntRemoveException(void *GuestHandle, QWORD Context)
Removes a custom exception added with GLUE_IFACE.AddExceptionFromAlert.See PFUNC_IntRemoveException f...
Definition: introapi.c:1452
IntRemoveAllProtectedProcesses
INTSTATUS IntRemoveAllProtectedProcesses(void *GuestHandle)
Removes the protection policies for all processes.
Definition: introapi.c:522
PBYTE
uint8_t * PBYTE
Definition: intro_types.h:47
QWORD
unsigned long long QWORD
Definition: intro_types.h:53
IntGetCurrentIntroOptions
INTSTATUS IntGetCurrentIntroOptions(void *GuestHandle, QWORD *IntroOptions)
Get the currently used introcore options.
Definition: introapi.c:1077
IntFlushAlertExceptions
INTSTATUS IntFlushAlertExceptions(void *GuestHandle)
Removes all the custom exceptions added with GLUE_IFACE.AddExceptionFromAlert.See PFUNC_IntFlushAlert...
Definition: introapi.c:1499
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.
Definition: introapi.c:585
IntGetCurrentInstructionLength
INTSTATUS IntGetCurrentInstructionLength(void *GuestHandle, DWORD CpuNumber, BYTE *Length)
Returns the length of the instruction at which the current guest RIP points.
Definition: introapi.c:729
IntGetCurrentInstructionMnemonic
INTSTATUS IntGetCurrentInstructionMnemonic(void *GuestHandle, DWORD CpuNumber, CHAR *Mnemonic)
Returns the mnemonic of the instruction at which the current guest RIP points.
Definition: introapi.c:806
WCHAR
uint16_t WCHAR
Definition: intro_types.h:63
DWORD
uint32_t DWORD
Definition: intro_types.h:49
_In_reads_bytes_
#define _In_reads_bytes_(expr)
Definition: intro_sal.h:25
IntInjectFileAgentInGuest
INTSTATUS IntInjectFileAgentInGuest(void *GuestHandle, PBYTE AgentContent, DWORD AgentSize, const CHAR *Name)
Drops a file on the guest hard disk.
Definition: introapi.c:658
IntModifyDynamicOptions
INTSTATUS IntModifyDynamicOptions(void *GuestHandle, QWORD NewOptions)
Modifies the introcore options.
Definition: introapi.c:980
IntAbortEnableIntro
INTSTATUS IntAbortEnableIntro(void *GuestHandle, BOOLEAN Abort)
Abort the introcore loading process.
Definition: introapi.c:1545
IntAddRemoveProtectedProcessUtf16
INTSTATUS IntAddRemoveProtectedProcessUtf16(void *GuestHandle, const WCHAR *FullPath, DWORD ProtectionMask, BOOLEAN Add, QWORD Context)
Toggles protection options for a process.
Definition: introapi.c:435
_In_z_
#define _In_z_
Definition: intro_sal.h:17
IG_LOG_LEVEL
enum _IG_LOG_LEVEL IG_LOG_LEVEL
Controls the verbosity of the logs.
_GUEST_INFO
Guest information.
Definition: intro_types.h:2377
IntNewGuestNotification
INTSTATUS IntNewGuestNotification(void *GuestHandle, QWORD Options, PBYTE UpdateBuffer, DWORD BufferLength)
Handles a new guest. It is essentially the Introcore entry point.
Definition: introapi.c:81
INTRO_EVENT_TYPE
enum _INTRO_EVENT_TYPE INTRO_EVENT_TYPE
Event classes.
CHAR
char CHAR
Definition: intro_types.h:56
IntFlushGpaCache
INTSTATUS IntFlushGpaCache(void *GuestHandle)
Flushed the introcore GPA cache.
Definition: introapi.c:1026
IntGetVersionString
INTSTATUS IntGetVersionString(DWORD FullStringSize, DWORD VersionStringSize, CHAR *FullString, CHAR *VersionString)
Get the version string information for the current guest.
Definition: introapi.c:1599