Interface IDSandboxHooks

All Superinterfaces:
IPriorityBasedHooks

public interface IDSandboxHooks extends IPriorityBasedHooks
An interface for user-defined hooks called by dexdec's IR sandbox when executing external (not in DEX) code.

Tutorial on how to use sandbox hooks: in the JEB coreplugins/scripts/ folder, refer to DOptEmuSandboxHooksExample.py.DISABLED for an example (removed the .DISABLED extension to enable the plugin).

See Also:
  • Method Details

    • loadClass

      default Class<?> loadClass(String name) throws DexDecEvalSandboxExecutionException
      This method is called when an external class is to be loaded by the sandbox. A hook implementation may attempt to load the class first. If a class is loaded, this method should return it. No other hooks nor the sandbox will then attempt to load the class.

      Important: this method is called within the context of a sandbox thread. For safety reasons, execution of the code will be restricted. In particular, most classes outside the standard JDK (java.* packages) will refused to be loaded.

      Parameters:
      name - binary name of the class
      Returns:
      a loaded class or null, indicating other hooks or the sandbox should proceed
      Throws:
      DexDecEvalSandboxExecutionException - to report an exception generated by the emulated code
    • setField

      default Boolean setField(long reqid, String addr, String fsig, Object obj, Object[] avalue) throws DexDecEvalSandboxExecutionException
      This method is called when the sandbox is about to set a field's value.
      Parameters:
      reqid - internal request id
      addr - caller location
      fsig - field signature
      obj - field object
      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 sandbox itself (no other hook will run, the sandbox 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 sandbox will not set the the field)
      Throws:
      DexDecEvalSandboxExecutionException - to report an exception generated by the emulated code
    • getField

      default Wrapper<Object> getField(long reqid, String addr, String fsig, Object obj) throws DexDecEvalSandboxExecutionException
      This method is called when the sandbox is about to get a field's value.
      Parameters:
      reqid - internal request id (if this method returned null, the same value will be provided to the subsequent call to examineFieldValue)
      addr - caller location
      fsig - field signature
      obj - field object (not the value!)
      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 sandbox may attempt to read the field itself)
      Throws:
      DexDecEvalSandboxExecutionException - to report an exception generated by the emulated code
    • examineFieldValue

      default Wrapper<Object> examineFieldValue(long reqid, Object value)
      This method is called after the sandbox has read a field value. It provides the field value and offers a chance for the hook to modify or replace it.
      Parameters:
      reqid - internal request id, matching a previous call to getField
      value - the field value that was read
      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 sandbox will resume and provide the value previously retrieved)
    • invokeMethod

      default Wrapper<Object> invokeMethod(long reqid, String addr, String msig, Object obj, List<Object> args) throws DexDecEvalSandboxExecutionException
      This method is called when the sandbox is about to execute a non-constructor method.
      Parameters:
      reqid - internal request id (if this method returned null, the same value will be provided to the subsequent call to examineMethodResult)
      addr - caller location
      msig - method signature
      obj - the target object (null for a static method)
      args - method invocation arguments
      Returns:
      the hook may provide a result, in which case other hooks will not be tried; if null is returned, other hooks will be tried and eventually, the sandbox will proceed and attempt invocation itself
      Throws:
      DexDecEvalSandboxExecutionException - to report an exception generated by the emulated code
    • examineMethodResult

      default Wrapper<Object> examineMethodResult(long reqid, Object result)
      This method is called after the sandbox has invoked a non-constructor method. It provides the return value and offers a chance for the hook to modify or replace it.
      Parameters:
      reqid - internal request id, matching a previous call to invokeMethod
      result - the method's return value
      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 sandbox execution will resume and provide the original returned value)
    • newInstance

      default Wrapper<Object> newInstance(long reqid, String addr, String msig, List<Object> args) throws DexDecEvalSandboxExecutionException
      This method is called when an instance is about to be constructed.
      Parameters:
      reqid - internal request id (the same value will be provided to the subsequent call to examineCreatedInstance)
      addr - caller location
      msig - constructor signature
      args - constructor arguments, giving a chance for this hook to modify the arguments before the constructor is called
      Returns:
      the hook may provide a result, in which case other hooks will not be tried; if null is returned, other hooks will be tried and eventually, the sandbox will proceed and attempt creation itself
      Throws:
      DexDecEvalSandboxExecutionException - to report an exception generated by the emulated code
    • examineCreatedInstance

      default void examineCreatedInstance(long reqid, Object obj)
      This method is called after an object instance was constructed.
      Parameters:
      reqid - internal request id, matching a previous call to newInstance
      obj - the constructed instance, giving a hook an opportunity to modify it