Integrate the Malware Detection SDK

Prev Next

Android

For the SDK to function, you need to add the required manifest permissions, integrate the SDK, and generate a malware list.

Manifest permissions

Add the following to the AndroidManifest.xml file:

<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />

This grants full package visibility, on which all three SDK features depend to scan installed apps. Without this visibility, Android restricts which packages are visible and results will be incomplete.

If you use a remote URL for the malware list, also add the following:

<uses-permission android:name="android.permission.INTERNET" />

Integration

You can integrate the SDK either via a local Maven repository, or with an aar file.

Integration via local Maven repository

The SDK product package includes a local Maven repository in the maven/ folder. This resolves transitive dependencies automatically and enables inline KDoc in Android Studio.

Copy the maven/ folder from the SDK package into your app's directory (i.e. together with build.gradle), then add the following to build.gradle:

repositories {
    maven { url uri("${rootDir}/app/maven") }
}

dependencies {
    implementation 'com.onespan:sdk_malware_detection_android:+'
}

Integration via aar file (flat dependency)

Place the MalwareDetectionSDK.aar file from the SDK package into your app’s libs/ folder, then add the following to build.gradle:

repositories {
    flatDir { dirs 'libs' }
}

dependencies {
    implementation(name: 'MalwareDetectionSDK', ext: 'aar')

    // Required transitive dependencies
    implementation("androidx.work:work-runtime-ktx:2.11.1")
    implementation("androidx.security:security-crypto:1.1.0")
    implementation("androidx.room:room-runtime:2.8.4")
    implementation("androidx.room:room-ktx:2.8.4")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.10.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}

Malware list

Before initializing malware detection, generate a signed malware list using the Malware List Encryption Tool included in the SDK package:

java -jar MalwareListEncryptionTool.jar -f definitions.json -o output/

The input is a JSON array of malware definitions. All fields are optional but each entry must include at least on hash.

[
  {
    "packageName": "com.example.malware",
    "md5Hash": "d8e8fca2dc0f896fd7cb4cb0031ba249",
    "sha1Hash": "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83",
    "sha256Hash": "b94f6f125c79e3a5ffaa826f584c10d52ada669e6762051b826b55776d05a8a7"
  }
]

Run the JAR with no arguments to print full usage instructions.

The Encryption Tool produces three files:

  • signed_malware_list.json

    The signed definitions consumed by the SDK at runtime.

  • app_keys.json

    Keys used by the SDK to verify the list. These keys must be bundled in your app's assets or stored on device (see Usage).

  • client_keys.json

    Retained by the list maintainer. Pass it back with -k to update the list without rotating the keys already deployed in the app.

Usage

Obtain an instance via MalwareDetection.getInstance, passing typed sources for the app keys and malware definition files.

Assets (bundled with the apk)

MalwareDetection.getInstance(
    context = context,
    appKeys = AppKeys.FromAssets("app_keys.json"),
    malwareList = MalwareList.FromAssets("signed_malware_list.json"),
)

File (device storage)

The application must have permissions to read the file.

MalwareDetection.getInstance(
    context = context,
    appKeys = AppKeys.FromFile(File(context.filesDir, "app_keys.json")),
    malwareList = MalwareList.FromFile(File(context.filesDir, "list.json")),
)

Remote malware list (HTTP/HTTPS)

App keys must still come from assets or a local file. Only the malware list can be fetched remotely.

MalwareDetection.getInstance(
    context = context,
    appKeys = AppKeys.FromAssets("app_keys.json"),
    malwareList = MalwareList.FromUrl("https://example.com/malware_list.json"),
)

Pass a custom OkHttpClient to MalwareList.FromUrl to configure proxy settings, authentication interceptors, TLS settings, or timeouts. Responses are cached with ETag support. When the network is unavailable, the SDK automatically uses the cached copy.

Requires android.permission.INTERNET in the manifest.

Remote Access Tool (RAT) detection

Detects Remote Access Tools (e.g. AnyDesk, TeamViewer, Splashtop) that may be installed or active on the device.

val ratDetection = RatDetection.getInstance(context)
val items = ratDetection.startRatAnalysis()

Each RatItem in the result includes a probability score for whether the package is a RAT and whether it is currently active, along with package metadata.

Side-loading detection

Identifies packages that were likely installed outside of official app stores (e.g. via ADB or unknown sources).

val sideLoadingDetection = SideLoadingDetection.getInstance(context)
val packages = sideLoadingDetection.getSideLoadedPackages()

iOS

To use the Malware Detection SDK in your iOS project

  1. Link MalwareDetectionSDK.xcframework from the OneSpan Mobile Security Suite or Project Cyber package to your Xcode project (linked framework and libraries).

You are now ready to use the Malware Detection SDK.

API reference documentation and sample applications

To learn more about the public APIs and their functions, exceptions, and error codes, refer to the technical documentation that is included in the product package for each SDK and each platform. In the product package, you can also find the sample applications provided for each platform to see examples of how the SDKs can be used.

These sample apps are intended only to demonstrate basic scenarios and SDK usage. They are not designed to be copied directly into production projects!