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

🛡️ Start freeRASP

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

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

The most frequent issues occurring during integration:

For more general issues or questions, visit page. You can also check out the , where you can report issues and view existing reports.

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.

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.

The Dev version of freeRASP is intended for usage during the development phase. It serves the purpose of segregating development and production data, as well as disabling certain checks that are not applicable during the development process. These checks include:

• Emulator usage (onSimulator)

• Debugging (onDebug)

• Signing (onAppIntegrity)

• Unofficial store (onUnofficialStore)

• Obfuscation issues (onObfuscationIssues)

• Developer mode (onDevMode)

• ADB Enabled (onADBEnabled)

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

📝 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

📦 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: [
        '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 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")
  );

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

📝 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:13.0.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=",
           "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

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 onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) {
       println("onMalwareDetected")
   }

   Do not implement the onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) callback yet. It will be soon introduced as a new feature of freeRASP, although, it is implemented via this SDK as well. You can use just println("onMalwareDetected") for now.

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

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

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

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

constructor(props) {
  super(props);

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

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.

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.

Interfaces

public interface ThreatDetected

Methods:

• void onRootDetected()

• void onDebuggerDetected()

• void onEmulatorDetected()

• void onTamperDetected()

• void onUntrustedInstallationSourceDetected()

• void onHookDetected()

• void onDeviceBindingDetected()

• void onObfuscationIssuesDetected()

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:

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

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.

The most frequent issues occurring during integration:

General

Android Devices

iOS Devices

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 .

Manual setup

1. Increase minSdkVersion

   This can be done in two ways:

   • update the minSdkVersion property directly in android/build.gradle, or
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:

   3. if not already configured, add also:

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

📦 Install the plugin

Install the plugin using your preferred package manager

Synchronize the project files across native platforms

⚙️ Setup the Configuration for your App

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

👷 Handle detected threats

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

🛡️ Start freeRASP

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

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:

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.

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

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.

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.

The most frequent issues occurring during integration:

For more general issues or questions, visit page. You can also check out the , where you can report issues and view existing reports.

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.

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

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

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.

Then run the following command to apply the preferences:

iOS

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

📦 Install the plugin

Install the plugin using Cordova CLI

⚙️ Setup the Configuration for your App

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

👷 Handle detected threats

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

🛡️ Start freeRASP

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

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

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:

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.

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