Configuration
To initialize Malwarelytics for Android, it’s necessary to provide a configuration - an instance of AppProtectionConfig. The configuration tells the SDK what features to use and in what mode to initialize. The SDK can be initialized in online or offline mode.
Offline Mode Configuration
The offline mode configuration doesn’t require any API credentials. In this mode, it’s recommended not to use the Anti-Malware feature.
The RASP feature is disabled by default unless an RASP configuration is provided. The minimum configuration needs the application’s signatureHash to be supplied in RepackageDetectionConfig (part of RaspConfig) for repackaging detection to be properly configured.
An example of a minimum offline mode initialization code is:
// Prepare minimum offline configuration
val config = AppProtectionConfig.Builder(appContext)
// Turn off Anti-Malware feature
.antivirusConfig(
AntivirusConfig.Builder()
.enableAntivirus(false)
.build()
)
// The RASP feature is disabled by default
// Providing any RASP configuration turns the RASP feature on
.raspConfig(
RaspConfig.Builder()
.repackage(
// Configure repackaging detection
RepackageDetectionConfig.Builder()
.signatureHash(listOf(SIGNATURE_HASH))
.build()
)
.build()
)
.build()
// Initialize AppProtection class asynchronously
val appProtection = AppProtection.getInstance()
appProtection.initializeAsync(config, object: AppProtection.InitializationObserver {
override fun onInitialized(initializationResult: InitializationResult) {
// App Protection is fully ready to be used now
}
})
Online Mode Configuration
A bare minimum required for online mode is to provide apiUsername, apiPassword, and apiSignaturePublicKey to the AppProtectionConfig.Builder. The API credentials allow the SDK to communicate with the Malwarelytics console application. The API credentials can be obtained in the Malwarelytics console in Get the SDK section.
Similarly to offline mode, the RASP feature is disabled by default unless a RASP configuration is provided. For all RASP features to be enabled with the default configuration, the application’s signatureHash must be supplied in RepackageDetectionConfig (part of RaspConfig).
Here is an example of minimum online configuration:
// Prepare minimum configuration
val config = AppProtectionConfig.Builder(appContext)
// API credentials are for online mode only
.apiUsername(API_USERNAME)
.apiPassword(API_PASSWORD)
.apiSignaturePublicKey(API_SIGNATURE_PUBLIC_KEY)
// Internal user and device IDs are for online mode only
// Configure the IDs here if they are available at config time.
// Otherwise update the IDs after initialization via the `AppProtection` instance
.clientAppUserId(INTERNAL_CLIENT_USER_ID)
.clientAppDeviceId(INTERNAL_CLIENT_DEVICE_ID)
// The Anti-Malware feature is enabled by default
// The RASP feature is disabled by default
// Providing any RASP configuration turns the RASP feature on
.raspConfig(
RaspConfig.Builder()
// repackaging detection needs signatureHash
.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 now fully ready to be used
override fun onInitialized(initializationResult: InitializationResult) {
// App Protection is now fully ready to be used
// Internal user and device IDs can now be updated
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 in Get the SDK section.
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.