Configuration
Filtering Purpose
Facilities are provided to obtain detailed information about the attributes of devices. Filters may then be defined and checked against all devices attempting to fetch Approov tokens. These filters can match against specific device attributes.
When a filter matches then this is shown in a special graph within the Live Metrics. This allows an appreciation of the timing and prevalence of particular attributes to be known. This can be useful for understanding the population of devices that are using your Approov account. Moreover, these facilities may be used for understanding any suspicious behavior and/or by Approov support staff understanding any irregularities in the operation of apps using your account.
Options are provided to ban particular devices with specific characteristics, and even to apply special security policies to matching devices. This may be used by Approov support staff to run customized security rules that are able to gather more detailed telemetry from specific devices for analysis.
Getting Specific Device Information
It is possible to obtain more detailed device information for any device that has had a device specific security policy added. At least one Approov fetch must be performed to collect the information (remembering that a previously fetched Approov token may take up to 5 minutes to expire before the app needs to fetch a new one, if it is not restarted).
Once this is done the information can be obtained as follows, by specifying the device ID:
approov device -getInfo qZka0yfv+ExvOq3PRh6pGw==
The information most recently collected is shown, along with the local time of its capture:
captured: 2020-07-23 11:51:26 BST
rejection-flags: app-not-registered
public-flags: app-not-registered,rooted,root-risk,xposed
ip: 1.2.3.4
device-id: qZka0yfv+ExvOq3PRh6pGw==
device: Android 8.1.0, Nexus 5X, google, bullhead, en
archid: arm64-v8a
device-props: {'Model':'Nexus 5X','Fingerprint':'google/bullhead/bullhead:8.1.0/OPM6.171019.030.E1/4805388:user/release-keys'}
sdkid: 4000
sdk-version: 2.4.0
app-name: Approov OkHttp Shapes
app-version: 3.0(3)
appid: com.criticalblue.demo
app-id-sig: NhVaAEGs3U6fLObhZAIdRh71wVF7kSOL0aAMv+e5TvU=
app-sig: tL8CNNpf4XlekWkwuyJaCRtcntJyjZ1ujYJ7CZMO+Fk=
attest-reason: launch
The information consists of a series of <key>:<value> attributes as detailed in Specific Device Information.
The individual device information is collected and held by the Approov servers on a best effort basis. The information may be cleared from time to time so you should save it in a local file if you wish to keep it more permanently.
Specific Device Information
This details the information that may be made available for a specific device. The exact set of information may vary over time and also between iOS and Android.
| Key | Description |
app-id-sig | On Android this provides the overall identity signature used when registering an App Bundle or APK signed by Google Play signing (as the raw app signature may change depending on the app delivered to an individual device). |
app-name | The public name of the app. |
app-sig | The signature of the app that is running. |
app-version | The version of the app. |
appattest-risk-metric | Only shown on iOS if the AppAttest feature is enabled, showing the captured Fraud Risk from the device. |
appid | The unique package name of the app. |
archid | Processor architecture type. |
arcprefix | First 5 digits of the Attestation Response Code to assist in correlating this information with a specific Approov token. |
attest-reason | The reason for performing an Approov token fetch. |
boot-hash | This is only available on Android when using hardware based key attestation. This is a base64 encoded digest of all data protected by the device's verified boot process. |
boot-key | This is only available on Android when using hardware based key attestation. It is a base64 encoded secure hash of the public key used to verify the integrity and authenticity of all code that executes during device boot up as part of the device's verified boot process. |
custom-claim | Provides the base64 encoded 256-bit hash of a binding value if Token Binding is used. |
device | Information about the particular model of the device. |
device-id | The 128-bit base64 encoded device ID. |
device-props | Provides more detailed information about the particular model and OS build of a device (although it does not uniquely identify an individual device). |
install-pubkey | If the SDK version supports this, then this provides the installation public key. This is a base64 DER encoded ASN.1 EC key. |
ip | The IP address of the client, independently of the IP Tracking Policy that has been selected. Although, you should note that, the IP addresses are only held in the memory of the Approov cloud servers and are never committed to any file storage. |
playintegrity-app | Only shown on Android if the Play Integrity feature is enabled, providing any app integrity verdict obtained. |
playintegrity-certs | Only shown on Android if the Play Integrity feature is enabled, providing the fingerprints of any SHA256 hashes of certificates used to sign the app. |
playintegrity-device | Only shown on Android if the Play Integrity feature is enabled, providing any device integrity verdicts obtained. |
playintegrity-licensing | Only shown on Android if the Play Integrity feature is enabled, providing any app licensing verdict obtained. |
probe-result | Only shown if the Certificate Pins From a Device feature is used to extract the certificate chain for a URL from the perspective of an individual device. |
public-flags | The full set of device property flags that have been collected, comma separated. |
rejection-flags | Set of device property flags that have been collected and are causing the device to fail attestation, comma separated. If this key is not present then the device was passed. |
sdk-version | The version of the SDK being used. |
sdkid | The particular library ID of the SDK being used. |
system-hash | Base64 encoded 256-bit hash of the executable system image that identifies a particular build of a device. |
user-property | Optional for the user property that may be set in the SDK. This is normally used to identify which particular quickstart variant is being used. |
Adding a Device Filter
A device filter may created that checks the attributes of every device fetching an Approov token to determine if it has a particular attribute. For instance:
approov filter -add ipmatch -key ip -value 1.2.3.4
This adds a new filter called ipmatch. This name is used to reference the filter and also appears in the Live: Mobile App Attestations Grafana dashboard if the filter is matched. The name is restricted to a maximum of 20 characters of lower case alphanumerics and the - sign only. If a filter name is reused then the previous settings are overridden.
The -key option determines the particular key in the information to be checked against, ip in this case. If the key is not present then the match never occurs. The -value specifies the specific text for the value for the match to occur. To match any non-empty value for the given key, the -exists option can be used. In this case the match is for any device using the IP address 1.2.3.4. (This initial form requires an exact verbatim match, to have a single filter with more general matching semantics, see the section on Regular Expression Filtering.). See Specific Device Information for a full list of the keys that may be used and their meanings.
With the default options the only impact is to show the match in the Live: Mobile App Attestations Grafana dashboard.
Filtering may be restricted to only new devices by using the -newInstallOnly flag:
approov filter -add special-app-sig -key app-sig -value DRJNqt37tsdHwb9FKFT80dPqXlOHqZnZy68zAiVSsvM= -newInstallOnly
In this case the matching is looking for a particular app signature amongst device IDs that attest for the first time.
A maximum of 25 filters may be defined at any one time.
Regular Expression Filtering
Normally when a filter -value is specified it must be an exact verbatim match for the specified key's value. However, it is also possible to do Regular expression matching if the -regex option is used. For example:
approov filter -add android7 -key device -value "Android 7" -regex
This creates a filter that checks for the substring Android 7 in the device property. By default a specified regular expression performs a substring match. However, the full power of regular expressions may be used. There is a useful interactive tool here for constructing regular expressions.
Regular expression filtering can be particularly useful for checking if a device has particular properties in the flags-all device information key. Simply specify the required flag name with -regex and this will do a substring match to check if the flag is set, regardless of other flags (being careful to make sure the flag name is not itself a substring of some other flag name).
Conjunction Filters
It is possible to create a filter that is only matched if a set of other filters all match. This allows the creation of more complex conditions that require matches across multiple different device information keys.
For instance, if you have previously setup a filter called android7 and another one called ipmatch, then you create a new filter that is the conjunction of these two as follows:
approov filter -add both-matched -conjunction android7+ipmatch
This new filter will only match if both the input filters are matched on the same device. You specify the set of input filters using a + separated list provided to the command. Note that these inputs must be ordinary filters and not conjunction filters themselves.
It is also possible to negate one or more filters within a conjunction. You can achieve this by adding such filters at the end of the expression grouped using brackets and prefixed with a negation operator, ¬ or ~. Using the example above, we can create a filter which matches an ipmatch filter only when it is from a device that is neither android7 nor android8:
approov filter -add ipmatch-non-droid7-8 -conjunction ipmatch+¬(android7+android8)
When you first add a conjunction filter a check is made that the input filters are present. However, if these are subsequently removed then the conjunction filter will never match since all inputs must be present for a match to occur.
Inverted Filters
It is possible to invert the overall result of a filter. This allows assertions which are not necessarily possible with -exists or -value alone.
For instance, if you wish to create a filter which matches all non-Android devices, you can invert a filter which matches Android devices as follows:
approov filter -add non-android -key device -value "Android" -regex -invert
Listing Device Filters
All currently set filters can be shown as follows:
approov filter -list
The list of options associated with the filter are shown on the right hand side of the filter listing:
2 filters:
ipmatch ip: 1.2.3.4
special-app-sig app-sig: DRJNqt37tsdHwb9FKFT80dPqXlOHqZnZy68zAiVSsvM= newDIDOnly
Removing a Device Filter
Any named filter can be removed as follows:
approov filter -remove special-app-sig
If you remove a filter that is an input to a conjunction filter, then it will never match until the input filter is replaced,