Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Santa

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 ASL or ULS (if built with the 10.12 SDK or later). 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) null: Don’t output any event logs. Defaults to filelog.
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 (BETA) Path to a file access configuration plist.
FileAccessPolicyUpdateIntervalSec Integer (BETA) 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.)

*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>
							</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.