public interface

IDSandboxHooks

implements IPriorityBasedHooks
com.pnfsoftware.jeb.core.units.code.android.ir.IDSandboxHooks

Class Overview

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

Summary

Public Methods
abstract void examineCreatedInstance(long reqid, Object obj)
This method is called after an object instance was constructed.
abstract Wrapper<Object> examineFieldValue(long reqid, Object value)
This method is called after the sandbox has read a field value.
abstract Wrapper<Object> examineMethodResult(long reqid, Object result)
This method is called after the sandbox has invoked a non-constructor method.
abstract Wrapper<Object> getField(long reqid, String addr, String fsig, Object obj)
This method is called when the sandbox is about to get a field's value.
abstract Wrapper<Object> invokeMethod(long reqid, String addr, String msig, Object obj, List<Object> args)
This method is called when the sandbox is about to execute a non-constructor method.
abstract Class<?> loadClass(String name)
This method is called when an external class is to be loaded by the sandbox.
abstract Wrapper<Object> newInstance(long reqid, String addr, String msig, List<Object> args)
This method is called when an instance is about to be constructed.
abstract Boolean setField(long reqid, String addr, String fsig, Object obj, Object[] avalue)
This method is called when the sandbox is about to set a field's value.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.units.IPriorityBasedHooks

Public Methods

public abstract 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

public abstract 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)

public abstract 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)

public abstract Wrapper<Object> getField (long reqid, String addr, String fsig, Object obj)

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

public abstract Wrapper<Object> invokeMethod (long reqid, String addr, String msig, Object obj, List<Object> args)

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

public abstract Class<?> loadClass (String name)

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

public abstract Wrapper<Object> newInstance (long reqid, String addr, String msig, List<Object> args)

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

public abstract Boolean setField (long reqid, String addr, String fsig, Object obj, Object[] avalue)

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