Configuration

Two configuration methods can be used to control Santa: a local configuration profile and a sync server controlled configuration. There are certain options that can only be controlled with a local configuration profile and others that can only be controlled with a sync server controlled configuration. Additionally, there are options that can be controlled by both, marked with a single asterisk in the first table below.

Santa’s local configuration is managed using Apple Configuration Profiles(pdf link), also known as mobileconfig files, which are in an Apple-specific XML format.

Local Configuration Profile

Key	Value Type	Description
ClientMode*	Integer	1 = MONITOR, 2 = LOCKDOWN, defaults to MONITOR
FailClosed	Bool	If true and the ClientMode is LOCKDOWN: execution will be denied when there is an error reading or processing an executable file.
FileChangesRegex*	String	The regex of paths to log file changes. Regexes are specified in ICU format.
AllowedPathRegex*	String	A regex to allow if the binary, certificate, or Team ID scopes did not allow/block execution. Regexes are specified in ICU format.
BlockedPathRegex*	String	A regex to block if the binary, certificate, or Team ID scopes did not allow/block an execution. Regexes are specified in ICU format.
EnableBadSignatureProtection	Bool	Enable bad signature protection, defaults to NO. If this flag is set to YES, binaries with a bad signing chain will be blocked even in MONITOR mode, unless the binary is allowed by an explicit rule.
EnablePageZeroProtection	Bool	Enable `__PAGEZERO` protection, defaults to YES. If this flag is set to YES, 32-bit binaries that are missing the `__PAGEZERO` segment will be blocked even in MONITOR mode, unless the binary is allowed by an explicit rule.
EnableSilentMode	Bool	If true, Santa will not post any GUI notifications. This can be a very confusing experience for users, use with caution. Defaults to NO.
EnableSilentTTYMode	Bool	If true, Santa will not post any TTY notifications. This can be a very confusing experience for users, use with caution. Defaults to NO.
AboutText	String	The text to display when the user opens Santa.app. If unset, the default text will be displayed.
MoreInfoURL	String	The URL to open when the user clicks “More Info…” when opening Santa.app. If unset, the button will not be displayed.
EventDetailURL	String	See the EventDetailURL section below.
EventDetailText	String	Related to the above property, this string represents the text to show on the button.
UnknownBlockMessage	String	In Lockdown mode this is the message shown to the user when an unknown binary is blocked. If this message is not configured a reasonable default is provided.
BannedBlockMessage	String	This is the message shown to the user when a binary is blocked because of a rule if that rule doesn’t provide a custom message. If this is not configured a reasonable default is provided.
ModeNotificationMonitor	String	The notification text to display when the client goes into Monitor mode. Defaults to “Switching into Monitor mode”.
ModeNotificationLockdown	String	The notification text to display when the client goes into Lockdown mode. Defaults to “Switching into Lockdown mode”.
SyncBaseURL	String	The base URL of the sync server.
SyncProxyConfiguration	Dictionary	The proxy configuration to use when syncing. See the Apple Documentation for details on the keys that can be used in this dictionary.
SyncEnableCleanSyncEventUpload	Bool	If true, events will be uploaded to the sync server even if a clean sync is requested. Defaults to false.
ClientAuthCertificateFile	String	If set, this contains the location of a PKCS#12 certificate to be used for sync authentication.
ClientAuthCertificatePassword	String	Contains the password for the PKCS#12 certificate.
ClientAuthCertificateCN	String	If set, this is the Common Name of a certificate in the System keychain to be used for sync authentication. The corresponding private key must also be in the keychain.
ClientAuthCertificateIssuerCN	String	If set, this is the Issuer Name of a certificate in the System keychain to be used for sync authentication. The corresponding private key must also be in the keychain.
ServerAuthRootsData	Data	If set, this is valid PEM containing one or more certificates to be used for certificate pinning. To comply with ATS the certificate chain must also be trusted in the keychain.
ServerAuthRootsFile	String	The same as the above but is a path to a file on disk containing the PEM data.
MachineOwner	String	The machine owner.
MachineID	String	The machine ID.
MachineOwnerPlist	String	The path to a plist that contains the MachineOwnerKey / value pair.
MachineOwnerKey	String	The key to use on MachineOwnerPlist.
MachineIDPlist	String	The path to a plist that contains the MachineOwnerKey / value pair.
MachineIDKey	String	The key to use on MachineIDPlist.
EventLogType	String	Defines how event logs are stored. Options are 1) syslog: Sent to ULS. 2) filelog: Sent to a file on disk. Use EventLogPath to specify a path. 3) protobuf (BETA): Sent to file on disk using a maildir-like format. 4) json (BETA): Same as file but output is one JSON object per line 5) null: Don’t output any event logs. Defaults to filelog.
EventLogPath	String	If EventLogType is set to filelog or json, EventLogPath will provide the path to save logs. Defaults to /var/db/santa/santa.log. If you change this value ensure you also update com.google.santa.newsyslog.conf with the new path.
EventLogPath	String	If EventLogType is set to filelog, EventLogPath will provide the path to save logs. Defaults to /var/db/santa/santa.log. If you change this value ensure you also update com.google.santa.newsyslog.conf with the new path.
SpoolDirectory	String	If EventLogType is set to protobuf, SpoolDirectory will provide the the base directory used to save files according to a maildir-like format. Defaults to /var/db/santa/spool.
SpoolDirectoryFileSizeThresholdKB	Integer	If EventLogType is set to protobuf, SpoolDirectoryFileSizeThresholdKB defines the per-file size limit for files stored in the spool directory. Events are buffered in memory until this threshold would be exceeded (or SpoolDirectoryEventMaxFlushTimeSec is exceeded). Defaults to 100.
SpoolDirectorySizeThresholdMB	Integer	If EventLogType is set to protobuf, SpoolDirectorySizeThresholdMB defines the total combined size limit of all files in the spool directory. Once the threshold is met, no more events will be saved. Defaults to 100.
SpoolDirectoryEventMaxFlushTimeSec	Integer	If EventLogType is set to protobuf, SpoolDirectoryEventMaxFlushTimeSec defines the maximum amount of time events will stay buffered in memory before being flushed to disk, regardless of whether or not SpoolDirectoryFileSizeThresholdKB would be exceeded. Defaults to 10.
EnableMachineIDDecoration	Bool	If YES, this appends the MachineID to the end of each log line. Defaults to NO.
MetricFormat	String	Format to export metrics as, supported formats are “rawjson” for a single JSON blob and “monarchjson” for a format consumable by Google’s Monarch tooling. Defaults to “”.
MetricURL	String	URL describing where monitoring metrics should be exported.
MetricExportInterval	Integer	Number of seconds to wait between exporting metrics. Defaults to 30.
MetricExportTimeout	Integer	Number of seconds to wait before a timeout occurs when exporting metrics. Defaults to 30.
MetricExtraLabels	Dictionary	A map of key value pairs to add to all metric root labels. (e.g. a=b,c=d) defaults to @{}). If a previously set key (e.g. host_name is set to “” then the key is remove from the metric root labels. Alternatively if a value is set for an existing key then the new value will override the old.
EnableAllEventUpload	Bool	If YES, the client will upload all execution events to the sync server, including those that were explicitly allowed.
DisableUnknownEventUpload	Bool	If YES, the client will not upload events for executions of unknown binaries allowed in monitor mode
BlockUSBMount	Bool	If set to ‘True’ blocking USB Mass storage feature is enabled. Defaults to `False`.
RemountUSBMode	Array	Array of strings for arguments to pass to mount -o (any of “rdonly”, “noexec”, “nosuid”, “nobrowse”, “noowners”, “nodev”, “async”, “-j”). when forcibly remounting devices. No default.
FileAccessPolicyPlist	String	Path to a file access configuration plist. This is ignored if `FileAccessPolicy` is also set.
FileAccessPolicy	Dictionary	A complete file access configuration policy embedded in the main Santa config. If set, `FileAccessPolicyPlist` will be ignored.
FileAccessPolicyUpdateIntervalSec	Integer	Number of seconds between re-reading the file access policy config and policies/monitored paths updated.
SyncClientContentEncoding	String	Sets the Content-Encoding header for requests sent to the sync service. Acceptable values are “deflate”, “gzip”, “none” (Defaults to deflate.)
SyncExtraHeaders	Dictionary	Dictionary of additional headers to include in all requests made to the sync server. System managed headers such as Content-Length, Host, WWW-Authenticate etc will be ignored.

*overridable by the sync server: run santactl status to check the current running config

EventDetailURL

When the user gets a block notification, a button can be displayed which will take them to a web page with more information about that event.

This property contains a kind of format string to be turned into the URL to send them to. The following sequences will be replaced in the final URL:

Key	Description
%file_identifier%	SHA-256 of the file that was blocked
%bundle_or_file_identifier%	SHA-256 of the file that was blocked or the bundle containing it, if available
%file_sha%	Deprecated, acts like bundle_or_file_identifier
%machine_id%	ID of the machine
%username%	The executing user
%serial%	System’s serial number
%uuid%	System’s UUID
%hostname%	System’s full hostname

For example: https://sync-server-hostname/%machine_id%/%file_sha%

Example Configuration Profile

Here is an example of a configuration profile that could be set. It was generated with Tim Sutton’s great mcxToProfile tool. A copy is also available here.

A few key points to when creating your configuration profile:

com.google.santa needs to be the key inside PayloadContent
The PayloadScope needs to be System

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PayloadContent</key>
	<array>
		<dict>
			<key>PayloadContent</key>
			<dict>
				<key>com.google.santa</key>
				<dict>
					<key>Forced</key>
					<array>
						<dict>
							<key>mcx_preference_settings</key>
							<dict>
								<key>BannedBlockMessage</key>
								<string>This application has been banned</string>
								<key>ClientMode</key>
								<integer>1</integer>
								<key>EnablePageZeroProtection</key>
								<false/>
								<key>EventDetailText</key>
								<string>Open sync server</string>
								<key>EventDetailURL</key>
								<string>https://sync-server-hostname/blockables/%file_sha%</string>
								<key>FileChangesRegex</key>
								<string>^/(?!(?:private/tmp|Library/(?:Caches|Managed Installs/Logs|(?:Managed )?Preferences))/)</string>
								<key>MachineIDKey</key>
								<string>MachineUUID</string>
								<key>MachineIDPlist</key>
								<string>/Library/Preferences/com.company.machine-mapping.plist</string>
								<key>MachineOwnerKey</key>
								<string>Owner</string>
								<key>MachineOwnerPlist</key>
								<string>/Library/Preferences/com.company.machine-mapping.plist</string>
								<key>ModeNotificationLockdown</key>
								<string>Entering Lockdown mode</string>
								<key>ModeNotificationMonitor</key>
								<string>Entering Monitor mode&lt;br/&gt;Please be careful!</string>
								<key>MoreInfoURL</key>
								<string>https://sync-server-hostname/moreinfo</string>
								<key>SyncBaseURL</key>
								<string>https://sync-server-hostname/api/santa/</string>
								<key>UnknownBlockMessage</key>
								<string>This application has been blocked from executing.</string>
								<key>SyncExtraHeaders</key>
								<dict>
									<key>X-API-Key</key>
									<string>da823De3Dsadq3234dqwe32kv</string>
								</dict>
							</dict>
						</dict>
					</array>
				</dict>
			</dict>
			<key>PayloadEnabled</key>
			<true/>
			<key>PayloadIdentifier</key>
			<string>0342c558-a101-4a08-a0b9-40cc00039ea5</string>
			<key>PayloadType</key>
			<string>com.apple.ManagedClient.preferences</string>
			<key>PayloadUUID</key>
			<string>0342c558-a101-4a08-a0b9-40cc00039ea5</string>
			<key>PayloadVersion</key>
			<integer>1</integer>
		</dict>
	</array>
	<key>PayloadDescription</key>
	<string>com.google.santa</string>
	<key>PayloadDisplayName</key>
	<string>com.google.santa</string>
	<key>PayloadIdentifier</key>
	<string>com.google.santa</string>
	<key>PayloadOrganization</key>
	<string></string>
	<key>PayloadRemovalDisallowed</key>
	<true/>
	<key>PayloadScope</key>
	<string>System</string>
	<key>PayloadType</key>
	<string>Configuration</string>
	<key>PayloadUUID</key>
	<string>9020fb2d-cab3-420f-9268-acca4868bdd0</string>
	<key>PayloadVersion</key>
	<integer>1</integer>
</dict>
</plist>

Configuration profiles have a .mobileconfig file extension. There are a couple ways to install configuration profiles:

Double click them in Finder
Use an MDM, which is discussed further below

Sync Server Provided Configuration

Key	Value Type	Description
client_mode	String	MONITOR or LOCKDOWN, defaults to MONITOR.
clean_sync**	Bool	If set to `True` Santa will clear all local rules and download a fresh copy from the sync-server. Defaults to `False`.
batch_size	Integer	The number of rules to download or events to upload per request. Multiple requests will be made if there is more work than can fit in single request. Defaults to 50.
upload_logs_url**	String	If set, the endpoint to send Santa’s current logs. No default.
allowed_path_regex	String	Same as the “Local Configuration” AllowedPathRegex. No default.
blocked_path_regex	String	Same as the “Local Configuration” BlockedPathRegex. No default.
full_sync_interval*	Integer	The max time to wait before performing a full sync with the server. Defaults to 600 secs (10 minutes) if not set.
fcm_token*	String	The FCM token used by Santa to listen for FCM messages. Unique for every machine. No default.
fcm_full_sync_interval*	Integer	The full sync interval if a fcm_token is set. Defaults to 14400 secs (4 hours).
fcm_global_rule_sync_deadline*	Integer	The max time to wait before performing a rule sync when a global rule sync FCM message is received. This allows syncing to be staggered for global events to avoid spikes in server load. Defaults to 600 secs (10 min).
enable_bundles*	Bool	If set to `True` the bundle scanning feature is enabled. Defaults to `False`.
enable_transitive_rules	Bool	If set to `True` the transitive rule feature is enabled. Defaults to `False`.
enable_all_event_upload	Bool	If set to `True` the client will upload events for all executions, including those that are explicitly allowed.
block_usb_mount	Bool	If set to ‘True’ blocking USB Mass storage feature is enabled. Defaults to `False`.
remount_usb_mode	Array	Array of strings for arguments to pass to mount -o (any of “rdonly”, “noexec”, “nosuid”, “nobrowse”, “noowners”, “nodev”, “async”, “-j”). when forcibly remounting devices. No default.

*Held only in memory. Not persistent upon process restart.

**Performed once per preflight run (if set).

MDM-Specific Client Configuration

As of macOS 10.14 Mojave, Apple introduced the requirement that various modes of operation by executables on macOS had to be explicitly allowed and those allowances could only be ‘silently’ applied with an MDM that had ‘supervision’ status on a computer, either via automated device enrollment (also known as DEP) or when opted in by the end user through a process referred to as User Approved MDM. This comes into play when a binary wants to have read access system-wide, for example when an app is launched from a directory considered private to a user. An example payload for this use case is provided here

This would be used alongside a payload allowing notifications to be sent, and for allowing the system extension to be loaded without end user interaction.

Please note that for release package installers that included the kernel extension as part of the payload (prior to 2021.8) the end user to be prompted to allow it unless explicitly allowed with another MDM-delivered configuration profile to the supervised system.