🚀Kotlin Multiplatform

💡 Example: https://github.com/talsec/Free-RASP-KMP/tree/main/example

👀 Understanding the Project Layout

The following structure outlines the critical directories and files you will interact with during the integration. The project is divided into the shared module (logic) and platform-specific modules (configuration).

Pay attention to the highlighted files, as these are the exact locations where you will apply changes in the upcoming steps.

[YourProjectName]/
├───build.gradle.kts                 
├───settings.gradle.kts              <-- Step 1: Add Dependency Repositories
├───gradle.properties            
├───gradle/
│   └───libs.versions.toml       
├───composeApp/      
│   ├───build.gradle.kts             <-- Step 1: Add Dependencies & Obfuscation
│   └───src/
│       ├───commonMain/          
│       │   └───kotlin/              <-- Step 3: Create SecurityManager.kt
│       ├───androidMain/         
│       │   ├───kotlin/
│       │   └───AndroidManifest.xml  <-- Step 2: Add Android Permissions
│       └───iosMain/             
│           └───kotlin/
└───iosApp/                  
    ├───iosApp.xcodeproj/            <-- Step 2: Link Frameworks in Xcode
    ├───iosApp/                  
    │   ├───ContentView.swift    
    │   └───iOSApp.swift         
    ├───TalsecBridge.xcframework/    <-- Step 2: Native iOS dependency
    └───TalsecRuntime.xcframework/   <-- Step 2: Native iOS dependency

📝 Prerequisites

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

Kotlin version: 2.2.0
Minimum Android Target SDK: API Level 23
Minimum iOS Deployment Target: 13.0

🚀 Integration Steps

📦 Dependency Setup

To enable the SDK, you must configure your project to access the required repositories and native binaries across all target platforms.

Update the settings.gradle.kts file to include the necessary URLs within the dependencyResolutionManagement block.

// File: settings.gradle.kts

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

Ensure that the XCFramework dependencies are correctly linked and available to the iOS target of your Kotlin Multiplatform project.

Download the TalsecRuntime.xcframework and TalsecBridge.xcframework to your local machine. These frameworks can be found either in the release assets or directly within the GitHub repository. It is crucial to ensure that you download the version corresponding to the current KMP library version you are using, regardless of which download option you choose.
- 👉 Click here to access the frameworks in the releases 👈
- 👉 Click here to get the frameworks in the repo👈

We recommend placing these files into the iosApp/ folder of your project

Navigate to the iosApp directory via terminal and launch the project in Xcode using the following commands:

cd iosApp
xed iosApp.xcodeproj

In Xcode, navigate to the Project Navigator (left sidebar) and select your project root.
- Select your application Target (usually named iosApp).
- Scroll down to the Frameworks, Libraries, and Embedded Content section and click the + button at the bottom of the list.
- In the dialog window, click the Add Other... button at the bottom left, then select Add Files... from the pop-up menu to browse your local storage.
- Locate and select both TalsecRuntime.xcframework and TalsecBridge.xcframework.
Once added, ensure that the Embed option for both frameworks is set to Embed & Sign.

Declare the dependencies in the build.gradle.kts file of your :app module:

// File: build.gradle.kts (:app)
kotlin {
    ...
    sourceSets {
        ...
        commonMain.dependencies {
            ...
            implementation("com.aheaditec.talsec.security:freeRASP_KMP:1.0.0")
            ...
        }
        ...
    }
}

🔐 Add Permissions to AndroidManifest.xml

Some checks require additional permissions in order to work properly. Add the following permissions to your AndroidManifest.xml file inside the <manifest> root tag. If your app already has these permissions, you don't need to add them again.

Some permissions also require runtime request.

Screenshot and Screen Recording Detection

To enable detection for screenshots and screen recordings, include these required permissions:

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

Support Limitations

Screenshot Detection is supported on Android 14 (API level 34) and higher.
Screen Recording Detection is supported on Android 15 (API level 35) and higher.

Location Spoofing Detection

To enable detection for location spoofing, include these required permissions:

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

Unsecure WiFi Detection

To enable detection for unsecure WiFi, include these required permissions:

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

Quick Copy

<uses-permission android:name="android.permission.DETECT_SCREEN_CAPTURE" />
<uses-permission android:name="android.permission.DETECT_SCREEN_RECORDING" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

⚙️ Application Configuration Setup

To ensure freeRASP functions correctly in a Kotlin Multiplatform environment, you need to provide the necessary configuration within the shared module. All required values must be filled in for the plugin to operate properly.

Create a Security Manager

It is recommended to encapsulate the configuration and initialization logic into a separate singleton object (e.g. SecurityManager). This keeps your UI code clean and makes the security logic reusable.

Create a new file in your common source set and define the configuration:

// File: composeApp/src/commonMain/kotlin/.../SecurityManager.kt

object SecurityManager {

    private val config = freeraspConfig(
        watcherMail = "[email protected]",
        androidConfig = AndroidConfig(
            packageName = "your.package.name",
            certificateHashes = listOf("mVr/qQLO8DKTwqlL+B1qigl9NoBnbiUs8b4c2Ewcz0k=")
        ),
        iosConfig = IOSConfig(
            bundleIds = listOf("your.bundle.id"),
            teamId = "YOUR_TEAM_ID"
        ),
        isProd = true,
        killOnBypass = true
    )
    
    // Initialization logic will be added in the next step
    suspend fun start(scope: CoroutineScope) {
        // ...
    }

}

Configuration Parameters

isProd - 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.
killOnBypass - a boolean flag that enables the freeRASP in-SDK reaction to kill the application if it detects any unwanted manipulation with the callback mechanisms.
watcherMail - By providing your watcherMail, you consent to receive security reports, product updates, and other essential communications from Talsec. Learn more about the role of watcherMail.

🧠 Handle Detected Threats

Once the configuration is ready, you need to start the monitoring service and listen for incoming threats.

Implement Monitoring Logic

Update your SecurityManager to start the freeRASP engine and handle the threatEvents flow.

// File: composeApp/src/commonMain/kotlin/.../SecurityManager.kt

suspend fun start(scope: CoroutineScope){
     FreeraspKMP.threatEvents.onEach { event ->
          when (event) {
            is FreeRaspEvent.AdbEnabled -> TODO()
            is FreeRaspEvent.AppIntegrity -> TODO()
            is FreeRaspEvent.Debug -> TODO()
            is FreeRaspEvent.DevMode -> TODO()
            is FreeRaspEvent.DeviceBinding -> TODO()
            is FreeRaspEvent.DeviceID -> TODO()
            is FreeRaspEvent.Malware -> TODO()
            is FreeRaspEvent.MultiInstance -> TODO()
            is FreeRaspEvent.ObfuscationIssues -> TODO()
            is FreeRaspEvent.Passcode -> TODO()
            is FreeRaspEvent.PrivilegedAccess -> TODO()
            is FreeRaspEvent.ScreenRecording -> TODO()
            is FreeRaspEvent.Screenshot -> TODO()
            is FreeRaspEvent.SecureHardwareNotAvailable -> TODO()
            is FreeRaspEvent.Simulator -> TODO()
            is FreeRaspEvent.SystemVPN -> TODO()
            is FreeRaspEvent.UnofficialStore -> TODO()
            is FreeRaspEvent.Hooks -> TODO()
            is FreeRaspEvent.AllChecksFinished -> TODO()
            is FreeRaspEvent.LocationSpoofing -> TODO()
            is FreeRaspEvent.TimeSpoofing -> TODO()
            is FreeRaspEvent.UnsecureWifi -> TODO()
            }
          }.flowOn(Dispatchers.IO)
              .launchIn(scope)
          
    try {
      FreeraspKMP.start(config)
      
      // Optional: Configure additional protections
      FreeraspKMP.blockScreenCapture(true)
    } catch (e: Exception) {
        println("Error starting freeRASP: ${e.message}")    
    }
}

Initialize in Entry Point

Finally, call the start method from your main UI entry point (e.g., App.kt) using a LaunchedEffect. This ensures monitoring begins as soon as the app launches.

// File: composeApp/src/commonMain/kotlin/.../App.kt

@Composable
fun App() {
    MaterialTheme {
    
        // Start security monitoring when the App composable enters the composition
        LaunchedEffect(Unit) {
            SecurityManager.start(this)
        }
        
        // ... Rest of your UI content
    }
}

🌁 How to Enable Source Code Obfuscation

Code obfuscation (minification) is a critical security step that reduces the size of the compiled code and renames classes and variables to make reverse engineering significantly more difficult.

To enable obfuscation for the Android target, update the build.gradle.kts file in your shared module (usually :composeApp or :androidApp):

// File: composeApp/build.gradle.kts

android {
    ...
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(getDefaultProguardFile("proguard-android.txt"),
             "proguard-rules.pro")
        }
    }
}

Important Notes

Reflection - Some other modules in your project may rely on reflection. If the app crashes after enabling obfuscation, you may need to add specific keep rules to your proguard-rules.pro file.
Obfuscation Callback - If there is an issue with the obfuscation configuration regarding freeRASP, the plugin will notify you via the obfuscationIssues callback.

👉 Read more about the importance of obfuscation in the wiki. 👈

☢️ Optional Module: freeMalwareDetection

freeMalwareDetection is a powerful feature designed to enhance the security of your Android application. It quickly and efficiently scans for malicious or suspicious applications (e.g., Android malware) based on various blacklists and security policies.

This feature helps to detect apps with suspicious package names, hashes, or potentially dangerous permissions.

This feature is available only for the Android platform.

To learn more about this feature and its integration, please refer to the official documentation.

👉 Go to freeMalwareDetection Documentation 👈

🖥️ Check Talsec Portal

Check out Data Visualisation Portal and register using your watcherMail to see your data. If you integrated the SDK successfully, the application will be present after a few hours. The visualisations will be active later due to the bucketing mechanism.

You have to use the same email for the Portal as you used for the watcherMail parameter.

PreviousTroubleshooting NextAPI

Last updated 8 days ago