USBMon

App with endpoint security extension to monitor USB storage devices. Events can be shipped directly to Splunk, using the Splunk HTTP Event Collector (HEC).

Configuration

Endpoint security extension

In order to be able to install the endpoint security extension without prompting the user, two configurations need to be distributed and installed.

TCC for full-disk-access

See com.apple.TCC.configuration-profile-policy payload in configuration profile example.

System extension policy

See com.apple.system-extension-policy payload in configuration profile example.

USBMon

USBMon must be configured using a com.apple.ManagedClient.preferences payload (See configuration profile or JAMF custom plist examples)

Key	Type	Value
`AppText`	String	The text to display in the system extension host app.
`MuteFseventsdEvents`	Boolean	If events generated by the file system events API (fseventsd) should be muted or not. Not muted by default.
`MuteSpotlightEvents`	Boolean	If events generated by the metadata server (for Spotlight) should be muted or not. Not muted by default.
`Shipper`	String	The name of the module to use to ship the events. ATM, only the `Splunk` module is available.
`ShipperConfiguration`	Dict	The configuration of the shipper module. Each shipper module has a different set of configuration keys, described below.

Splunk shipper

The configuration keys specific to the Splunk shipper:

Key	Type	Value
`HECURL`	String	The base URL (with port, without path) of the Splunk HEC endpoint.
`HECToken`	String	NOT RECOMMENDED the HEC token. See `HECTokenKeychainAccount` for a recommended way of distributing the HEC token.
`HECTokenKeychainAccount`	String	The name of the system keychain generic password account containing the HEC token. This is the recommended way to distribute the HEC token.
`Index`	String	The name of the Splunk index.
`Source`	String	The name of the Splunk source.
`ExtraHeaders`	Dict	OPTIONAL A String/String dictionary of extra headers that will be added to each Splunk request.

The HEC token, necessary to authenticate with the Splunk HEC, can be configured using 2 different methods:

set the HECToken key in the configuration. This is NOT RECOMMENDED, since all the secrets needed to ship events to splunk would be in the configuration profile, and thus, probably readable by all principals on the machine.
add the HEC token as a generic password system Keychain item, and reference this item in the configuration. The HECTokenKeychainAccount must match the name of the System Keychain Item, so that USBMon can retrieve the HEC token (i.e. the Keychain item password).

To create a system keychain generic password item for the HEC token, the following command can be used. For example, if HECTokenKeychainAccount in the USBMon configuration is set to USBMon HEC token, and the HEC token is d57c75da-05ce-4896-b2b6-d75b421795c7:

sudo security add-generic-password \
     -a "USBMon HEC token" \
     -w "d57c75da-05ce-4896-b2b6-d75b421795c7" \
     -s USBMon \
     -T /Applications/USBMon.app/Contents/Library/SystemExtensions/pro.zentral.USBMon.Extension.systemextension/Contents/MacOS/pro.zentral.USBMon.Extension \
     /Library/Keychains/System.keychain

IMPORTANT with the -T option, we add the currently installed version of USBMon to the Keychain item ACLs, to allow USBMon to read the password. USBMon must be installed before this command is used. This command can be used in the postinstall script of the package for example.

Activation

The containing app is USBMon.app (Bundle ID: pro.zentral.USBMon), and must be installed in the /Applications folder. The extension (Bundle ID: pro.zentral.USBMon.Extension) is embedded in the containing application bundle, and can be activated (installed, replaced) using the containing app:

/Applications/USBMon.app/Contents/MacOS/USBMon --activate-system-extension

Debugging

Logs

To stream the logs generated by USBMon, the following command can be used:

log stream --debug --info \
           --predicate 'subsystem BEGINSWITH "pro.zentral.USBMon"'

The log show command can be used to search for past log entries.

Force restart

To force the extension to restart, the following command can be used:

sudo launchctl stop WQ28ZDJ49Y.pro.zentral.USBMon.Extension

This, in combination with the log stream command, can help if they are some errors in the configuration that need to be fixed.