freerasp 5.0.3

Flutter library for improving app security and threat monitoring on Android and iOS mobile devices. Learn more about provided features on the freeRASP's homepage first.

freeRASP for Flutter

freeRASP for Flutter is a mobile in-app protection and security monitoring SDK. It aims to cover the main aspects of RASP (Runtime App Self Protection) and application shielding.

📔 Table of contents

• Overview
• Usage
  • Step 1: Prepare freeRASP library
    • iOS setup
    • Android setup
  • Step 2: Setup the Configuration for your App
    • Dev vs Release version
  • Step 3: Handle detected threats
  • Step 4: Start the freeRASP
  • Step 5: Additional note about obfuscation
  • Step 6: User Data Policies
• Troubleshooting
• Security Report
• Commercial versions (RASP+ and more)
  • Plans comparison
• About Us
• License

Overview

The freeRASP is available for Flutter, Android, and iOS developers. We encourage community contributions, investigations of attack cases, joint data research, and other activities aiming to make better app security and app safety for end-users.

freeRASP SDK is designed to combat

• Reverse engineering attempts
• Re-publishing or tampering with the apps
• Running application in a compromised OS environment
• Malware, fraudsters, and cybercriminal activities

Key features are the detection and prevention of

• Root/Jailbreak (e.g., unc0ver, check1rain)
• Hooking framework (e.g., Frida, Shadow)
• Untrusted installation method
• App/Device (un)binding

Additional freeRASP features include low latency, easy integration and a weekly Security Report containing detailed information about detected incidents and potential threats, summarizing the state of your app security.

The commercial version provides a top-notch protection level, extra features, support and maintenance. 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
• 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 https://talsec.app.

Learn more about freemium freeRASP features at GitHub main repository.

Usage

We will guide you step-by-step, but you can always check the expected result in the example.

Step 1: Prepare freeRASP library

Add dependency to your pubspec.yaml file

dependencies:
  freerasp: 5.0.3

and run pub get

iOS setup

If you are upgrading from a previous version of freeRASP, please remove the old TalsecRuntime.xcframework and integration script from your project:

1. Go to your project's ios folder
2. Open Runner.xcworkspace in Xcode
3. On top bar select Runner -> Edit Scheme...
4. On the left side select Build -> Pre-actions
5. Find integration script and click trash icon on the right side to remove it
6. Open the .flutter-plugins (in the root folder of the app), and get the address, where the freerasp is installed.
7. Go to the given folder, and remove the freerasp folder file.
8. Delete .symlinks folder from project.
9. Run pub get
10. Run pod install to test it

Otherwise, no further setup is required.

Note: You need Xcode 13 to be able to build the application.

Android setup

• From root of your project, go to android > app > build.gradle
• In defaultConfig update minSdkVersion to at least 21 (Android 5.0) or higher

android {
...
defaultConfig {
    ...
    minSdkVersion 21
    ...
    }
...
}

Step 2: Setup the Configuration for your App

Add imports to the top of the file where you want to use Talsec:

import 'package:freerasp/freerasp.dart';

To properly configure freeRASP for your app, you need to initialize it with a configuration that contains relevant details about your app. In addition for freeRASP to work correctly, it is necessary that Flutter Bindings are initialized. This can be satisfied by calling WidgetsFlutterBinding.ensureInitialized(), as shown in the code snippet below.

void main() {
  ...

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

  // create configuration for freeRASP
  final config = TalsecConfig(
    /// For Android
    androidConfig: AndroidConfig(
      packageName: 'your.package.name',
      signingCertHashes: [
        'AKoRu...'
      ],
      supportedStores: ['some.other.store'],
    ),

    /// For iOS
    iosConfig: IOSConfig(
      bundleIds: ['YOUR_APP_BUNDLE_ID'],
      teamId: 'M8AK35...',
    ),
    watcherMail: '[e-mail]',
    isProd: true,
  );
}

Here, a TalsecConfig is created with both AndroidConfig and IOSConfig. Identifiers packageName and signingCertHashes are required for Android version.

• packageName - package name of your app you chose when you created it
• signingCertHashes - list of hashes of the certificates of the keys which were used to sign the application. At least one hash value must be provided. Hashes which are passed here must be encoded in Base64 form

We provide a handy util tool to help you convert your SHA-256 hash to Base64:

// Signing hash of your app
String base64Hash = hashConverter.fromSha256toBase64(sha256HashHex);

We strongly recommend using result value of this tool in signingCertHashes. Do not use this tool directly in signingCertHashes to get value. If you are not sure how to get your hash certificate, you can check out the guide on our Github wiki. .

Similarly, bundleIds and teamId are needed for iOS version of app. If you publish on the Google Play Store and/or Huawei AppGallery, you don't have to assign anything to supportedStores as those are supported out of the box.

Next, pass a mail address to watcherMail to be able to get reports. Mail has a strict form [e-mail] which is passed as String.

If you are developing only for one of the platforms, you can leave the configuration part for the other one, i.e., delete the other configuration.

Dev vs Release version

The Dev version is used during the development of the application. It separates development and production data and disables some checks which won't be triggered during the development process:

• Emulator-usage (onEmulatorDetected, onSimulatorDetected)
• Debugging (onDebuggerDetected)
• Signing (onTamperDetected, onSignatureDetected)
• Unofficial store (onUntrustedInstallationSource, onUnofficialStoreDetected)

Dev vs Release is currently managed using isProd flag in TalsecConfig class:

TalsecConfig(
   isProd: true,
   ...
)

isProd defaults to true when undefined. If you want to use the Dev version to disable checks described above, set the parameter to false. Make sure that you have the Release version in the production (i.e. isProd set to true)!

Step 3: Handle detected threats

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

void main() {
  ...

  // Setting up callbacks
  final callback = ThreatCallback(
      onAppIntegrity: () => print("App integrity"),
      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"),
      onUnofficialStore: () => print("Unofficial store")
  );

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

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

Step 4: Start the 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);
}

Step 5: Additional note about obfuscation

The freeRASP contains public API, so the integration process is as simple as possible. Unfortunately, this public API also creates opportunities for the attacker to use publicly available information to interrupt freeRASP operations or modify your custom reaction implementation in threat callbacks. In order for freeRASP to be as effective as possible, it is highly recommended to apply obfuscation to the final package/application, making the public API more difficult to find and also partially randomized for each application so it cannot be automatically abused by generic hooking scripts.

Android

The majority of Android projects support code shrinking and obfuscation without any additional need for setup. The owner of the project can define the set of rules that are usually automatically used when the application is built in the release mode. For more information, please visit the official documentation

• https://developer.android.com/studio/build/shrink-code
• https://www.guardsquare.com/manual/configuration/usage

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

android {
    ...

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

Step 6: User Data Policies

See the generic info about freeRASP data collection here.

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

Apple has a similar approach and specifies the types of collected data.

You should also visit our Android and iOS submodules to learn more about their respective data policies.

And you're done 🎉!

Troubleshooting

[Android] Could not find ... dependency issue

Solution: Add dependency manually ( see issue).

In android -> app -> build.gradle add these dependencies

dependencies {

 ... some other dependecies ...

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

[iOS] Unable to build release for simulator in Xcode (errors)

Solution: Simulator does not support release build of Flutter - more about it here. Use a real device in order to build the app in release mode.

[iOS] MissingPluginException occurs on hot restart

Solution: Technical limitation of Flutter - more about it here . Use command flutter run to launch app (i.e. run app from scratch).

[Android] Code throws java.lang.UnsatisfiedLinkError: No implementation found for... exception when building APK

Solution: Android version of freeRASP is already obfuscated.

Add this rule to your proguard-rules.pro file:

-keepclasseswithmembernames,includedescriptorclasses class * {
native ;
}

[iOS] Building using Codemagic fails: No such module 'TalsecRuntime'

Solution: You have to adjust Codemagic building pipeline. Instructions how to do it are here.

If you encounter any other issues, you can see the list of solved issues here, or open up a new one.

Security Report

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

The report provides a quick overview of the security incidents, their dynamics, app integrity, and reverse engineering attempts. It contains info about the security of devices, such as OS version or the ratio of devices with screen locks and biometrics. Each visualization also comes with a concise explanation.

To receive Security Reports, fill out the watcherMail field in Talsec config.

📊 Commercial versions (RASP+ and more)

We provide app security hardening SDK: i.e. AppiCrypt®, Customer Data Encryption (local storage), End-to-end encryption, Strings protection (e.g. API keys) and Dynamic Certificate Pinning to our commercial customers as well. To get the most advanced protection compliant with PSD2 RT and eIDAS and support from our experts, contact us at talsec.app.

The commercial version provides a top-notch protection level, extra features, support, and maintenance. 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
• 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 https://talsec.app.

TIP: You can try freeRASP and then upgrade easily to an enterprise service.

Plans Comparison

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

	freeRASP	Business RASP+
Runtime App Self Protection (RASP, app shielding)
Advanced root/jailbreak protections	basic	advanced
Runtime reverse engineering controls Debug Emulator Hooking protections (e.g. Frida)	basic	advanced
Runtime integrity controls Tamper protection Repackaging / Cloning protection Device binding protection Unofficial store detection	basic	advanced
Device OS security status check HW security module control Screen lock control	yes	yes
UI protection Overlay protection Accessibility services protection	no	yes
Hardening suite
Security hardening suite Customer Data Encryption (local storage) End-to-end encryption Strings protection (e.g. API keys) Dynamic certificate pinning	no	yes
AppiCrypt® - App Integrity Cryptogram
API protection by mobile client integrity check, online risk scoring, online fraud prevention, client App integrity check. The cryptographic proof of app & device integrity.	no	yes
Monitoring
AppSec regular email reporting	yes (up to 100k devices)	yes
Data insights and auditing portal	no	yes
Embed code to integrate with portal	no	yes
API data access	no	yes
Fair usage policy
Mentioning of the App name and logo in the marketing communications of Talsec (e.g. "Trusted by" section of the Talsec web or in the social media).	over 100k downloads	no
Threat signals data collection to Talsec database for processing and product improvement	yes	no

For further comparison details (and planned features), follow our discussion.

About Us

Talsec is an academic-based and community-driven mobile security company. We deliver in-App Protection and a User Safety suite for Fintechs. We aim to bridge the gaps between the user's perception of app safety and the strong security requirements of the financial industry.

Talsec offers a wide range of security solutions, such as App and API protection SDK, Penetration testing, monitoring services, and the User Safety suite. You can check out offered products at our web.

License

This project is provided as freemium software i.e. there is a fair usage policy that impose some limitations on the free usage. The SDK software consists of opensource and binary part which is property of Talsec. The opensource part is licensed under the MIT License - see the LICENSE file for details.