Configuration
The minimum configuration for the Malwarelytics is setting up the username, password and the public key in 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 environments PRODUCTION
(default value) for production builds. And TEST
for development and test builds. The environment can be altered globally or on per-platform basis. Different environments require different access credentials.
Configuring the Malwarelytics
To enable Malwarelytics in your React Native app, you need to call the initialize
method with the following configuration object. All properties are optional:
import { Malwarelytics } from 'react-native-malwarelytics';
await Malwarelytics.sharedInstance.initialize({
// Global environment applied to both platforms. Default value is 'PRODUCTION'
environment: 'PRODUCTION',
// Following object provides optional client identification. If such values are not available at application's
// startup, then you can set it to Malwarelytics later. The purpose of identifiers are 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 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 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 Apple platform, overrides the global environment set above.
},
// The 'rasp' section defines behavior of RASP module for Apple platform. Most of the features supports
// 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 debugger is detected. On top of default actions you can specify 'BLOCK' action
// that prevents the debugger to be connected to the process.
debugger: { action: 'BLOCK' },
// Action defined when 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 defined when HTTP proxy is configured on the device.
httpProxy: { action: 'NOTIFY' },
// Action defined when VPN is active on the device.
vpn: { action: 'NOTIFY' },
// Action defined when repackaged app is detected. You have 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 used to sign app package.
trustedCertificates: ["BASE64"]
},
// Action defined when there's an ongoing call
call: {
action: "NOTIFY"
},
// Action defined when a presence of an app from the list is detected.
appPresence: {
action: "NOTIFY",
apps: iosDetectableApps // Array with apps that can be detected. 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 user takes a screenshot. The default value is `true`.
enableScreenshotTakenCollection: true
},
// Customer grouping is advanced technique that is described in separate section of this document.
customerGrouping: {
sourceBundleId: undefined,
appBundleId: undefined,
audienceGroupId: undefined
}
},
// The 'android' section configures Malwarelytics for Android platform.
android: {
// The 'service' section defines connection to Malwarelytics Service for 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 Antivirus module
// produces a lot of false-positive reports in such 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 Android platform, overrides the global environment set above.
},
// The 'rasp' section defines behavior of RASP module for Android platform. Most of the features supports
// 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 behaviour when the device is detected as an emulator.
action: 'NOTIFY'
},
// Behavior of root detection.
root: {
// Action defines behavior when the when 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 triggers 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 behaviour when your app is being debugged.
action: 'NOTIFY'
},
// Behavior of repackaging detection.
repackage: {
// Action defines behavior when 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 feature.
screenshot: {
// Action defines behavior of the blocking feature. It is blocked by default.
action: 'BLOCK'
},
// Behaviour of screen reader detection.
screenReader: {
// Action defines behavior of the blocking feature. It is blocked by default.
// Screen readers are blocked only when an enabled screen reader is detected that is not allowed in `allowedScreenReaders` config item.
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 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 behavior of the protection feature. If tapjacking should be blocked. It is on by default.
// Tapjacking is blocked only when a problematic apps meeting 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 blocking tapjacking. 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 behavior of the detection when a HTTP proxy is configured on the device.
action: 'NOTIFY'
},
// Behavior of VPN detection.
vpn: {
// Action defines behavior of the detection when a VPN is active on the device.
action: 'NOTIFY'
},
// Behavior of ADB detection feature.
adb: {
// Action defines behavior of the detection when enabled ADB is detected. Note that there's no 'NO_ACTION' option for adb.
action: 'NOTIFY'
},
// Behavior of active call detection.
activeCall: {
// Action defines behavior of the detectoin when active call is detected.
action: 'NOTIFY'
},
// Behavior of app presence detection.
appPresence: {
// Action defines behavior of the detection when app are detected.
action: 'NOTIFY',
// Collection of remote desktop apps the detection is looking for.
remoteDesktopApps: [
{
// Defined 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
}
]
}
},
// Antivirus component configuration. If not set, default values are used.
antivirus: {
// Enable or disable Antivirus. Default is false.
disable: false,
// Malwarelytics in silent mode does not show any UI. Default is true.
enableSilentMode: true,
// How often will be antivirus database checked (hourly). Default is 48 hours.
onlineCheckIntervalHours: 48,
// If databse update should be performend on SDK initialize. Default is true.
updateOnInitialize: true
},
// ISO 639-1 language code that the app will be used for UI localization.
languageCode: 'en',
// Customer grouping is advanced technique that is described in 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 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 Malwarelytics
instance and re-initializing with a new configuration. 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.