Interface IDSandboxHooks
- All Superinterfaces:
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 Summary
Modifier and TypeMethodDescriptiondefault void
examineCreatedInstance
(long reqid, Object obj) This method is called after an object instance was constructed.examineFieldValue
(long reqid, Object value) This method is called after the sandbox has read a field value.examineMethodResult
(long reqid, Object result) This method is called after the sandbox has invoked a non-constructor method.This method is called when the sandbox is about to get a field's value.This method is called when the sandbox is about to execute a non-constructor method.default Class<?>
This method is called when an external class is to be loaded by the sandbox.newInstance
(long reqid, String addr, String msig, List<Object> args) This method is called when an instance is about to be constructed.default Boolean
This method is called when the sandbox is about to set a field's value.Methods inherited from interface com.pnfsoftware.jeb.core.units.IPriorityBasedHooks
getPriority
-
Method Details
-
loadClass
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 idaddr
- caller locationfsig
- field signatureobj
- field objectavalue
- 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 toexamineFieldValue
)addr
- caller locationfsig
- field signatureobj
- 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
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 togetField
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 toexamineMethodResult
)addr
- caller locationmsig
- method signatureobj
- 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
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 toinvokeMethod
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 toexamineCreatedInstance
)addr
- caller locationmsig
- constructor signatureargs
- 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
This method is called after an object instance was constructed.- Parameters:
reqid
- internal request id, matching a previous call tonewInstance
obj
- the constructed instance, giving a hook an opportunity to modify it
-