lixagent.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Bitdefender
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef _LIX_AGENT_H_
#define _LIX_AGENT_H_

#include "aghcall.h"
#include "agent.h"

#define LIX_AGENT_MAX_FUNCTIONS         256

#define LIX_AGENT_MAX_NAME_LENGTH       128
#define LIX_AGENT_MAX_ARGS_LENGTH       1024


typedef struct _LIX_TASK_OBJECT LIX_TASK_OBJECT;


typedef INTSTATUS
(*PFUNC_AgentCallbackHypercall)(
    _In_opt_ void *Context
    );



typedef INTSTATUS
(*PFUNC_AgentCallbackCompletion)(
    _In_opt_ void *Context
    );

typedef enum _LIX_AGENT_HYPERCALL
{
    lixAgentHypercallNone = 0,  
    lixAgentHypercallVmcall,    
    lixAgentHypercallInt3       
} LIX_AGENT_HYPERCALL;


typedef enum _LIX_AGENT_TAG
{
    // NOTE: Never change this to anything other than 0
    lixAgTagNone = 0,

    // Tags used for agents without threads
    lixAgTagInit,                       
    lixAgTagUninit,                     
    lixAgTagCreateThread,               

    // Tags used for agents with threads
    lixAgThreadTagDeployFile,           
    lixAgThreadTagDeployFileExec,       
    lixAgThreadTagRunCommand            

} LIX_AGENT_TAG;


#pragma pack(push)
#pragma pack(1)
typedef struct _LIX_AGENT_HEADER
{
    DWORD   Tag;                
    WORD    DataSize;           
    WORD    ExitOffset;         
    WORD    CodeSize;           
    QWORD   Address;            
} LIX_AGENT_HEADER, *PLIX_AGENT_HEADER;
#pragma pack(pop)


typedef struct _LIX_AGENT_TOKEN
{
    QWORD Hypercall;            
    QWORD Completion;           
    QWORD Error;                
} LIX_AGENT_TOKEN;


typedef struct _LIX_AGENT_DATA
{
    LIX_AGENT_HEADER    Header;     
    LIX_AGENT_TOKEN     Token;      

    BYTE                *Code;      
    QWORD               Address;    
    DWORD               Size;       

} LIX_AGENT_DATA, *PLIX_AGENT_DATA;


typedef struct _LIX_AGENT_THREAD
{
    LIX_AGENT_TAG           Tag;                    
    LIX_AGENT_HYPERCALL     HypercallType;          

    LIX_AGENT_DATA          Data;                   

    struct
    {
        PFUNC_AgentCallbackHypercall    Hypercall;  
        PFUNC_AgentCallbackCompletion   Completion; 
    } Callback;

    struct
    {
        BYTE    *Address;                           
        DWORD   Size;                               

        DWORD   CurrentOffset;
    } Content;

    void        *Context;                           

} LIX_AGENT_THREAD, *PLIX_AGENT_THREAD;


typedef struct _LIX_AGENT
{
    LIST_ENTRY          Link;                           

    LIX_AGENT_TAG       Tag;                            
    DWORD               TagEx;                          

    DWORD               Agid;                           

    LIX_AGENT_HYPERCALL HypercallType;                  
    LIX_AGENT_DATA      Data;                           
    LIX_AGENT_THREAD    *Thread;                        

    CHAR                Name[IG_MAX_AGENT_NAME_LENGTH]; 

    struct
    {
        PFUNC_AgentCallbackHypercall    Hypercall;      
        PFUNC_AgentCallbackCompletion   Completion;     
    } Callback;

    struct
    {
        QWORD   Address;                                

        BYTE    Bytes[16];                              
        BYTE    Length;                                 

        void    *CloakHandle;                           

        BOOLEAN Restored;                               
    } Instruction;

} LIX_AGENT, *PLIX_AGENT;


typedef struct _LIX_AGENT_FUNCTIONS_LIST
{
    DWORD   Required;           
    DWORD   Count;              
    char    *Name[256];         
} LIX_AGENT_FUNCTIONS_LIST, *PLIX_AGENT_FUNCTIONS_LIST;


typedef struct _LIX_AGENT_FUNCTINS
{
    struct
    {
        WORD                    Sublevel;
        BYTE                    Patch;
        BYTE                    Version;
        WORD                    Backport;
    } Version;                                  

    DWORD                       Count;          
    LIX_AGENT_FUNCTIONS_LIST    List[20];       

} LIX_AGENT_FUNCTIONS, *PLIX_AGENT_FUNCTIONS;

typedef struct _LIX_AGENT_HANDLER
{
    enum _LIX_AGENT_TAG       Tag;              
    enum _LIX_AGENT_HYPERCALL HypercallType;    

    struct
    {
        WORD    Length;                         
        void    *Content;                       
    } Args;

    struct
    {
        WORD    Length;                         
        void    *Content;                       
    } Code;

    struct
    {
        DWORD                Count;             
        LIX_AGENT_FUNCTIONS *Content;           
    } Functions;

    struct
    {
        DWORD                        Count;     
        struct _LIX_AGENT_HANDLER   *Content;   
    } Threads;

} LIX_AGENT_HANDLER, *PLIX_AGENT_HANDLER;


#pragma pack(push)
#pragma pack(1)

typedef struct _LIX_AGENT_INIT_ARGS
{
    struct
    {
        QWORD ModuleLength;         
        QWORD PerCpuLength;         
    } Allocate;
} LIX_AGENT_INIT_ARGS, *PLIX_AGENT_INIT_ARGS;


typedef struct _LIX_AGENT_UNINIT_ARGS
{
    struct
    {
        QWORD ModuleAddress;        
        QWORD PerCpuAddress;        
    } Free;

    struct
    {
        QWORD MaskClear;            
        QWORD MaskSet;              
    } Attr;
} LIX_AGENT_UNINIT_ARGS, *PLIX_AGENT_UNINIT_ARGS;


typedef struct _LIX_AGENT_CREATE_THREAD_ARGS
{
    struct
    {
        QWORD Length;               
    } Allocate;
} LIX_AGENT_CREATE_THREAD_ARGS, *PLIX_AGENT_CREATE_THREAD_ARGS;


typedef struct _LIX_AGENT_THREAD_DEPLOY_FILE_ARGS
{
    QWORD KernelVersion;                        

    struct
    {
        QWORD   Length;
    } Allocate;

    struct
    {
        char    Root;                               
        char    Name[LIX_AGENT_MAX_NAME_LENGTH];    
    } FilePath;

    struct
    {
        QWORD   UhmWaitProc;                    
        QWORD   UhmWaitExec;                    
    } Umh;

} LIX_AGENT_THREAD_DEPLOY_FILE_ARGS, *PLIX_AGENT_THREAD_DEPLOY_FILE_ARGS;


typedef struct _LIX_AGENT_THREAD_DEPLOY_FILE_EXEC_ARGS
{
    QWORD       KernelVersion;                      
    QWORD       FilePathOffset;                     

    struct
    {
        QWORD   Length;
    } Allocate;

    struct
    {
        char    Root;                               
        char    Name[LIX_AGENT_MAX_NAME_LENGTH];    
    } FilePath;


    struct
    {
        char    Args[LIX_AGENT_MAX_ARGS_LENGTH];    
    } Exec;

    struct
    {
        QWORD   UhmWaitProc;                        
        QWORD   UhmWaitExec;                        
    } Umh;

} LIX_AGENT_THREAD_DEPLOY_FILE_EXEC_ARGS, *PLIX_AGENT_THREAD_DEPLOY_FILE_EXEC_ARGS;


typedef struct _LIX_AGENT_THREAD_RUN_CLI_ARGS
{
    struct
    {
        char    Args[LIX_AGENT_MAX_ARGS_LENGTH];    
    } Exec;

    struct
    {
        QWORD   UhmWaitProc;                        
        QWORD   UhmWaitExec;                        
    } Umh;

} LIX_AGENT_THREAD_RUN_CLI_ARGS, *PLIX_AGENT_THREAD_RUN_CLI_ARGS;
#pragma pack(pop)


INTSTATUS
IntLixAgentInject(
    _In_ LIX_AGENT_TAG Tag,
    _In_opt_ PFUNC_AgentCallbackHypercall HypercallCallback,
    _In_opt_ PFUNC_AgentCallbackCompletion CompletionCallback
    );

INTSTATUS
IntLixAgentThreadInject(
    _In_ LIX_AGENT_TAG Tag,
    _In_ DWORD TagEx,
    _In_ AGENT_TYPE AgentType,
    _In_opt_ PFUNC_AgentCallbackHypercall HypercallCallback,
    _In_opt_ PFUNC_AgentCallbackCompletion CompletionCallback,
    _In_opt_ const char *Name,
    _In_opt_ BYTE *ContentAddress,
    _In_ DWORD ContentSize
    );

INTSTATUS
IntLixAgentActivatePendingAgent(
    void
    );

void
IntLixAgentEnableInjection(
    void
    );

_Success_(return != agNone)
AG_WAITSTATE
IntLixAgentGetState(
    _Out_opt_ DWORD *Tag
    );

void
IntLixAgentDisablePendingAgents(
    void
    );

void
IntLixAgentNameRemoveByAgid(
    _In_ DWORD Agid
    );

DWORD
IntLixAgentNameGetTagByAgid(
    _In_ DWORD Agid
    );

LIX_AGENT_TAG
IntLixAgentIncProcRef(
    _In_ const char *Name
    );

LIX_AGENT_TAG
IntLixAgentDecProcRef(
    _In_ const char *Name,
    _Out_ BOOLEAN *Removed
    );

INTSTATUS
IntLixAgentHandleInt3(
    _In_ QWORD Rip
    );

INTSTATUS
IntLixAgentHandleVmcall(
    _In_ QWORD Rip
    );

void
IntLixAgentInit(
    void
    );

INTSTATUS
IntLixAgentUninit(
    void
    );

LIX_AGENT_HANDLER *
IntLixAgentGetHandlerByTag(
    _In_ LIX_AGENT_TAG AgentTag
    );

LIX_AGENT_HANDLER *
IntLixAgentThreadGetHandlerByTag(
    _In_ LIX_AGENT_TAG AgentTag,
    _In_ LIX_AGENT_TAG ThreadTag
    );

void
IntLixAgentSendEvent(
    _In_ AGENT_EVENT_TYPE Event,
    _In_ DWORD AgentTag,
    _In_ DWORD ErrorCode
    );

#endif // !_LIX_AGENT_H_