Interface IDEmulatorHooks

All Superinterfaces:
IPriorityBasedHooks

public interface IDEmulatorHooks extends IPriorityBasedHooks
An interface for user-defined hooks called by dexdec's IR emulator when executing internal (in DEX) code.

Tutorial on how to use emulator hooks: in the JEB coreplugins/scripts/ folder, refer to DOptEmuHooksExample.py.DISABLED for an example in Python, DOptEmuHooksGlobalExample.java.DISABLED for an example in Java (remove the .DISABLED extension to enable the plugin).

See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    default Wrapper<IDImm>
    examineMethodResult(long reqid, IDImm result)
    This method is called after the emulator successfully executed the IR of an internal dex method.
    default Wrapper<IDImm>
    invokeMethod(long reqid, String msig, List<IDImm> args)
    This method is called when the emulator is about to execute the IR of an internal dex method.
    default Boolean
    setField(long reqid, String fsig, IDImm obj, IDImm[] avalue)
    This method is called when the emulator is about to set an internal field's value.

    Methods inherited from interface com.pnfsoftware.jeb.core.units.IPriorityBasedHooks

    getPriority
  • Method Details

    • setField

      default Boolean setField(long reqid, String fsig, IDImm obj, IDImm[] avalue)
      This method is called when the emulator is about to set an internal field's value.
      Parameters:
      reqid - internal request id
      fsig - field signature
      obj - field object, null if static
      avalue - a one-element array containing the value to be set (this is an input/output array; if this method returns false, the value located in the array will be used by the sandbox to set the field)
      Returns:
      null to indicate that nothing was done and execution should proceed as normal; false to indicate that the hook provided a field value to be set by the emulator itself (no other hook will run, the emulator will set the field located in the `avalue` array); true to indicate that the hook has completed the operation (no other hook will run, the emulator will not set the field)
    • invokeMethod

      default Wrapper<IDImm> invokeMethod(long reqid, String msig, List<IDImm> args)
      This method is called when the emulator is about to execute the IR of an internal dex method.
      Parameters:
      reqid - internal request id
      msig - target method to be executed
      args - the evaluated arguments (careful, the first entry is the object's `this` iff the target method is not static)
      Returns:
      if non-null, the result will be used as the invocation return; if null, proceed (other hooks will be executed)
    • examineMethodResult

      default Wrapper<IDImm> examineMethodResult(long reqid, IDImm result)
      This method is called after the emulator successfully executed the IR of an internal dex method.
      Parameters:
      reqid - internal request id (matching the id provided to a previous call to invokeMethod)
      result - the execution result, which may be modified
      Returns:
      the hook may provide an object (wrapped in a Wrapper object; the object itself may be null); returning null means proceed as normal (other hooks will be tried, and eventually, the emulator execution will resume and provide the original returned value)