#ifndef VM_SDK_API_H_ #define VM_SDK_API_H_ #include #include #include #ifdef _WIN32 #include #ifdef VM_SDK_API_EXPORT #define VM_SDK_API __declspec(dllexport) #else #define VM_SDK_API __declspec(dllimport) #endif // VM_SDK_API_EXPORT #define VM_SDK_CALL_TYPE __stdcall #elif defined(__linux__) #include #if defined(VM_SDK_BUILD) || defined(VM_SDK_API_EXPORT) #define VM_SDK_API __attribute__((visibility("default"))) #else #define VM_SDK_API #endif #define VM_SDK_CALL_TYPE #elif defined(__APPLE__) #include #define VM_SDK_API __attribute__((visibility("default"))) #define VM_SDK_CALL_TYPE #else #error "Unsupported platform: not Windows, Linux, or macOS" #endif #ifdef __cplusplus extern "C" { #endif #pragma pack(push) #pragma pack(1) typedef enum AhaVMSupportStatus { AhaVMSupportStatusSupported = 0, AhaVMSupportStatusOSFailed, AhaVMSupportStatusFileMissX64Ipc, AhaVMSupportStatusFileMissX64Biz, AhaVMSupportStatusFileMissX86Ipc, AhaVMSupportStatusFileMissX86Biz, AhaVMSupportStatusSignatureFailed, AhaVMSupportStatusFileVersionMismatch, AhaVMSupportStatusWineNotSupported, AhaVMSupportStatusArchUnsupported, AhaVMSupportStatusFileMissX64Helper, AhaVMSupportStatusFileMissX86Helper, } AhaVMSupportStatus; typedef enum AhaVMAuditAction { AhaVMAuditAction_Nil = 0, AhaVMAuditAction_Create, AhaVMAuditAction_Delete, AhaVMAuditAction_Rename, AhaVMAuditAction_CopyOnWrite, AhaVMAuditAction_DeleteToRecycle, AhaVMAuditAction_Connect, AhaVMAuditAction_Send, AhaVMAuditAction_Recv, } AhaVMAuditAction; typedef enum AhaVMAuditPermission { AhaVMAuditPermission_Normal, AhaVMAuditPermission_Black, AhaVMAuditPermission_White, } AhaVMAuditPermission; typedef enum AhaVMProcessState { AhaVMProcessState_Created = 0, AhaVMProcessState_LaunchFailed, AhaVMProcessState_Launched, AhaVMProcessState_Crashed, AhaVMProcessState_Exited, AhaVMProcessState_CreateFailed, AhaVMProcessState_InjectFailed, AhaVMProcessState_Dump } AhaVMProcessState; typedef enum AhaVMInfoType { AhaVMInfoType_Files = 0, } AhaVMInfoType; typedef enum AhaVMActionType { AhaVMActionType_MergeFiles = 0, AhaVMActionType_DiscardFiles = 1, AhaVMActionType_UpdateConfig = 2, AhaVMActionType_FlushStatistics = 3, AhaVMActionType_CollectDump = 4, } AhaVMActionType; typedef enum AhaVMActionEventType { AhaVMActionEventType_Progress = 0, } AhaVMActionEventType; typedef struct AhaVMActionProgressData { const char* lpSandboxPath; const char* lpHostPath; uint64_t ullBytesCopied; uint64_t ullTotalBytes; } AhaVMActionProgressData; typedef struct AhaVMActionEvent { AhaVMActionEventType type; union { AhaVMActionProgressData progress; } data; } AhaVMActionEvent; typedef enum AhaVMAuditNetPermission { AhaVMAuditNetPermission_Unknown = -1, AhaVMAuditNetPermission_Deny = 0, AhaVMAuditNetPermission_Allow = 1, } AhaVMAuditNetPermission; /** * Trace callback function type * @param pContext The context pointer passed in * AhaVMInitParams * @param lpTraceMessage The trace message, JSON format string, utf8 encoded */ typedef void(VM_SDK_CALL_TYPE* VMSDK_TraceCallback)(const void* pContext, const char* lpTraceMessage); /** * Crash callback function type * @param pContext The context pointer passed in AhaVMInitParams * @param dwExceptionCode exception code */ typedef void(VM_SDK_CALL_TYPE* VMSDK_CrashCallback)(const void* pContext, uint32_t dwExceptionCode); /** * VMed Process callback function type * @param pContext The context pointer passed in AhaVMInitParams * @param emState AhaVMProcessState * @param dwProcessId Process ID * @param dwErrorCode Process error code * @param lpVMId VM ID, utf8 encoded */ typedef void(VM_SDK_CALL_TYPE* VMSDK_ProcessCallback)(const void* pContext, AhaVMProcessState emState, uint32_t dwProcessId, uint32_t dwErrorCode, const char* lpVMId); /** * Action callback function type * @param pContext The context pointer passed in VMSDK_Action * Function * @param type AhaVMActionType (e.g. AhaVMActionType_MergeFiles) * @param pEvent * Details about the current action event (Progress) */ typedef bool(VM_SDK_CALL_TYPE* VMSDK_ActionCallback)(const void* pContext, AhaVMActionType type, const AhaVMActionEvent* pEvent); /** * File audit callback function type * @param pContext The context pointer passed in AhaVMInitParams * @param dwErrorCode The error code of the file operation, win32 error code * @param dwProcessId The process ID that performed the file operation * @param llTimestamp The timestamp of the file operation * @param emAction The action type of the file operation * @param emSrcPermission The source file permission before the operation * @param emDstPermission The destination file permission after the operation * @param lpSrcFilePath The source file path involved in the file operation, utf8 encoded * @param lpDstFilePath The destination file path involved in the file operation, utf8 encoded */ typedef void(VM_SDK_CALL_TYPE* VMSDK_FileAuditCallback)(const void* pContext, uint32_t dwErrorCode, uint32_t dwProcessId, uint64_t llTimestamp, AhaVMAuditAction emAction, AhaVMAuditPermission emSrcPermission, AhaVMAuditPermission emDstPermission, const char* lpSrcFilePath, const char* lpDstFilePath); /** * Net audit callback function type * @param pContext The context pointer passed in AhaVMInitParams * @param dwErrorCode The error code of the file operation, win32 error code * @param dwProcessId The process ID that performed the file operation * @param llTimestamp The timestamp of the file operation * @param emAction The action type of the file operation * @param emNetPermission The net permission before the operation * @param dwProtocol The socket of protocol * @param dwSrcPort The socket of source port * @param dwDstPort The socket of destination port * @param lpSrcIPAddr The socket of source ip address * @param lpDstIPAddr The socket of destination ip address * @param lpDomainName The destination ip address from lpDomainName */ typedef void(VM_SDK_CALL_TYPE* VMSDK_NetAuditCallback)(const void* pContext, uint32_t dwErrorCode, uint32_t dwProcessId, uint64_t llTimestamp, AhaVMAuditAction emAction, AhaVMAuditNetPermission emNetPermission, uint32_t dwProtocol, uint32_t dwSrcPort, uint32_t dwDstPort, const char* lpSrcIPAddr, const char* lpDstIPAddr, const char* lpDomainName); typedef struct AhaVMInitParams { /** * VMSDK & VMCore log directory, utf8 encoded */ const char* lpVMLogDir = NULL; /** * VM dump directory, utf8 encoded */ const char* lpVMDumpDir = NULL; /** * VM Core binary files directory, the parent directory of x64/x86 binaries, utf8 encoded */ const char* lpVMBinDir = NULL; /** * VM running cache files directory, utf8 encoded */ const char* lpVMCacheDir = NULL; /** * The path to the configuration folder for the VM's built-in tools., Json utf8 encoded * { * "tools_dir": [ * "X:\\tools\\ffmpeg", * "X:\\tools\\xzip"] * } */ const char* lpVMToolsJsonConfig = NULL; /** * Trace callback function pointer */ VMSDK_TraceCallback pTraceCallback = NULL; /** * Trace callback context pointer */ const void* pTraceContext = NULL; /** * Crash callback function pointer */ VMSDK_CrashCallback pCrashCallback = NULL; /** * Crash callback context pointer */ const void* pCrashContext = NULL; /** * Process callback function pointer */ VMSDK_ProcessCallback pProcessCallback = NULL; /** * Process callback context pointer */ const void* pProcessContext = NULL; /** * File audit callback function pointer */ VMSDK_FileAuditCallback pFileAuditCallback = NULL; /** * File audit callback context pointer */ const void* pFileAuditContext = NULL; /** * Net audit callback function pointer */ VMSDK_NetAuditCallback pNetAuditCallback = NULL; /** * Net audit callback context pointer */ const void* pNetAuditContext = NULL; /** * SDK initialization configuration, JSON format string, utf8 encoded. * Supported fields: * product_name: Product name, such as Feishu/Trae. * log_encrypt: Default is 0 (output full paths), non-zero encrypts all output paths. */ const char* lpConfig = NULL; } AhaVMInitParams; typedef struct AhaVMStartParams { /** * VM ID, utf8 encoded */ const char* lpVMId = NULL; /** * VM configuration content, JSON format string, utf8 encoded */ const char* lpConfig = NULL; #if defined(__linux__) || defined(__APPLE__) /** * Executable file path, utf8 encoded. */ const char* lpExecutablePath = NULL; /** * Child process working directory, utf8 encoded */ const char* lpCurrentDirectory = NULL; /** * execve argv array. lpArgv[0] is the child process argv0 and may differ from lpExecutablePath. * If lpArgv is NULL, lpExecutablePath is used as argv0. */ const char* const* lpArgv = NULL; /** * Number of items in lpArgv. */ size_t nArgc = 0; /** * Explicit child process environment entries in KEY=VALUE form. */ const char* const* lpEnvp = NULL; /** * Number of items in lpEnvp. */ size_t nEnvCount = 0; /** * Whether the child process should inherit the parent process environment. */ bool bInheritParentEnv = true; /** * Optional output process ID. Set to the VM root pid on success, 0 on failure. */ pid_t* lpProcessId = NULL; #endif } AhaVMStartParams; #pragma pack(pop) // Check if the current system supports VM can be called before VMSDK_Init, return value is // AhaVMSupportStatus VM_SDK_API int VM_SDK_CALL_TYPE VMSDK_IsVMSupported(const char* lpUtf8VMBinDir); VM_SDK_API bool VM_SDK_CALL_TYPE VMSDK_Init(const AhaVMInitParams* pInitParams); VM_SDK_API void VM_SDK_CALL_TYPE VMSDK_UnInit(void); // Get lpVMId's VM Info JSON format string, utf8 encoded VM_SDK_API const char* VM_SDK_CALL_TYPE VMSDK_GetVMInfo(const char* lpVMId, AhaVMInfoType type); // Do the action thing by type, tell the result via callback VM_SDK_API bool VM_SDK_CALL_TYPE VMSDK_Action(const char* lpVMId, AhaVMActionType type, const char* lpJsonUtf8Data, const void* pContext, const VMSDK_ActionCallback lpCallBack); // Free VMSDK_GetVMInfo return memory VM_SDK_API void VM_SDK_CALL_TYPE VMSDK_FreeVMInfo(void* lpInfo); // Create a process in the VM environment VM_SDK_API bool VM_SDK_CALL_TYPE VMSDK_CreateProcess( #ifdef _WIN32 LPCWSTR lpApplicationName, LPWSTR lpCommandLine, LPSECURITY_ATTRIBUTES lpProcessAttributes, LPSECURITY_ATTRIBUTES lpThreadAttributes, BOOL bInheritHandles, DWORD dwCreationFlags, LPVOID lpEnvironment, LPCWSTR lpCurrentDirectory, LPSTARTUPINFOW lpStartupInfo, LPPROCESS_INFORMATION lpProcessInformation, const AhaVMStartParams* lpStartParams #elif defined(__linux__) || defined(__APPLE__) const AhaVMStartParams* lpStartParams #else #error "Unsupported platform: not Windows, Linux, or macOS" #endif ); #ifdef __cplusplus } #endif #endif // VM_SDK_API_H_