Configuration

View product v0.24.0

The simplest way to initialize Malwarelytics for Android is in the Application.onCreate() system callback. A bare minimum required for integration is to provide apiUsername, apiPassword and apiSignaturePublicKey to the AppProtectionConfig.Builder. Additionally, in order for RASP features to be enabled with default configuration, application signatureHash must be supplied.

Here is an example of minimum initialization code including RASP features:

class MyApplication : Application() {

    override fun onCreate() {
        // Prepare minimum configuration
        val config = AppProtectionConfig.Builder(appContext)
            .apiUsername(API_USERNAME)
            .apiPassword(API_PASSWORD)
            .apiSignaturePublicKey(API_SIGNATURE_PUBLIC_KEY)
            .clientAppUserId(INTERNAL_CLIENT_USER_ID) // Use if internal user ID is available at config time
            .clientAppDeviceId(INTERNAL_CLIENT_DEVICE_ID) // Use if internal device ID is available at config time
            .antivirusConfig(
                AntivirusConfig.Builder()
                        .build()
            )
            .raspConfig(
                RaspConfig.Builder()
                        .signatureHash(SIGNATURE_HASH)
                        .build()
            )
            .build()

        // Initialize AppProtection class
        val appProtection = AppProtection.getInstance()
        appProtection.initializeAsync(config, object: AppProtection.InitializationObserver {
            // App Protection is fully ready to be used now
            override fun onInitialized(initializationResult: InitializationResult) {
                // Setup internal IDs when you are able to obtain them
                appProtection.updateClientAppUserId(INTERNAL_CLIENT_USER_ID)
                appProtection.updateClientAppDeviceId(INTERNAL_CLIENT_DEVICE_ID)
            }
        })
        // ...
    }
}

The API_USERNAME, API_PASSWORD and API_SIGNATURE_PUBLIC_KEY values can be found in the Malwarelytics console.

INTERNAL_CLIENT_USER_ID and/or INTERNAL_CLIENT_DEVICE_ID are your custom identifiers that allow you to recognize your client.

For information on how to obtain the SIGNATURE_HASH value, read the Repackaging Detection guide.

See the RASP feature overview and the Anti-Malware feature overview for detailed documentation of available detections and security features.

Configuration Reference List

This is a reference list of all configuration options.

AppProtectionConfig

Global Malwarelytics configuration options:

val config = AppProtectionConfig.Builder(appContext)

    // Anti-Malware feature configuration
    .antivirusConfig(antivirusConfig)

    // RASP feature configuration
    .raspConfig(raspConfig)

    // API username
    .apiUsername(username)

    // API password
    .apiPassword(password)

    // API signature public key
    .apiSignaturePublicKey(apiSignaturePublicKey)

    // change environment configuration
    .environment(environmentConfiguration)

    // custom identifier of client
    .clientAppUserId("SOME_CLIENT_USER_ID_VALUE")

    // custom identifier of client device
    .clientAppDeviceId("SOME_CLIENT_DEVICE_ID_VALUE")

    // configuration of customer grouping and naming in the web app
    .customerGroupingConfig(customerGroupingConfig)

    .build()

AntivirusConfig

Configuration options for the Anti-Malware component:

val antivirusConfig = AntivirusConfig.Builder()
                // define if the Anti-Malware component of Malwarelytics is enabled
                .enableAntivirus(Boolean)

                // use default built-in suggestions
                .useDefaultSuggestions(Boolean)

                // set factory for foreground service notification
                .setForegroundServiceNotificationFactory(notificationFactory)

                // set detailed configuration of smart protection
                .smartProtectionConfig(smartProtectionConfig)

                // change default threat mitigation UI - screen & notification
                .setThreatMitigationUIConfig(threatMitigationUIConfig)

                .build()

ThreatMitigationUIConfig

Configuration options for Threat Mitigation UI, an Anti-Malware feature:

val threatMitigationUIConfig = AntivirusConfig.ThreatMitigationUIConfig.Builder()
                .notificationSmallIcon(R.drawable.my_notification_icon)
                .notificationChannelId("AV-CHANNEL")
                .screenDeleteIcon(R.drawable.custom_delete_icon)
                .screenSettingsIcon(R.drawable.custom_settings_icon)
                .screenTheme(R.style.CustomThreatScreenTheme)
                .customLocalization("cs")
                .build()

SmartProtectionConfig

Configuration options for Smart Protection, an Anti-Malware feature:

val smartProtectionConfig = AntivirusConfig.SmartProtectionConfig.Builder()
                .smartProtectionEnabled(true)
                .silentModeEnabled(true)
                .smartProtectionIntervalHours(72)
                .performInitialFirstUpdate(true)
                .build()

RaspConfig

Configuration options for the RASP component:

val raspConfig = RaspConfig.Builder()
    .checkEmulator(Boolean)
    .exitOnEmulator(Boolean)
    .exitOnEmulatorUrl(String)
    .checkRoot(Boolean)
    .exitOnRoot(Boolean)
    .exitOnRootUrl(String)
    .exitOnRootMinConfidence(Float) // value from 0.0 to 1.0
    .checkDebugger(Boolean)
    .exitOnDebugger(Boolean)
    .exitOnDebuggerUrl(String)
    .checkRepackaging(Boolean)
    .exitOnRepackaging(Boolean)
    .exitOnRepackagingUrl(String)
    .signatureHash(String)          // SHA-1 of signing certificate(s)
    .checkScreenSharing(Boolean)
    .exitOnScreenSharing(Boolean)
    .exitOnScreenSharingUrl(String)
    .blockScreenshots(Boolean)
    .blockScreenReaders(Boolean)
    .allowedScreenReaders(Collection<RaspConfig.ApkAllowlistItem>)
    .customProcessName(String)      // when set, turns of useStealthyProcessName
    .useStealthyProcessName(Boolean)
    .blockTapjacking(Boolean)
    .ignoreTapjackingSystemApps(Boolean)
    .blockTapjackingSensitivity(ThreatIndex)
    .allowedTapjackingApps(Collection<RaspConfig.ApkAllowlistItem>)
    .checkHttpProxy(Boolean)
    .exitOnHttpProxy(Boolean)
    .exitOnHttpProxyUrl(String)
    .checkVpn(Boolean)
    .exitOnVpn(Boolean)
    .exitOnVpnUrl(String)
    .exitOnAdbEnabled(Boolean)
    .exitOnAdbEnabledUrl(String)
    .checkActiveCall(Boolean)
    .build()

CustomerGroupingConfig

Configuration options for customer grouping in the web console:

val customerGroupingConfig = AppProtectionConfig.CustomerGroupingConfig.Builder()
    .sourcePackageName(String) // max len 255 characters
    .appPackageName(String) // max len 255 characters
    .audienceGroupId(String) // max len 20 characters
    .build()

Configuration of Server Environment

Malwarelytics provides two predefined environments — production and test. The production environment is used by default. Environment can be specified with these pre-defined constants:

// Production environment
val environmentConfiguration = AppProtectionConfig.EnvironmentConfiguration.PRODUCTION_ENVIRONMENT

// Test environment
val environmentConfiguration = AppProtectionConfig.EnvironmentConfiguration.TEST_ENVIRONMENT

Environment configuration can be set only through configuration of AppProtection.

val config = AppProtectionConfig.Builder(appContext)
    .environment(environmentConfiguration)
    // …
    .build()

For special use, environment configuration allows definition of custom environments with optional SSL pinning. These custom environments can be defined with:

// The argument defines environment URL. No SSL pinning is used in this case.
val environmentConfiguration = EnvironmentConfiguration(String)

// The first argument defines environment URL.
// The second argument is supposed to contain values of SHA-256 digests of certificate data - X509Certificate.encoded.
val environmentConfiguration = EnvironmentConfiguration(String, List<ByteArray>)

// The first argument defines environment URL.
// The second argument is supposed to contain base64 encoded values of SHA-256 digests of certificate data - X509Certificate.encoded.
val environmentConfiguration = EnvironmentConfiguration(String, vararg String)

Configuration Change

Any configuration change of Malwarelytics for Android requires releasing AppProtection instance and re-initializing with a new configuration.

More details about releasing AppProtection instance are described in Releasing section of the documentation.

Malwarelytics for Android cannot be used after release. It has to be re-initialized first.