Device claim scripts

Prev Next

If built-in device claims do not collect the information you need from a user's device, you can write and upload native executable scripts. These scripts are called scripted (formerly on-demand) device claims.

After the user signs in, the scripts are pushed to the user's device. The client runs these executables, and the returned information becomes a claim in the Controller. You can then use these claims in assignment criteria scripts in policies.

NOTE

Running arbitrary scripts on users' devices is a security risk. If you do not use this feature, disable it.  

As of AppGate ZTNA version 6.6, profile DNS name verification is required to run device claim scripts. Follow the steps to verify your profiles.

WARNING

If you have not yet updated to version 6.6 and you intend to continue using device claim scripts after you upgrade, you must obtain an updated license file before upgrading your Collective to 6.6.


Functionality of device claim scripts

A device claim script script can be any executable file type supported by the target client platform—for example, a native Win32 binary or a .bat file on Windows, or a Bourne shell script on Unix. The script runs with the same rights as the user. The Controller  sends a checksum for the executable, and the client checks whether the local copy has changed. If it has changed, the script is downloaded again. Scripts are saved on the user's device, for example on Windows in %homepath%\appdata\appgate\.

NOTE

Because the script, execution environment, and measurement points are party under user control, treat device claim results as untrusted and do not rely on them for critical security decisions.

A script can be designed as a single function with no arguments, or it can support multiple options based on the arguments provided. It must complete within 12 seconds or it times out. It must return exit code 0 for the claim to be set. The claim value is set to the last line written to stdout.

Example device claim script

The following example checks whether a file exists or whether a process is running on Linux. The --pathexists option checks for the specified file at a given location, and the --process option checks whether the specified process is currently running. The script returns yes or no, which you can evaluate in a condition.

1#!/bin/sh
set -e
  case "$1" in
    '--pathexists')
      [ -e "$2" ]
      ;;
    '--process')
      ps -C "$2" 2>&1 > /dev/null
      ;;
    *)
      echo "Usage: $0"
      echo "  --pathexists <file>"
      echo "  --process <name>"
      exit 1
      ;;
esac

NOTE

If you create a script such as an sh file, include #!/bin/sh at the beginning. If not, AppGate ZTNA will not receive the output.