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: 'NOTIFY' },
            // 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"] 
            }
        },
        // 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: {
            // Action defined when device is detected as rooted.
            root: { 
                action: 'EXIT',
                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 
            },
            // Action defined when repackaged app is detected.
            repackage: {
                action: 'EXIT',
                // 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" ]
            },
            // Action defined when your app is running in emulator.
            emulator: { action: 'NOTIFY' },
            // Action defined when your app is being debugged.
            debugger: { action: 'NOTIFY' },
            // Action defined when presence of ADB is detected. Note that 'NO_ACTION' option is ignored.
            adb: { action: 'NOTIFY' },
            // 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 screen sharing is detected.
            screenSharing: { action: 'NOTIFY' },
            // Screen readers detection.
            screenReaders: {
                // Turn on/off blocking screen readers. It is on by default. 
                // Screen readers are blocked only when an enabled screen reader is detected that is not allowed in `allowedScreenReaders`. 
                block: true,
                // 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: ''
                    }
                ]
            },
            // Turns on/off blocking taking screenshots and screen recording. It is on by default.
            blockScreenshots: true,
            // Behaviour of tapjacking prevention
            tapjacking: {
                // Turn on/off blocking tapjacking. It is on by default. Tapjacking is blocked only when 
                // problematic apps meeting sensitivity criteria defined by `blockSensitivity` are present. 
                block: true,
                // 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
            },
            // Sets custom name to be used for the app process. When set, turns off `useStealthyProcessName`.
            customProcessName: undefined,
            // Whether to use a stealthy name for the app's process. It is on by default. 
            // When true a name is selected randomly from a list of stealthy process names. It is turned off when 
            // customProcessName is set.
            useStealthyProcessName: true
        },
        // 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
        }
    }
});

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.

Last updated on May 10, 2023 (11:33) View product
Search

1.0.x

Malwarelytics for React Native