> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/sdk-lite/setup/android/security-checks.md).

# Security Checks

## Context

Face Liveness Lite protects the liveness result with two independent layers of checks:

<table><thead><tr><th width="146.1328125">Layer</th><th width="101.234375">Where it runs</th><th width="118.19921875">When it runs</th><th>What you receive when it blocks</th></tr></thead><tbody><tr><td>Certta device checks</td><td>On the device, in the SDK</td><td>Before and during the capture</td><td><code>LivenessLiteEvent.Error</code> with type <code>SECURITY_EXCEPTION</code>. No signed response.</td></tr><tr><td>Liveness checks</td><td>On the liveness servers</td><td>While the capture is processed</td><td><code>LivenessLiteEvent.Failure</code> with type <code>DEVICE_ISSUE</code>, with a signed response.</td></tr></tbody></table>

Both layers are always part of the flow. The Certta device checks can be turned off with `enableSecurity`. The liveness checks cannot be turned off from the app.

## Certta Device Checks

The SDK checks the device before and during the capture to make sure the result was not tampered with. If the device looks compromised, the SDK stops the capture and returns an error instead of a result.

### **What is checked**

| Protection         | What it detects                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| Root detection     | Rooted devices, the `su` binary, Magisk and Zygisk.                                                         |
| Hooking frameworks | Frida (library, server port, threads and files), Xposed and LSPosed.                                        |
| Code integrity     | Hooking or injection libraries loaded into the app, and system functions redirected or patched at runtime.  |
| Debugging          | A debugger attached to the app, a process tracing the app, or an app built as debuggable.                   |
| Timing analysis    | Execution timing that suggests a debugger or step tracer. Used to confirm other findings, never on its own. |

The checks are fail-closed: if one of them cannot run, the SDK treats it as a threat. A broken or bypassed check never lets the capture through.

Any finding blocks the capture. There is no severity level that is allowed to continue.

{% hint style="info" %}
Emulators are not blocked by the device checks on their own. An emulator is only blocked when it triggers one of the checks above, for example when the emulator image is rooted or the app is a debug build.
{% endhint %}

### **How it works**

1. **Before the capture.** When you call `startLiveness()`, the SDK checks the device before opening the camera. If a threat is found, the camera never opens.
2. **During the capture.** While the capture is running, the SDK checks the device again every 2 seconds. If a threat appears, for example a hooking tool attached in the middle of the capture, the capture is stopped right away.
3. **At the end.** When the run ends, the monitoring stops.

The checks also run during `prewarm()`. A threat found there does not return an error: the prewarm is skipped, and `startLiveness()` runs the checks again.

{% hint style="danger" %}
Once a threat is found on a device, the result is saved in the app's private storage and included in every later check. The device stays blocked until the app data is cleared or the app is reinstalled.
{% endhint %}

### **Configuration**

| Parameter        | Type      | Default | Description                                                           |
| ---------------- | --------- | ------- | --------------------------------------------------------------------- |
| `enableSecurity` | `Boolean` | `true`  | Runs the Certta device checks before and during the liveness capture. |

{% hint style="info" %}
Keep `enableSecurity` set to `true` in production. Turning it off removes the protection against tampered devices.
{% endhint %}

### **When a threat is found**

The SDK returns a `LivenessLiteEvent.Error` with the type `SECURITY_EXCEPTION`. The `description` summarizes how many threats were found, grouped by severity:

```
Security threat detected during process: Security threats detected: 1 critical, 1 medium
```

Retrying on the same device returns the same error, because the finding is saved until the app data is cleared or the app is reinstalled. For the recommended message and what to do, see [SECURITY\_EXCEPTION](https://docs.caf.io/sdk-lite/error-handling/android/error-handling.md#security_exception).

## Liveness Checks

The capture is processed by the liveness service, which runs its own checks against digital injection attacks, such as manipulated video streams or a tampered app. These checks run on the server, so they cannot be bypassed on the device.

When these checks do not pass, the capture is still processed and the SDK returns a `LivenessLiteEvent.Failure` with the type `DEVICE_ISSUE`, together with a signed response. Validate it on your backend like any other result.

### **Liveness environments**

The liveness checks run in an environment configured for your account. Each environment type applies its own rules:

| Environment type | Build configuration | Installation mode                     | Injection tests |
| ---------------- | ------------------- | ------------------------------------- | --------------- |
| Development      | Any build           | Any installation                      | Pass            |
| Production       | Release build       | ADB                                   | Fail            |
| Production       | Release build       | Normal installation, APK or app store | Pass            |
| Production       | Debug build         | ADB                                   | Fail            |
| Production       | Debug build         | Normal installation, APK or app store | Fail            |
| Test             | Release build       | ADB                                   | Fail            |
| Test             | Release build       | Normal installation, APK or app store | Pass            |
| Test             | Debug build         | ADB                                   | Fail            |
| Test             | Debug build         | Normal installation, APK or app store | Fail            |

When the injection tests fail, the SDK returns a `DEVICE_ISSUE` failure.

{% hint style="info" %}
Running the app from Android Studio installs it through ADB. In production, a run started this way returns `DEVICE_ISSUE` even with a release build. To test the full flow, install a release build from an APK file or from the app store.
{% endhint %}

The liveness environment used by your account is configured by Certta. If you need a different setup for testing, contact your Certta account team.

### Testing Your Integration

Because of both layers, a debug build from Android Studio cannot complete a liveness capture in production:

* With `enableSecurity = true`, the Certta device checks detect the debuggable app and return `SECURITY_EXCEPTION`.
* With `enableSecurity = false`, the capture runs, but the liveness checks return a `DEVICE_ISSUE` failure.

To test the full flow, use a release build installed from an APK file or the app store, with `enableSecurity = true`.

{% hint style="danger" %}
If a test device was blocked by the Certta device checks before, it stays blocked after you change the build. Clear the app data or reinstall the app.
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/setup/android/security-checks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
