Configuration

View product develop

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, for RASP features to be enabled with default configuration, the application signatureHash must be supplied in RepackageDetectionConfig (part of RaspConfig).

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 an internal user ID is available at config time
            .clientAppDeviceId(INTERNAL_CLIENT_DEVICE_ID) // Use if an internal device ID is available at config time
            .antivirusConfig(
                AntivirusConfig.Builder()
                        .build()
            )
            .raspConfig(
                RaspConfig.Builder()
                    .repackage(
                        RepackageDetectionConfig.Builder()
                            .signatureHash(listOf(SIGNATURE_HASH))
                            .build()
                    )
                    .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 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 the client
    .clientAppUserId("SOME_CLIENT_USER_ID_VALUE")

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

    // configuration of customer grouping and naming in the web app
    .customerGroupingConfig(customerGroupingConfig)
        
    // device fingerprinting configuration
    .fingerprint(fingerprintType)

    .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()
    .emulator(DetectionConfig)
    .root(RootDetectionConfig)
    .debugger(
        DebuggerDetectionConfig.Builder()
            .action(DetectionConfig)
            .debuggerTypes(Collection<DebuggerType>)
            .build()
    )
    .repackage(
        RepackageDetectionConfig.Builder()
            .action(DetectionConfig)
            .signatureHash(Collection<String>) // SHA-1 of signing certificate(s)
            .build()
    )
    .screenSharing(DetectionConfig)
    .screenReader(
        ScreenReaderBlockConfig.Builder()
            .action(BlockConfig)
            .allowedScreenReaders(Collection<RaspConfig.ApkAllowlistItem>)
            .build()
    )
    .screenshot(
        ScreenshotConfig.Builder()
            .blockAction(BlockConfig)
            .detectionAction(SimpleDetectionConfig)
            .build()
    )
    .processName(ProcessNameConfig)
    .tapjacking(
        TapjackingBlockConfig.Builder()
            .action(BlockConfig)
            .ignoreTapjackingSystemApps(Boolean)
            .blockTapjackingSensitivity(ThreatIndex)
            .allowedTapjackingApps(Collection<RaspConfig.ApkAllowlistItem>)
            .build()
    )
    .httpProxy(DetectionConfig)
    .vpn(DetectionConfig)
    .adb(DetectionConfig)
    .activeCall(SimpleDetectionConfig)
    .appPresence(
        AppPresenceDetectionConfig.Builder()
            .action(DetectionConfig)
            .remoteDesktopApps(Collection<AppPresenceDetectionConfig.NamedApkItem>)
            .build()
    )
    .sendInfoOutputs(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. The 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 the configuration of AppProtection.

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

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

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

// The first argument defines the 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 the 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 the AppProtection instance and re-initializing with a new configuration.

More details about releasing the 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.