Handling Results

When the background evaluation process completes and identifies one or more threats, the detection engine triggers a callback to your application. This section details how to intercept this callback, parse the threat data, and implement dynamic remediation strategies.

Receiving the Callback

The results of the scan are delivered asynchronously via the standard Threat Callback mechanism. Because the engine automatically filters out safe system applications and caches benign results, this callback is only fired if a suspicious application is actively detected on the device.

Implement the onMalwareDetected method from the ThreatListener.ThreatDetected interface:

override fun onMalwareDetected(suspiciousApps: List<SuspiciousAppInfo>?) {
    suspiciousApps?.forEach { app ->
        Log.w("Talsec", "Detected malware: ${app.packageInfo.packageName}")
    }
}

Provide the onMalware callback within your ThreatCallback object:

final callback = ThreatCallback(
    onMalware: (List<SuspiciousAppInfo?> suspiciousApps) {
        for (var app in suspiciousApps) {
            print('Detected malware: ${app?.packageInfo.packageName}');
        }
    },
    // Other callbacks...
);

Add the malware callback to your actions object:

import { type SuspiciousAppInfo } from 'freerasp-react-native';

const actions = {
    // Other threat callbacks...
    malware: (suspiciousApps: SuspiciousAppInfo[]) => {
        console.log('Detected suspicious apps: ', suspiciousApps);
    },
};

Add the malware callback to your actions object:

import { type SuspiciousAppInfo } from 'capacitor-freerasp'; 

const actions = {
    // Other threat callbacks...
    malware: (suspiciousApps: SuspiciousAppInfo[]) => {
        console.log('Detected suspicious apps: ', suspiciousApps);
    },
};

Add the malware callback to your actions object:

const actions = {
    // Other threat callbacks...
    malware: (suspiciousApps) => {
        console.log('Detected suspicious apps: ', suspiciousApps);
    },
};

Collect FreeRaspEvent.Malware events from the threatEvents SharedFlow:

FreeraspKMP.threatEvents
    .filterIsInstance<FreeRaspEvent.Malware>()
    .collect { event ->
        event.suspiciousAppInfo.forEach { app ->
            println("Detected malware: ${app.packageInfo.packageName}")
        }
    }

Interpreting SuspiciousAppInfo

For each identified threat, the engine generates a SuspiciousAppInfo data object containing metadata about the offending application and the specific rules it violated.

The structure of this object depends on the version of the module integrated into your project.

Modern (V2) API

Compatibility

Android: 18.1.0 | Flutter: 8.0.0 | React Native: 5.0.0 |

Capacitor: 3.0.0 | Cordova: 9.0.0 | KMP: 2.0.0

Property

Type

Description

packageInfo.packageName

String

Unique package identifier.

packageInfo.appName

String?

Public display name.

packageInfo.version

String?

versionName string.

packageInfo.installerStore

String?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

String?

Base64 encoded icon (null by default).

reasons

Set<String>

Rules violated (blocklist, installSource, suspiciousPermission).

permissions

Set<String>?

Exact permissions that triggered detection (if flagged with suspiciousPermission).

Property

Type

Description

packageInfo.packageName

String

Unique package identifier.

packageInfo.appName

String?

Public display name.

packageInfo.version

String?

versionName string.

packageInfo.installerStore

String?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

String?

Base64 encoded icon (null by default).

reasons

List<String>

Rules violated (blocklist, installSource, suspiciousPermission).

permissions

List<String>?

Exact permissions that triggered detection (if flagged with suspiciousPermission).

Property

Type

Description

packageInfo.packageName

string

Unique package identifier.

packageInfo.appName

string?

Public display name.

packageInfo.version

string?

versionName string.

packageInfo.installerStore

string?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

string?

Base64 encoded icon (null by default).

reasons

string[]

Rules violated (blocklist, installSource, suspiciousPermission).

permissions

string[]?

Exact permissions that triggered detection (if flagged with suspiciousPermission).

Property

Type

Description

packageInfo.packageName

string

Unique package identifier.

packageInfo.appName

string?

Public display name.

packageInfo.version

string?

versionName string.

packageInfo.installerStore

string?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

string?

Base64 encoded icon (null by default).

reasons

string[]

Rules violated (blocklist, installSource, suspiciousPermission).

permissions

string[]?

Exact permissions that triggered detection (if flagged with suspiciousPermission).

Property

Type

Description

packageInfo.packageName

string

Unique package identifier.

packageInfo.appName

string?

Public display name.

packageInfo.version

string?

versionName string.

packageInfo.installerStore

string?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

string?

Base64 encoded icon (null by default).

reasons

string[]

Rules violated (blocklist, installSource, suspiciousPermission).

permissions

string[]?

Exact permissions that triggered detection (if flagged with suspiciousPermission).

Property

Type

Description

packageInfo.packageName

String

Unique package identifier.

packageInfo.appName

String?

Public display name.

packageInfo.version

String?

versionName string.

packageInfo.installerStore

String?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

String?

Base64 encoded icon (null by default).

reasons

Set<String>

Rules violated (blocklist, installSource, suspiciousPermission).

permissions

Set<String>?

Exact permissions that triggered detection (if flagged with suspiciousPermission).

Premium Tier Extension

The Premium tier adds a fourth reason: onlineMalwareDatabase — returned when the application is confirmed as malicious by the App Reputation API cloud database.

Legacy (V1) API

Compatibility

Android: <18.1.0 | Flutter: <8.0.0 | React Native: <5.0.0 |

Capacitor: <3.0.0 | Cordova: <9.0.0 | KMP: <2.0.0

Property

Type

Description

packageInfo

PackageInfo

The native Android PackageInfo object. Provides comprehensive OS-level metadata about the flagged application (e.g., version, signatures, installed location).

reason

String

The primary threat signal (blocklist, installSource, or suspiciousPermission). Returns only the highest-priority match (suspiciousPermission overrides installSource).

Property

Type

Description

packageInfo.packageName

String

Unique package identifier.

packageInfo.appName

String?

Public display name.

packageInfo.version

String?

versionName string.

packageInfo.installationSource

String?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

String?

Base64 encoded icon (null by default).

reason

String

The primary threat signal (blocklist, installSource, or suspiciousPermission). Returns only the highest-priority match (suspiciousPermission overrides installSource).

Property

Type

Description

packageInfo.packageName

string

Unique package identifier.

packageInfo.appName

string?

Public display name.

packageInfo.version

string?

versionName string.

packageInfo.installerStore

string?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

string?

Base64 encoded icon (null by default).

reason

string

The primary threat signal (blocklist, installSource, or suspiciousPermission). Returns only the highest-priority match (suspiciousPermission overrides installSource).

Property

Type

Description

packageInfo.packageName

string

Unique package identifier.

packageInfo.appName

string?

Public display name.

packageInfo.version

string?

versionName string.

packageInfo.installerStore

string?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

string?

Base64 encoded icon (null by default).

reason

string

The primary threat signal (blocklist, installSource, or suspiciousPermission). Returns only the highest-priority match (suspiciousPermission overrides installSource).

Property

Type

Description

packageInfo.packageName

string

Unique package identifier.

packageInfo.appName

string?

Public display name.

packageInfo.version

string?

versionName string.

packageInfo.installerStore

string?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

string?

Base64 encoded icon (null by default).

reason

string

The primary threat signal (blocklist, installSource, or suspiciousPermission). Returns only the highest-priority match (suspiciousPermission overrides installSource).

Property

Type

Description

packageInfo.packageName

String

Unique package identifier.

packageInfo.appName

String?

Public display name.

packageInfo.version

String?

versionName string.

packageInfo.installerStore

String?

Installer package name (e.g., com.android.vending).

packageInfo.appIcon

String?

Base64 encoded icon (null by default).

reason

String

The primary threat signal (blocklist, installSource, or suspiciousPermission). Returns only the highest-priority match (suspiciousPermission overrides installSource).

Retrieving the App Icon

By default, the appIcon property is omitted to reduce the computation time required to serialize the payload. If your application requires displaying a threat warning dialog with visual context, retrieve the icon asynchronously.

Retrieve the icon natively using the Android PackageManager:

val drawable = context.packageManager.getApplicationIcon(app.packageInfo.packageName)

Exception Handling Required

The getApplicationIcon method throws a PackageManager.NameNotFoundException if the system cannot locate the package. Wrap this call in a try-catch block.

import 'dart:convert';

final decodedImage = base64.decode(app.packageInfo.appIcon!);
Image.memory(decodedImage);

Exception Handling Required

Calls to getAppIcon() will throw a native exception if the user uninstalls the target application before the fetch completes. Wrap the execution in a try-catch block and implement a fallback UI.

import { getAppIcon, type SuspiciousAppInfo } from 'freerasp-react-native';

const retrieveIcon = async (app: SuspiciousAppInfo) => {
    try {
        const iconBase64 = await getAppIcon(app.packageInfo.packageName);
        app.packageInfo.appIcon = iconBase64;
    } catch (error) {
        console.error('Failed to retrieve icon', error);
    }
};

Exception Handling Required

The getAppIcon() Promise will reject if the target application is uninstalled before the fetch completes. Wrap the await call in a try-catch block.

import { getAppIcon } from 'capacitor-freerasp';

const retrieveIcon = async (app) => {
    try {
        const iconBase64 = await getAppIcon(app.packageInfo.packageName);
        app.packageInfo.appIcon = iconBase64;
    } catch (error) {
        console.error('Failed to retrieve icon', error);
    }
};

Exception Handling Required

The getAppIcon() Promise will reject if the target application is uninstalled before the fetch completes. Wrap the await call in a try-catch block.

const retrieveIcon = async (app) => {
    try {
        const iconBase64 = await getAppIcon(app.packageInfo.packageName);
        app.packageInfo.appIcon = iconBase64;
    } catch (error) {
        console.error('Failed to retrieve icon', error);
    }
};

Exception Handling Required

The getAppIcon() Promise will reject if the target application is uninstalled before the fetch completes. Wrap the await call in a try-catch block.

val iconBase64 = FreeraspKMP.getAppIcon(app.packageInfo.packageName)

Exception Handling Required

getAppIcon() throws a FreeraspKMPException if the target application cannot be found. Wrap the call in a try-catch block and implement a fallback UI.

Local Whitelisting

Because behavioral heuristics are probabilistic, legitimate tools may occasionally be flagged. To handle false positives, you can manually whitelist specific package names on the local device.

Once an application is whitelisted, the engine ignores it during all future evaluations until the detection configuration changes.

Security Constraint

Never automatically whitelist sideloaded applications based purely on their package name. Attackers frequently spoof popular package names to bypass filters. Always implement a UI flow requiring the user to explicitly confirm trust before executing the whitelist method.

Talsec.addToWhitelist(context, "com.trusted.sideloaded.app")

Talsec.instance.addToWhitelist("com.trusted.sideloaded.app");

import { addToWhitelist } from 'freerasp-react-native';

try {
    await addToWhitelist('com.trusted.sideloaded.app');
} catch (error) {
    console.error('Whitelist error: ', error);
}

import { addToWhitelist } from 'capacitor-freerasp';

try {
    await addToWhitelist('com.trusted.sideloaded.app');
} catch (error) {
    console.error('Whitelist error: ', error);
}

try {
    await addToWhitelist('com.trusted.sideloaded.app');
} catch (error) {
    console.error('Whitelist error: ', error);
}

FreeraspKMP.addToWhiteList("com.trusted.sideloaded.app")

Pre-Initialization Whitelisting

If your logic requires whitelisting an application immediately upon the first launch, the addToWhitelist method must be executed before calling the core Talsec.start() initialization routine.

Remediation

If you determine an application is an absolute threat and the user is unable to proceed, you can programmatically prompt them to uninstall it.

Because Android security constraints prevent applications from silently uninstalling other packages, remediation requires direct user intervention. The standard approach is to dispatch a native Intent that routes the user to the system's Application Details screen.

val intent = Intent(android.provider.Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
    data = Uri.fromParts("package", app.packageInfo.packageName, null)
    flags = Intent.FLAG_ACTIVITY_NEW_TASK
}
context.startActivity(intent)

import 'package:android_intent_plus/android_intent.dart';

final intent = AndroidIntent(
    action: 'android.settings.APPLICATION_DETAILS_SETTINGS',
    data: 'package:${app.packageInfo.packageName}',
);
await intent.launch();

import IntentLauncher from 'react-native-intent-launcher';

IntentLauncher.startActivity({
    action: 'android.settings.APPLICATION_DETAILS_SETTINGS',
    data: `package:${app.packageInfo.packageName}`,
});

import { IntentLauncher } from '@capgo/capacitor-intent-launcher';

await IntentLauncher.startActivity({
    action: 'android.settings.APPLICATION_DETAILS_SETTINGS',
    data: `package:${app.packageInfo.packageName}`,
});

window.plugins.intentShim.startActivity(
    {
        action: "android.settings.APPLICATION_DETAILS_SETTINGS",
        data: `package:${app.packageInfo.packageName}`
    },
    () => console.log('Settings launched successfully'),
    (err) => console.error('Failed to launch settings:', err)
);

val intent = Intent(android.provider.Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
    data = Uri.fromParts("package", app.packageInfo.packageName, null)
    flags = Intent.FLAG_ACTIVITY_NEW_TASK
}
context.startActivity(intent)

PreviousConfiguration NextValidation

Last updated 2 months ago