How to create a custom check using a plist on macOS systems
19397
Created On 03/03/21 14:14 PM - Last Modified 08/16/24 20:27 PM
Objective
This article will discuss how to create and test a custom check using a plist entry on macOS systems.
Environment
- GlobalProtect (GP) App
- macOS systems
Procedure
- Create the plist entry to test with (if you don't already have one that you want to use)
- For example, if you wanted to create a new plist entry with a key named "testKeyName" and testKeyName with a value of "testKeyVal", open Terminal and use the following command:
user1@user1s-Mac ~ % defaults write com.pantest.plist testKeyName testKeyVal
- This will create a plist entry in the User Preferences folder at ~/Library/Preferences. The GP app for macOS can only read plist entries in the User Preferences folder ( ~/Library/Preferences) or the System Preferences folder ( /Library/Preferences ).
- To confirm the plist entry, use the defaults read command:
user1@user1s-Mac ~ % defaults read com.pantest.plist
{
testKeyName = testKeyVal;
}
- Configure the portal/gateway to collect the custom plist and key info
- This step will be one of two ways, depending on if you want to use the plist/key for selecting a GP agent configuration, or if you want to use the plist/key in a HIP profile for use in a security policy.
A) To configure the portal to collect the custom plist info for use in selecting a GP agent configuration
Select your portal configuration (as seen in the screenshot) and select Portal Data Collection. This is where you can direct the Portal to collect custom check info for use in GP agent config selection criteria. Under custom checks, select Mac and then add the plist name (do not include .plist at the end) and in our example, we also will add a key from this plist, for which we want the GP to obtain the value for. Note that if you configure the plist for the portal only, as mentioned in this step, you will not see a log for HIP match even if there is an existing HIP object. That is relevant for step B only.
To tell if the configuration is being received on the app, you can check PanGPS.log for entries similar to the following:
Debug( 77): Portal config criteria is restored.
Dump ( 101): CSC custom check: custom-checks>
<mac-os>
<plist>
<entry name="com.pantest">
<key>
<member>testKeyName</member>
</key>
</entry>
</plist>
</mac-os>
</custom-checks>
If you don't match any agent config criteria, you may see a message stating that you are not authorized to connect to GlobalProtect Portal. You can confirm that no agent configuration was matched in PanGPS.log with a "<portal-status>No portal configuration</portal-status>" entry.
B) To configure the gateway to collect the custom plist info for use in a HIP profile/security policy
Select your portal configuration and then, agent configuration from the Agent tab. Click HIP Data Collection and make sure that the "Collect HIP Data" box is checked. Then, at the bottom select Custom Checks > Mac and add the plist value the same as directed above in Step A. Do not add .plist at the end of the plist name.
To confirm the data is being collected, you can check PanGPS.log and find the following:
P51675-T13059 03/03/2021 08:40:07:594 Debug( 71): HipCustomCheck(): check registry key com.pantest completed. Exist: yes, Value: (null)
P51675-T13059 03/03/2021 08:39:59:535 Debug( 242): testKeyName is type of String.
P51675-T13059 03/03/2021 08:39:59:535 Debug( 245): Preference testKeyName has string value testKeyVal
- If using step B from above for use of custom check data in Security Policies, you can configure a HIP object to confirm that the firewall is receiving the expected data from the agent
- To configure a HIP object. go to Objects > GlobalProtect > HIP Objects and add an object. Enable Custom Checks, and select Plist, then create the object as desired. You can use the "plist does not exist" to check if the plist is not on the client machine, or you can leave the Key/Values blank and unselect the plist does not exist to check that the plist does exist. This has the same effect as checking the negate button from the list of Plists under the custom checks tab. If you want to check for a specific Key/Value pair, enter the Key name and key value expected for a match. In our example, we will use the plist, key name and key value we created above on our client machine. If you want to match client machines where the key value is NOT a specific value, check the negate button column next to the key/value pair.
- After you have committed this change, and have the client disconnect/reconnect to GP, you should see entries under Monitor > HIP Objects.
- Once you see the expected matches here, you can create HIP profiles for use in security policies.
Additional Information
Collect Application and Process Data From Endpoints
Note in the article: On Windows, macOS, and Linux devices, when you configure Custom Checks such as to collect registry or plist entries, GlobalProtect hides this information in the Host Profile summary of the GlobalProtect app.