> For the complete documentation index, see [llms.txt](https://docs.talsec.app/freerasp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talsec.app/freerasp/freerasp/integration/kotlin-multiplatform/api.md). # API ## Configuration These classes define the behavior of the freeRASP SDK. You must instantiate `freeraspConfig` to pass it into the `start()` method. **`class freeraspConfig`** The root configuration object required to initialize the SDK.

Property	Type	Default	Description
`androidConfig`	`AndroidConfig?`	`null`	Configuration specific to the Android platform.
`iosConfig`	`IOSConfig?`	`null`	Configuration specific to the iOS platform.
`watcherMail`	`String`	-	Required. The email address where security reports will be sent.
`isProd`	`Boolean`	`true`	If `true`, the SDK runs in production mode. If `false`, strict checks are disabled for development. See Wiki↗
`killOnBypass`	`Boolean`	`true`	If `true`, the app will terminate automatically when a critical threat (e.g., Hooking, Debugging) is detected.

**`class AndroidConfig`** Settings specific to the Android platform.

Property	Type	Default	Description
`packageName`	`String`	`-`	The expected package name of the app.
`certificateHashes`	`List<String>`	`-`	A list of expected signing certificate hashes (Base64 encoded).
`supportedAlternativeStores`	`List<String>`	`[]`	A list of allowed alternative app stores .
`malwareConfig`	`MalwareConfig?`	`null`	Optional configuration for the Malware Detection module.

**`class IOSConfig`** Settings specific to the iOS platform.

Property	Type	Default	Description
`bundleIds`	`List<String>`	`-`	A list of expected Bundle IDs for the app.
`teamId`	`String`	`-`	The Apple Team ID associated with your developer account.

**`class MalwareConfig`** Advanced configuration for the Malware Detection feature **(Android only)**.

Property	Type	Default	Description
`blacklistedPackageNames`	`List<String>`	`[]`	A list of package names that should trigger a malware alert.
`blacklistedHashes`	`List<String>`	`[]`	A list of certificate hashes for blacklisted apps.
`suspiciousPermissions`	`List<String>`	`[]`	A list of suspicious permission combinations.
`whitelistedInstallationSources`	`List<String>`	`[]`	A list of trusted installation sources (stores).

## Core Interface **`object FreeraspKMP`** The main singleton object used to interact with the library.

Property Type Description

Property	Type	Description
`threatEvents`	`SharedFlow<FreeRaspEvent>`	A stream of security events detected by the SDK. Subscribe to this flow to react to threats in real-time.
`raspExecutionStateEvents`	`SharedFlow<RaspExecutionStateEvent>`	A stream of RASP execution lifecycle events. Subscribe to receive execution state updates such as `AllChecksFinished`.

threatEvents

SharedFlow<FreeRaspEvent>

A stream of security events detected by the SDK. Subscribe to this flow to react to threats in real-time.

raspExecutionStateEvents SharedFlow<RaspExecutionStateEvent> A stream of RASP execution lifecycle events. Subscribe to receive execution state updates such as AllChecksFinished.

#### Methods `start(config)` Initializes and starts the freeRASP protection. ```kts suspend fun start(config: freeraspConfig) ``` `addToWhiteList(packageName)` Adds a package name to the whitelist. Useful if the malware detector falsely flags a legitimate app. ```kts suspend fun addToWhiteList(packageName: String) ``` `blockScreenCapture(enable)` Enables or disables protection against screen recording and screenshots. ```kts suspend fun blockScreenCapture(enable: Boolean) ``` * **enable**: Set to `true` to block capture, `false` to allow it. `isScreenCaptureBlocked()` Checks if screen capture blocking is currently active. ```kts suspend fun isScreenCaptureBlocked(): Boolean ``` * **Returns**: `true` if blocked, `false` otherwise. `getAppIcon(packageName)` Retrieves the icon of an installed application as a Base64 string. ```kts suspend fun getAppIcon(packageName: String): String ``` * **Returns**: Base64 encoded string of the icon. `storeExternalId(data)` Stores an external identifier (e.g., User ID) to correlate reports in the Talsec Dashboard. ```kts suspend fun storeExternalId(data: String) ``` {% hint style="info" %} Throws `FreeraspKMPException` if the operation fails. {% endhint %} `removeExternalId()` Removes a previously stored external identifier. ```kts suspend fun removeExternalId() ``` ## Events All events inherit from `sealed class FreeRaspEvent`. They are emitted via the `threatEvents` flow. ### `FreeRaspEvent`

Event	Platform	Description
`PrivilegedAccess`	🤖 🍎	Detects Root (Android) or Jailbreak (iOS) access.
`Debug`	🤖 🍎	Detects if a Debugger is attached to the application.
`Simulator`	🤖 🍎	Detects if the app is running on an Emulator or Simulator.
`AppIntegrity`	🤖 🍎	Detects if the app signature or checksum has been tampered with.
`UnofficialStore`	🤖 🍎	Detects if the app was installed from an unrecognized source.
`Hooks`	🤖 🍎	Detects hooking frameworks (e.g., Frida, Xposed) injected into the process.
`DeviceBinding`	🤖 🍎	Detects if the device identity or cryptographic keys have changed.
`Screenshot`	🤖 🍎	Notification that a screenshot was taken.
`ScreenRecording`	🤖 🍎	Notification that screen recording is active.
`Passcode`	🤖 🍎	Detects if the device is not protected by a lock screen.
`SecureHardwareNotAvailable`	🤖 🍎	Detects if the hardware-backed keystore is unavailable.
`SystemVPN`	🤖 🍎	Detects if a system-wide VPN is active.
`DeviceID`	🍎	Indicates that the unique device identifier has changed or is inconsistent.
`ObfuscationIssues`	🤖	Detects if the code is not properly obfuscated (missing ProGuard/R8).
`DevMode`	🤖	Detects if Developer Options are enabled in settings.
`AdbEnabled`	🤖	Detects if USB Debugging (ADB) is active.
`MultiInstance`	🤖	Detects App Cloning (multiple instances running).
`UnsecureWifi`	🤖	Detects connection to an unencrypted Wi-Fi network.
`TimeSpoofing`	🤖🍎	Detects manual manipulation of system time.
`LocationSpoofing`	🤖	Detects attempts to falsify the device’s location to bypass geofences or fake presence.
`Automation`	🤖	Detects automation frameworks (e.g. Appium)
`Bootloader`	🤖	Detects that the device bootloader is unlocked or otherwise compromised.
`Malware`	🤖	Detects suspicious applications. Contains `suspiciousAppInfo`.

### `RaspExecutionStateEvent`

Event	Platform	Description
AllChecksFinished	🤖 🍎	Confirms that the initialization is complete and all active security checks have been executed.

{% hint style="info" %} **Platform Availability** 🤖 **Android** - Supported on Android devices. 🍎 **iOS** - Supported on iOS devices. {% endhint %} For a detailed description of each event and its security implications, please refer to the [Wiki section ↗](/freerasp/freerasp/wiki/threat-detection.md). #### Malware Detection Configuration `class SuspiciousAppDetectionConfig` Advanced configuration for the Malware Detection feature **(Android only)**. | Property | Type | Default | Description | | ---------------------- | --------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- | | `packageNames` | `List?` | `null` | Package names of known malicious apps. | | `hashes` | `List?` | `null` | Certificate hashes of known malicious apps. | | `requestedPermissions` | `List>?` | `null` | Permission groups an app must **request** to be flagged as suspicious. | | `grantedPermissions` | `List>?` | `null` | Permission groups an app must be actively **granted** to be flagged as suspicious. | | `scanScope` | `ScanScope` | `ScanScope(ScopeType.SIDELOADED_ONLY)` | Defines which installed apps are scanned. | | `reasonMode` | `ReasonMode` | `ReasonMode.HIGHEST_CONFIDENCE` | Controls how detection reasons are reported. | For full details on `ScanScope`, `ScopeType`, and `ReasonMode` behavior, see the[ Malware Detection Configuration guide](/freerasp/freemalwaredetection/integration-guide/configuration.md). `data class SuspiciousAppInfo` Found inside the payload of the `Malware` event.

Property	Type	Description
`packageInfo`	`PackageInfo`	Detailed information about the detected application.
`reasons`	`Set<String>`	The specific detection rule that triggered the alert (e.g., `"Blacklisted Package"` or `"Suspicious Permissions"`).
`permissions`	`List<String>`	List of permissions declared by the suspicious app.

`data class PackageInfo` Contains metadata about an installed application.

Property	Type	Description
`packageName`	`String`	The unique package name (Application ID).
`appName`	`String?`	The name of the app.
`version`	`String?`	The version of the app.
`appIcon`	`String?`	The app icon as a Base64 encoded string.
`installerStore`	`String?`	The store from which the app was installed.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.talsec.app/freerasp/freerasp/integration/kotlin-multiplatform/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.