react-native-malwarelytics/src/MalwarelyticsConfig.ts

Malwarelytics for React Native protects your banking or fintech app from a broad range of mobile security threats with an industry-leading mobile threat intelligence solution.

//
// Copyright 2023 Wultra s.r.o.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions
// and limitations under the License.
//

import type { Apk } from "./model/antivirus/Apk"
import type { ThreatIndex } from "./model/antivirus/ApkThreat"
import type { DebuggerType } from "./model/rasp/DebuggerInfo"

// ---------------------------------------------------------------------------------------
//
//                                     C O M M O N
//
// ---------------------------------------------------------------------------------------

/**
 * Configuration for Malwarelytics Module.
 */
export interface MalwarelyticsConfig {
    /**
     * Configuration for Apple Services.
     */
    apple?: MalwarelyticsAppleConfig
    /**
     * Configuration for Android Services.
     */
    android?: MalwarelyticsAndroidConfig
    /**
     * Configures client or device's identification if this information is available in the
     * time of Malwarelytics module initialization.
     */
    clientIdentification?: MalwarelyticsClientIdentification
    /**
     * Server environment. The default value is "PRODUCTION".
     */
    environment?: MalwarelyticsServiceEnvironment
}

/**
 * Configuration for connection to Malwarelytics service.
 */
export interface MalwarelyticsServiceConfig {
    /**
     * Username for the Malwarelytics service.
     */
    username: string
    /**
     * Password for the Malwarelytics service.
     */
    password: string
    /**
     * Signature public key for the Malwarelytics service. Default value is undefined.
     */
    signaturePublicKey?: string
    /**
     * Server environment configured per platform. If set, then this value overrides the 
     * value set in the root of the configuration.
     */
    environment?: MalwarelyticsServiceEnvironment
}

/**
 * Defines Malwarelytics Service Environment:
 * - `"TEST"` - Test environment.
 * - `"PROD"` - Production environment.
 * 
 * Note that using test environment will cause a warning print in the debug console.
 */
export type MalwarelyticsServiceEnvironment = "TEST" | "PRODUCTION"

/**
 * Configuration for user or device identifiers in case that
 * such information is available in case of Malwarelytics initialization.
 */
export interface MalwarelyticsClientIdentification {
    /**
     * Client's identifier.
     */
    clientId?: string
    /**
     * Device's identifier.
     */
    deviceId?: string
}

// ---------------------------------------------------------------------------------------
//
//                              A P P L E   Specific
//
// ---------------------------------------------------------------------------------------

/** 
 * Configuration of the Malwarelytics SDK for the Apple platform. 
 */
export interface MalwarelyticsAppleConfig {
    /**
     * Configures connection to the remote Malwarelytics service. If no service is provided,
     * then module will work in offline mode.
     */
    service?: MalwarelyticsServiceConfig
    /** 
     * RASP component configuration. If not set, default values are used. 
     */
    rasp?: MalwarelyticsAppleRaspConfig;
    /**
     * Configuration of the events that are sent to the server. 
     */
    events?: MalwarelyticsAppleEventsConfig;
    /**
     * Configuration of customer grouping and naming in the Malwarelytics web console.
     */
    customerGrouping?: MalwarelyticsAppleCustomerGroupingConfig;
}

/** 
 * Configuration of the RASP features on the Apple platforms 
 */
export interface MalwarelyticsAppleRaspConfig {
    /** 
     * Jailbreak detection configuration. The default action is `NOTIFY`.
     */
    jailbreak?: MalwarelyticsAppleBasicDetectionConfig;
    /**
     * Debugger detection configuration. The default action is `NOTIFY`. 
     */
    debugger?: MalwarelyticsAppleDebuggerDetectionConfig;
    /** 
     * Reverse engineering tools presence detection configuration. The default action is `NOTIFY`.
     */
    reverseEngineeringTools?: MalwarelyticsAppleBasicDetectionConfig;
    /** 
     * HTTP proxy detection configuration. The default action is `NOTIFY`. 
     */
    httpProxy?: MalwarelyticsAppleBasicDetectionConfig;
    /**
     * Repackaging detection configuration. The default action is `NO_ACTION` with empty array of certificates.
     */
    repackage?: MalwarelyticsAppleRepackagingDetectionConfig;
    /** 
     * Screen capturing detection. The default action is `NOTIFY`. 
     */
    screenCapture?: MalwarelyticsAppleScreenCaptureDetectionConfig;
    /**
     * VPN detection config. The default value is `NOTIFY`.
     */
    vpn?: MalwarelyticsAppleBasicDetectionConfig;
    /**
     * Call detection config. The default value is `NOTIFY`.
     */
    call?: MalwarelyticsAppleSimpleDetectionConfig;
    /**
     * App presence detection. 3rd party app presence. 
     * The default value is `.manual` with empty array of apps.
     */
    appPresence?: MalwarelyticsAppleAppPresenceDetectionConfig;
}

/**
 * Configuration of the events collection. 
 */
export interface MalwarelyticsAppleEventsConfig {
    /** 
     * Way to disable event collection in general. The default value is `true`. 
     */
    enableEventCollection?: boolean;
    /**
     * Event will be reported when user takes a screenshot. The default value is `true`.
     */
    enableScreenshotTakenCollection?: boolean;
}

/** 
 * Configuration of customer grouping and naming in the Malwarelytics web console. 
 */
export interface MalwarelyticsAppleCustomerGroupingConfig {
    /**
     * Set custom source bundle identifier.
     * The value has to match application credentials defined in the web application.
     *
     * Maximum length of the value is 255 characters.
     */
    sourceBundleId?: string;
    /**
     * Set app bundle identifier to obtain extra granularity
     * of the information displayed in the web application.
     * Distinguishes application purposes or segmentation in one organization.
     *
     * Maximum length of the value is 255 characters.
     */
    appBundleId?: string;
    /**
     * Set audience group ID to obtain extra granularity
     * of the information displayed in the web application.
     * Distinguishes users from different customer systems (RETAIL, CORPORATE, ...).
     *
     * Maximum length of the value is 20 characters.
     */
    audienceGroupId?: string;
}


/**
 * Configuration of the repackaging detection behavior 
 */
export interface MalwarelyticsAppleRepackagingDetectionConfig {
    /** 
     * Behavior of the repackaging detection 
     */
    action: MalwarelyticsAppleDetectionAction;
    /** 
     * Trusted certificates for ad-hoc or enterprise distribution.
     * 
     * This is needed only for non-production distribution.
     * 
     * How to retrieve the certificate:
     * 1. Open the Keychain Access application.
     * 2. Find a certificate that will be used to sign your application, for example, “Apple Development: Jan Tester (c)”.
     * 3. Right-click on the item and click “Export…”.
     * 4. Export the certificate in the .cer format.
     * 5. Open up the terminal and cd into the folder with your exported certificate.
     * 6. Encode the certificate in Base64 with cat your_exported.cer | base64.
     */
    trustedCertificates?: [string];
    /**
     * This URL will be open in the default browser when app is terminated in case that the `action` is `EXIT`. 
     */
    exitUrl?: string;
}


/** 
 * Configuration of the basic detection behavior 
 */
export interface MalwarelyticsAppleBasicDetectionConfig {
    /**
     * Behavior of the detection
     */
    action: MalwarelyticsAppleDetectionAction;
    /** 
     * This URL will be open in the default browser when app is terminated in case that the `action` is `EXIT`.
     */
    exitUrl?: string;
}

/**
 * Configuration of the debugger detection behavior 
 */
export interface MalwarelyticsAppleDebuggerDetectionConfig {
    /**
     * Behavior of the debugger detection
     */
    action: MalwarelyticsAppleDebuggerDetectionAction;
    /**
     * This URL will be open in the default browser when app is terminated in case that the `action` is `EXIT`. 
     */
    exitUrl?: string;
}

/**
 * Configuration of the screen capture detection behavior.
 */
export interface MalwarelyticsAppleScreenCaptureDetectionConfig {
    /** Behavior of the detection */
    action: MalwarelyticsAppleScreenCaptureDetectionAction;
    /** This URL will be open in the default browser when app is terminated in case that the `action` is `EXIT`. */
    exitUrl?: string;
    /** Overlay that will be displayed when screen capture is detected in case that the `action` is `HIDE`. */
    overlay?: MalwarelyticsAppleOverlay;
}

/** 
 * Configuration of the simple detection behavior. 
 */
export interface MalwarelyticsAppleSimpleDetectionConfig {
    /** 
     * Behavior of the detection 
     */
    action: MalwarelyticsAppleSimpleDetectionAction;
}

/**
 * Configuration of the app presence detection behavior.
 */
export interface MalwarelyticsAppleAppPresenceDetectionConfig {
    /** 
     * Behavior of the detection 
     */
    action: MalwarelyticsAppleAppPresenceDetectionAction;
    /** 
     * Applications that can be detected on the phone if present. 
     */
    apps: MalwarelyticsAppleDetectableApp[]; 
}

/**
 * Configuration of application that can be detected on the phone if present.
 */
export interface MalwarelyticsAppleDetectableApp {
    deeplinkProtocols: string[];
    name: string;
    category: MalwarelyticsAppleDetectableAppCategory;
    tag?: string;
}

/** 
 * Configuration of the screen capture overlay. 
 */
export interface MalwarelyticsAppleOverlay {
    type: MalwarelyticsAppleOverlayType;
    color?: MalwarelyticsAppleColor;
    image?: MalwarelyticsAppleImage;
}

/**
 * UIColor abstraction for configuration.
 */
export interface MalwarelyticsAppleColor {
    red: number;
    green: number;
    blue: number;
    alpha: number;
}

/**
 * UIImage abstraction for configuration.
 */
export interface MalwarelyticsAppleImage {
    name: string;
}

/**
 * Category of MalwarelyticsAppleDetectableApp
 * REMOTE_DESKTOP - Remote desktop apps are apps that can screen cast phone screen.
 */
export type MalwarelyticsAppleDetectableAppCategory = "REMOTE_DESKTOP"

/**
 * NO_ACTION - do nothing
 * NOTIFY - notify via the observer
 * BLOCK - block the debugger
 * EXIT - exit the app
 */
export type MalwarelyticsAppleDebuggerDetectionAction = "NO_ACTION" | "NOTIFY" | "BLOCK" | "EXIT";

/**
 * NO_ACTION - do nothing
 * NOTIFY - notify via the observer
 * EXIT - exit the app
 */
export type MalwarelyticsAppleDetectionAction = "NO_ACTION" | "NOTIFY" | "EXIT";

/**
 * NO_ACTION - do nothing
 * NOTIFY - notify via the observer
 * HIDE - hide app's content with an overlay when screen capture is detected
 * EXIT - exit the app
 */
export type MalwarelyticsAppleScreenCaptureDetectionAction = "NO_ACTION" | "NOTIFY" | "HIDE" | "EXIT";

/**
 * NO_ACTION - do nothing
 * NOTIFY - notify via the observer
 */
export type MalwarelyticsAppleSimpleDetectionAction = "NO_ACTION" | "NOTIFY";

/**
 * MANUAL - automatic detection is turned off, you can do a manual check
 * NOTIFY - notify via the observer
 */
export type MalwarelyticsAppleAppPresenceDetectionAction = "MANUAL" | "NOTIFY"

/**
 * DEFAULT - default cover with a solid color and an application icon
 * COLOR - cover with a solid color
 * IMAGE - cover with an image
 */
export type MalwarelyticsAppleOverlayType = "DEFAULT" | "COLOR" | "IMAGE";

// ---------------------------------------------------------------------------------------
//
//                             A N D R O I D   Specific
//`
// ---------------------------------------------------------------------------------------

/**
 * Configuration of the Malwarelytics SDK for the Android platform. 
 */
export interface MalwarelyticsAndroidConfig {
    /**
     * Configures connection to the remote Malwarelytics service. If no service is provided,
     * then module will work in offline mode.
     */
    service?: MalwarelyticsServiceConfig
    /**
     * ISO 639-1 language code that the app will be used for UI localization. 
     */
    languageCode?: string;

    /**
     * Antivirus component configuration. If not set, default values are used.
     */
    antivirus?: MalwarelyticsAndroidAntivirusConfig;

    /** 
     * RASP component configuration. If not set, default values are used. 
     */
    rasp?: MalwarelyticsAndroidRaspConfig;

    /**
     * Configuration of customer grouping and naming in the Malwarelytics web console.
     */
    customerGrouping?: MalwarelyticsAndroidCustomerGroupingConfig;

    /**
     * Configuration of device fingerprinting.
     */
    fingerprint?: MalwarelyticsAndroidFingerprintType;
}

/**
 * Configuration of customer grouping and naming in the Malwarelytics web console. 
 */
export interface MalwarelyticsAndroidCustomerGroupingConfig {
    /**
     * Set custom source package name.
     * The value has to match application credentials defined in the web application.
     *
     * Maximum length of the value is 255 characters.
     */
    sourcePackageName?: string;
    /**
     * Set app app package name to obtain extra granularity
     * of the information displayed in the web application.
     * Distinguishes application purposes or segmentation in one organization.
     *
     * Maximum length of the value is 255 characters.
     */
    appPackageName?: string;
    /**
     * Set audience group ID to obtain extra granularity
     * of the information displayed in the web application.
     * Distinguishes users from different customer systems (RETAIL, CORPORATE, ...).
     *
     * Maximum length of the value is 20 characters.
     */
    audienceGroupId?: string;
}

/**
 * Type of device fingerprinting performed.
 */
export enum MalwarelyticsAndroidFingerprintType {
    /**
     * Fingerprinting is completely turned off on all devices.
     * No fingerprinting method is used.
     */
    NONE = "NONE",
    /**
     * Basic fingerprinting.
     *
     * Fingerprinting uses only some fingerprinting methods. Only the methods that are safe on all devices.
     */
    BASIC = "BASIC",
    /**
     * Safe fingerprinting.
     *
     * Using full fingerprinting on non-problematic device.
     * Using basic fingerprinting on problematic devices. Those are some Pixel devices with Android 14.
     */
    SAFE = "SAFE",
    /**
     * Full fingerprinting.
     *
     * Using all available fingerprinting methods.
     */
    FULL = "FULL"
}

/** 
 * Antivirus component configuration for Android platform
 */
export interface MalwarelyticsAndroidAntivirusConfig {
    
    /**
     * Disable or enable Antivirus. Default is false, so Antivirus is enabled.
     */
    disable?: boolean;
   
    /**
     * Malwarelytics in silent mode does not show any UI. Default is true.
     */
    enableSilentMode?: boolean;
        
    /**
     * How often will be antivirus database checked (hourly). Default is 48 hours.
     */
    onlineCheckIntervalHours?: number;

    /**
     * If databse update should be performend on SDK initialize. Default is true.
     */
    updateOnInitialize?: boolean;
}

/**
 * Configuration action for RASP detection.
 * - `'NO_ACTION'` - Do not check this type of RASP event.
 * - `'NOTIFY'` - Notify application via the RASP listener.
 * - `'EXIT'` - Exit application.
 */
export type MalwarelyticsAndroidRaspAction = 'NO_ACTION' | 'NOTIFY' | 'EXIT'

/**
 * Configuration action for RASP blocking feature.
 * - `'NO_ACTION'` - Do nothing.
 * - `'BLOCK'` - Block the feature.
 */
export type MalwarelyticsAndroidRaspBlockAction = 'NO_ACTION' | 'BLOCK'

/**
 * Configuration action for process name change feature.
 * - `'NO_ACTION'` - Do nothing.
 * - `'USE_STEALHY'` - Use stealthy process name.
 */
export type MalwarelyticsAndroidRaspProcessNameAction = 'NO_ACTION' | 'USE_STEALTHY'

/**
 * Configuration action for ADB detection.
 * - `'NOTIFY'` - Notify application via the RASP listener.
 * - `'EXIT'` - Exit application.
 */
export type MalwarelyticsAndroidRaspAdbDetectionAction = 'NOTIFY' | 'EXIT'

/**
 * Configuraiton action for simple RASP detection.
 * - `'NO_ACTION'` - Do not check this type of RASP event.
 * - `'NOTIFY'` - Notify application via the RASP listener.
 */
export type MalwarelyticsAndroidRaspSimpleDetectionAction = 'NO_ACTION' | 'NOTIFY'


/**
 * Configuration for RASP event detection.
 */
export interface MalwarelyticsAndroidRaspDetectionConfig {
    /**
     * Action to execute when particular RASP event is detected.
     */
    action: MalwarelyticsAndroidRaspAction
    /**
     * If action is 'EXIT', then this URL is opened on application's exit.
     */
    exitUrl?: string
}

/**
 * Configuration for ROOT RASP event detection.
 */
export interface MalwarelyticsAndroidRaspRootDetectionConfig extends MalwarelyticsAndroidRaspDetectionConfig {
    /**
     * 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?: number
}

/**
 * Configuration for Android debugger RASP event detection.
 */
export interface MalwarelyticsAndroidRaspDebuggerDetectionConfig extends MalwarelyticsAndroidRaspDetectionConfig {

    debuggerTypes?: DebuggerType[];
}

/**
 * Configuration for Repackaging RASP event detection.
 */
export interface MalwarelyticsAndroidRaspRepackageDetectionConfig extends MalwarelyticsAndroidRaspDetectionConfig {
    /**
     * One or more values of SHA-1 of signing certificate(s). To get the hash, follow instructions from 
     * [Obtaining Signature Hash](https://developers.wultra.com/components/malwarelytics-android/develop/documentation/Repackaging-Detection#obtaining-signature-hash) document.
     * 
     * Expecting lowercase hex value without any byte separators. No default value is set.
     */
    signatureHash?: string[];
}

/**
 * Configuration for RASP event detection.
 */
export interface MalwarelyticsAndroidRaspBlockConfig {
    /**
     * Action to execute when particular RASP event is detected.
     */
    action: MalwarelyticsAndroidRaspBlockAction
}

/**
 * Configuration for screen readers RASP detection.
 */
export interface MalwarelyticsAndroidRaspScreenReaderBlockConfig extends MalwarelyticsAndroidRaspBlockConfig {
    /** Defines collection of allowed screen readers. It is empty by default. */
    allowedScreenReaders?: Apk[];
}

/**
 * Configuration for process name change feature.
 */
export interface MalwarelyticsAndroidRaspProcessNameConfig {
    action: MalwarelyticsAndroidRaspProcessNameAction;
    customProcessName?: string;
}

/**
 * Tapjacking configuration.
 */
export interface MalwarelyticsAndroidRaspTapjackingBlockConfig extends MalwarelyticsAndroidRaspBlockConfig {
    /** 
     * Defines sensitivity for blocking tapjacking. The default value is ThreatIndex.HIGHLY_DANGEROUS. 
     */
    blockSensitivity?: ThreatIndex;

    /**
     * Define whether to ignore system apps in blocking tapjacking. The default value is false
     */
    ignoreSystemApps?: boolean;

    /**
     * List of allowed tapjacking-capable apps. User for fine-tuning tapjacking protection.
     * It enables to ignore apps that are capable of tapjacking. Use to get rid of false-positives.
     */
    allowedTapjackingApps?: Apk[];
}

/**
 * ADB configuration.
 */
export interface MalwarelyticsAndroidRaspAdbDetectionConfig {
    /** Behavior of the detection */
    action: MalwarelyticsAndroidRaspAdbDetectionAction;
    /** This URL will be open in the default browser when app is terminated in case that the `action` is `EXIT`. */
    exitUrl?: string;
}

/**
 * Simple detection configuration.
 */
export interface MalwarelyticsAndroidRaspSimpleDetectionConfig {
    /** Behavior of the detection */
    action: MalwarelyticsAndroidRaspSimpleDetectionAction;
}

/**
 * App presence configuration.
 */
export interface MalwarelyticsAndroidRaspAppPresenceDetectionConfig extends MalwarelyticsAndroidRaspDetectionConfig{
    /** List of apps that the SDK is looking for. 
     *  When not defined, the default list of remote apps from native SDK is used.
     */
    remoteDesktopApps?: MalwarelyticsAndroidRaspNamedApkItem[];
}

/** 
 * Configuration of app the presence of which should be checked. 
 */
export interface MalwarelyticsAndroidRaspNamedApkItem {
    /** Defined custom name to be used for the application. */
    displayName: String;
    /** Package name (application ID) of the app. */
    packageName: String;
    /** SHA-1 hash of the app's signature. The signature hash is optional. */
    signatureHash?: String;
}


/**
 * Runtime Application Self-Protection Configuration for Android platform
 */
export interface MalwarelyticsAndroidRaspConfig {

    /**
     * Emulator detection configuration. The default action is 'NOTIFY'. 
     */
    emulator?: MalwarelyticsAndroidRaspDetectionConfig;

    /**
     * Root detection configuration. The default action is 'NOTIFY'. 
     */
    root?: MalwarelyticsAndroidRaspRootDetectionConfig;
    
    /**
     * Debugger detection configuration. The default action is 'NOTIFY'. 
     */
    debugger?: MalwarelyticsAndroidRaspDebuggerDetectionConfig;
   
    /**
     * Repackaging detection configuration. The default action is 'NOTIFY'. 
     */
    repackage?: MalwarelyticsAndroidRaspRepackageDetectionConfig;
  
    /**
     * Screen sharing detection configuration. The default action is 'NOTIFY'. 
     */
    screenSharing?: MalwarelyticsAndroidRaspDetectionConfig;

    /** 
     * Turns on/off blocking taking screenshots and screen recording. The default action is 'BLOCK'.
     */
    screenshot?: MalwarelyticsAndroidRaspBlockConfig;

    /**
     * Screen readers detection. If no configuration is provided, then the default values 
     * are applied. See `MalwarelyticsAndroidRaspScreenReadersConfig` interface for more details.
     * The default action is 'BLOCK'.
     */
    screenReader?: MalwarelyticsAndroidRaspScreenReaderBlockConfig;

    /** 
     * Sets custom name to be used for the app process. The default action is 'USE_STEALTHY'.
     */
    processName?: MalwarelyticsAndroidRaspProcessNameConfig;

    /**
     * Tapjacking configuration. If no configuration is provided then the default values are applied.
     * See `MalwarelyticsAndroidRaspTapjackingConfig` interface for more details.
     * The default action is 'BLOCK'.
     */
    tapjacking?: MalwarelyticsAndroidRaspTapjackingBlockConfig;
 
    /**
     * HTTP proxy detection configuration. The default action is 'NOTIFY'. 
     */
    httpProxy?: MalwarelyticsAndroidRaspDetectionConfig;

    /**
     * VPN detection configuration. The default action is 'NOTIFY'. 
     */
    vpn?: MalwarelyticsAndroidRaspDetectionConfig;

    /**
     * ADB detection configuration. Be aware that there's no 'NO_ACTION' action, so this
     * detection is always ON.
     * 
     * The default action is 'NOTIFY'.
     */
    adb?: MalwarelyticsAndroidRaspAdbDetectionConfig;

    /**
     * Active call detection configuration. The default action is 'NOTIFY'.
     */
    activeCall?: MalwarelyticsAndroidRaspSimpleDetectionConfig;

    /**
     * App presence detection configuration. The default action is 'NOTIFY'.
     */
    appPresence?: MalwarelyticsAndroidRaspAppPresenceDetectionConfig;
}