> 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.md).

# Integration Guide

This section provides a technical overview of the freeMalware Detection module's execution flow. Understanding this operational lifecycle is a critical prerequisite for a successful integration, as it defines precisely when vulnerability scans occur, how state is managed, and how threat results are dispatched to the application.

***

## The Detection Pipeline

Upon initialization, the detection engine executes a strict, automated pipeline before delivering any threat telemetry. The process is designed to minimize battery consumption and optimize startup performance through asynchronous batch operations.

```mermaid
flowchart TD
    A[Engine Initialization] --> B{Configuration Changed?}
    B -->|Yes| C[Clear Scan Cache]
    C --> D[Perform Asynchronous Scan]
    B -->|No| D
    
    D --> E
    D -.->|App Interrupted| O[Terminate Scan]

    subgraph loop["Per-App Evaluation Loop"]
        direction TB
        E{App Scanned Previously?}
        E -->|Yes| F[Ignore App]
        E -->|No| G{Is Trusted?}
        G -->|Yes| F
        G -->|No| H[Evaluate App]
        H --> I{Is Suspicious?}
        I -->|Yes| K[Add to Threat Results]
        I -->|No| J[Mark as Safe]
    end

    K --> M
    J --> M
    F --> M
    M[Save Safe Apps to Cache]
    M --> N[Dispatch Threat Callback]

    classDef highlight fill:#f9f9f9,stroke:#333,stroke-width:2px;
    classDef interrupt fill:#fff3e0,stroke:#e65100,stroke-width:2px,stroke-dasharray:5 5;
    class N highlight;
    class O interrupt;
```

***

* **Handling Configuration Changes:** On each launch, the engine checks whether the active detection configuration has changed since the last scan. If a change is detected, the internal cache of previously evaluated applications is purged, and all packages are re-evaluated from scratch against the updated definitions.
* **Asynchronous Batch Evaluation:** The scanning process is offloaded to a background thread. For each installed application, the engine first checks whether it was already recorded in the safe cache from a previous scan, and — if not — whether it is explicitly trusted. Applications that satisfy either condition are skipped without further evaluation. Only the remaining applications are passed to the on-device malware evaluator, which requires no network connectivity.
* **Safe Cache & Trust Management:** Only after the entire evaluation batch successfully completes are applications marked as benign recorded in a persistent internal cache. Explicitly trusted applications are bypassed at evaluation time but are not written to the cache, as they are re-identified on each launch. During subsequent launches (provided the configuration remains unchanged), cached applications are bypassed entirely, resulting in near-instantaneous initialization times. However, if the application is terminated before the background batch completes, the safe cache is not updated and the full scan will restart upon the next launch.
* **Threat Callback Dispatch:** The final threat callback is dispatched on the main thread only after all installed applications have been successfully evaluated.

***

## Application Lifecycle Constraints

Because comprehensive background scanning is a resource-intensive operation, the detection engine limits its execution frequency.

{% hint style="info" %}
**Single Execution per Process**

The freeMalware Detection callback is triggered only once per application process lifecycle, immediately following the initial scan.

The scan does NOT re-trigger when the application transitions between background and foreground states (e.g., when the user minimizes and later resumes the app).
{% endhint %}

### Recommended Implementation Strategy

Since the engine will not continuously re-notify the application of an existing threat upon resuming, the host application architecture must handle threat state retention.

To prevent users from bypassing your security screen by backgrounding and resuming the application, your UI logic must maintain awareness of the threat:

1. **Persist the Threat State**: When the callback fires, save a flag (e.g., `isMalwareDetected = true`) in your application's session memory.
2. **Enforce on Resume**: Whenever the application returns to the foreground (e.g., via Android's `onResume`, Flutter's `AppLifecycleState.resumed`, or React Native's `AppState.currentState`), check this saved flag. If the flag is true, immediately re-display your blocking UI.

***

## Threat Remediation Validation

Because the detection engine operates on a scanning schedule rather than real-time monitoring, it does not provide uninstallation hooks. If a user removes a malicious application, the SDK does not notify you directly; the threat will simply be omitted from the results of the next background scan.

To programmatically verify that the device environment is secure after a user claims to have remediated the threat, implement the following strategy:

* **Dynamic OS Validation**: Utilize standard operating system APIs (such as Android's `PackageManager`) to actively query if the offending package name is still present on the system.


---

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

```
GET https://docs.talsec.app/freerasp/freemalwaredetection/integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.