The most frequent issues occurring during integration:

For more general issues or questions, visit FAQ page. You can also check out the Issues section of our GitHub repository, where you can report issues and view existing reports.

📝 Prerequisites

The freeRASP has the following prerequisites that must be met before starting.

Android

The Android implementation uses Kotlin serialization plugin; following line has to be added to the plugins block in platforms/android/build.gradle:

plugins {
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.7.10'
}

freeRASP requires minSdkVersion level of >=23, targetSdkVersion level of >=31 and Kotlin support. Add the following lines to the config.xml file in your project root directory.

<preference name="GradlePluginKotlinEnabled" value="true" />
<preference name="GradlePluginKotlinCodeStyle" value="official" />
<preference name="GradlePluginKotlinVersion" value="1.7.10" />
<preference name="android-minSdkVersion" value="23" />
<preference name="android-targetSdkVersion" value="31" />
<preference name="android-compileSdkVersion" value="31" />

Then run the following command to apply the preferences:

$ cordova prepare android

iOS

freeRASP plugin uses Swift. Install the following plugin to support Swift in your project.

$ cordova plugin add cordova-plugin-add-swift-support --save

📦 Install the plugin

Install the plugin using Cordova CLI

cordova plugin add cordova-talsec-plugin-freerasp

⚙️ Setup the Configuration for your App

To ensure freeRASP functions correctly, you need to provide the necessary configuration and initialize it. All required values must be filled in for the plugin to operate properly. Use the following template to configure the plugin. Detailed descriptions of the configuration options are provided on the API page.

For Android apps, you must get your expected signing certificate hashes in Base64 form. You can go through this manual to learn how to sign your app in more detail, including manual signing and using Google's Play app signing.

In the the entry point to your app, import freeRASP and add the code below.

/* global cordova, talsec */

const config = {
    androidConfig: {
        packageName: 'com.example.helloapp',
        certificateHashes: ['your_signing_certificate_hash_base64'],
        supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
    },
    iosConfig: {
        appBundleIds: 'com.example.helloapp',
        appTeamId: 'your_team_ID'
    },
    watcherMail: 'your_email_address@example.com',
    isProd: true
};

👷 Handle detected threats

freeRASP executes periodical checks when the application is running. You can handle the detected threats using listeners. For example, you can log the event, show a window to the user or kill the application. See the Threat detection in the wiki to learn more details about the performed checks and their importance for app security.

Threat reactions can be specified inside a JavaScript object, which is then passed into the initialization function:

// reactions to detected threats
const actions = {
    // Android & iOS
    privilegedAccess: () => {
        console.log('privilegedAccess');
    },
    // Android & iOS
    debug: () => {
        console.log('debug');
    },
    // Android & iOS
    simulator: () => {
        console.log('simulator');
    },
    // Android & iOS
    appIntegrity: () => {
        console.log('appIntegrity');
    },
    // Android & iOS
    unofficialStore: () => {
        console.log('unofficialStore');
    },
    // Android & iOS
    hooks: () => {
        console.log('hooks');
    },
    // Android & iOS
    deviceBinding: () => {
        console.log('deviceBinding');
    },
    // Android & iOS
    secureHardwareNotAvailable: () => {
        console.log('secureHardwareNotAvailable');
    },
    // Android & iOS
    systemVPN: () => {
        console.log('systemVPN');
    },
    // Android & iOS
    passcode: () => {
        console.log('passcode');
    },
    // iOS only
    deviceID: () => {
        console.log('deviceID');
    },
    // Android only
    obfuscationIssues: () => {
        console.log('obfuscationIssues');
    },
    // Android only
    devMode: () => {
        console.log('devMode');
    },
    // Android only
    adbEnabled: () => {
        console.log('adbEnabled');
    }
};

🛡️ Start freeRASP

freeRASP can be started after the Cordova initialization is completed, for example, inside the onDeviceReady function in the index.js.

talsec.start(config, actions)
    .then(() => {
        console.log('Talsec initialized.');
    })
    .catch((error) => {
        console.log('Error during Talsec initialization: ', error);
    });

🌁 Enable source code obfuscation

The easiest way to obfuscate your app is via code minification, a technique that reduces the size of the compiled code by removing unnecessary characters, whitespace, and renaming variables and functions to shorter names. It can be configured for Android devices in android/app/build.gradle like so:

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }
}

Additionally, create or extend proguard-rules.pro in android/app folder and exclude Cordova’s specific classes that rely on package names from being obfuscated:

-keep class org.apache.cordova.** {*;}
-keep public class * extends org.apache.cordova.CordovaPlugin
-flattenpackagehierarchy

Please note that some other modules in your app may rely on reflection, therefore it may be necessary to add corresponding keep rules into proguard-rules.pro file.

If there is a problem with the obfuscation, freeRASP will notify you about it via obfuscationIssues callback.

Read more about why this is important in the wiki.

☢️ (Optionally) Integrate freeMalwareDetection

freeMalwareDetection is a powerful feature designed to enhance the security of your Android application by quickly and efficiently scanning for malicious or suspicious applications (e.g. Android malware) based on various blacklists and security policies.

It helps to detect apps with suspicious package names, hashes, or potentially dangerous permissions.

Visit the freeMalwareDetection repository to learn more about this feature! For the integration, refer to the integration guide for the Cordova platform.

Types

TalsecConfig

Specifies configuration for your app. See the table below for detailed description of the attributes.

AndroidConfig

Specifies configuration for instances of the app running on Android devices. See the table below for detailed description of the attributes.

IOSConfig

Specifies configuration for instances of the app running on Android devices. See the table below for detailed description of the attributes.

NativeEventEmitterActions

Specifies a set of callbacks that are used to notify the application when certain security threat is detected.

Actions

Methods

const start = async (config: FreeraspConfig, eventListenerConfig: NativeEventEmitterActions): Promise<void>

Method is used to start freeRASP's audit and set up listeners for threats.