> 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/integration-guide/configuration.md).

# Configuration

The freeMalware Detection module is configured directly in code — no external files or API calls are required. Pass your detection parameters through `SuspiciousAppDetectionConfig` (V2 API) or via the legacy configuration fields (V1 API).

***

## Modern (V2) API

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

The V2 configuration API is available from the following minimum 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`
{% endhint %}

{% tabs %}
{% tab title="Android" %}

```kotlin
val detectionConfig = SuspiciousAppDetectionConfig(
    packageNames = setOf("com.suspicious.app"),
    hashes = setOf("755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21"),
    requestedPermissions = setOf(
        setOf("android.permission.READ_SMS"),
        setOf("android.permission.BIND_ACCESSIBILITY_SERVICE"),
        setOf("android.permission.REQUEST_INSTALL_PACKAGES")
    ),
    grantedPermissions = setOf(
        setOf("android.permission.BIND_ACCESSIBILITY_SERVICE")
    ),
    malwareScanScope = MalwareScanScope(
        scanScope = ScopeType.SIDELOADED_ONLY,
        trustedInstallSources = listOf("com.android.vending")
    ),
    reasonMode = ReasonMode.HIGHEST_CONFIDENCE
)

val config = TalsecConfig.Builder(packageName, certificateHash)
    .suspiciousAppDetectionConfig(detectionConfig)
    .build()
```

{% endtab %}

{% tab title="Flutter" %}

```dart
final detectionConfig = SuspiciousAppDetectionConfig(
    packageNames: ["com.suspicious.app"],
    hashes: ["755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21"],
    requestedPermissions: [
        ["android.permission.READ_SMS"],
        ["android.permission.BIND_ACCESSIBILITY_SERVICE"],
        ["android.permission.REQUEST_INSTALL_PACKAGES"]
    ],
    grantedPermissions: [
        ["android.permission.BIND_ACCESSIBILITY_SERVICE"]
    ],
    scanScope: ScanScope(
        scopeType: ScopeType.sideloadedOnly,
        trustedInstallSources: ["com.android.vending"]
    ),
    reasonMode: ReasonMode.highestConfidence,
);

final config = TalsecConfig(
    androidConfig: AndroidConfig(
        packageName: packageName,
        signingCertHashes: [certificateHash],
        suspiciousAppDetectionConfig: detectionConfig,
    ),
);
```

{% endtab %}

{% tab title="React Native" %}

```typescript
const config: TalsecConfig = {
    androidConfig: {
        packageName: 'com.example.app',
        certificateHashes: ['...'],
        suspiciousAppDetectionConfig: {
            packageNames: ['com.suspicious.app'],
            hashes: ['755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21'],
            requestedPermissions: [
                ['android.permission.READ_SMS'],
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
                ['android.permission.REQUEST_INSTALL_PACKAGES'],
            ],
            grantedPermissions: [
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
            ],
            scanScope: {
                scopeType: 'SIDELOADED_ONLY',
                trustedInstallSources: ['com.android.vending'],
            },
            reasonMode: 'HIGHEST_CONFIDENCE',
        },
    },
};
```

{% endtab %}

{% tab title="Capacitor" %}

```typescript
const config: TalsecConfig = {
    watcherMail: 'your@email.com',
    androidConfig: {
        packageName: 'com.example.app',
        certificateHashes: ['...'],
        suspiciousAppDetectionConfig: {
            packageNames: ['com.suspicious.app'],
            hashes: ['755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21'],
            requestedPermissions: [
                ['android.permission.READ_SMS'],
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
                ['android.permission.REQUEST_INSTALL_PACKAGES'],
            ],
            grantedPermissions: [
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
            ],
            scanScope: {
                scopeType: 'SIDELOADED_ONLY',
                trustedInstallSources: ['com.android.vending'],
            },
            reasonMode: 'HIGHEST_CONFIDENCE',
        },
    },
};
```

{% endtab %}

{% tab title="Cordova" %}

```typescript
const config: TalsecConfig = {
    watcherMail: 'your@email.com',
    androidConfig: {
        packageName: 'com.example.app',
        certificateHashes: ['...'],
        suspiciousAppDetectionConfig: {
            packageNames: ['com.suspicious.app'],
            hashes: ['755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21'],
            requestedPermissions: [
                ['android.permission.READ_SMS'],
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
                ['android.permission.REQUEST_INSTALL_PACKAGES'],
            ],
            grantedPermissions: [
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
            ],
            scanScope: {
                scopeType: 'SIDELOADED_ONLY',
                trustedInstallSources: ['com.android.vending'],
            },
            reasonMode: 'HIGHEST_CONFIDENCE',
        },
    },
};
```

{% endtab %}

{% tab title="KMP" %}

```kotlin
val detectionConfig = SuspiciousAppDetectionConfig(
    packageNames = listOf("com.suspicious.app"),
    hashes = listOf("755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21"),
    requestedPermissions = listOf(
        listOf("android.permission.READ_SMS"),
        listOf("android.permission.BIND_ACCESSIBILITY_SERVICE"),
        listOf("android.permission.REQUEST_INSTALL_PACKAGES")
    ),
    grantedPermissions = listOf(
        listOf("android.permission.BIND_ACCESSIBILITY_SERVICE")
    ),
    scanScope = ScanScope(
        scopeType = ScopeType.SIDELOADED_ONLY,
        trustedInstallSources = listOf("com.android.vending")
    ),
    reasonMode = ReasonMode.HIGHEST_CONFIDENCE
)

val config = freeraspConfig(
    watcherMail = "your@email.com",
    androidConfig = AndroidConfig(
        packageName = packageName,
        certificateHashes = listOf(certificateHash),
        suspiciousAppDetectionConfig = detectionConfig
    )
)
```

{% endtab %}
{% endtabs %}

### Configuration Parameters

<table><thead><tr><th width="199.20703125">Parameter</th><th width="173.8515625">Type</th><th width="184.3671875">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>packageNames</code></td><td><code>Set</code>/<code>List&#x3C;String></code></td><td><code>null</code></td><td>Package identifiers to explicitly blocklist.</td></tr><tr><td><code>hashes</code></td><td><code>Set</code>/<code>List&#x3C;String></code></td><td><code>null</code></td><td>SHA-256 APK hashes to explicitly blocklist.</td></tr><tr><td><code>requestedPermissions</code></td><td><code>Set</code>/<code>List&#x3C;List&#x3C;String>></code></td><td><code>null</code></td><td>Permission sets — flagged if all permissions in any set appear in the app's manifest.</td></tr><tr><td><code>grantedPermissions</code></td><td><code>Set</code>/<code>List&#x3C;List&#x3C;String>></code></td><td><code>null</code></td><td>Permission sets — flagged if all permissions in any set are actively granted by the user.</td></tr><tr><td><code>malwareScanScope</code> (Android) / <code>scanScope</code> (others)</td><td><code>MalwareScanScope</code> / <code>ScanScope</code></td><td><code>SIDELOADED_ONLY</code>, no trusted sources</td><td>Controls which applications enter the scan. See <a href="#scan-scope">Scan Scope</a> below.</td></tr><tr><td><code>reasonMode</code></td><td><code>ReasonMode</code></td><td><code>HIGHEST_CONFIDENCE</code></td><td>Controls the detection decision logic. See Reason Mode below.</td></tr></tbody></table>

### Scan Scope

The scan scope determines which installed applications are subject to heuristic evaluation.

| scopeType                           | Behavior                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------- |
| `SIDELOADED_ONLY` *(default)*       | Evaluates non-system, non-OEM applications not installed from a trusted source. |
| `SIDELOADED_AND_OEM`                | Includes OEM pre-installed applications.                                        |
| `SIDELOADED_AND_SYSTEM_EXCLUDE_OEM` | Includes system applications, excludes OEM.                                     |
| `SIDELOADED_AND_SYSTEM_AND_OEM`     | Includes all non-trusted applications regardless of origin.                     |
| `ALL`                               | Evaluates every installed application without exception.                        |

<table><thead><tr><th width="224.80859375">Exclusions</th><th>Description</th></tr></thead><tbody><tr><td><code>trustedInstallSources</code></td><td>Accepts a list of installer package names (e.g., <code>com.android.vending</code> for Google Play). Applications installed from these sources are excluded from scope-based evaluation.</td></tr></tbody></table>

{% hint style="info" %}
Official stores are not excluded by default. To exclude Google Play apps from evaluation, explicitly add `com.android.vending` to `trustedInstallSources`.
{% endhint %}

### Reason Mode

The reason mode determines the logic used to decide which applications are surfaced as threats based on the available signals.

| Mode                             | Behavior                                                                                                       |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `HIGHEST_CONFIDENCE` *(default)* | Flags scope-based results only when a permission match is also present. Blocklist matches are always included. |
| `ALL`                            | Flags every application within the configured scan scope, regardless of permission results.                    |

***

## Legacy (V1) API

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

The legacy V1 API is only supported in SDK versions prior to the V2 update (listed below). It does not provide `reasonMode` control, `requestedPermissions`, or granular scan scoping, and defaults to `ALL` mode.

**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`&#x20;
{% endhint %}

{% tabs %}
{% tab title="Android" %}

```kotlin
val config = TalsecConfig.Builder(packageName, certificateHash)
    .blacklistedPackageNames(arrayOf("com.suspicious.app"))
    .blacklistedHashes(arrayOf("755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21"))
    .suspiciousPermissions(arrayOf(
        arrayOf("android.permission.READ_SMS"),
        arrayOf("android.permission.BIND_ACCESSIBILITY_SERVICE")
    ))
    .whitelistedInstallationSources(arrayOf("com.android.vending"))
    .build()
```

{% endtab %}

{% tab title="Flutter" %}

```dart
final config = TalsecConfig(
    androidConfig: AndroidConfig(
        packageName: packageName,
        signingCertHashes: [certificateHash],
        malwareConfig: MalwareConfig(
            blacklistedPackageNames: ["com.suspicious.app"],
            blacklistedHashes: ["755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21"],
            suspiciousPermissions: [
                ["android.permission.READ_SMS"],
                ["android.permission.BIND_ACCESSIBILITY_SERVICE"]
            ],
            whitelistedInstallationSources: ["com.android.vending"],
        ),
    ),
);
```

{% endtab %}

{% tab title="React Native" %}

```typescript
const config: TalsecConfig = {
    androidConfig: {
        packageName: 'com.example.app',
        certificateHashes: ['...'],
        blacklistedPackageNames: ['com.suspicious.app'],
        blacklistedHashes: ['755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21'],
        suspiciousPermissions: [
            ['android.permission.READ_SMS'],
            ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
        ],
        whitelistedInstallationSources: ['com.android.vending'],
    },
};
```

{% endtab %}

{% tab title="Capacitor" %}

```typescript
const config: TalsecConfig = {
    watcherMail: 'your@email.com',
    androidConfig: {
        packageName: 'com.example.app',
        certificateHashes: ['...'],
        malwareConfig: {
            blacklistedPackageNames: ['com.suspicious.app'],
            blacklistedHashes: ['755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21'],
            suspiciousPermissions: [
                ['android.permission.READ_SMS'],
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
                ['android.permission.REQUEST_INSTALL_PACKAGES'],
            ],
            whitelistedInstallationSources: ['com.android.vending'],
        },
    },
};
```

{% endtab %}

{% tab title="Cordova" %}

```typescript
const config: TalsecConfig = {
    watcherMail: 'your@email.com',
    androidConfig: {
        packageName: 'com.example.app',
        certificateHashes: ['...'],
        malwareConfig: {
            blacklistedPackageNames: ['com.suspicious.app'],
            blacklistedHashes: ['755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21'],
            suspiciousPermissions: [
                ['android.permission.READ_SMS'],
                ['android.permission.BIND_ACCESSIBILITY_SERVICE'],
                ['android.permission.REQUEST_INSTALL_PACKAGES'],
            ],
            whitelistedInstallationSources: ['com.android.vending'],
        },
    },
};
```

{% endtab %}

{% tab title="KMP" %}

```kotlin
val config = freeraspConfig(
    watcherMail = "your@email.com",
    androidConfig = AndroidConfig(
        packageName = packageName,
        certificateHashes = listOf(certificateHash),
        malwareConfig = MalwareConfig(
            blacklistedPackageNames = listOf("com.suspicious.app"),
            blacklistedHashes = listOf("755ee39ff11bad65193c4806cadb9cedda41e20663c35494cb7d4e9646ddcf21"),
            suspiciousPermissions = listOf(
                listOf("android.permission.READ_SMS"),
                listOf("android.permission.BIND_ACCESSIBILITY_SERVICE")
            ),
            whitelistedInstallationSources = listOf("com.android.vending")
        )
    )
)
```

{% endtab %}
{% endtabs %}

### Configuration Parameters

| Parameter                        | Type                         | Description                                                                            |
| -------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------- |
| `blacklistedPackageNames`        | `Array`/`List<String>`       | Package identifiers to explicitly blocklist.                                           |
| `blacklistedHashes`              | `Array`/`List<String>`       | SHA-256 APK hashes to explicitly blocklist.                                            |
| `suspiciousPermissions`          | `Array`/`List<List<String>>` | Permission sets — flagged if all permissions in any set are actively granted.          |
| `whitelistedInstallationSources` | `Array`/`List<String>`       | Trusted installer package names. Apps from unlisted sources are treated as sideloaded. |


---

# 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/integration-guide/configuration.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.