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.

• 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

• Unity

freeRASP is currently tested and compatible with:

• 🤖 Android smartphones, tablets, emulators, Android TVs

• 🍎 iPhones, iPads, simulators

Discover freeRASP

Integration

Integrate freeRASP for your platform

Security Reports

Learn about regular security reports

License

How is freeRASP licensed

Commercial Subscriptions

Get maximum protection for your app

User Data Policies

Learn how we process your data

Community [Apply to Join!]

Space for developer's creativity, community programs

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 freeMalwareDetection, 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 intended for development purposes. It allows you to work on your app without interference from security features that could disrupt the process, e.g. if you would implement killing of the application on the debugger callback.

The Release version is meant for production and must always be used for your published app. It enables all security protections provided by freeRASP.

To configure this, set the isProd flag in freeRASP:

• Release: isProd = true

• Dev: isProd = false

⚠️Dev version 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 Appropriate Version to Continue Integration

Choose the relevant section based on your app development platform:

Android

iOS

Flutter

React Native

Cordova

Capacitor

Unity

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

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" />

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

Config via settings.gradle:

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 = uri("https://jitpack.io") }
    maven { url = uri("https://europe-west3-maven.pkg.dev/talsec-artifact-repository/freerasp") }
}

Config via build.gradle:

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 = uri ("https://jitpack.io") }
    maven { url = uri ("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:15.1.0'
}

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

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. Set up the Configuration for your app with your values, which are explained in more detail in API.

   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="
       ) // Replace with your release (!) signing certificate hash(es)
       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

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 to learn more details about the performed checks and their importance for app security.

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

   For the onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) callback, make sure you visit freeMalwareDetection, a powerful feature designed to scan for malicious or suspicious apps.

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. Modify initialization of ThreatListener:

   TalsecApplication.kt

   Copy

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

4. (Optional) 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" />

   To utilize active protection, you can use Talsec.blockScreenCapture(activity, true). To receive whether the screen capture is blocked, you can use the Talsec.isScreenCaptureBlocked(). For more details about all these screen capture methods, see Screen Capture. Integration of all these methods should be performed at the Application level to best address the Android lifecycle:

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

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

Read more about why this is important in the wiki.

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.

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

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

Sends callbacks to your app when a threat is detected. Read more about the meaning of the callbacks in the wiki.

Methods:

• void onRootDetected()

• void onDebuggerDetected()

• void onEmulatorDetected()

• void onTamperDetected()

• void onUntrustedInstallationSourceDetected()

• void onHookDetected()

• void onDeviceBindingDetected()

• void onObfuscationIssuesDetected()

• void onScreenshotDetected()

• void onScreenRecordingDetected()

public interface DeviceState

Provides device state listener to get additional information about device state. Read more about the meaning of the device state listeners in the wiki.

Methods:

• void onUnlockedDeviceDetected()

• void onHardwareBackedKeystoreNotAvailableDetected()

• void onDeveloperModeDetected()

• void onADBEnabledDetected()

• void onSystemVPNDetected()

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.

📦 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
       /// [DEPRECATED] 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
   }

📱(Optionally) Add screenshot and screen capture blocking

To utilize active screen shot and screen capture (e.g. mirroring, screen recording) protection, you can use Talsec.blockScreenCapture(enable: Bool, window: UIWindow) with specific UIWindow on which it should be blocked. To receive whether the screen capture is blocked in the specific UIWindow, you can use the Talsec.isScreenCaptureBlocked(in window: UIWindow). For more details about all these screen capture methods, see Screen Capture.

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

public static func blockScreenCapture(enable: Bool, window: UIWindow)

• The method blocks the screen capture in specific UIWindow.

public static func isScreenCaptureBlocked(in window: UIWindow) -> Bool

• The method returns whether the screen capture is blocked in specific UIWindow.

public static func storeExternalId(externalId: String)

• The method stores an externalId into the logs for data collection.

Protocols

public protocol SecurityThreatHandler

Methods

func threatDetected(_ securityThreat: TalsecRuntime.SecurityThreat)

• Notifier about detected threats.

Enums

public enum SecurityThreat : String, Codable, CaseIterable, Equatable

Provides all types of threats detected by freeRASP. Read more about the meaning of the threats in the wiki.

Cases

• signature

• jailbreak

• debugger

• runtimeManipulation

• passcode

• simulator

• missingSecureEnclave

• systemVPN

• deviceChange

• deviceID

• unofficialStore

• screenshot

• screenRecording

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.

📝 Prerequisites

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

• Minimum SDK level: 23 or higher

• Gradle version: 8.12.1 or higher

• Compile SDK version: 35

• Kotlin version: 2.1.0

Android

Some versions of Flutter projects, by default, support lower levels of minimum SDK or Gradle version.

Update minimum SDK and compile SDK level :

• 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 {
    compileSdk 35
    // ... some other declarations ...
    defaultConfig {
        minSdkVersion 23
        // ... some other declarations ...
    }
}

Update Gradle and Kotlin version:

• From the root of your project, go to android > settings.gradle

• In plugins

  • Update version of com.android.application plugin to 8.8.1

  • Update version of org.jetbrains.kotlin.android plugin to 2.1.0

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.8.1" apply false
    id "org.jetbrains.kotlin.android" version "2.1.0" apply false
}

In older projects using imperative approach, the paths may be different:

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

• In dependencies , update version of com.android.tools.build:gradle dependecy to 8.8.1

dependencies {
    classpath 'com.android.tools.build:gradle:8.8.1'    
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}

Then you also need to update gradle wrapper:

• From the root of your project, go to android > gradle> wrapper > gradle-wrapper.properties

• In distributionUrl update version to 8.12.1

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.12.1-all.zip

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" />

To utilize active protection, you can use await Talsec.instance.blockScreenCapture(enabled: true). To receive whether the screen capture is blocked, you can use the await Talsec.instance.isScreenCaptureBlocked(). For more details about all these screen capture methods, see Screen Capture.

iOS

Xcode 15 is required to be able to build the application

📦 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

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. 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 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: [
        'mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k='
      ], // Replace with your release (!) signing certificate hash(es)
      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 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.

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"),
      onScreenshot: () => print("Screenshot"),
      onScreenRecording: () => print("Screen recording"),
  );

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

To remove the rule, you need to find freerasp in your cache folder. More about where to find the cache folder here. Then navigate to the freerasp-X.Y.Z/android/build.gradle file and delete the line:

consumerProguardFiles 'consumer-rules.pro'

Read more about why obfuscation 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 Flutter platform.

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

📦 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

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.

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

More about signing hash and how to obtain it in Getting Signing Certificate Hash.

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

More about bundle ID and how to obtain one: FlutterFlow Documentation | App Deployment.

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

1. Go to the website: https://developer.apple.com/account.

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

The freeRASP Action offers multiple callbacks for handling threats. A callback is an Action that gets triggered when a threat is detected.

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.

Visit Threat detection to learn more details about the performed checks and their importance for app security.

Limitations

Limited configuration

freeRASP for Flutter allows you to define multiple values for:

• Signing certificate hash

• Supported app store

• Bundle ID

Due to FlutterFlow's limitations, the current implementation of freeRASP for FlutterFlow only allows you to specify a single value for each of these attributes. If want to provide more values, you can download the code and adjust those parameters manually (see Flutter)

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

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

A class which represents a set of callbacks that are used to notify the application when certain security threat is detected. Read more about the meaning of the callbacks in the wiki.

Methods

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

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

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

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" />

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

  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: ['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: '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');
  },
  // Android & iOS
  screenshot: () => {
    console.log('screenshot');
  },
  // Android & iOS
  screenRecording: () => {
    console.log('screenRecording');
  },
};

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

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

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 = async (): void

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

const blockScreenCapture = async (enable: boolean): Promise<string>

const isScreenCaptureBlocked = async (): Promise<boolean>

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

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, compileSdkVersion level of >=34, and Kotlin support.

Since freeRASP 8.0.0, it is also necessary to raise version of Kotlin above 2.0.0 in your project.

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="2.0.0" />
<preference name="android-minSdkVersion" value="23" />
<preference name="android-targetSdkVersion" value="31" />
<preference name="android-compileSdkVersion" value="34" />

Then run the following command to apply the preferences:

$ cordova prepare android

Enable Screenshot and Screen Recording Detection

To detect screenshots and screen recordings , add the following permission to your Android Manifest (via config.xml):

 <platform name="android">
  <config-file target="AndroidManifest.xml" parent="/*">
   <uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
   <uses-permission android:name="android.permission.DETECT_SCREEN_RECORDING" />
  </config-file>
</platform>

To utilize active protection, you can use

await talsec.blockScreenCapture(true);

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

const response = await talsec.isScreenCaptureBlocked();

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

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: ['mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k='],  // Replace with your release (!) signing certificate hash(es)
        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');
    },
    // Android & iOS
    screenshot: () => {
      console.log('screenshot');
    },
    // Android & iOS
    screenRecording: () => {
      console.log('screenRecording');
    },
};

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

const blockScreenCapture = async (enable: boolean): Promise<string>

const isScreenCaptureBlocked = async (): Promise<boolean>

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

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) or higher.

ext {
    minSdkVersion 23
 }

Raise Kotlin version

Since freeRASP 2.0.0, it is necessary to raise version of Kotlin in your project.

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

• In buildscript.ext, update kotlin_version to at least 2.0.0 or higher.

buildscript {
    ext {
        kotlin_version = '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" />

To utilize active protection, you can use

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

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

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

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

📦 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: ['mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k='], // Replace with your release (!) signing certificate hash(es)
    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');
  },
  // Android & iOS
  screenshot: () => {
    console.log('screenshot');
  },
  // Android & iOS
  screenRecording: () => {
    console.log('screenRecording');
  },
};

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

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.

const blockScreenCapture = async (enable: boolean): Promise<boolean>

const isScreenCaptureBlocked = async (): Promise<boolean>

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

📝 Prerequisites

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

• Unity Editor level: 6 or higher

• Minimum SDK level: 23 or higher

📦 Install Plugin

First, you'll need to install freeRASP for Unity. Head over to [Github Unity Plugin Release Link] and download the latest plugin. The plugin file should have a .unitypackage extension.

Next, import the plugin into your Unity project: right-click on Assets → Import Package → Custom Package.

Android (freeRASP for Android v15.1.0)

⚙️ Set Up the Configuration for Your App

To ensure freeRASP works properly, you need to configure and initialize it with the required settings. All necessary values must be provided for the plugin to function correctly. Detailed explanations of each configuration option are available on the Android API documentation page.

The first step involves obtaining your app's signing certificate hashes in Base64 format. Refer to the provided manual for comprehensive guidance on app signing, which covers both manual signing methods and Google Play's app signing service.

In this guide, we'll create the Game.cs script (see our sample) attached to a GameObject to initialize freeRASP and configure reactions. You can use any other scripts in your business logic that are initiated when the app starts.

In the Game.cs (or your app’s entry point), import freeRASP and add the following code:

using UnityEngine;

public class Game : MonoBehaviour
{
    // Start is called once before the first execution of Update after the MonoBehaviour is created
    void Start()
    {
        bool isProd = true;
        string watcherMailAddress = "your_mail@example.com";

        // Android related configs
        string expectedPackageName = "com.unity.rasp.game";
        string[] expectedSigningCertificateHashBase64 = new string[] { "Tmac/QIomCqEGS1jYqy9cMMrqaitVoZLpjXzCMnt55Q=" };
        string[] supportedAlternativeStores = new string[] { "com.sec.android.app.samsungapps" };

        // initialize talsec
        TalsecPlugin.Instance.initAndroidTalsec(expectedPackageName, expectedSigningCertificateHashBase64, 
        supportedAlternativeStores, watcherMailAddress, isProd);
        TalsecPlugin.Instance.setAndroidCallback(this); // set Android callback
    }

    // Update is called once per frame
    void Update()
    {

    }
}

👷 Handle detected threats

To receive threat notifications, implement the AndroidThreatDetectedCallback interface. It contains multiple methods that are triggered when freeRASP periodically scans the device for security threats. Implement these methods within your game logic or main application class.

// Implementation of AndroidThreatDetectedCallback interface
public void onRootDetected()
{
    Debug.Log("Unity - Root detected");
}

public void onTamperDetected()
{
    Debug.Log("Unity - Tamper detected");
}

public void onDebuggerDetected()
{
    Debug.Log("Unity - Debugger detected");
}

public void onEmulatorDetected()
{
    Debug.Log("Unity - Emulator detected");
}

public void onObfuscationIssuesDetected()
{
    Debug.Log("Unity - Obfuscation issues detected");
}
public void onScreenshotDetected()
{
    Debug.Log("Unity - Screenshot detected");
}

public void onScreenRecordingDetected()
{
    Debug.Log("Unity - Screen recording detected");
}

public void onUntrustedInstallationSourceDetected() {
    Debug.Log("Unity - Untrusted installation source detected");
}

public void onHookDetected() {
    Debug.Log("Unity - Hook detected");
}

public void onDeviceBindingDetected() {
    Debug.Log("Unity - Device binding detected");
}

public void onUnlockedDeviceDetected() {
    Debug.Log("Unity - Unlocked device detected");
}

public void onHardwareBackedKeystoreNotAvailableDetected() {
    Debug.Log("Unity - Hardware backed keystore not available detected");
}

public void onDeveloperModeDetected() {
    Debug.Log("Unity - Developer mode detected");
}

public void onADBEnabledDetected() {
    Debug.Log("Unity - ADB enabled detected");
}

public void onSystemVPNDetected() {
    Debug.Log("Unity - System VPN detected");
}

Add freeRASP Maven Repository

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

    repositories {
        google()
        mavenCentral()

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

        flatDir {
            dirs "${project(':unityLibrary').projectDir}/libs"
        }
    }
}

iOS (freeRASP for iOS v6.11.0)

⚙️ Set Up the Configuration for Your App

To ensure freeRASP works properly, you need to configure and initialize it with the required settings. All necessary values must be provided for the plugin to function correctly. Detailed explanations of each configuration option are available on the iOS API documentation page.

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

using System;
using UnityEngine;
using System.Collections;
using System.Collections.Generic;

public class Game : MonoBehaviour
{
    // Start is called once before the first execution of Update after the MonoBehaviour is created
    void Start()
    {
        // common configs
        bool isProd = true;
        string watcherMailAddress = "your_mail@example.com";

        // iOS related configs
        string[] appBundleIds = new string[] { "com.unity.freeRASP" };
        string teamId = "TEAM ID";

        // initialize talsec
        TalsecPlugin.Instance.initiOSTalsec(appBundleIds, teamId, watcherMailAddress, isProd);
        TalsecPlugin.Instance.setiOSCallback(this); // set callback
    }

}

👷 Handle detected threats

To receive threat notifications, implement the IOSThreatDetectedCallback interface. It contains multiple methods that are triggered when freeRASP periodically scans the device for security threats. Implement these methods within your game logic or main application class.

// Implementation of IOSThreatDetectedCallback interface
public void signatureDetected() {
Debug.Log("Signature detected");
}

public void jailbreakDetected() {
Debug.Log("Jailbreak detected");
}

public void debuggerDetected() {
Debug.Log("Debugger detected");
}

public void runtimeManipulationDetected() {
Debug.Log("Runtime manipulation detected");
}

public void passcodeDetected() {
Debug.Log("Passcode detected");
}

public void passcodeChangeDetected() {
Debug.Log("Passcode change detected");
}

public void simulatorDetected() {
Debug.Log("Simulator detected");
}

public void missingSecureEnclaveDetected() {
Debug.Log("Unity - Missing secure enclave detected");
}

public void deviceBindingDetected() {
Debug.Log("Device binding detected");
}

public void unofficialStoreDetected() {
Debug.Log("Unofficial store detected");
}

public void systemVPNDetected() {
Debug.Log("System VPN detected");
}

public void screenshotDetected() {
Debug.Log("Screenshot detected");
}

public void screenRecordingDetected() {
Debug.Log("Screen recording detected");
}

public void deviceIDDetected() {
Debug.Log("Device ID detected");
}

Add freeRASP

Once you are done with your game in Unity Hub; proceed to export the project. Once exported, open up the project in Xcode and add freeRASP dependency:

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

   (select v6.11.0: https://github.com/talsec/Free-RASP-iOS/tree/v6.11.0/Talsec)

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 (https://github.com/talsec/Free-RASP-iOS/releases/tag/v6.11.0).

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 Fair Usage Policy: 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, AppiCrypt®.

For further details, please refer to the next page.

AppiCrypt®

One of the most valued commercial features is AppiCrypt® - 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 talsec.app.

Plans Comparison

freeRASP is freemium software, i.e. there is a Fair Usage Policy (FUP) that imposes some limitations on free usage.

Get your price for premium products.