Dexcalibur Agent¶

Dexcalibur-agent is a framework, and a Frida library, required by hook scripts generated by the Reversense platform.

Its purpose is to provide scheduling mechanisms, key point system, various tracing features and helpers.

This library injects itself into the hook context a global variable named DXC, then your hooks as well as processing inside the hook context can use it.

Note

When could I use it ?

Mainly to create a hook fragment manually, or when you edit the hooking strategy of am Inspector

Communication with the Reversense platform, and error handling for various scenarios are done through the DXC.send*() method.

1. Key Points¶

Key Points are used to schedule the load/unload of hook at runtimes, and trigger server-side or device-side events on specific conditions.

1.A Register a builtin key point¶

Built-in key points offer way to capture particular events such as the loading of a library by the linker, somme system call over a specific file or address, and so on.

When you register a key point, the hook script start to trace a specific behavior and stream events when a specific condition is fulfilled.

Example:

DXC.kp.DlOpen("libName")

1.B Attach hook load/unload to a key point¶

DXC.kp.register("dlopen","libName",()=>{
    /*@@__CONTENT__@@*/
});

2. Communication with the Reversense platform¶

To send a message to the Reversense platform from a hook fragment, use the DXC.send() method like in the example below:

DXC.send(
    "@@__HOOK_ID__@@",
    "@@__FRAG_ID__@@",
    {
        msg: msg
    }
);

The tokens @@__HOOK_ID__@@ and @@__FRAG_ID__@@ are automatically replaced by the hook id and fragment id of the hook (to identify the function) and fragment (to identify the purpose) when the Reversense platform starts the application.

3. Error handling¶

The library offer two builtin methods to warn the remote platform something went wrong without stopping the target application.

3.A Hook definition error¶

The method DXC.sendDefinitionError( pErrCode:number, pHookId:string, pMsg:any) is used to warn the remote platform that a hook cannot be attached to a target function or location because the address to hook is not valid. The root cause is typically a missing library or a wrong memory address (e.g. a null pointer, not mapped, etc ...).

While this method is often generated by Reversense, you can call it manually if you want to warn the remote platform about a hooking error.

DXC.sendDefinitionError( 1, "HOOK ID", "Function not found")

If you, or the AI, expect to use it in a hook template, as a fragment, where the HOOK IDis not known, then replace it by the @@__HOOK_ID__@@ token.

The usual pattern for a fragment template is :

var cls_@@__CLSDEF__@@ = null;
var meth_@@__METHDEF__@@ = null;

try{
    cls_@@__CLSDEF__@@ = Java.use('@@__FQCN__@@');
    meth_@@__METHDEF__@@ = cls_@@__CLSDEF__@@["@@__METHNAME__@@"].overload(@@__ARGS__@@);
    meth_@@__METHDEF__@@.implementation = function(@@__HOOK_ARGS__@@) {
      //..  
    };
}catch(e){
    DXC.sendDefinitionError(1, "@@__HOOK_ID__@@", e );
}

3.A Hook runtime error¶

DXC.sendDefinitionError( pErrCode:number, pHookId:string, pMsg:any)
DXC.sendError()