接口说明

头文件说明

• iMonitor.h 驱动、应用层共用的定义
• iMonitorSDK.h SDK接口定义
• iMonitorProtocol.h SDK事件协议辅助类
• iMonitorSDKExtesnion.h 基于SDK在应用层实现的扩展功能

注意：如果接口变化，以最新版本的SDK头文件为准

接口说明

IMonitorManager

SDK的使用接口

interface IMonitorManager : public IUnknown
{
    virtual HRESULT            Start                (IMonitorCallbackInternal* Callback) = 0;
    virtual HRESULT            Start                (IMonitorCallback* Callback) = 0;
    virtual HRESULT            Control              (PVOID Data, ULONG Length, PVOID OutData, ULONG OutLength, PULONG ReturnLength) = 0;
    virtual HRESULT            Stop                 (void) = 0;
    virtual HRESULT            UnloadDriver         (void) = 0
    
    virtual HRESULT            CreateRuleEngine     (LPCWSTR Path, IMonitorRuleEngine** Engine) = 0;
    virtual HRESULT            CreateAgentEngine    (ULONG MaxThread, IMonitorAgentEngine** Engine) = 0;
};

函数	说明
Start	设置驱动回调、安装并启动驱动
Control	跟驱动通讯的入口，详细参考cxMSGUserXxxx结构体
CreateRuleEngine	应用层扩展功能： 加载规则引擎，详细参考规则引擎部分
CreateAgentEngine	应用层扩展功能：创建网络中间人服务器，详细参考网络代理部分
UnloadDriver	停止并卸载驱动

支持的Control参数类型

类型	说明
cxMSGUserSetGlobalConfig	设置全局配置
cxMSGUserGetGlobalConfig	获取全局配置
cxMSGUserSetSessionConfig	设置当前会话配置
cxMSGUserGetSessionConfig	获取当前配置会话
cxMSGUserSetMSGConfig	设置监控消息配置，开启监控都通过这个命令字设置
cxMSGUserGetMSGConfig	获取监控消息配置
cxMSGUserEnableProtect	开启自保护
cxMSGUserDisableProtect	关闭自保护
cxMSGUserAddProtectRule	添加保护规则
cxMSGUserRemoveProtectRule	删除保护规则
cxMSGUserRemoveAllProtectRule	清空保护规则

IMonitorCallback

事件回调接口，监控到的事件都通过OnCallback通知到应用层，在回调里面可以通过IMonitorMessage获取事件的详细信息，也可以设置需要响应的结果。

interface IMonitorCallback
{
	//
	//	DisableXxxMonitor: (在驱动启动前设置生效) 表示是否关闭Xxx的监控，如果只需要部分能力，建议关闭其他不需要的监控。一般用于优化性能，解决冲突。
	//	InternalCallback: 内部使用，接管原始的消息
	//	ExtensionFieldTable: 消息扩展字段
	//
	struct GlobalConfig {
			bool			DisableFileMonitor	= false;
			bool			DisableRegMonitor	= false;
			bool			DisableSocketMonitor= false;
			bool			DisableWFPMonitor	= false;
			bool			DisableNPMSMonitor	= false;
			bool			DisableUserMonitor	= true;
			bool			InternalCallback	= false;

			MonitorExtensionFieldTable ExtensionFieldTable;
	};

	virtual void			OnConfig			(GlobalConfig& Config) {}
	virtual void			OnCustomEvent		(ULONG Type, PVOID Context) {}
	virtual bool			OnInternalCallback	(cxMSGHeader* Header, HANDLE FilterHandle, ULONGLONG MessageId) { return false; }
	virtual void			OnCallback			(IMonitorMessage* Message) = 0;
};

一般只需要关注OnCallback回调，监控到的消息都通过这个回调通知。

如果需要禁用某些功能，或者扩展自定义的字段，则可以通过OnConfig回调修改GlobalConfig后返回。

OnCustomEvent 是自定义事件，如果插入事件到驱动分发线程，用于不想加锁解决某些同步问题。

OnInternalCallback 是原始接口事件，完全接管驱动下发的消息，然后自己解析和处理返回结果。

IMonitorMessage

驱动事件消息，包括公共字段（当前进程信息等）、私有字段（具体参考附录的协议字段）

interface IMonitorMessage
{
	struct Binary {
		PVOID Data;
		ULONG Length;
	};

	//
	// 基础字段
	//

	virtual cxMSGHeader*	GetHeader			(void) = 0;
	inline ULONG			GetType				(void) { return GetHeader()->Type; }
	inline ULONG			GetStatus			(void) { return GetHeader()->Status; }
	inline ULONG			GetCurrentProcessId	(void) { return GetHeader()->CurrentProcessId; }
	inline ULONG			GetCurrentThreadId	(void) { return GetHeader()->CurrentThreadId; }

	virtual IMonitorMessageProcess* GetProcess	(void) = 0;
	virtual IMonitorMessageProcess* GetRpcCallerProcess(void) = 0; // 如果存在Rpc远程调用则返回调用者进程，否则返回GetProcess

	virtual LPCWSTR			GetTypeName			(void) = 0;
	virtual ULONG			GetFieldCount		(void) = 0;
	virtual emMSGDataType	GetFieldType		(ULONG Index) = 0;
	virtual LPCWSTR			GetFieldName		(ULONG Index) = 0;
	virtual ULONG			GetFieldIndex		(LPCWSTR Name) = 0;

	virtual ULONG			GetULONG			(ULONG Index) = 0;
	virtual ULONGLONG		GetULONGLONG		(ULONG Index) = 0;
	virtual cxMSGDataIPRef	GetIP				(ULONG Index) = 0;
	virtual Binary			GetBinary			(ULONG Index) = 0;
	virtual LPCWSTR			GetString			(ULONG Index) = 0;
	virtual LPCWSTR			GetFormatedString	(ULONG Index) = 0;

	virtual bool			IsMatch				(ULONG Index, LPCWSTR Pattern, bool IgnoreCase = true) = 0;

	//
	// 扩展字段，由开发者自行定义的字段，这些字段可以用于规则引擎，详细参考MonitorExtensionFieldTable
	//	HasValue: 表示是否有值，如果没有字段则返回默认值并且HasValue = false
	//

	virtual ULONGLONG		GetNumber			(LPCWSTR Name, bool* HasValue = nullptr) = 0;
	virtual LPCWSTR			GetString			(LPCWSTR Name, bool* HasValue = nullptr) = 0;

	//
	// Action 相关操作，用于返回消息结果给驱动：需要Waiting状态才能设置返回结果
	//

	virtual bool			IsWaiting			(void) = 0;
	virtual bool			SetAction			(const cxMSGAction& Action) = 0;
	virtual bool			SetBlock			(void) = 0;
	virtual bool			SetGrantedAccess	(ULONG Access) = 0;
	virtual bool			SetIPRedirect		(ULONG IP, USHORT Port, ULONG ProcessId = ::GetCurrentProcessId()) = 0;
	virtual bool			SetTerminateProcess	(void) = 0;
	virtual bool			SetTerminateThread	(void) = 0;
	virtual bool			SetInjectDll		(LPCWSTR Path, bool AlertThread, bool NewThread = false) = 0;
	virtual bool			SetFileRedirect		(LPCWSTR Path) = 0;
	virtual bool			InjectPacket		(PCHAR Data, ULONG Length, bool Inbound) = 0;

	//
	//	异步处理：
	//		设置Pending成功后，可以拥有IMonitorMessage的生命周期，允许在回调返回后继续使用。
	//		使用完毕，一定需要使用CompletePending来恢复状态，不然内核等待事件需要超时才能返回。
	//
	//	使用场景：需要弹框交互确认、或者是多线程处理的场景。
	//

	virtual bool			Pending				(void) = 0;
	virtual void			CompletePending		(void) = 0;

	virtual void			SetCustomContext	(PVOID Context) = 0;
	virtual PVOID			GetCustomContext	(void) = 0;

	virtual bool			IsUserMonitor		(void) = 0;
};

函数	说明
GetType	消息类型，比如 emMSGProcessCreate
GetTypeName	消息类型的字符串，比如 ProcessCreate
GetFieldCount	当前消息字段的格式，每个字段可以通过GetFieldXxx、GetXxx获取属性和值
GetStatus	Post请求有效：当前操作的执行结果
GetString	要求字段必须是字符串，如果对应的字段不是字符串，则返回空字符串
GetFormatedString	同GetString，区别在于：不是字符串的内容会强制转换成字符串
IsWaiting	驱动是否阻塞事件执行，如果是可以通过SetXxx来响应事件（阻止、重定向等）
SetBlock	阻止当前的操作
SetGrantedAccess	对于打开进程、打开线程操作，可以设置允许的打开权限
SetTerminateProcess	结束当前进程
SetTerminateThread	结束当前线程
SetInjectDll	对当前进程注入动态库（自己判断是32位的还是64位进程）
SetIPRedirect	对于Tcp连接，可以设置IP、Port重定向到新的地址
IsMatch	内置通配符字符串匹配，支持 * ？ > （> 表示目录，dir> 等同于 dir + dir\\*） IgnoreCase表示是否忽略大小写，默认忽略

IMonitorMessageProcess

消息对应的进程信息

interface IMonitorMessageProcess
{
	enum emProcessType {
		emProcessUnknown,
		emProcessServices,
		emProcessCsrss,
		emProcessSvchost,
		emProcessExplorer,
	};

	virtual ULONG			GetProcessId		(void) = 0;
	virtual ULONG			GetParentProcessId	(void) = 0;
	virtual	ULONG			GetCreatorProcessId	(void) = 0;
	virtual LPCWSTR			GetProcessName		(void) = 0;
	virtual LPCWSTR			GetProcessPath		(void) = 0;
	virtual LPCWSTR			GetCommandline		(void) = 0;
	virtual LPCWSTR			GetCompanyName		(void) = 0;
	virtual LPCWSTR			GetProductName		(void) = 0;
	virtual LPCWSTR			GetFileDescription	(void) = 0;
	virtual LPCWSTR			GetEmbeddedSigner	(void) = 0;
	virtual bool			IsEmbeddedSignerVerified(void) = 0;
	virtual LPCWSTR			GetCatalogSigner	(void) = 0;
	virtual bool			IsCatalogSignerVerified(void) = 0;
	virtual ULONGLONG		GetCreateTime		(void) = 0;
	virtual emProcessType	GetProcessType		(void) = 0;
	virtual bool			GetMD5				(UCHAR Hash[16]) = 0;
	virtual LPCWSTR			GetMD5String		(void) = 0;
	virtual bool			Is64Bit				(void) = 0;
	virtual bool			IsWOW64Process		(void) = 0;
};

IMonitorSDKExtesnion

在应用层实现的能力扩展，详细参考规则引擎、网络代理。