> 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/freemalwaredetection/detection-layers/behavioral-heuristics/heuristic-evaluation-logic.md).

# Heuristic Evaluation Logic

The evaluation mode determines how the SDK decides which applications constitute threats, based on the signals available at scan time.

The specific logic depends on your integration version:

* **Modern (V2) integrations:** Explicitly controlled by the `reasonMode` parameter — choose between strict `AND` logic (`HIGHEST_CONFIDENCE`) or broad `OR` logic (`ALL`).
* **Legacy (V1) integrations:** Fixed `OR` logic — equivalent to `ALL` mode, not configurable.

***

## Modern (V2) Heuristic Logic

{% hint style="warning" %}
**Applicability**

The configurable evaluation logic described below is active starting from the following SDK versions:

**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`

To utilize this logic, you **must** configure detection using the `SuspiciousAppDetectionConfig` (V2) API.
{% endhint %}

### `HIGHEST_CONFIDENCE`

The default and recommended mode. Flags an application only when multiple independent signals align — blocklist matches are always included, and scope-based results require a permission match as a second signal.

| Condition                              | Application State | Flagged                                                 |
| -------------------------------------- | ----------------- | ------------------------------------------------------- |
| Blocklist match                        | Any               | Yes — reason: `blocklist`                               |
| Permission config present, app matches | In scan scope     | Yes — reasons: `installSource` + `suspiciousPermission` |
| Permission config present, no match    | In scan scope     | No                                                      |
| No permission config                   | In scan scope     | No                                                      |

{% hint style="info" %}
**Why no permission config means no scope flags**

The permission check produces no output when no permission sets are configured. In `HIGHEST_CONFIDENCE` mode, a second signal is required to flag scope-based results — so without permission configuration, only blocklist matches are reported.
{% endhint %}

{% hint style="info" %}
**Premium Tier Extension**

The Premium tier adds a third signal — cloud verification against the App Reputation API. When the online database is active, the classifier uses a combined strategy: applications flagged by the cloud database are always included, and applications with `suspiciousPermission` that return an unknown online status are also flagged. This cross-signal confirmation further reduces false positives while expanding detection coverage.
{% endhint %}

### `ALL`

Prioritizes maximum coverage over false-positive reduction. Every application that enters the configured scan scope is flagged, regardless of permission results.

| Application                                     | Reasons Returned                         |
| ----------------------------------------------- | ---------------------------------------- |
| Blocklist match (hash or package name)          | `blocklist`                              |
| In scan scope, no dangerous permissions         | `installSource`                          |
| In scan scope, matches dangerous permission set | `installSource` + `suspiciousPermission` |

{% hint style="warning" %}
`suspiciousPermission` is never returned in isolation. Permission analysis runs only on applications already identified as being within the scan scope, so `suspiciousPermission` always appears alongside `installSource`.
{% endhint %}

### **Scan Scope and Which Apps Are Flagged**

Which applications enter the scan scope depends on the configured scope type and `trustedInstallSources`. In the default configuration — scope `SIDELOADED_ONLY`, no `trustedInstallSources` — the SDK scans all applications that are not system or OEM apps. This **includes applications installed from official stores such as Google Play**, because official stores are not excluded by default.

To exclude applications installed from specific sources, configure `trustedInstallSources` with the relevant installer package names (for example, `com.android.vending` for Google Play).

[**→ View scan scope configuration**](/freerasp/freemalwaredetection/integration-guide/configuration.md)

***

### Legacy (V1) Heuristic Logic

{% hint style="warning" %}
**Applicability**

The fixed evaluation logic described below applies to SDK versions prior to the V2 update:

**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`
{% endhint %}

Older versions of the SDK do not support the `reasonMode` parameter. The heuristic engine functions identically to the modern `ALL` mode — every application within the scan scope is flagged, regardless of whether it matched any permission set.

This frequently results in false positives for benign sideloaded tools. Migration to `SuspiciousAppDetectionConfig` is recommended to access `HIGHEST_CONFIDENCE` mode and reduce noise.

{% hint style="info" %}
**Upgrade Recommended**

If you are experiencing a high rate of false positives from benign sideloaded apps, update your SDK to benefit from modern heuristics and configurable evaluation logic.
{% endhint %}

***

## Recommended Response Strategy

The appropriate response depends on the reason codes returned and your application's risk tolerance.

* **`blocklist` results** are high-confidence. The application matches an explicit entry you or the SDK defined. Immediate action is justified.
* **`installSource` + `suspiciousPermission` results** indicate a sideloaded application requesting a dangerous capability combination. The risk level depends on the specific permissions involved. Consider prompting the user or restricting access until the application is reviewed.
* **`installSource` alone** (`ALL` mode only) means the application is within scope but showed no other indicators. Treat these as informational — use them to prompt user awareness rather than hard-blocking.

[**→ View result handling and recommended reactions**](/freerasp/freemalwaredetection/integration-guide/handling-results.md)


---

# 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/freemalwaredetection/detection-layers/behavioral-heuristics/heuristic-evaluation-logic.md?ask=<question>&goal=<endgoal>
```

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