⚛️React Native

Example: https://github.com/talsec/Free-RASP-ReactNative

📝 Prerequisites

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

Android

freeRASP requires a minimum SDK level of 23. React Native projects, by default, support even lower levels of minimum SDK. This creates an inconsistency we must solve by updating the minimum SDK level of the application:

From the root of your project, go to android > build.gradle.
In buildscript, update minSdkVersion to at least 23 (Android 6.0) or higher.

android/build.gradle

buildscript {
    ext {
      minSdkVersion 23
    }
}

Raise Kotlin version

Since freeRASP 4.0.0, it is necessary to raise version of Kotlin in your project. This applies for projects running on RN < 0.77.

From the root of your project, go to android > build.gradle (or equivalent).
In buildscript.ext, update kotlinVersion to at least 2.0.0 or higher.
In buildscript.dependencies, specify the same version forkotlin-gradle-plugin .

buildscript {
    ext {
        kotlinVersion = '2.0.0'
    }
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.0")
    }

Enable Screenshot and Screen Recording Detection

To detect screenshots and screen recordings , add the following permissions to your AndroidManifest.xml file inside the <manifest> root tag:

 <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
 <uses-permission android:name="android.permission.DETECT_SCREEN_RECORDING" />

Screenshot Detection is supported on Android 14 (API level 34) and higher. Screen Recording Detection is supported on Android 15 (API level 35) and higher.

To utilize active protection, you can use

import { blockScreenCapture } from 'freerasp-react-native';
await blockScreenCapture(true);

To receive whether the screen capture is blocked, you can use

import { isScreenCaptureBlocked } from 'freerasp-react-native';
const response = await isScreenCaptureBlocked();

For more details about all these screen capture methods, see Screen Capture.

iOS

freeRASP React Native plugin uses Pods. Navigate to the ios folder and run:

$ pod install

📦 Install the plugin

Install the plugin using your preferred package manager
npm
```
npm install freerasp-react-native
```
yarn
```
yarn add freerasp-react-native
```
Navigate to the ios folder and run:
```
$ pod install
```

⚙️ 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.

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

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.

FreeRASP provides a React Custom Hook that handles all required logic as registration of freeRASP, mounting and unmounting of listeners for you.

App.tsx

import { useFreeRasp } from 'freerasp-react-native';

// app configuration
const config = {
  androidConfig: {
    packageName: 'com.awesomeproject',
    certificateHashes: ['mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k='],  // replace with your release (!) signing certificate hash(es)
    supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
  },
  iosConfig: {
    appBundleId: 'com.awesomeproject',
    appTeamId: 'your_team_ID',
  },
  watcherMail: '[email protected]', // for Security Reports, Talsec Portal, Updates
  isProd: true,
};

isProd is a boolean flag that determines whether the freeRASP integration is in the Dev or Release version. If you want to learn more about isProd, visit this wiki section.

killOnBypass is a boolean flag that enables the freeRASP in-SDK reaction to kill the application if it detects any unwanted manipulation with the callback mechanisms. If you want to learn more about killOnBypass, visit this wiki section.

By providing your watcherMail, you consent to receive security reports, product updates, and other essential communications from Talsec. Learn more about the role of watcherMail.

👷 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 should be specified inside a JavaScript object.

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

🛡️ Start freeRASP

Start freeRASP to detect threats by calling the useFreeRasp hook, below the created config and the callback handler:

useFreeRasp(config, actions);

Please note that useFreeRasp Hook should be called outside useEffect.

When freeRASP initializes correctly, you should see freeRASP initialized message in the logs. Otherwise, you'll see a warning with a description of what went wrong.

You can override this default behaviour by extending the actions object with started key (to change action after successful initialization), and initializationError key (to set up action after unsuccessful initialization)

For the version you’re integrating, you can find the specific dSYMs for debugging in Releases.

Alternative: Initialize freeRASP in a Class component

Import methods from the freeRASP plugin:

import {
  talsecStart,
  setThreatListeners,
  removeThreatListeners,
} from 'freerasp-react-native';

Override componentDidMount() method in the entry point to your app set listeners to threats and start freeRASP:

async componentDidMount() {
  await setThreatListeners(actions);
  const response = await talsecStart(config);
  console.log(response); // freeRASP started
}

In this code snippet, actions is object with your reactions to threats and config is a freeRASP configuration object from previous parts of the readme.

Override componentWillUnmount() method where you clean up the listeners:

componentWillUnmount() {
  removeThreatListeners();
}

🌁 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:

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

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 React Native platform.

🖥️ Check Talsec Portal

Check out Data Visualisation Portal and register using your watcherMail to see your data. If you integrated the SDK successfully, the application will be present after a few hours. The visualisations will be active later due to the bucketing mechanism.

You have to use the same email for the Portal as you used for the watcherMail parameter.

PreviousTroubleshooting NextExpo

Last updated 9 days ago