Configuration
The minimum configuration for the Malwarelytics is setting up the username, password, and the public key in the malwarelytics.xml
(for each platform Android/iOS). 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 configured in malwarelytics.xml
. Different environments require different access credentials.
Configuring the Service
To enable Malwarelytics in your Cordova app, you need to call the initialize
method with the following configuration object. All properties are optional.
// Note that all the folowing configurations are optional, you can pass empty object {} and it will work.
// It is recommended to set your client id though to identify the user.
await window.plugins.malwarelytics.initialize({
clientId: "your-client-id", // To identify the user. Can be changed later.
deviceId: "your-client-id", // To identify the users phone. Can be changed later.
// Configuration for the Android platform
androidConfig: {
languageCode: "en", // Language of the UI (for smart protection)
antivirusConfig: { // Configuration of the antivirus component
enableSilentMode: false, // Silent mode enabled = no UI
onlineCheckIntervalHours: 48, // check for update every 48 hours
updateOnInitialize: true // the virus database will be updated on the startup
},
raspConfig: { // configiration of the Runtime Application Self Protection
emulator: {
action: "NOTIFY" // to enable observer reports, but don't exit when on emulator
},
root: {
action: "EXIT", // to exit when the device is rooted
exitUrl: "https://wultra.com", // web URL to be opened when the app is terminated
exitOnRootMinConfidence: 1 // exit only when we are sure
},
debugger: {
action: "EXIT", // to exit when a debugger is connected
exitUrl: "https://wultra.com", // web URL to be opened when the app is terminated
},
repackage: {
action: "EXIT", // to exit when the app is repackaged
exitUrl: "https://wultra.com", // web URL to be opened when the app is terminated
signatureHash: ["a9fe....6d94"] // hash of the apps signature (Base64-encoded SHA-1 hash)
},
screenSharing: {
action: "NOTIFY" // to enable observer reports, but don't exit when screen is shared
},
screenshot: {
action: "BLOCK" // to block screenshots
},
screenReader: {
action: "BLOCK", // disable screen readers
allowedScreenReaders: [{packageName: "com.google.android.marvin.talkback", signatureHash: "9b424c2d27ad51a42a337e0bb6991c76eca44461"}] // allowed screenreaders, when not set the default list of frequently used legitimate screenreaders is used
},
processName: {
action: "USE_STEALTHY" // use stealthy process name
customProcessName: "my.stealthy.packagename" // to use custom value, random value is used otherwise
},
tapjacking: {
action: "BLOCK", // to block tapjacking
blockTapjackingSensitivity: "HIGHLY_DANGEROUS", // block tapjacking for highly dangerous and malware apps
ignoreTapjackingSystemApps: false, // whether to ignore system apps in blocking tapjacking
allowedTapjackingApps: [] // list of apps capabale of tapjacking that will be ignored
},
httpProxy: {
action: "NOTIFY" // to enable observer reports
},
vpn: {
action: "NOTIFY" // to enable observer reports
},
adb: {
action: "NOTIFY" // to enable observer reports
},
activeCall: {
action: "NOTIFY" // to enable observer reports
}
},
customerGrouping: {
// customer grouping is advanced technique that is described in separated documentation topic
sourcePackageName: null,
appPackageName: null,
audienceGroupId: null
}
},
// Configuration for the Apple platform
appleConfig: {
raspConfig: { // configiration of the Runtime Application Self Protection
// when the device is jalibreaked, exit and show url
jailbreak: { action: "EXIT", exitUrl: "https://wultra.com?exit=jalibreak" },
// when debugger is connected, exit and show url
debugger: { action: "EXIT", exitUrl: "https://wultra.com?exit=debugger" },
// when reverse engineering tools are present, notify via the observer
reverseEngineeringTools: { action: "NOTIFY" },
// when HTTP proxy is on, notify via the observer
httpProxy: { action: "NOTIFY" },
// when the app is repackaged, exit and show url
repackage: { action: "EXIT", exitUrl: "https://wultra.com?exit=repackaged", base64EncodedTrustedCertificates: ["BASE64encodedcert"]},
// when screen is being captured, notify via the observer
screenCapture: { action: "NOTIFY" },
// when VPN is on, notify via the observer
vpnChanged: { action: "NOTIFY" },
// when there's an ongoing call, notify via the observer
callDetection: { action: "NOTIFY" }
},
onlineConfig: {
events: {
enableEventCollection: true, // enable event collection (like app turned on/off)
enableScreenshotTakenCollection: true // enable screenshot event collection
},
customerGrouping: {
// customer grouping is advanced technique that is described in separated documentation topic
sourceBundleId: null,
appBundleId: null,
audienceGroupId: null
}
}
}
});
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 MalwarelyticsConfig.android.customerGrouping
and MalwarelyticsConfig.android.customerGrouping
add extra metadata that is passed into the web console.
The data allow 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.