Migration Guide to Version 1.0.x

View product develop

Malwarelytics for Android version 1.0.0 introduces a new format of RaspConfig. Update from previous versions requires refactoring of the whole RASP configuration.

The change was introduced to remove unnecessary confusion in the range of possible configurations for each runtime protection feature. Also, the ever-growing list of RASP configuration items made it difficult to find all the available options for a feature. The new configuration better reflects all possible behaviors of each feature.

The new format of RaspConfig groups all config items of each runtime feature together into a configuration group. All RASP configuration groups are either value-based or builder-based.

Value-Based Config Groups

Value-based config groups are constructed with a sealed class like DetectionConfig. The configuration item expects only one value to be inserted. The value is either an object (e.g value NoAction indicating that the feature is turned off) or a data class with extra arguments (e.g. value Exit(exitUrl:String?) indicating that the app will be terminated and optionally a certain URL will be opened). See the example in Value-Based Configuration Group

Builder-Based Config Groups

Builder-based config groups are complex configuration groups such as RaspConfig itself. These groups have Builder classes allowing configuration of all behavioral aspects. Each of these config groups has an item named action which determines the primary behavior of the feature. The action item is a value-based config group itself. See the example in Builder-Based Configuration Group.

Summary of RASP Config Groups

Config Group	Type
emulator(DetectionConfig)	value-based
root(RootDetectionConfig)	value-based
debugger(DebuggerDetectionConfig)	builder-based
repackage(RepackageDetectionConfig)	builder-based
screenSharing(DetectionConfig)	value-based
screenshot(BlockConfig)	value-based
screenReader(ScreenReaderBlockConfig)	builder-based
processName(ProcessNameConfig)	value-based
tapjacking(TapjackingBlockConfig)	builder-based
httpProxy(DetectionConfig)	value-based
vpn(DetectionConfig)	value-based
adb(AdbDetectionConfig)	value-based
activeCall(SimpleDetectionConfig)	value-based
appPresence(AppPresenceDetectionConfig)	builder-based

Value-Based Configuration Group

An example of a value-based configuration item is emulator configuration.

Previously the feature was configured with three items:

raspConfigBuilder
    .checkEmulator(Boolean)
    .exitOnEmulator(Boolean)
    .exitOnEmulatorUrl(String)

It was refactored into a value-based configuration item:

raspConfigBuilder
    .emulator(DetectionConfig)

Available values of DetectionConfig:

Value	Description
`NoAction`	indicates that emulators will not be automatically detected. A manual check is still possible.
`Notify`	indicates that emulators will be automatically detected and observers will be notified.
`Exit(` `exitUrl:String?)`	indicates that emulators will be automatically detected and the app will be terminated when an emulator is automatically detected.

Builder-Based Configuration Group

An example of a builder-based configuration item is tapjacking configuration.

Previously the feature was configured with four items:

raspConfigBuilder
    .blockTapjacking(Boolean)
    .ignoreTapjackingSystemApps(Boolean)
    .blockTapjackingSensitivity(ThreatIndex)
    .allowedTapjackingApps(Collection<RaspConfig.ApkAllowlistItem>)

It was refactored into a builder-based configuration item:

raspConfigBuilder
    .tapjacking(
        TapjackingBlockConfig.Builder()
            .action(BlockConfig)
            .ignoreTapjackingSystemApps(Boolean)
            .blockTapjackingSensitivity(ThreatIndex)
            .allowedTapjackingApps(Collection<RaspConfig.ApkAllowlistItem>)
            .build()
    )

Method	Description
`action(BlockConfig)`	specifies the automatic behavior of the tapjacking protection feature. Defaults to `BlockConfig.Block`. However, tapjacking is not blocked unless a “problematic” app is installed on the device. An app is deemed “problematic” when it meets sensitivity criteria defined by `blockTapjackingSensitivity`.
`ignoreTapjackingSystemApps(Boolean)`	indicates whether tapjacking protection should ignore system apps in the checks. Defaults to `false`. If set to `true` all system apps will be ignored and tapjacking will get blocked only if a non-system “problematic” app is present.
`blockTapjackingSensitivity(ThreatIndex)`	defines tapjacking protection sensitivity. Defaults to `ThreatIndex.HIGHLY_DANGEROUS`.
`allowedTapjackingApps(Collection<RaspConfig.ApkAllowlistItem>)`	defines a collection of allowed app capable of tapjacking. It is empty by default.

Available values of BlockConfig:

Value	Description
`NoAction`	indicates that tapjacking will not be automatically blocked. A manual check for tapjacking apps is still possible.
`Block`	indicates that tapjacking will be automatically blocked.

Config Item Replacements

Here is the mapping list of the RaspConfig items from version 0.24.0 into new items in version 1.0.0.

Config items groupped by feature in version 0.24.0	Config item in version 1.0.0
`checkEmulator(Boolean)` `exitOnEmulator(Boolean)` `exitOnEmulatorUrl(String)`	`emulator(DetectionConfig)`
`checkRoot(Boolean)` `exitOnRoot(Boolean)` `exitOnRootUrl(String)` `exitOnRootMinConfidence(Float)`	`root(RootDetectionConfig)`
`checkDebugger(Boolean)` `exitOnDebugger(Boolean)` `exitOnDebuggerUrl(String)`	`debugger(DebuggerDetectionConfig)`
`checkRepackaging(Boolean)` `exitOnRepackaging(Boolean)` `exitOnRepackagingUrl(String)` `signatureHash(String)`	`repackage(RepackageDetectionConfig)`
`checkScreenSharing(Boolean)` `exitOnScreenSharing(Boolean)` `exitOnScreenSharingUrl(String)`	`screenSharing(DetectionConfig)`
`blockScreenshots(Boolean)`	`screenshot(BlockConfig)`
`blockScreenReaders(Boolean)` `allowedScreenReaders(Collection<RaspConfig.ApkAllowlistItem>)`	`screenReader(ScreenReaderBlockConfig)`
`customProcessName(String)` `useStealthyProcessName(Boolean)`	`processName(ProcessNameConfig)`
`blockTapjacking(Boolean)` `ignoreTapjackingSystemApps(Boolean)` `blockTapjackingSensitivity(ThreatIndex)` `allowedTapjackingApps(Collection<RaspConfig.ApkAllowlistItem>)`	`tapjacking(TapjackingBlockConfig)`
`checkHttpProxy(Boolean)` `exitOnHttpProxy(Boolean)` `exitOnHttpProxyUrl(String)`	`httpProxy(DetectionConfig)`
`checkVpn(Boolean)` `exitOnVpn(Boolean)` `exitOnVpnUrl(String)`	`vpn(DetectionConfig)`
`exitOnAdbEnabled(Boolean)` `exitOnAdbEnabledUrl(String)`	`adb(AdbDetectionConfig)`
`checkActiveCall(Boolean)`	`activeCall(SimpleDetectionConfig)`
N/A	`appPresence(AppPresenceDetectionConfig)`

Each RASP feature has a dedicated documentation page where you can find more details about its configuration.