# Understanding Security Posture

[`securityPosture`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#securityposture) is the security evaluation of a device, determined by the current device status.
Current device status is determined by factors such as if the device has been rooted, if it is running a custom ROM, and more.

`securityPosture` is broken down in the response into [`devicePosture`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#deviceposture) and an additional list of [`postureDetails`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#posturedetail) which contains the field [`securityRisk`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#securityrisk).

The `securityRisk` field gives an idea of why the device is not considered to be in the most secure state, while the `advice` list can help perform actions to improve the security posture of the device.
For example:

```
 {
  "devicePosture": "POTENTIALLY_COMPROMISED",
  "postureDetails": [
    {
      "securityRisk": "UNKNOWN_OS",
      "advice": [
        {
          "defaultMessage": "The user should lock their device's bootloader."
        }
      ]
    },
    {
      "securityRisk": "HARDWARE_BACKED_EVALUATION_FAILED"
    }
  ]
}
```

## Evaluating Security Posture

By default, `securityPosture` is evaluated using key attestation, specifically [hardware-backed key attestation (HBKA)](https://developer.android.com/training/articles/security-key-attestation) if applicable, providing a trustworthy security verdict as it generates and signs the attestation in secure hardware.

It may sometimes be the case that HBKA cannot be used for this evaluation. To reflect this, `securityRisk` will return "HARDWARE_BACKED_EVALUATION_FAILED". This means that `securityPosture` can be evaluated but not with HBKA, meaning that the device's boot integrity state could be compromised (e.g. the device could be rooted) and go undetected by software-based detection.

## Understanding Security Posture Verdicts

Different combinations of `devicePosture` and `securityRisk` can be interpreted to understand the overall security of the device. Please be aware that the list below is not exhaustive:

- If `devicePosture` returns "SECURE" and `securityRisk` returns "HARDWARE_BACKED_EVALUATION_FAILED" the device's integrity is secure, but this could not be confirmed by HBKA.
- If `devicePosture` returns "POTENTIALLY_COMPROMISED" and no `securityRisk` result is returned, then HBKA is used in the evaluation and considers the device as compromised.
- If `devicePosture` returns "POTENTIALLY_COMPROMISED" and `securityRisk` returns "HARDWARE_BACKED_EVALUATION_FAILED" then only software based checks could be performed, yet the integrity threat signals are strong enough to consider the device as compromised.
- If `devicePosture` returns "POSTURE_UNSPECIFIED" then the security evaluation could not be completed. We recommend waiting for the re-issuance of the HBKA, which occurs when a new verdict is returned, to see if it can return a specific value. However, it is expected for "POSTURE_UNSPECIFIED" to occur on initial install for a short period of time.

### Android Management API to Play Integrity API mappings

The following table provides the mapping equivalence between AM API verdict and
the Play Integrity API verdict response.

| [AM API DevicePosture](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#deviceposture) | [AM API Posture.Detail.SecurityRisk](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#PostureDetail.FIELDS.security_risk) | [Play Integrity API verdict equivalent](https://developers.google.com/google/play/integrity/verdicts#device-integrity-field) |
|---|---|---|
| [`SECURE`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#DevicePosture.ENUM_VALUES.SECURE) | [`SECURITY_RISK_UNSPECIFIED`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#SecurityRisk.ENUM_VALUES.SECURITY_RISK_UNSPECIFIED) | `MEETS_STRONG_INTEGRITY` |
| [`SECURE`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#DevicePosture.ENUM_VALUES.SECURE) | contains: [`HARDWARE_BACKED_EVALUATION_FAILED`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#SecurityRisk.ENUM_VALUES.HARDWARE_BACKED_EVALUATION_FAILED) | `MEETS_DEVICE_INTEGRITY` |
| [`AT_RISK`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#DevicePosture.ENUM_VALUES.AT_RISK) | contains: [`HARDWARE_BACKED_EVALUATION_FAILED`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#SecurityRisk.ENUM_VALUES.HARDWARE_BACKED_EVALUATION_FAILED) | `MEETS_DEVICE_INTEGRITY` |
| [`POTENTIALLY_COMPROMISED`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#DevicePosture.ENUM_VALUES.POTENTIALLY_COMPROMISED) | contains: [`UNKNOWN_OS`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#SecurityRisk.ENUM_VALUES.UNKNOWN_OS) | `MEETS_BASIC_INTEGRITY` |
| [`POTENTIALLY_COMPROMISED`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#DevicePosture.ENUM_VALUES.POTENTIALLY_COMPROMISED) | contains: [`COMPROMISED_OS`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#SecurityRisk.ENUM_VALUES.COMPROMISED_OS) | `<unset>` |
| [`POSTURE_UNSPECIFIED`](https://developers.google.com/android/management/reference/rest/v1/enterprises.devices#DevicePosture.ENUM_VALUES.POSTURE_UNSPECIFIED) | `<any>` | `<unset>` |