Analysis & Actions
Analyzing New App Installs
Information for new devices (i.e. device IDs that have not previously been seen) is collected automatically. It can be obtained by using new-install as the parameter for -getInfo:
approov device -getInfo new-install
A stream of information for the most recent app installs is provided, with a separator providing the ID and the local capture time.
--- w4mmGFZkpz5oPz6w6gl1Cw== 2020-07-23 12:10:43 BST ---
rejection-flags: app-not-registered
public-flags: app-not-registered,jailbroken,devicecheck-unavailable
ip: 1.2.3.4
device-id: w4mmGFZkpz5oPz6w6gl1Cw==
device: iOS, 12.1.2, iPhone7,2, en_ES
archid: arm64
sdkid: 4505
sdk-version: 2.4.0
app-name: Approov Shapes
app-version: 1.0
appid: ios.swift.shapes.demo.approov.io
app-sig: DRJNqt37tsdHwb9FKFT80dPqXlOHqZnZy68zAiVSsvM=
attest-reason: expiry
The new device information is collected and held by the Approov servers on a best effort basis. Only the information for the last 100 new devices is held and earlier entries are discarded. Note also that 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.
If you wish to obtain information for all new app installs then the following short bash script can be used. This appends to the approov-new-install.txt file any new devices on a per-minute basis. This ensures that, unless there are more than 100 new devices per minute, all the new device information will be captured.
#!/bin/bash
while true; do
echo "getting new devices"
approov device -getInfo new-install -clear >> approov-new-install.txt
sleep 1m
done
The use of the -clear option ensures that prior data is cleared on each call so there is no duplicate information in the generated file. Note that this approach cannot be used by more than one user at a time.
Analyzing Filtered Devices
It is possible to capture full device information for any device that matches a filter. To enable this you must use the -captureDeviceInfo flag on the added filter, for example:
approov filter -add ipmatch -key ip -value 1.2.3.4 -captureDeviceInfo
Information for any device that matches the ipmatch filter is then collected. The information can be obtained by using filtered as the parameter for -getInfo:
approov device -getInfo filtered
A stream of information for the most recent filter matches is provided, with a separator providing the ID and the local capture time:
--- w4mmGFZkpz5oPz6w6gl1Cw== 2020-07-23 12:10:43 BST ---
matched-filters: ipmatch
flags-all: app-not-registered,jailbroken,devicecheck-unavailable
ip: 1.2.3.4
device-id: w4mmGFZkpz5oPz6w6gl1Cw==
device: iOS, 12.1.2, iPhone7,2, en_ES
archid: arm64
sdkid: 4505
sdk-version: 2.4.0
app-name: Approov Shapes
app-version: 1.0
appid: ios.swift.shapes.demo.approov.io
app-sig: DRJNqt37tsdHwb9FKFT80dPqXlOHqZnZy68zAiVSsvM=
attest-reason: expiry
Note that the first property shown is matched-filters which lists all of the filters that were matched by the device.
The device filtering information is collected and held by the Approov servers on a best effort basis. Only the information for the last 100 new devices is held and earlier entries are discarded. Note also that 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.
If you wish to obtain information for all filtered devices then the following short bash script can be used. This appends to the approov-filtered.txt file any filtered devices on a per-minute basis. This ensures that, unless there are more than 100 filtered devices per minute, all the information will be captured.
#!/bin/bash
while true; do
echo "getting filtered devices"
approov device -getInfo filtered -clear >> approov-filtered.txt
sleep 1m
done
The use of the -clear option ensures that prior data is cleared on each call so there is no duplicated information.
Rejecting Filtered Devices
A -reject option is provided so that any device which matches is automatically rejected, and will not receive a valid Approov token. For example:
approov filter -add ipmatch -key ip -value 1.2.3.4 -reject
This requires confirmation:
WARNING: using the ban or reject option will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
successfully set filter ipmatch
This rejects any device that attempts to fetch an Approov token from the IP address 1.2.3.4.
You should be especially careful when using this option as it is available with dev role privileges. If a match is used that covers too many devices then this could cause large numbers of app users to be rejected. Always test the match without reject first and examine the metrics to determine the prevalence of the match.
Banning Filtered App Installs
A -ban option is provided so that any app installation which matches is automatically banned. For example:
approov filter -add ipmatch -key ip -value 1.2.3.4 -ban
This requires confirmation:
WARNING: using the ban or reject option will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
successfully set filter ipmatch
This bans any device ID that attempts to fetch an Approov token from the IP address 1.2.3.4.
Note that any such ban will be associated with the app installation and it will continue to be banned even if the filter is subsequently removed.
You should be especially careful when using this option as it is available with dev role privileges. If a match is used that covers too many devices then this could cause large numbers of app users to be rejected. Always test the match without banning first and examine the metrics to determine the prevalence of the match.
Marking Filtered Devices as Risky
A -risky option is provided so that matching devices are automatically marked as risky, for example:
approov filter -add ipmatch -key ip -value 1.2.3.4 -risky
This means any request from IP address 1.2.3.4 will have the risky-device flag asserted.
The impact of this is two-fold:
- The device will be issued Approov tokens that have a 2 -minute lifetime rather than the usual 5.
- If the
riskAnnotation Policy is set then this means that therisky-deviceflag will be set. This enables backend systems to observe this annotation and potentially perform different actions for the device.
Custom Filtered Security Policy
It is possible to use the special device ID value ++FilteredSecPolicy++w== to provide a security policy that is applied to any device which matches specific filters. Firstly add this pseudo device ID as follows:
approov device -add ++FilteredSecPolicy++w== -policy alt-rules,default,default
For the filtered security policy to have an effect, you should use a different security rules name (shown as alt-rules in the above example) from the global policy setting in the account. Note though that it is not possible to set custom rejection or annotation rules.
The example alt-rules shown above will not work (there are no such rules). Normally this feature is used in conjunction with Approov support staff for more detailed analysis of specific activity on your account and so you should contact Approov support if you wish to use this feature.
You are not able to use the -pinMode option on this special device ID but the -probeURL value is applied.
In order to enable this behavior for a particular filter you must use the -execFilteredSecPolicy option, for example.
approov filter -add ipmatch -key ip -value 1.2.3.4 -execFilteredSecPolicy
This causes any request from IP address 1.2.3.4 to execute the custom filtered security policy.
It is also possible to make a certain percentage of all devices execute the special filtered security policy, instead of the standard one for the account. You can simply set the percentage as follows:
approov filter -setSamplingPercentage 0.1
An admin role and confirmation is required to make this change:
WARNING: using sampling will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
successfully set sampling percentage
This sets the sampling percentage to 0.1%. This means that 0.1% of all devices will execute the special filtered security policy rather than the standard account security policy. This determination is made on the basis of the device ID so that the same device will either be subject to the special policy or not. However, the selections change on each day so the sampling moves across the device population. Note that the maximum that may be specified is 5%.
You can always see the current setting with:
approov filter -getSamplingPercentage
Adding this special security policy causes a very small addition to the latency of Approov fetches, independently of the number of devices that use it. Thus we suggest you only leave this special policy added for as long as you need to use it.
Observing All Fetching Devices
A record is kept of the device IDs of any apps that are fetching Approov tokens. This is held in time order, with an optional timestamp. It can be obtained with:
approov device -getFetches timed
Which provides a list of the fetches like this:
qZka0yfv+ExvOq3PRh6pGw== 2020-07-23 12:10:45 BST
qZka0yfv+ExvOq3PRh6pGw== 2020-07-23 16:27:12 BST
w4mmGFZkpz5oPz6w6gl1Cw== 2020-07-23 16:27:20 BST
This is useful for analysis of the device IDs that are using the account, and perhaps frequency of use analysis to determine if particular device IDs are responsible for a high use of the account. These devices can then be added as custom devices for more detailed analysis if required. The parameter timed indicates that timestamps should be included.
The fetching device ID information is collected and held by the Approov servers on a best effort basis. Only the information for the last 1000 requests is held and earlier entries are discarded. Note also that 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.
A simple script such as the following can be used to collect this information into the local file approov-fetches.txt:
#!/bin/bash
while true; do
echo "getting latest fetches"
approov device -getFetches untimed -clear >> approov-fetches.txt
sleep 1m
done
This simply captures the latest untimed information every minute and uses the -clear option to discard the obtained information so that it is not duplicated in the resultant file.
Analyzing Captured Streams
Information collected regarding fetches or the attributes of particular devices can be easily manipulated using standard commands. For instance, imagine we have captured approov-fetches.txt showing two different devices using the account as follows:
qZka0yfv+ExvOq3PRh6pGw==
w4mmGFZkpz5oPz6w6gl1Cw==
w4mmGFZkpz5oPz6w6gl1Cw==
w4mmGFZkpz5oPz6w6gl1Cw==
w4mmGFZkpz5oPz6w6gl1Cw==
qZka0yfv+ExvOq3PRh6pGw==
qZka0yfv+ExvOq3PRh6pGw==
w4mmGFZkpz5oPz6w6gl1Cw==
w4mmGFZkpz5oPz6w6gl1Cw==
We can easily count the number of occurrences of each device ID as follows:
sort approov-fetches.txt | uniq -c
Which will output the device IDs and their frequencies as follows:
3 qZka0yfv+ExvOq3PRh6pGw==
6 w4mmGFZkpz5oPz6w6gl1Cw==
We can use this technique to analyze the frequency of use by certain device IDs or the frequency of occurrence of particular device attributes. This method can be used to identify commonly occurring device attributes, which can then be used in further searches in the original file to find the full context of each interesting match.
Note that this output can of course itself be piped to a file, such as output.txt. You can then show the most commonly occurring repeats as follows:
sort -h -r output.txt | less
The -h and -r options cause the most frequently occurring lines to be shown first.