1 of 4

React Native

📝 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
    }
}

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: ['your_signing_certificate_hash_base64'],
    supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
  },
  iosConfig: {
    appBundleId: 'com.awesomeproject',
    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 should be specified inside a JavaScript object.

// reactions for 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

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 constructor() method in the entry point to your app set listeners to threats and start freeRASP:

constructor(props) {
  super(props);

  // Add these method calls
  setThreatListeners(actions);
  talsecStart(config);
}

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.

Expo

freeRASP for React Native is a bare React Native plugin. When installing freeRASP into a project that uses Expo SDK, there may be extra configuration needed.

To integrate freeRASP into the Expo projects, follow the instructions for React Native. After that, continue on this page.

We provide a plugin config that sets up the dependencies of freeRASP without the need to eject the Expo project. It is recommended to use the plugin config. However, manual setup is also possible.

Plugin config setup

Add the plugin config to your app.json and specify the minSdkVersion (use at least 23). Additionally, if you are using Expo 50, increase the version of R8 above 8.2 with the R8Version property (to support sealed classes on Android).

"plugins":[
    [
        "freerasp-react-native/app.plugin.js",
        {
            "android":{
                "minSdkVersion":"23",
                "R8Version":"8.3.37" // optional for Expo 50
            }
        }
    ]
]

Manual setup

Increase minSdkVersion
This can be done in two ways:
- update the minSdkVersion property directly in android/build.gradle, or
- use expo-build-properties plugin, which updates the property in the prebuild phase. Read more in the Expo docs.
Add maven dependency
1. open android/build.gradle (if you don't see the android folder, run npx expo prebuild -p android in terminal to create it)
2. add the following dependency under allprojects > repositories:
  maven { url "https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp" }
3. if not already configured, add also:
  maven { url 'https://www.jitpack.io' }

API

Description of the freeRASP API

Types

`TalsecConfig`

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

field

type

description

sample value

`AndroidConfig`

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

field

type

description

sample value

`IOSConfig`

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

field

type

description

sample value

`NativeEventEmitterActions`

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

Actions

Hooks

`const useFreeRasp = (config: TalsecConfig, actions: NativeEventEmitterActions)`

React Custom Hook responsible for starting freeRASP and setting up listeners

Methods

`const setThreatListeners = async (config: NativeEventEmitterActions): void`

Sets up listeners for detected threats

`const talsecStart = async (options: TalsecConfig): Promise<string>`

Method is used to start freeRASP's audit. Returns 'freeRASP started'string when successful.

`const removeThreatListeners = (): void`

Unregisters threat listeners. Should be called only when the app is being terminated.

Troubleshooting

See the most frequent issues occurring during integration.

The most frequent issues occurring during integration:

General

Could not determine the dependencies of task ':freerasp-react-native:compileDebugAidl'

Solution:

In package.json, update react-native to a higher patch version and run npm install (or yarn install).

See this issue to find out which patch version is relevant for you.

Invalid hook call. Hooks can only be called inside of the body of a function component.

Reason: The useFreeRasp Hook cannot be called inside useEffect.

Solution:

If you want to initialize freeRASP inside useEffect, you have to handle the initialization on your own. Such inititialization would look like this:

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

...

useEffect(() => {
  setThreatListeners(actions);
  talsecStart(config);

  return () => {
    removeThreatListeners();
  };
}, []);

Where actions, config are objects described in the integration guide.

Android Devices

Execution failed for task ':freerasp-react-native:minifyReleaseWithR8'.

Sealed classes are not supported as program classes when generating class files.

Reason: Kotlin sealed classes are not supported in AGP 8.1 used by some versions of RN (currently 0.73.x)

Solution: Follow this comment on Google Issue Tracker, which also contains additional information about the issue.

iOS Devices

Unsupported Swift architecture

Reason: The arm64 macro is not set under Rosetta.

Solution: Go to <your_project>/node_modules/freerasp-react-native/ios/TalsecRuntime.xcframework/ios-arm64/TalsecRuntime.framework/Headers/TalsecRuntime-Swift.h and move the following code (lines 4 and 5 in the file) to the top of the file:

#ifndef TALSECRUNTIME_SWIFT_H
#define TALSECRUNTIME_SWIFT_H

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.

React Native

📝 Prerequisites

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

Android

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
    }
}

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

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

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: ['your_signing_certificate_hash_base64'],
    supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
  },
  iosConfig: {
    appBundleId: 'com.awesomeproject',
    appTeamId: 'your_team_ID',
  },
  watcherMail: 'your_email_address@example.com',
  isProd: true,
};

👷 Handle detected threats

Threat reactions should be specified inside a JavaScript object.

// reactions for 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

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.

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 constructor() method in the entry point to your app set listeners to threats and start freeRASP:

constructor(props) {
  super(props);

  // Add these method calls
  setThreatListeners(actions);
  talsecStart(config);
}

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

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

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.