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