# PAN GlobalProtect HIP

The HIP ('Host Integrity Protection') mechanism is a security scanner for the PAN GlobalProtect VPNs, in the same vein as Cisco's CSD and Juniper's Host Checker (tncc.jar).

## How it works

It is somewhat less intrusive than CSD or TNCC, because it does not appear to work by downloading a trojan binary from the VPN server. Instead, it runs a HIP report generator (built-in as part of the official GlobalProtect VPN client software), which generates an "HIP report" XML file.

HIP flow used in the official clients:

1. Client authenticates and fetches the tunnel configuration from the GlobalProtect gateway.
2. Client runs HIP report generator and computes MD5 digest of report.
3. Client checks whether a HIP report is required (`/ssl-vpn/hipreportcheck.esp`), including its MD5 digest and gateway-assigned IP address in the report.
4. Gateway responds whether or not a HIP report is required (normally, it doesn't require a new one if a report with the same MD5 digest and same IP address have been submitted recently).
5. Client uploads the complete HIP report to (`/ssl-vpn/hipreport.esp`).
6. Server confirms acceptance of HIP report with a success message.

If all goes well, the client should have the expected level of access to resources on the network after these steps are complete. However, two things can go wrong:

- Many GlobalProtect servers report that they require HIP reports (#3 above), but don't actually enforce this requirement. (For this reason, OpenConnect does not currently fail if a HIP report is required but no HIP report script is provided.)
- Many GlobalProtect servers will claim that the HIP report was accepted successfully (#6 above) but silently fail to enable the expected network access, presumably because some aspect of the HIP report contents were not approved.

## HIP support in OpenConnect

OpenConnect supports HIP report generation and submission by passing the `--csd-wrapper=SCRIPT` argument with a shell script to generate a HIP report in the format expected by the server. This shell script must output the HIP report to standard output and exit successfully (status code 0). The HIP script is called with the following command-line arguments:

       --cookie: a URL-encoded string, as output by openconnect
                 --authenticate --protocol=gp, which includes parameters
                 --from the /ssl-vpn/login.esp response

       --client-ip{,v6}: IPv4/6 addresses allocated by the GlobalProtect
                         VPN for this client (included in
                         /ssl-vpn/getconfig.esp response)

       --md5: The md5 digest to encode into this HIP report. All that
              really matters is that the value in the HIP report
              submission should match the value in the HIP report check.

## Generating/spoofing a HIP report

Two example scripts are included in the OpenConnect distribution, in the `trojans/` subdirectory: `hipreport.sh` (which reproduces the behavior of a GlobalProtect Windows client) and `hipreport-android.sh` (a report with minimal contents suitable for use on an Android device).

Depending on how picky your GlobalProtect VPN is, it may be necessary to spoof or alter some of the parameters of the HIP report to match the output of one of the official clients. In order to capture the contents of the official Windows client's HIP reports, enable the highest logging level for the "PanGPS Service", and then sift through the giant `PanGPS.log` file (which should be in the same directory as the executables, normally `c:\Program Files\PaloAlto Networks\GlobalProtect`) to find the HIP report submission.