If you there is any issue, bug or question, please do not hesitate to create a GitHub issue on the respective repository or email [email protected]. The GitHub is strongly preferred.

Furthermore, if you have any ideas for improvements or feature requests, either of the product or the documentation, contact us as well, we will be glad to hear your thoughts! 🚀

Before starting the integration, please ensure the following steps are completed.

Whitelists are lists that contain data about applications which should not be flagged as malware.

There are two types of whitelist:

• Installation Source Based

• Dynamic Package Name Based

Installation Source Whitelist

An installation source whitelist contains a list of installation sources (package names) which are considered trustworthy.

We use installation source during two checks:

• standalone installation source check - any application that is installed from a source that is not whitelisted will be returned as suspicious in the scan result with the reason value set as installSource

• suspicious permissions check - as mentioned in Suspicious Permissions list, while checking permissions, we also check the installation source to reduce false positives. The logic is the same as in the standalone installation source check, any application installed from a source that is not whitelisted will be considered as installed from an untrusted source.

Examples of Installer Package Names

• com.android.vending Package name of Google Play Store

• com.huawei.appmarket Package name of Huawei App Gallery

• com.google.android.packageinstaller Package name of the Package Installer system app, which is responsible for managing the installation of applications on Android devices. Applications installed manually using an APK file will usually have this package name as their installation source.

• unknown Some applications might have their installation source set as null. This is considered as the installation source unknown. This can be true for some system apps or for apps installed through ADB. During development, your applications will fall into this category.

Setting up whitelist

TalsecConfig config = new TalsecConfig.Builder(context.getPackageName(), new String[] {CERTIFICATE_HASH})
        .whitelistedInstallationSources(new String[]{"com.android.vending"})
        .build();        

final config = TalsecConfig(
  androidConfig: AndroidConfig(
    malwareConfig: MalwareConfig(
      whitelistedInstallationSources: ['com.android.vending'],
    ),
    // Other config data
  ),
  // Other config data
);

const config = {
  androidConfig: {
    malwareConfig: {
      whitelistedInstallationSources: ['com.android.vending'],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      whitelistedInstallationSources: ['com.android.vending'],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      whitelistedInstallationSources: ['com.android.vending'],
    },
    // Other config data
  }
  // Other config data
}

Dynamic Package Name Based Whitelist

The dynamic package name whitelist contains package names that are considered safe and will be ignored in the scan results.

This list is dynamic, meaning you can add to it before, during, or after a scan. This is useful for handling local false positives, allowing users or the integrating application to whitelist less-known but trusted applications.

Setting up whitelist

Talsec.addToWhitelist(context, "com.example.app")

Talsec.instance.addToWhitelist('com.example.app');

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

try {
  const response = await addToWhitelist('com.example.app');
  // response: true
} catch (error: any) {
  console.info('Error while adding app to malware whitelist: ', error);
}

try {
  const response = await talsec.addToWhitelist('com.example.app');
  // response: true
} catch (error: any) {
  console.info('Error while adding app to malware whitelist: ', error);
}

import { addToWhitelist } from 'capacitor-freerasp';

try {
  const response = await addToWhitelist('com.example.app');
  // response: true
} catch (error: any) {
  console.info('Error while adding app to malware whitelist: ', error);
}

Each application, whose specification is defined in one of the blacklists and is found on the device, is returned in the scan results.

There are three types of blacklists:

• Package Name Based

• Hash Based

• Permission Based

Package Name Based Blacklist

A package name blacklist contains a list of package names which you consider as suspicious (or malware).

Each application, whose package name is defined in the blacklist and is found on the device, is returned in the scan results.

If the application is flagged as suspicious, the scan result will show reason value set as blacklist.

Setting up blacklist

TalsecConfig config = new TalsecConfig.Builder(context.getPackageName(), new String[] {CERTIFICATE_HASH})
        .blacklistedPackageNames(new String[]{"com.example.app"})
        .build();

const config = {
  androidConfig: {
    malwareConfig: {
      blacklistedPackageNames: ['com.example.app'],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      blacklistedPackageNames: ['com.example.app'],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      blacklistedPackageNames: ['com.example.app'],
    },
    // Other config data
  }
  // Other config data
}

Hash Based Blacklist

A hash-based blacklist contains a list of SHA-256 hashes of the application APK which you consider as suspicious (or malware).

Each application, whose APK hash is defined in the blacklist and is found on the device, is returned in the scan results.

If the application is flagged as suspicious, the scan result will show reason value set as blacklist.

Setting up blacklist

TalsecConfig config = new TalsecConfig.Builder(context.getPackageName(), new String[] {CERTIFICATE_HASH})
        .blacklistedHashes(new String[]{"exampleHash"})
        .build();

final config = TalsecConfig(
  androidConfig: AndroidConfig(
    malwareConfig: MalwareConfig(
      blacklistedHashes: ['exampleHash'],
    ),
    // Other config data
  ),
  // Other config data
);

const config = {
  androidConfig: {
    malwareConfig: {
      blacklistedHashes: ['exampleHash'],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      blacklistedHashes: ['exampleHash'],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      blacklistedHashes: ['exampleHash'],
    },
    // Other config data
  }
  // Other config data
}

Calculating Hash of the APK

There are many ways how to compute the SHA-256 hash of the APK; for instance, on Unix, you can use:

shasum -a 256 yourfile.apk

Suspicious Permissions list

A suspicious permissions list contains a list of permission lists which you consider suspicious when granted to an application.

Each list contains a group of permissions. For an application to be marked as suspicious, all permissions in given group must be granted:

// Blacklist of permissions
[
    // List (group) of permissions
    // Application is suspicious if it has *GRANTED* all of permissions from 
    // given group
    ["android.provider.Telephony.SMS_RECEIVED", "android.permission.SEND_SMS"]
    ["android.permission.READ_CALL_LOG"]
]

If the application is flagged as suspicious, the scan result will show reason value set as suspiciousPermission.

To reduce the amount of false positives, we also check whether the application with suspicious permissions is installed from an untrusted installation source.

Setting up suspicious permissions list

TalsecConfig config = new TalsecConfig.Builder(context.getPackageName(), new String[][] {CERTIFICATE_HASH})
        .suspiciousPermissions(new String[][]{{"android.permission.ACCESS_COARSE_LOCATION"}})
        .build();

final config = TalsecConfig(
  androidConfig: AndroidConfig(
    malwareConfig: MalwareConfig(
      suspiciousPermissions: [
        ['android.permission.ACCESS_COARSE_LOCATION']
      ],
    ),
    // Other config data
  ),
  // Other config data
);

const config = {
  androidConfig: {
    malwareConfig: {
      suspiciousPermissions: [
        ['android.permission.ACCESS_COARSE_LOCATION']
      ],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      suspiciousPermissions: [
        ['android.permission.ACCESS_COARSE_LOCATION']
      ],
    },
    // Other config data
  }
  // Other config data
}

const config = {
  androidConfig: {
    malwareConfig: {
      suspiciousPermissions: [
        ['android.permission.ACCESS_COARSE_LOCATION']
      ],
    },
    // Other config data
  }
  // Other config data
}

freeMalwareDetection is a powerful SDK designed to enhance the security of your Android application by quickly and efficiently scanning for malicious (or suspicious) applications based on various blacklists and security policies.

Features

📌 In-App Malware Detection

Secure your Android app with quick, efficient threat scans. Detect SMS OTP Stealers, Ransomware, Fraudulent Apps, Spyware, Risky Apps, Copycats, Clipper Malware, Fake Security Apps, Keyloggers, Phishing Apps, Malware Droppers and Banking Malware.

🛜 Offline Processing – Everything Happens On-Device

All scanning and evaluation is performed directly on a device, ensuring complete functionality without the need for an internet connection. This approach enhances both reliability and privacy, as no data is transmitted or stored externally.

🛡️ Customizable Blacklists Easily define and manage to tailor malware detection to your needs.

⚡ Asynchronous Scanning Perform malware scans in the background without affecting the app's performance.

🔍 Comprehensive Details Receive detailed information on detected threats to inform users effectively.

✅ Google Play Review Compliant

Malware detection generally complies with Google Play policies without any additional involvement. Optional improved detection capabilities utilizing QUERY_ALL_PACKAGES permission (optional feature) require .

🚀 Easy Integration Simple integration process with robust documentation and support.

Everything you need to detect fraud & abuse malware

Infography

Main usage scenarios

Without User Involvement: Process Risky Apps in Your Business Logic

Malware detection provides a list of suspicious apps, allowing your business logic to take appropriate action based on your objectives:

• 📊 User and device risk scoring – Assess potential threats based on detected apps.

• 🕵️ Study malware – Analyze malicious behavior to improve defenses.

• 🔒 Block some features – Restrict access to sensitive actions for security.

• ⚠️ Monitor and prevent new scams – Detect emerging fraud patterns targeting your business.

With User Involvement: Display Malware Warning UI to Alert Users

1. Developer (during development): Define criteria for suspicious apps using blacklists and suspicious permission lists.

2. SDK (at runtime): The SDK scans the device for suspicious apps installed on the device.

3. Your app (at runtime): Display the malware warning UI to alert users and allow them to confirm the trustworthiness of the listed risky apps (or some of them).

4. User: Users can approve trusted apps or uninstall detected apps that seem malicious or potentially malicious.

5. SDK (at runtime): Approved apps are added to the whitelist to prevent future warnings about the same apps.

Supported platforms

freeMalwareDetection is currently supported for:

Malware detection is an integral part of the freeRASP SDK and is configured using the same TalsecConfig object. Malware configuration in TalsecConfig allows you to customize the behavior of the malware detection feature.

To enable malware detection, extend the configuration used during the initial integration of the SDK:

// Android uses Builder pattern for configuration

TalsecConfig config = new TalsecConfig.Builder(context.getPackageName(), new String[] {CERTIFICATE_HASH})
        .blacklistedPackageNames(new String[]{"com.example.app"})
        .blacklistedHashes(new String[]{"exampleHash"})
        .suspiciousPermissions(new String[][]{{"android.permission.READ_CONTACTS"}, {"android.permission.SEND_SMS"}})
        .whitelistedInstallationSources(new String[]{"com.android.vending"})
        .build();

// React Native uses nested malware configuration object (malwareConfig)  

const config = {
  androidConfig: {
    ...
    malwareConfig: {
      blacklistedHashes: ['exampleHash'],
      blacklistedPackageNames: ['com.example.app'],
      suspiciousPermissions: [
        ['android.permission.BLUETOOTH', 'android.permission.INTERNET'],
        ['android.permission.BATTERY_STATS'],
      ],
      whitelistedInstallationSources: ['com.android.vending'],
    },
  }
}

// Cordova uses nested malware configuration object (malwareConfig)  

const config = {
  androidConfig: {
    ...
    malwareConfig: {
      blacklistedHashes: ['exampleHash'],
      blacklistedPackageNames: ['com.example.app'],
      suspiciousPermissions: [
        ['android.permission.BLUETOOTH', 'android.permission.INTERNET'],
        ['android.permission.BATTERY_STATS'],
      ],
      whitelistedInstallationSources: ['com.android.vending'],
    },
  }
}

// Capacitor uses nested malware configuration object (malwareConfig)   

const config = {
  androidConfig: {
    ...
    malwareConfig: {
      blacklistedHashes: ['exampleHash'],
      blacklistedPackageNames: ['com.example.app'],
      suspiciousPermissions: [
        ['android.permission.BLUETOOTH', 'android.permission.INTERNET'],
        ['android.permission.BATTERY_STATS'],
      ],
      whitelistedInstallationSources: ['com.android.vending'],
    },
  }
}

It includes the following fields:

• blacklistedPackageNames A list of package names , any app with a package name in this list will trigger a detection.

• blacklistedHashes A list of APK hashes, which will trigger a detection. These hashes typically represent known malicious app versions.

• suspiciousPermissions A list of permissions that, if granted to another app, trigger a detection. You can specify single permissions or groups of permissions that, if requested together, are flagged as suspicious.

• whitelistedInstallationSource A list of trusted sources from which apps can be installed.

Scanning

The Malware Detection scan starts automatically, without any need for initialization. It is being run asynchronously in a separate thread along with other freeRASP checks, so it has no significant impact either on the application or freeRASP checks performance.

Based on the provided blacklists, Malware Detection examines installed applications to determine if they match any configurations listed in the blacklist.

System Applications

To avoid false positives, system applications are filtered out from:

• Permission-based blacklist

• Installation sources whitelist

and therefore won't be present in the results of scan.

Processing Scan Results

Receiving Results

The results of the scan are received using a callback mechanism from the freeRASP SDK by triggering malware callback:

// The following callback from the ThreatCallback has to be provided:

final callback = ThreatCallback(
  onMalware: (susApps) {
    // TODO: Not yet implemented    
  }
  // Other callbacks...
);

// The following callback in the actions object has to be provided:

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

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

// The following callback in the actions object has to be provided:

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

// The following callback in the actions object has to be provided:

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

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

Result Interpretation

After the scan is complete, freeRASP provides a result - a list of suspicious applications.

Each suspicious application in the list includes two main components:

• SuspiciousAppInfo An object containing details about the application.

• Reason A string explaining why the application was flagged as suspicious.

Caching

Scanned applications are stored in a cache until all applications on the device have been scanned. Only after the entire scan is complete , the callback mechanism sends the results to the application.

For example, if the application is only open for a few seconds and only a portion of the scan is completed, the results will be available the next time the application is opened for a longer period.

If any changes are made to the configuration—such as modifying a blacklist in the TalsecConfig—the cache is cleared, and the scanning process restarts from the beginning. This ensures that all applications are re-scanned under the latest security settings.

Result Handling

The results can be handled in many different ways.

For example:

• Logging on the back-end Collect data about found suspicious applications and potential threats (or even whitelists in case of "false positives"). However, be aware that Google considers package names as personal and sensitive information, so special requirements apply to their collection.

• Blocking certain logic if a specific application (or type of application) is detected.

• Showcase the results Suggest to the user that they can add the application to the whitelist or navigate them to uninstall the application.

Tip

On Android (i.e. not hybrid platforms), if you want to uninstall the application (noted below as item), you can use the following code snippet to navigate directly to the system settings where the application can be uninstalled:

Intent intent = new Intent(android.provider.Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
Uri uri = Uri.fromParts("package", item.getPackageInfo().packageName, null);
intent.setData(uri);
context.startActivity(intent);