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.

Variables

TalsecConfig

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

Classes

public class ThreatListener

Constructor

public ThreatListener(@NonNull ThreatDetected threatsCallback, @Nullable DeviceState deviceStateCallback)

• Listener for the threats detected by freeRASP

Methods

public void registerListener(Context context)

Registers your reactions to detected threats with freeRASP.

public void unregisterListener(Context context)

Unregisters the reactions to detected threats.

public final class Talsec

Methods

public static void start(Context context, TalsecConfig config)

The method used to start freeRASP's functionality.

public static void blockScreenCapture(Activity activity, boolean enable)

The method used to Block / Unblock screen Capture.

public static void isScreenCaptureBlocked()

The method used to Know the state of screen capture blocking whether blocked or not.

Interfaces

public interface ThreatDetected

Methods:

• void onRootDetected()

• void onDebuggerDetected()

• void onEmulatorDetected()

• void onTamperDetected()

• void onUntrustedInstallationSourceDetected()

• void onHookDetected()

• void onDeviceBindingDetected()

• void onObfuscationIssuesDetected()

• void onScreenshotDetected()

• void onScreenRecordingDetected()

public interface DeviceState

Methods:

• void onUnlockedDeviceDetected()

• void onHardwareBackedKeystoreNotAvailableDetected()

• void onDeveloperModeDetected()

• void onADBEnabledDetected()

• void onSystemVPNDetected()

The general flow of the integration can be decomposed into the following steps:

1. Conforming to the prerequisites, e.g. setting up Android minSdkVersion.

2. Adding the dependency.

3. Setting up the configuration for the application, e.g. package name or whether it is production or not (see #dev-vs-release-version).

4. Handling the detected threats (callbacks).

5. Starting the SDK.

6. Enabling the source code obfuscation.

7. Become familiar with Security Report, User Data Policies and License.

8. Looking at , to provide an additional layer of protection by detecting malware or suspicious applications.

9. Looking at Features and Pricing plans if you are interested in more advanced solutions to protect your application and business.

10. Reading through Wiki and FAQ, if you are interested in more detailed information about internal workings.

Dev vs Release version

The Dev version is used to not complicate the development process of the application, e.g. if you would implement killing of the application on the debugger callback. It disables some detections which won't be triggered during the development process:

• Emulator/Simulator

• Debugging

• Tampering/Repackaging

• Unofficial store/source

• Obfuscation issues

• Developer mode

• ADB Enabled

Choose the relevant section based on your app development platform:

freeRASP is a lightweight and easy-to-integrate mobile security library designed to protect apps from potential threats during the application's runtime. It contains multiple security checks, each aimed to cover possible attack vectors to ensure a high level of application security.

What does freeRASP do?

freeRASP provides protection against potentially dangerous behaviour, including the following:

• Using rooted or jailbroken devices (e.g., su, Magisk, unc0ver, check1rain, Dopamine).

• Reverse engineering attempts.

• Running hooking frameworks (e.g., Frida, Xposed or Shadow).

• Tampering or repackaging the application.

• Installing the app through untrusted methods/unofficial stores.

• Running the app in various emulators.

• Detecting Screenshot and Screen Recording attempts.

Advantages

• Reactions to various attacks and detected security threats via an API (callback mechanism).

• Simple integration.

• VPN and Developer Mode (Android) detection.

• ADB, Developer Mode, USB debugging detections.

• No significant effect on the app performance.

• Weekly security report via email indicating the security status of devices and app integrity.

• Fulfills OWASP MASVS-RESILIENCE requirements.

Limitations

• Limits of Fair Usage Policy (limited to 100k app downloads).

• Data collection from your app to Talsec DB.

• Security protections:

  • basic protection against root/jailbreak (including Magisk, Dopamine),

  • basic runtime reverse engineering controls,

  • basic runtime integrity controls.

• No overlay and accessibility services misuse protection.

Workflow scheme

Supported platforms

freeRASP is currently supported for:

• Android

• iOS

• Flutter

• React Native

• Cordova

• Capacitor

Discover freeRASP

📝 Prerequisites

freeRASP requires a minimum SDK level of 23. To update the minimum SDK level of the application, follow these steps:

1. From the root of your project (or module level), go to the build.gradle.

2. Update minSdkVersion to at least 23 (Android 6.0) or higher.

buildscript {
    ext {
      minSdkVersion 23
    }
}

📦 Add the dependency

Set Talsec's Artifact Registry in your project's settings.gradle (or build.gradle). You should comment out the relevant section in settings.gradle, if you want to use build.gradle, as settings.gradle is preferred:

repositories {
        google()
        mavenCentral()
        maven { url "https://jitpack.io"}
        maven { url "https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp" }
}

repositories {
    google()
    mavenCentral()
    maven { url "https://jitpack.io" }
    maven { url "https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp" }
}

Set dependencies in your :app module's build.gradle:

dependencies {
    // freeRASP SDK  
    implementation 'com.aheaditec.talsec.security:TalsecSecurity-Community:14.0.1'
}

⚙️ Setup the Configuration for your App

1. Create an arbitrary subclass of Application(), override its onCreate()method and implement ThreatListener.ThreatDetected interface. You can, of course, use your Application subclass if you already have one in your project. If you encounter issues importing ThreatListener.ThreatDetected, please use 'Sync Project with Gradle Files' to resolve them.“

   TalsecApplication.kt

   Copy

   class TalsecApplication : Application(), ThreatListener.ThreatDetected {
       override fun onCreate() {
           super.onCreate()
       }
   }

2. Add a new subclass to AndroidManifest.xml, inside <application> tag:

   AndroidManifest.xml

   Copy

   <application
       android:name=".TalsecApplication"
   />

3. TalsecApplication.kt

   Copy

   companion object {
       private const val expectedPackageName = "com.aheaditec.talsec.demoapp" // Don't use Context.getPackageName!
       private val expectedSigningCertificateHashBase64 = arrayOf(
           "mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k=",
           "ZjLPK1Dle5JS1aUu1NuNEVVXarMEsCXvni/Kv/FK+tw="
       ) // Replace with your release (!) signing certificate hashes
       private const val watcherMail = "john@example.com" // for Alerts and Reports
       private val supportedAlternativeStores = arrayOf(
           "com.sec.android.app.samsungapps" // Add other stores, such as the Samsung Galaxy Store
       )
       private val isProd = true
   }

   TalsecApplication.kt

   Copy

   override fun onCreate() {
       ...
       
       val config = TalsecConfig.Builder(
           expectedPackageName,
           expectedSigningCertificateHashBase64)
           .watcherMail(watcherMail)
           .supportedAlternativeStores(supportedAlternativeStores)
           .prod(isProd)
           .build()
   }

👷 Handle detected threats

1. Implement methods of ThreatListener.ThreatDetected interface:

   TalsecApplication.kt

   Copy

   override fun onRootDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onDebuggerDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onEmulatorDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onTamperDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onUntrustedInstallationSourceDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onHookDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onDeviceBindingDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onObfuscationIssuesDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onScreenshotDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onScreenRecordingDetected() {
       TODO("Not yet implemented")
   }
   
   override fun onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) {
       println("onMalwareDetected")
   }

2. Optionally, you can use a device state listener to get additional information about the device state, like passcode lock and HW-backed Keystore state:

   TalsecApplication.kt

   Copy

   private val deviceStateListener = object : ThreatListener.DeviceState {
       override fun onUnlockedDeviceDetected() {
           TODO("Not yet implemented")
       }
       override fun onHardwareBackedKeystoreNotAvailableDetected() {
           TODO("Not yet implemented")
       }
   
       override fun onDeveloperModeDetected() {
           TODO("Not yet implemented")
       }
       
       override fun onADBEnabledDetected() {
           TODO("Not yet implemented")
       }
   
       override fun onSystemVPNDetected() {
           TODO("Not yet implemented")
       }
   }

3. Optionally, you can integrate the screen capture methods to detect threats like screenshots - onScreenshotDetected() or screen recording - onScreenRecordingDetected(). If you do not implement the steps below, these detections will not work, in that case, you can just leave the implementations empty.

   To use onScreenshotDetected() you have to be on Android 14+ (API 34+). Also, the application needs the following permission:

   Copy

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

   To use onScreenRecordingDetected() you have to be on Android 15+ (API 35+). Also, the application needs the following permission:

   Copy

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

   TalsecApplication.kt

   Copy

   import android.view.WindowManager.SCREEN_RECORDING_STATE_VISIBLE
   import java.util.function.Consumer
   
   class TalsecApplication : Application(), ThreatListener.ThreatDetected {
       private var currentActivity: Activity? = null
       private var screenCaptureCallback: Activity.ScreenCaptureCallback? = null
       private val screenRecordCallback: Consumer<Int> = Consumer<Int> { state ->
           if (state == SCREEN_RECORDING_STATE_VISIBLE) {
               Talsec.onScreenRecordingDetected()
           }
       }
       
       override fun onCreate() {
           ...
           registerActivityLifecycleCallbacks(object : ActivityLifecycleCallbacks {
               override fun onActivityCreated(activity: Activity, bundle: Bundle?) {
   
                   // Set to 'true' to block screen capture
                   Talsec.blockScreenCapture(activity, false)
               }
   
               override fun onActivityStarted(activity: Activity) {
                   unregisterCallbacks()
                   currentActivity = activity
                   registerCallbacks(activity)
               }
   
               override fun onActivityResumed(activity: Activity) {}
               override fun onActivityPaused(activity: Activity) {}
   
               override fun onActivityStopped(activity: Activity) {
                   if (activity == currentActivity) {
                       unregisterCallbacks()
                       currentActivity = null
                   }
               }
   
               override fun onActivitySaveInstanceState(activity: Activity, bundle: Bundle) {}
               override fun onActivityDestroyed(activity: Activity) {}
           })
       }
       
       private fun registerCallbacks(activity: Activity) {
           if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
               screenCaptureCallback = Activity.ScreenCaptureCallback {
                   Talsec.onScreenshotDetected()
               }
               activity.registerScreenCaptureCallback(
                   baseContext.mainExecutor, screenCaptureCallback!!
               )
           }
   
           if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
               val initialState = activity.windowManager.addScreenRecordingCallback(
                   mainExecutor, screenRecordCallback
               )
               screenRecordCallback.accept(initialState)
           }
       }
       
       private fun unregisterCallbacks() {
           currentActivity?.let { activity ->
               if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE && screenCaptureCallback != null) {
                   activity.unregisterScreenCaptureCallback(screenCaptureCallback!!)
                   screenCaptureCallback = null
               }
   
               if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) {
                   activity.windowManager.removeScreenRecordingCallback(screenRecordCallback)
               }
           }
       }
   }

4. Modify initialization of ThreatListener:

   TalsecApplication.kt

   Copy

   override fun onCreate() {
       ...
       // ThreatListener(this).registerListener(this)
       ThreatListener(this, deviceStateListener).registerListener(this)
   }

🛡️ Start freeRASP

override fun onCreate() {
    ...
    Talsec.start(this, config)
}

🌁 Enable source code obfuscation

You can make sure that the obfuscation is enabled by checking the value of minifyEnabled property in your module's build.gradle file.

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

☢️ (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.

Currently, there are no commonly present issues solely for the Native iOS development platform. 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.

📦 Add the dependency

1. From GitHub, Copy Talsec folder into your Application folder.

2. Drag & drop the Talsec folder to your .xcworkspace.

3. Add TalsecRuntime framework to Target > Build Phases > Link Binary With Libraries.

4. In the General > Frameworks, Libraries, and Embedded Content choose Embed & Sign.

Note: In case you are using Carthage, the zipped version of the framework is included in the GitHub Releases.

⚙️ Setup the Configuration for your App

To ensure freeRASP functions correctly, you need to provide the necessary configuration. 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 AppDelegate import TalsecRuntime and add the following code (e.g., in the didFinishLaunchingWithOptions method.:

let config = TalsecConfig(
    appBundleIds: ["YOUR_APP_BUNDLE_ID"], 
    appTeamId: "YOUR TEAM ID", 
    watcherMailAddress: "WATCHER EMAIL ADDRESS", 
    isProd: true
)

👷 Handle detected threats

You can handle the detected events using handlers. For example, you can log the event, show a window to the user or kill the application. See the Threat detection to learn more details about the performed checks and their importance for app security.

1. Anywhere in your project (e.g. in AppDelegate), add the following code as an extension:

   AppDelegate.swift

   Copy

   import TalsecRuntime
   
   extension SecurityThreatCenter: SecurityThreatHandler {
       public func threatDetected(_ securityThreat: TalsecRuntime.SecurityThreat) {
           print("Found incident: \(securityThreat.rawValue)")
       }
   }

2. Use the code above for handling these types of events:

   TalsecRuntime

   Copy

   public enum SecurityThreat: String, Codable, CaseIterable, Equatable {
       /// app integrity / repackaging / tampering
       case signature = "appIntegrity"
       /// jailbreak
       case jailbreak = "privilegedAccess"
       /// debugger
       case debugger = "debug"
       /// runtime manipulation / hooks
       case runtimeManipulation = "hooks"
       /// disabled passcode
       case passcode
       /// passcode change
       case passcodeChange
       /// simulator
       case simulator
       /// missing Secure Enclave
       case missingSecureEnclave
       /// device binding
       case deviceChange = "device binding"
       /// changed deviceID
       case deviceID
       /// unofficial store or Xcode build
       case unofficialStore
       /// Detected system VPN
       case systemVPN
       /// screenshot
       case screenshot
       /// screen recording and screen mirroring
       case screenRecording
   }

🛡️ Start freeRASP

Invoke the following method right after setting up the TalsecConfig in previous steps.

...
let config = TalsecConfig(...)
Talsec.start(config: config)

Variables

TalsecConfig

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

Classes

public class Talsec

Methods

public static func start(config: TalsecRuntime.TalsecConfig)

• The method used to start freeRASP's audit.

Protocols

public protocol SecurityThreatHandler

Methods

func threatDetected(_ securityThreat: TalsecRuntime.SecurityThreat)

• Notifier about detected threats.

Enums

public enum SecurityThreat : String, Codable, CaseIterable, Equatable

Cases

• signature

• jailbreak

• debugger

• runtimeManipulation

• passcode

• simulator

• missingSecureEnclave

• systemVPN

• deviceChange

• deviceID

• unofficialStore

• screenshot

• screenRecording

Variables

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.

Methods

Future<void> start(TalsecConfig config)

Starts freeRASP with configuration provided in config.

void attachListener(ThreatCallback callback)

Attaches instance of ThreatCallback to freeRASP. If ThreatCallback is already attached, current one will be detached and replaced with callback. When threat is detected, respective callback of ThreatCallback is invoked.

Classes

ThreatCallback

Methods

This page provides you with all the necessary information about for . Please read it carefully. If you have a question, don't hesitate to .

📦 Install the plugin

In this section, you will implement the imported freeRASP Action.

1. On your app's initial page, navigate to the UI Builder.

2. On the right panel, click on Actions.

3. In the Action Flow Editor box, click Open.

4. In the newly opened window, click on On Page Load at the top.

5. Click Add Action (or + and then Add Action, if you already have an Action).

6. On the right panel, search for the runRASP Custom Action.

7. Select the runRASP Action.

⚙️ Setup the Configuration for your App

The freeRASP Action requires several arguments to be filled to function. Some data are related to specific platforms.

If you are developing the application exclusively for one platform, you can omit the configuration part related to the other platform. If you don't want to provide configuration to an unrelated platform, provide an empty string:

1. Click the orange variable icon next to the Value label

2. Scroll down to Constants

3. Click Constant to expand the dropdown menu

4. Select Empty String

Configuration parameters

watcherMail

watcherMail is an email address designated for receiving security reports. Ensure that the email address follows the strict name@domain.com format.

isProd

[Android] packageName

packageName is a unique identifier for your Android application.

You can find the packageName value for your application in FlutterFlow settings:

1. Navigate to Settings and Integrations.

2. Locate and select App Details.

3. In the textbox labelled Package Name, you will find the package name associated with your application.

[Android] signingCertHash

signingCertHash is a hash of the certificate of the key which was used to sign the application. The value of the hash must be encoded in Base64 form.

[Android] supportedStore (optional)

supportedStore is a third-party app store to which your application is uploaded. By including this store, freeRASP considers it as trusted source.

To add a store, add the package name of the store to the supportedStore list.

[iOS] bundleId

bundleId is a unique identifier for your iOS application.

[iOS] teamId

teamId is a unique identifier assigned to a development team enrolled in the Apple Developer Program.

You can find your teamId on the Apple Developer portal:

2. Log in using the account that is used to sign and release your app.

3. Scroll down to the Membership details section.

4. Look for the line labelled "Team ID" - the value of your team will be displayed there.

👷 Handle detected threats

To implement callback:

1. Open Action Flow Editor with runRASP action.

2. Open one of the dropdown menus labelled "onX" on the right panel (X for a given type of reaction, for example, onAppIntegrity)

3. In the Action Flow Editor box, click on Open.

4. Implement your reaction.

Limitations

Limited configuration

freeRASP for Flutter allows you to define multiple values for:

• Signing certificate hash

• Supported app store

• Bundle ID

Mobile support only

Currently, freeRASP supports only Android and iOS. When running the application in the FlutterFlow web client, freeRASP will not be initialized.

[Android] Minimal SDK level

The minimum required Android SDK level for freeRASP is 23. FlutterFlow applications have a minimum SDK level of 21 by default.

This creates some restrictions:

• Deploying the application from the FlutterFlow web client is not possible.

• Downloading the APK from the FlutterFlow web client is not supported.

To overcome these limitations, we recommend following these steps:

1. Download the code.

2. Manually raise the SDK level in the build.gradle file to 23.

3. Deploy the application using Google Play Console.

Raising SDK version

1. From the root of your project, go to android > app > build.gradle

2. In defaultConfig update minSdkVersion to at least 23 (Android 6.0) or higher

android {
...
defaultConfig {
    ...
    minSdkVersion 23
    ...
    }
...
}

📝 Prerequisites

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

Android

freeRASP requires a minimum SDK level of 23. Some versions of Flutter 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 > app > build.gradle.

• In defaultConfig, update minSdkVersion property to at least 23 (Android 6.0) or higher.

android {
    defaultConfig {
        minSdkVersion 23
    }
}

iOS

Xcode 15 is required to be able to build the application

Useful AppSec articles

📦 Install the plugin

Run the following command inside the project directory to add the freeRASP dependency:

flutter pub add freerasp

⚙️ Setup the Configuration for your App

In the entry point to your app, import freeRASP and add the following code:

import 'package:freerasp/freerasp.dart';

void main() {

  // This line is important!
  WidgetsFlutterBinding.ensureInitialized();

  // create a configuration for freeRASP
  final config = TalsecConfig(
    /// For Android
    androidConfig: AndroidConfig(
      packageName: 'your.package.name',
      signingCertHashes: [
        'AKoRu...'
      ],
      supportedStores: ['com.sec.android.app.samsungapps'],
    ),

    /// For iOS
    iosConfig: IOSConfig(
      bundleIds: ['YOUR_APP_BUNDLE_ID'],
      teamId: 'M8AK35...',
    ),
    watcherMail: 'your_mail@example.com',
    isProd: true,
  );
}

👷 Handle detected threats

freeRASP reacts to threats using ThreatCallback. Internally, each threat has its own callback (of VoidCallback type), which is called when a threat is detected.

import 'package:freerasp/freerasp.dart';

void main() {

  // Setting up callbacks
  final callback = ThreatCallback(
      onAppIntegrity: () => print("App integrity"),
      onObfuscationIssues: () => print("Obfuscation issues"),
      onDebug: () => print("Debugging"),
      onDeviceBinding: () => print("Device binding"),
      onDeviceID: () => print("Device ID"),
      onHooks: () => print("Hooks"),
      onPasscode: () => print("Passcode not set"),
      onPrivilegedAccess: () => print("Privileged access"),
      onSecureHardwareNotAvailable: () => print("Secure hardware not available"),
      onSimulator: () => print("Simulator"),
      onSystemVPN: () => print("System VPN"),
      onDevMode: () => print("Developer mode"),
      onADBEnabled: () => print("USB debugging enabled"),
      onUnofficialStore: () => print("Unofficial store")
  );

  // Attaching listener
  Talsec.instance.attachListener(callback);
}

🛡️ Start freeRASP

Start freeRASP to detect threats just by adding this line below the created config and the callback handler:

void main() async {

  // start freeRASP
  await Talsec.instance.start(config);
}

🌁 Enable source code obfuscation

In order to provide as much protection as possible, freeRASP enhances security measures by implementing ProGuard consumer rules, which obfuscate specific sections of the SDK. However, these rules are applied to your Android app code as well due to inheritance.

In certain cases, you may prefer to exclude this rule.

consumerProguardFiles 'consumer-rules.pro'

☢️ (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.

The most frequent issues occurring during integration:

General

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

...

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

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

Android Devices

iOS Devices

#ifndef TALSECRUNTIME_SWIFT_H
#define TALSECRUNTIME_SWIFT_H

The most frequent issues occurring during integration:

General

Android Devices

dependencies {
    ...
    // Talsec dependency
    implementation 'com.aheaditec.talsec.security:TalsecSecurity-Community-Flutter:<version>'
}

-keepclasseswithmembernames,includedescriptorclasses class * {
native ;
}

android:extractNativeLibs="true"

<application
    android:label="freerasp_example"
    android:icon="@mipmap/ic_launcher"
    android:extractNativeLibs="true">

iOS Devices

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.

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

1. 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.

2. 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:

      Copy

      maven { url "https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp" }

   3. if not already configured, add also:

      Copy

      maven { url 'https://www.jitpack.io' }

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

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

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

  Copy

  npm install freerasp-react-native

  yarn

  Copy

  yarn add freerasp-react-native

• Navigate to the ios folder and run:

  Copy

  $ 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.

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);

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.

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
}

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.

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

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.

📝 Prerequisites

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

Android

freeRASP for Android requires a minSdkVersion level of >=23 and a targetSdkVersion level of >=33. Some Capacitor projects, by default, support even lower levels of minimum and target SDKs. This creates an inconsistency we must solve by updating the SDK levels of the application:

• From the root of your project, go to android > variables.gradle (or equivalent).

• In ext, update minSdkVersion to at least 23 (Android 6.0) and compileSdkVersion to at least 33 (Android 13) or higher.

ext {
    minSdkVersion 23
    compileSdkVersion 33
 }

📦 Install the plugin

Install the plugin using your preferred package manager

$ npm install capacitor-freerasp

Synchronize the project files across native platforms

$ npx cap sync

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

import { startFreeRASP } from 'capacitor-freerasp';

// app configuration
const config = {
  androidConfig: {
    packageName: 'com.capacitor.example',
    certificateHashes: ['yourSigningCertificateHashBase64'],
    supportedAlternativeStores: ['com.sec.android.app.samsungapps'],
  },
  iosConfig: {
    appBundleId: 'com.capacitor.example',
    appTeamId: 'yourTeamID',
  },
  watcherMail: 'yourEmailAddress@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 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

Pass the configuration and reactions you set up in previous steps into startFreeRASP function.

// returns `true` if freeRASP starts successfully; you can ignore this value
const started = await startFreeRASP(config, actions);

Based on your framework, we recommend:

• In React: Wrap this function in useEffect with an empty dependency array

• In Vue: Call the method inside the mounted property

• In Angular: Call the method inside the ngOnInit method

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

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 Capacitor platform.

Currently, there are no commonly present issues solely for the Capacitor development platform. For more general issues or questions, visit page. You can also check out the , where you can report issues and view existing reports.

freeRASP collects anonymized security diagnostics data from apps. These data contain:

• Application state and security.

• Device state and security.

• Anonymous app instance ID and device ID.

This information allows Talsec to provide a , improve the freeRASP product and even the , or prepare mobile security reports and articles.

All the data collected by the freeRASP is technical diagnostics information and anonymous, but depending on the regulations applied, it could be considered sensitive and/or personal data.

Talsec recommends adding the statement below to the dedicated privacy policy page of your app. You can also use the text below while filling in the or publishing.

Google Play's Data Safety Policy

Google Play requires all app publishers to declare how they collect and handle user data for the apps they publish on Google Play. They should inform users properly of the data collected by the apps and how the data is shared and processed. Google will reject the apps which do not comply with the policy.

The checks for the Google Play and details about data are specified above in .

App Store User Data Policy

Apple requires that all app developers disclose their data collection and handling practices for apps published on the App Store. Developers must clearly inform users about the data their apps collect, as well as how this data is shared and processed. Apps that do not adhere to Apple's data privacy guidelines will be rejected.

To comply with the policy, in the App Privacy section, it is important to check the following:

• Identifiers -> Device ID -> App Functionality

  • Talsec Security SDK can not link the device identifier to the user

• Diagnostics -> Performance Data -> App Functionality, Other Purposes, No for linking to the user

• Diagnostics -> Other diagnostics data -> App Functionality, Other Purposes, No for linking to the user

• Other data -> App Functionality, No for linking to the user

  • Security diagnostics data (such as jailbreak)

Disclosure Screen

Google Play’s User Data policy indicates that a prominent disclosure should be presented to the users in case of an app collecting personal or sensitive data.

Although freeRASP collects diagnostical data (anonymous and not user-related), you (as the app publisher) should consider adding a disclosure screen, describing why the security diagnostic data is needed, what data, and how the data is used.

The Security Report is a weekly summary describing the application's security state and characteristics of the devices it runs on in a practical and easy-to-understand way.

The report provides a quick overview about

• Security incidents and their dynamics

• App Integrity

• Reverse engineering attempts

It also contains information about devices such as

• OS version

• Ratio of devices with lock screens

• Ratio of devices with biometrics

Each visualization also comes with a concise explanation. To receive Security Reports, you need to fill out the watcherMail correctly. There can be only one mail value set up.

If you want to learn about the differences between freeRASP and BusinessRASP+, you’re in the right place. On this page, we’ll explore the key features and benefits of each option, compare their functionalities, and highlight how the BusinessRASP+ subscription can offer enhanced capabilities and support compared to the freeRASP plan. By the end, you’ll have a clear understanding of which solution best meets your needs and how to make the most of it.

What are the advantages of the commercial Talsec SDK subscription plans compared to freeRASP?

freeRASP is a freemium product, which means there are Fair Usage Policy conditions (over 100k downloads) for using it. This means that we count the total number of downloads, where multiple downloads or updates from a single device are considered as one download. For using freeRASP, please refer to the .

and are premium products with a subscription model (which includes SW licenses, SLA, maintenance updates, and more) for SDKs. It is not SaaS, which means we don't introduce any dependency on third-party web services for your mobile solution.

Talsec doesn't collect any customer data within RASP+, while freeRASP SDK sends the diagnostical information to Talsec servers to provide clients with regular security reports and improve the product. You should consider adding Talsec to the list of Data Processors in case of freeRASP usage.

Top 10 Advantages of Talsec RASP+ Business Subscription Over freeRASP

Here are the top 10 benefits of choosing a Talsec RASP+ Business subscription, which includes an SDK license, SLA, and additional services, compared to the freeRASP option.

Types

FreeraspConfig

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 startFreeRASP = async (config: FreeraspConfig, reactions: NativeEventEmitterActions): Promise<bool>

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

const removeThreatListeners = (): void

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

Talsec offers enhanced features and benefits with our BusinessRASP+ plans, building on top of our freeRASP offering. Here’s what you can expect:

• No limitations of freeRASP's : Have an unrestricted number of app downloads* (beyond the 100k cap of freeRASP).

• No Data Collection to Talsec Database: Your app's data are sent to your data collection services. You can even disable data collection.

• FinTech Grade Security: Experience advanced security features and service level agreements (SLAs) tailored for the financial technology sector.

• Bypass Protection: Business RASP+ offers enhanced security with app-specific SDK customization, while freeRASP uses a universal binary that is more susceptible to bypass.

• Enhanced API Protection: Safeguard your APIs and benefit from risk scoring with our proprietary technology, .

For further details, please refer to the .

AppiCrypt®

One of the most valued commercial features is - App Integrity Cryptogram.

It allows easy-to-implement API protection and App Integrity verification on the backend to prevent API abuse:

• Bruteforce attacks

• Botnets

• API abuse by App impersonation

• Session-hijacking

• DDoS

It is a unified solution that works across all mobile platforms without dependency on external web services (i.e., without extra latency, an additional point of failure, and maintenance costs).

Learn more about commercial features at .

Plans Comparison

freeRASP is freemium software, i.e. there is a Fair Usage Policy (FUP) that imposes some limitations on free usage. See the FUP section in the table below

*The Fair Usage Policy refers to the total number of downloads, where multiple downloads or updates from a single device are counted as one download.

Stay up-to-date with the latest features, improvements and bug fixes for freeRASP. Here you'll find detailed information about each update we've rolled out, organized by platform. Whether you're using the Android, iOS, Flutter, React Native, Capacitor, or Cordova version, all platforms are supported.

Explore the tabs below to see what's new and how the experience has been improved for you. If you're looking for specific changes or features, each update is documented for your convenience.

Latest from Articles

What's new?

Changelog