Configuration
The minimum configuration for Malwarelytics is setting up the username, password, and public key in the service configuration (for each each platform). However, we recommend configuring all features that are present in the SDK.
The Username
, Password
, and Signature Public Key
can be obtained in the Malwarelytics console. Note that these credentials are bound to your application Package Name/Bundle ID. If you need to support multiple environments (Package names/Bundle IDs), you need different credentials for each environment.
Environment
Malwarelytics offers two built-in environments PRODUCTION
(default value) for production builds, and TEST
for development and test builds. The environment can be altered globally or on a per-platform basis. Different environments require different access credentials.
Configuring the Malwarelytics
To enable Malwarelytics in your React Native app, it’s necessary to call the initialize
method using the following configuration object. All properties are optional:
import { Malwarelytics } from 'react-native-malwarelytics';
await Malwarelytics.sharedInstance.initialize({
// Global environment applied to both platforms. The default value is 'PRODUCTION'
environment: 'PRODUCTION',
// The following object provides optional client identification. If such values are not available at the application's
// startup, then you can set it to Malwarelytics later. The purpose of identifiers is to identify your users
// or their devices in the Malwarelytics Console.
clientIdentification: {
clientId: 'your-client-id', // Client's identifier (for example e-mail)
deviceId: 'device-id', // Device's identifier if you have some recognized in your systems.
},
// The 'apple' section configures Malwarelytics for Apple platforms.
apple: {
// The 'service' section defines the connection to Malwarelytics Service for Apple platforms. You can obtain
// all configuration values in the Malwarelytics Console.
// If no service is provided, then Malwarelytics will work in the offline mode.
service: {
username: "your-username-for-ios app",
password: "your-password-for-ios app",
signaturePublicKey: "your-sign-pk-for-ios-app",
environment: 'TEST' // Environment specific for the Apple platform, overrides the global environment set above.
},
// The 'rasp' section defines the behavior of the RASP module for the Apple platform. Most of the features support
// three basic actions - 'NO_ACTION' (SDK will do nothing), 'NOTIFY' - SDK will notify you via the listener,
// 'EXIT' - SDK will terminate your application. If exit is specified then you can provide additional
// `exitUrl` that is opened in the browser after the application is closed.
// The typical default action is 'NOTIFY'.
rasp: {
// Action defined when jailbreak is detected on the device.
jailbreak: { action: 'EXIT', exitUrl: 'https://wultra.com/?exit=jailbreak' },
// Action defined when the debugger is detected. On top of default actions, you can specify the 'BLOCK' action
// that prevents the debugger from being connected to the process.
debugger: { action: 'BLOCK' },
// Action defined when the device's screen is being captured.
screenCapture: {
action: 'HIDE', // Hide the app screen
overlay: {
type: 'COLOR', // Use overlay with the specified color
color: {
red: 128,
blue: 0,
green: 0,
alpha: 255
}
}
},
// Action defined when reverse engineering tools are detected on the device.
reverseEngineeringTools: { action: 'EXIT' },
// Action triggered when an HTTP proxy is configured on the device.
httpProxy: { action: 'NOTIFY' },
// Action triggered when a VPN is active on the device.
vpn: { action: 'NOTIFY' },
// Action triggered when a repackaged app is detected. It's necessary to provide an array of BASE64 encoded signing certificates that signed the application's package.
// The default action is 'NO_ACTION'
repackage: {
action: "EXIT",
exitUrl: "https://wultra.com/?exit=repackage",
// Array with Base64 encoded certificates that are used to sign the app package.
trustedCertificates: ["BASE64"]
},
// Action defined when there's an ongoing call
call: {
action: "NOTIFY"
},
// Action triggered when the presence of an app from the list is detected.
appPresence: {
action: "NOTIFY",
apps: iosDetectableApps // Array with apps that can be detected. A predefined array can be obtained from the native SDK with await Malwarelytics.sharedInstance.getKnownDetectableApps()
}
},
// Optional configuration of the events collection.
events: {
// Way to disable event collection in general. The default value is `true`.
enableEventCollection: true,
// Event will be reported when the user takes a screenshot. The default value is `true`.
enableScreenshotTakenCollection: true
},
// Customer grouping is an advanced technique that is described in a separate section of this document.
customerGrouping: {
sourceBundleId: undefined,
appBundleId: undefined,
audienceGroupId: undefined
}
},
// The 'android' section configures Malwarelytics for the Android platform.
android: {
// The 'service' section defines the connection to Malwarelytics Service for the Android platform. You can obtain
// all configuration values in the Malwarelytics Console.
// If no service is provided, then Malwarelytics will work in offline mode. Be aware that the Antivirus module
// produces a lot of false-positive reports in such a configuration.
service: {
username: "your-username-for-android app",
password: "your-password-for-android app",
signaturePublicKey: "your-sign-pk-for-android-app",
environment: 'TEST' // Environment specific for the Android platform, overrides the global environment set above.
},
// The 'rasp' section defines the behavior of the RASP module for the Android platform. Most of the features support
// three basic actions - 'NO_ACTION' (SDK will do nothing), 'NOTIFY' - SDK will notify you via the listener,
// 'EXIT' - SDK will terminate your application. If 'EXIT' is specified then you can provide additional
// `exitUrl` that is opened in the browser after the application is closed.
// The typical default action is 'NOTIFY'.
rasp: {
// Behavior of emulator detection.
emulator: {
// Action defines behavior when the device is detected as an emulator.
action: 'NOTIFY'
},
// Behavior of root detection.
root: {
// Action defines behavior when the when the device is detected as rooted.
action: 'EXIT',
// Url to be opened outside the app when the app exits because of the detection.
exitUrl: "https://wultra.com?exit=root",
// Minimum confidence value of heuristic root detections that trigger app termination.
// Works only if action is 'EXIT'. Possible values are between 0.0 (inclusive) and 1.0 (inclusive).
// The default value is 1.0.
exitOnRootMinConfidence: 1.0
},
// Behavior of debugger detection.
debugger: {
// Action defines behavior when your app is being debugged.
action: 'NOTIFY'
},
// Behavior of repackaging detection.
repackage: {
// Action defines behavior when the repackaged app is detected.
action: 'EXIT',
// Url to be opened outside the app when the app exits because of the detection.
exitUrl: "https://wultra.com?exit=repackage",
// SHA-1 of signing certificate(s). One or more values can be set.
// Expecting lowercase hex value without any byte separators. No default value is set.
signatureHash: [ "HEXADECIMAL" ]
},
// Behavior of screen sharing detection.
screenSharing: {
// Action defines behavior when screen sharing is detected.
action: 'NOTIFY'
},
// Behavior of screenshot and screen recording blocking and detection feature.
screenshot: {
// Action defines the behavior of the screenshot blocking feature. It is blocked by default.
blockAction: 'BLOCK',
// Action defines behavior when a screenshot is detected. It is detected by default. The feature works only on Android 14+.
detectionAction: 'NOTIFY'
},
// Behaviour of screen reader detection.
screenReader: {
// Action defines the behavior of the blocking feature. It is blocked by default.
// Screen readers are blocked only when an enabled screen reader not allowed in the `allowedScreenReaders` config item is detected.
action: 'BLOCK',
// Defines collection of allowed screen readers. It is empty by default.
allowedScreenReaders: [
{
// Screen reader's package name
packageName: 'com.trusted.screenReader',
// SHA-1 hash of the app's signature. The signature hash is optional but recommended to use.
signatureHash: ''
}
]
},
// Behaviour of process name change feature.
processName: {
// Action defines the behavior of the feature. If a stealthy process name should be used. It is on by default.
action: 'USE_STEALTHY',
// Whether to use a custom process name. A random name is used otherwise.
customProcessName: undefined
},
// Behaviour of tapjacking protection feature.
tapjacking: {
// Action defines the behavior of the protection feature. If tapjacking should be blocked. It is on by default.
// Tapjacking is blocked only when a problematic app meets sensitivity criteria defined by `blockSensitivity` are present.
action: 'BLOCK',
// Defines sensitivity for blocking tapjacking. The default value is ThreatIndex.HIGHLY_DANGEROUS.
blockSensitivity: 'HIGHLY_DANGEROUS',
// Defines whether to ignore system apps in tapjacking blocking. The default value is false
ignoreSystemApps: true,
// Collection of apps that are allowed (they don't cause tapjacking to be blocked).
allowedTapjackingApps: [
{
// App's package name.
packageName: 'com.example.app',
// SHA-1 hash of the app's signature. The signature hash is optional.
signatureHash: undefined
}
]
},
// Behavior of HTTP proxy detection.
httpProxy: {
// Action defines the detection behavior when an HTTP proxy is configured on the device.
action: 'NOTIFY'
},
// Behavior of VPN detection.
vpn: {
// Action defines the detection behavior when a VPN is active on the device.
action: 'NOTIFY'
},
// Behavior of ADB detection feature.
adb: {
// Action defines the detection behavior when enabled ADB is detected.
action: 'NOTIFY'
},
// Behavior of active call detection.
activeCall: {
// Action defines the detection behavior when an active call is detected.
action: 'NOTIFY'
},
// Behavior of app presence detection.
appPresence: {
// Action defines the detection behavior when certain apps are detected.
action: 'NOTIFY',
// A collection of remote desktop apps the detection is looking for.
remoteDesktopApps: [
{
// A custom name to be used for the application.
displayName: 'AnyDesk',
// Package name (application ID) of the app.
packageName: 'com.anydesk.anydeskandroid',
// SHA-1 hash of the app's signature. The signature hash is optional.
signatureHash: undefined
}
]
},
// Whether to send outputs of RASP info methods
sendInfoOutputs: true
},
// Antivirus component configuration. If not set, default values are used.
antivirus: {
// Enable or disable Antivirus. The default is false.
disable: false,
// Malwarelytics in silent mode does not show any UI. The default is true.
enableSilentMode: true,
// How often will the antivirus database be checked (in hours). The default is 48 hours.
onlineCheckIntervalHours: 48,
// If database update should be performed on SDK initialize. The default is true.
updateOnInitialize: true
},
// ISO 639-1 language code that the app will be used for UI localization.
languageCode: 'en',
// Customer grouping is an advanced technique that is described in a separate section of this document.
customerGrouping: {
sourceBundleId: undefined,
appBundleId: undefined,
audienceGroupId: undefined
},
// Configuration of device fingerprinting.
fingerprint: "SAFE"
}
});
Customer Grouping and Naming
The SDK allows passing custom values that are used to group data in the Malwarelytics web console application.
The configuration items in android.customerGrouping
and android.customerGrouping
add extra metadata that is passed into the web console. The options allow you to split data into groups and obtain different views on the data.
Limitations for the strings are the following:
- Max length of the
sourceBundleId
/sourcePackageName
is 255 characters - Max length of the
appBundleId
/appPackageName
is 255 characters - Max length of the
audienceGroupId
/audienceGroupId
is 20 characters
The main grouping of the data is achieved with sourceBundleId
/sourcePackageName
. The value has to agree with the application credentials in the web console.
The extra granularity of data views is achieved with appBundleId
/appPackageName
.
The last option audienceGroupId
is used to distinguish users from different customer systems such as “RETAIL”, “CORPORATE” and so on.
Configuration change
Any configuration change of Malwarelytics for React Native requires releasing the Malwarelytics
instance and re-initializing with a new configuration. The AppProtection
instance can be released by calling:
Malwarelytics.sharedInstance.shutdown()
Malwarelytics for React Native cannot be used after release. It has to be re-initialized first.