# Detection Handling

## 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.

{% hint style="warning" %}
Scanning may take longer when using a hash-based blacklist, as the apk hash must be computed for each app on the device, which can be an expensive operation.\
\
More about hash-based blacklist [here](https://docs.talsec.app/freerasp/freemalwaredetection/broken-reference).
{% endhint %}

### 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:

{% tabs %}
{% tab title="Android" %}
{% code overflow="wrap" fullWidth="true" %}

```kotlin
// The following callback from the ThreatListener.ThreatDetected has to be implemented:

override fun onMalwareDetected(p0: MutableList<SuspiciousAppInfo>?) {
    TODO("Not yet implemented")
}
```

{% endcode %}
{% endtab %}

{% tab title="Flutter" %}
{% code fullWidth="true" %}

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

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

{% endcode %}
{% endtab %}

{% tab title="React Native" %}

<pre class="language-typescript"><code class="lang-typescript"><strong>// The following callback in the actions object has to be provided:
</strong>
import { type SuspiciousAppInfo } from 'freerasp-react-native';

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

{% endtab %}

{% tab title="Cordova" %}

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

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

{% endtab %}

{% tab title="Capacitor" %}

```typescript
// 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);
    },
},
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Learn more about the callbacks [here](https://docs.talsec.app/freerasp/integration); see the respective platform.
{% endhint %}

### 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.

{% tabs %}
{% tab title="Android" %}
`SuspiciousAppInfo` object contains two properties:

* `packageInfo`&#x20;
  * Information about the contents of a package of the application, such as package name, version, and other relevant details.
  * Refers to the entire [PackageInfo](https://developer.android.com/reference/android/content/pm/PackageInfo) object.
* `reason`&#x20;

  * Contains String value with the information about which blacklist has been matched (for information about blacklists, see [Broken link](https://docs.talsec.app/freerasp/freemalwaredetection/broken-reference "mention")). Possible values are:
    * **`blacklist` -** if **at least one** of the following conditions holds for the application:
      * a package name has been matched with a package name in a **packageNames** blacklist, or
      * an application hash has been matched with an application hash in the **hashes** blacklist.
    * **`suspiciousPermission`** - if **both** of the following conditions hold for the application:
      * the application contains at least one of the suspicious groups of permissions, and
      * the application is installed from a non-whitelisted source.
    * **`installSource`** - if the application is installed from a non-whitelisted source.

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>If <strong>suspiciousPermission</strong> conditions hold as well, these take priority over the <strong>installSource</strong> for the <code>reason</code> value<em>.</em></p></div>

{% endtab %}

{% tab title="Flutter" %}
`SuspiciousAppInfo` object is composed of two variables:

* `packageInfo`&#x20;
  * PackageInfo - information about the contents of a package of the application, e.g., package name, version, and other relevant details.
  * `packageInfo` consists of:
    * `packageName` - type **String** - the name of the package. From the tag's `name` attribute.
    * `appName` - type **String?** - public name of the package, or undefined if not available. From the `android:name` attribute.
    * `version` -  type **String?** - the version name of the package as specified by the tag's `versionName` attribute, or undefined if not available.
    * `installerStore` - type **String?** - the name of the package responsible for the installation, or undefined if not available.
    * `appIcon` - type **String?** - the icon associated with an application. Returns PNG encoded as a base64 string, or undefined if icon is not available. The icon can then be displayed:
      * using `Image` widget:

        ```dart
        // Parsing and decoding image
        final SuspiciousAppInfo app = ...
        final decodedImage = base64.decode(app.packageInfo.appIcon);

        // In the widget tree, you can use:
        Image.memory(decodedImage);
        ```
* `reason`&#x20;
  * type **String** - the information about which blacklist has been matched (for information about blacklists, see [Broken link](https://docs.talsec.app/freerasp/freemalwaredetection/broken-reference "mention")).
  * **blacklist -** if **at least one** of the following conditions holds for the application:
    * a package name has been matched with a package name in a **packageNames** blacklist,
    * an application hash has been matched with an application hash in the **hashes** blacklist.
  * **suspiciousPermission** - if **both** of the following conditions hold for the application:
    * the application contains at least one of the suspicious groups of permissions,
    * the application is installed from a not-whitelisted source.
  * **installSource** - if the application is installed from a not-whitelisted source.

{% hint style="info" %}
If **suspiciousPermission** conditions hold as well, these take priority over the **installSource** for the `reason` valu&#x65;*.*
{% endhint %}
{% endtab %}

{% tab title="React Native" %}
`SuspiciousAppInfo` object is composed of two variables:

* `packageInfo`&#x20;
  * PackageInfo - information about the contents of a package of the application, e.g., package name, version, and other relevant details.
  * `packageInfo` consists of:
    * `packageName` - type **string** - the name of the package. From the tag's `name` attribute.
    * `appName` - type **string?** - public name of the package, or undefined if not available. From the `android:name` attribute.
    * `version` -  type **string?** - the version name of the package as specified by the tag's `versionName` attribute, or undefined if not available.
    * `installerStore` - type **string?** - the name of the package responsible for the installation, or undefined if not available.
    * `appIcon` - type **string?** - the icon associated with an application. Returns PNG encoded as a base64 string, or undefined if icon is not available. The icon can then be displayed:
      * using the standard `Image` component:&#x20;

        ```tsx
        <Image source={{ uri: `data:image/png;base64,${app.packageInfo.appIcon}` }} />
        ```
* `reason`&#x20;
  * type **string** - the information about which blacklist has been matched (for information about blacklists, see [Broken link](https://docs.talsec.app/freerasp/freemalwaredetection/broken-reference "mention")).
  * **blacklist -** if **at least one** of the following conditions holds for the application:
    * a package name has been matched with a package name in a **packageNames** blacklist,
    * an application hash has been matched with an application hash in the **hashes** blacklist.
  * **suspiciousPermission** - if **both** of the following conditions hold for the application:
    * the application contains at least one of the suspicious groups of permissions,
    * the application is installed from a not-whitelisted source.
  * **installSource** - if the application is installed from a not-whitelisted source.

{% hint style="info" %}
If **suspiciousPermission** conditions hold as well, these take priority over the **installSource** for the `reason` valu&#x65;*.*
{% endhint %}
{% endtab %}

{% tab title="Cordova" %}
`SuspiciousAppInfo` object is composed of two variables:

* `packageInfo`&#x20;
  * PackageInfo - information about the contents of a package of the application, e.g., package name, version, and other relevant details.
  * `packageInfo` consists of:
    * `packageName` - type **string** - the name of the package. From the tag's `name` attribute.
    * `appName` - type **string?** - public name of the package, or undefined if not available. From the `android:name` attribute.
    * `version` -  type **string?** - the version name of the package as specified by the tag's `versionName` attribute, or undefined if not available.
    * `installerStore` - type **string?** - the name of the package responsible for the installation, or undefined if not available.
    * `appIcon` - type **string?** - the icon associated with an application. Returns PNG encoded as a base64 string, or undefined if icon is not available. The icon can then be displayed:
      * using the standard `img` component:

        ```html
        <img src=`data:image/png;base64,${app.packageInfo.appIcon}`/>
        ```
* `reason`&#x20;
  * type **string** - the information about which blacklist has been matched (for information about blacklists, see [Broken link](https://docs.talsec.app/freerasp/freemalwaredetection/broken-reference "mention")).
  * **blacklist -** if **at least one** of the following conditions holds for the application:
    * a package name has been matched with a package name in a **packageNames** blacklist,
    * an application hash has been matched with an application hash in the **hashes** blacklist.
  * **suspiciousPermission** - if **both** of the following conditions hold for the application:
    * the application contains at least one of the suspicious groups of permissions,
    * the application is installed from a not-whitelisted source.
  * **installSource** - if the application is installed from a not-whitelisted source.

{% hint style="info" %}
If **suspiciousPermission** conditions hold as well, these take priority over the **installSource** for the `reason` valu&#x65;*.*
{% endhint %}
{% endtab %}

{% tab title="Capacitor" %}
`SuspiciousAppInfo` object is composed of two variables:

* `packageInfo`&#x20;
  * PackageInfo - information about the contents of a package of the application, e.g., package name, version, and other relevant details.
  * `packageInfo` consists of:
    * `packageName` - type **string** - the name of the package. From the tag's `name` attribute.
    * `appName` - type **string?** - public name of the package, or undefined if not available. From the `android:name` attribute.
    * `version` -  type **string?** - the version name of the package as specified by the tag's `versionName` attribute, or undefined if not available.
    * `installerStore` - type **string?** - the name of the package responsible for the installation, or undefined if not available.
    * `appIcon` - type **string?** - the icon associated with an application. Returns PNG encoded as a base64 string, or undefined if icon is not available. The icon can then be displayed:
      * using the standard `ion-img` component:

        ```tsx
        <IonImg src={`data:image/png;base64,${app.packageInfo.appIcon}`} />
        ```
* `reason`&#x20;
  * type **string** - the information about which blacklist has been matched (for information about blacklists, see [Broken link](https://docs.talsec.app/freerasp/freemalwaredetection/broken-reference "mention")).
  * **blacklist -** if **at least one** of the following conditions holds for the application:
    * a package name has been matched with a package name in a **packageNames** blacklist,
    * an application hash has been matched with an application hash in the **hashes** blacklist.
  * **suspiciousPermission** - if **both** of the following conditions hold for the application:
    * the application contains at least one of the suspicious groups of permissions,
    * the application is installed from a not-whitelisted source.
  * **installSource** - if the application is installed from a not-whitelisted source.

{% hint style="info" %}
If **suspiciousPermission** conditions hold as well, these take priority over the **installSource** for the `reason` valu&#x65;*.*
{% endhint %}
{% endtab %}
{% endtabs %}

### 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.&#x20;

For example:&#x20;

* **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](https://support.google.com/googleplay/android-developer/answer/10144311), 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.

<figure><img src="https://3557356308-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQ2PxZTOjhquOxcxftTrm%2Fuploads%2F1wAx8RZAXyR8RJ5dx0wY%2FSni%CC%81mka%20obrazovky%202024-08-05%20o%209.58.42.png?alt=media&#x26;token=7b02ef27-fd45-4052-ade8-179112141f70" alt="" width="320"><figcaption><p>Example of Result Showcasing</p></figcaption></figure>

### 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:&#x20;

{% code title="Android" overflow="wrap" fullWidth="false" %}

```java
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);
```

{% endcode %}