Basic Operation

The aardefender tool works on compiled Java classes, like the apkdefender tool operates on the application bytecode. aardefender tool is compatible with the supported Java versions up to Java 17. As much as possible of the bytecode is translated to native code. aardefender tool takes an unprotected Android archive (AAR) as input and produces a corresponding protected archive as output. The protected archive file is named <original-name>-protected.aar and placed in the same directory as the original archive.

During protection, the bytecode is translated to native code, and anti-tamper protections and obfuscation then applied. As with apkdefender tool, there are a number of conditions that prevent translation of specific classes and methods. Some of those methods are detected and excluded from translation by default, but often, exclusion of some additional packages, classes, or methods must be configured to maintain the application stability.

To enable good protection and accurate callgraph analysis, define the library API in configuration so that API methods are not fully wiped from the bytecode. Also give an approximate calling score to the API methods to enable evaluation of effects on performance. For more information refer to Public API methods and scores .

aardefender provides informational output from the execution steps to the stdout. More extensive debug output is collected to aardefender.log file in the current working directory.

aardefender operation is controlled with configuration directives given via command line and a JSON configuration file.

Invoking the Tool from the Command Line

The aardefender tool offers a command line interface. The following examples demonstrate the tool usage on Linux.

To protect the application, execute the following command:

aardefender -c <path-to-configuration-file> sdk-release.aar

A protected application app-release-protected.apk is produced.

Command line options

The supported command line options are listed in the following table:

Option	Required	Description
-c / --configuration-file	Mandatory	Path to the JSON configuration file
-m / --mapping-file	Mandatory	Path to the R8 mapping file. For details how to use the mapping file for filtering, see section R8 mapping file support
-v / --version	Optional	Outputs the apkdefender tool version information and build date

JSON Configuration file

A sample of the supported configuration file format and options is given below.

{
   "general_configuration": {
       "enable_debugger_detection": true,
       "enable_root_detection": false,
       "library_name": "sample_library"
   },
   "protection_scope": {
       "exclude_classes": [],
       "exclude_methods_from_translation": [],
       "exclude_packages": [],
       "exclude_translated_methods_from_wiping": [],
       "include_packages": [],
       "library_api_methods": {"api_method_1": 2, "api_method_2": 5}
   }
}

The configuration file format type is JSON. The allowed elements are explained in the table below. If an optional element is not given, the tool will use the specified default value.

General Configuration

Option	Required?	Type	Description
abis	Optional	Array	A list of application binary interfaces (ABIs) for which the application native libraries are built during protection. Support for any ABIs not in this list is dropped. By default the native libraries are built for all ABIs supported by the application.
api_level	Optional	Integer	Specifies the minSdk level as an integer, for example "24" (Android 7.0 "Nougat"). Normally the API level is retrieved from the AndroidManifest.xml file, but it can be overridden with this option. The API level is needed to use the Android platform libraries required during compilation. Android API levels from 24 to 36 are supported.
app _store_compatibility	Optional	String	Enable APK distribution via non-Google systems. Note that this option is exclusive, and other distribution systems cannot then be used for the protected application. Valid values: Amazon, Google Default: Google
connection_whitelist	Optional	Array	The list of allowed DNS names for connections. If the list is empty or unspecified, the feature is automatically disabled. This feature requires that the Monitoring service is enabled for the application, as any connection attempts to unauthorized DNS hosts are reported to the monitoring interface.
emulator_detection_action	Optional	String	Choose the action when it is detected that the application not running on a real hardware: `report` Report the emulator detection to a callback, which is implemented in the application. The callback implementation details are described in section Event callback `exit` Just exit the application when running on an emulator is detected. `report_and_exit` Report the emulator detection to the callback before exiting the application. Warning: Emulator detection should be considered a security breach, so selecting `report` is not recommended. Default: `exit`
enable_bytecode_literal _obfuscation	Optional	Boolean	Set to 'true' to enable removal of bytecode literals. String literals are completely removed from the bytecode, and replaced with native lookup calls that load the actual string values from the native code. Int literals are obfuscated using control flow obfuscation with junk code injection, where the actual literal initialization code path taken is determined using a native predicate function that is opaque to the bytecode level analysis. The scope of bytecode literal obfuscation is the untranslated plaintext bytecode within the protection scope. Literals within static class initializers are not obfuscated. Bytecode literal obfuscation is disabled by default.
enable_debugger_detection	Optional	Boolean	Set to false to disable debugger detection. If enabled, applications marked as debuggable in the AndroidManifest.xml cannot be protected. Debugger detection is enabled by default.
enable_emulator_detection	Optional	Boolean	Set to false to allow the application to run on an emulator. By default running the application on an emulator is not allowed.
enable_heuristic_debugger _detection	Optional	Boolean	Set to true to enable stronger anti-debug measures using heuristics to detect ptrace attacks, even from kernel-level exploits. Disabled by default.
enable_install_on_removable _media	Optional	Boolean	Set to 'true' to allow installing the application on a removable medium. Installing protected applications on removable media is disabled by default.
enable_method_wiping	Optional	Boolean	Set to true to enable method wiping. When enabled, unused translated static methods are completely removed. Disabled by default.
enable_require_v3_signature	Optional	Boolean	Set to 'true' to prevent fallback to older, less secure signature schemes if v3 signature block does not exist.
enable_root_detection	Optional	Boolean	Set to true to enable jailbreak detection. If an attempt is made to run the protected application on a rooted device, it will exit. If root detection is enabled, debugger detection must also be enabled. Root detection is disabled by default.
enable_strace_detection	Optional	Boolean	Set to 'true' to enable `strace` system call and signal tracing utility detection. `strace` detection cannot be enabled if the application is allowed to run on an emulator. If `strace` detection is enabled, also `'enable_debugger_detection'` option must be enabled. `strace` detection is disabled by default.
library_api_methods	Optional	Array	Public API methods that must not be wiped away from the aar library, and the calling scores. The option usage is described in section Public API methods and scores.
library_name	Required	String	Specifies the library name for the native library generated by apkdefender. Provide the name without the "lib" prefix and ".so" suffix.
monitor_api_key	Optional	String	API key to retrieve Monitoring service configuration. The key can be obtained from the App Shield Portal. The monitor_api_key corresponds to the appClientSecret field in the generated API key JSON. Monitoring is described in section Monitoring service.
monitor_api_key_id	Optional	String	ID of the Monitoring service API key given with the option monitor_api_key. The monitor_api_key_id corresponds to the appClientId field in the generated API key JSON.
monitor_api_key_owner_email	Optional	String	Email address connected to the account that was used to create the Monitoring service API key on Verimatrix Platform.
root_detection_action	Optional	String	Choose the action when device rooting is detected: `report` Report the detected device rooting to a callback, which is implemented in the application, and/or to the monitoring service. The callback implementation details are described in section Event callback. Monitoring feature is described further in section Monitoring service. `exit` Just exit the application when device rooting is detected. `report_and_exit` Note: This option is available for monitoring only. Report the rooting detection to the monitoring service before exiting the application. Exiting the application is the default action when device rooting is detected.
signing_certificate	Optional	Array or String	A file path or a list of the file paths for one or more signing certificates. Only RSA certificates are supported, and the certificate must be given in DER or PEM format. The signing certificate must be given to enable the full application integrity verification. At least one signing certificate must be given for binding. If Google Play Signing service is used, at least the signing certificate provided by Google must be given. Note that this is not the same as the developer certificate that is used to sign the application before Google Play Store upload. Additionally, a secondary accepted signing certificate can be given, to enable signing and testing the build locally. Note: Configuring the signing certificates will effectively restrict the usage of AAR into private key holders of given certificates.
signing_certificate_fingerprint	Optional	String	Use the signing_certificate option to configure the certificate binding for the full application integrity verification. However, in some cases only the certificate fingerprint is available, for example if an external distribution signing system is used. In such case the signing_certificate_fingerprint option can be used as an alternative. Note that in this case it is not possible to verify the signing algorithm, but the requirement still applies.
status_response_method	Optional	String	Configuration option to set the event callback method. This option is an alternative to annotating the method in the source code. The method name must be given including the package namespace and class name. If the method is in an inner class, an annotation must be used instead of this configuration option. For more details, see section Event callback
system_integrity_mode	Optional	String	Choose the system integrity verification mode: strict: System integrity verification is performed reliably in Trusted Execution Environment. Only such operation result is accepted as valid. default: Also software based attestation result is accepted for older Android devices (before version 8). basic: Software based attestation is more widely allowed. Certain attestation flow failures are ignored for older devices. Default: default
system_integrity_product _whitelist	Optional	Array	Device specific exemption for skipping the system integrity verification, while still performed for any other device. Defined by listing the ro.build.product property values for the exempted devices.
system_integrity_root_certificates	Optional	Array	Path to additional accepted root certificate files in PEM format for system integrity verification. By default only the Google certificates are included. Configuring custom root certificate is needed for any environment that is not CTS compliant.
target_app_id	Conditional	String	Defines the application ID of the final application that will include the AAR. The AAR can only be used in this application. This option is required when monitoring is enabled.
target_split	Optional	String	Defines the split APK that will include the protected AAR. If this option is defined, it is verified that the protected code is in the intended split APK. Also the integrity verification is then applied to the corresponding split.

Hooking Detection

This feature is always enabled for protected applications. There is no configuration option to disable it.

Protection Scope - protection_scope

Option	Required	Type	Description
exclude_classes	Optional	Array	Matching classes are removed from the protection scope. This may be useful as a quick workaround to exclude individual classes causing performance issues or other unexpected problems. Wildcards are supported.
exclude_methods_from_translation	Optional	Array	Matching methods are excluded from being translated, allowing a finer-grained protection scope. Wildcards are supported.
exclude_packages	Optional	Array	Matching packages are removed from the protection scope. This may be useful as a quick workaround to exclude individual classes causing performance issues or other unexpected problems. Wildcards are supported.
exclude_translated_methods_from_wiping	Optional	Array	Matching methods are excluded from wiping. Wiping some specific methods may not be feasible, e.g. because they are called from the native libraries. Wildcards are supported.
include_assets	Optional	Array	List any assets to be whitelisted for encryption. Wildcards are supported.
include_packages	Optional	Array	If any packages are specified in the list, all packages whose name does not match any of the specified include rules are removed from the protection scope. Wildcards are supported.
translated_packageless_classes	Optional	Boolean	Set to 'true' to include classes that do not have package in the translation scope. By default packageless classes are not translated.

Public API methods and scores

The library_api_methods option is used to declare the public API methods that must not be wiped from the aar library, and their calling scores. The scores represent roughly the number of calls during one application process lifecycle, for example:

For application object onCreate() the score is 1.
For activities onCreate() and onDestroy() a few more callscould be defined, as there would be some navigation back and forth.
For known low frequency API functions the score should be given as~1-10, to ensure a check will be injected.
For medium frequency functions a suitable score would be 30-100.
For high frequency functions where checks must not be injected the score should be exceeding 500 which is the default maximum score for adding explicit checks.

Alternatively, use annotations to define the API methods. For more information refer to section Annotations.