Monitoring and restricting APIs

DroidMate monitors APIs during execution using ArtHook. The list of monitored APIs has to be provided during build.

Updating the list of monitored APIs

DroidMate reads information from the projects/resources/monitored_apis.json file to build its monitoring layer.

Create new API

To monitor a new API create an entry with the following information:

• className: Fully-qualified name of the class which contains the method (String)
• methodName: Name of the method, without brackets and parameters (String)
• paramList: List of parameter types in JSON format (String)
• returnType: Type of the API's return (String)
• isStatic: If the API is static or not (boolean)
• exceptionType: Type of exception that will be generated when blocking the API. Must be a runtime exception (String)
• defaultReturnValue: Value that will be returned when mocking the API. Can be a value or function. (String)
• hookenMethod: Signature of the method that will be hooked, without parameters (String)
• logID: API identifier for logging (String)
• platformVersion: For which platform version the API should be activated (String)
• signature: Signature of the hook method (String)
• jniSignature: JNI signature of the method. Optional (String)
• invokeAPICode: Code to invoke the API. Parameters are named p0,p1,...,pn and the current object is called this. If is possible to write any custom java code into this field for personalized behaviour.

Example:

{
	"className": "android.hardware.Camera", 
	"methodName": "open", 
	"paramList": ["int"], 
	"returnType": "android.hardware.Camera", 
	"isStatic": true, 
	"hookedMethod": "android.hardware.Camera->open", 
	"exceptionType": "SecurityException", 
	"defaultReturnValue": "null", 
	"logID": " \"TId: \"+threadId+\" objCls: android.hardware.Camera mthd: open retCls: android.hardware.Camera params: int \"+convert(p0)+\" stacktrace: \"+stackTrace", 
	"platformVersion": "All", 
	"signature": "redir_android_hardware_Camera_open_97(int p0)", 
	"jniSignature": "Landroid/hardware/Camera;->open(I)Landroid/hardware/Camera; static", 
	"invokeAPICode": "Object returnVal =  OriginalMethod.by(new $() {}).invokeStatic (p0);\n        
					 return (android.hardware.Camera) returnVal;"
}

A script to convert from a JNI string into the JSON format is available at:

• https://github.com/natanieljr/droidmate-monitoredAPIs-converter

After you make your changes, do a build

To test if DroidMate successfully monitored your modified API list, observe the logcat output while the explored application is started. You will see 100+ messages tagged Instrumentation. If there were any failures, the messages will say so.

Restricting individual APIs

It is now possible to apply individual policies for each monitored API. The following API policies are available:

• Allow: Executes the code contained in the invokeAPICode tag.
• Deny: Generates an exception when the API is accessed. The exception type is defined by the exceptionType tag.
• Mock: Return the value defined in the defaultReturnValue tag.

The API policies should be added to the file located at:

repo/projects/resources/api_policies.txt

This file contains instructions and examples of policies.

In order to change policies without recompiling DroidMate, it is possible to use the --Deploy-replaceResources=false switch to prevent DroidMate from overriding the policy definition file in the temp_extracted_resources directory during execution. In this case it is just necessary to update the file in the directory and DroidMate will activate the new policies.

Preparing apps for API monitoring

While DroidMate can explore normal apps, it is intended to run on inlined ones. When run on inlined apks, DroidMate is able to monitor which Android APIs are being acessed. For normal APKs it can only measure the exploration coverage. Note: Inlined apps do not work on emulators.

To inline apps, run DroidMate in inline mode, instead of its default explore. The original app files (apks) will be retained and new inlines apk files will be created.

Inlined apks can be distinguished by an -inlined suffix in their name.

Example (assuming executable Jar)

java -jar DM-2.jar -ExecutionMode-explore=false --ExecutionMode-inline=true --Exploration-apksDir=/home/test/apks