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, 3 = STANDALONE 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 and when Santa has to make a default response just prior to deadlines expiring. Defaults to false.
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.
FileChangesPrefixFilters	Array	Array of path prefix strings. When an event is logged, if the target path (e.g. the file being written/removed/etc ) matches a prefix it will not be logged.
EnableBadSignatureProtection	Bool	If true, binaries with a bad signing chain will be blocked even in MONITOR mode, unless the binary is allowed by an explicit rule. Defaults to false.
EnablePageZeroProtection	Bool	If true, 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. Defaults to true.
EnableStandalonePasswordFallback	Bool	If true, Santa will fallback to password authorization for Standalone mode. Defaults to YES
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 false.
EnableTransitiveRules	Bool	If true, Santa will respect compiler rule types and create allow rules for the executables they produce. Defaults to false.
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 false.
EnableForkAndExitLogging	Bool	DEPRECATED. Please use Telemetry instead. If true, Santa will log FORK and EXIT event types. Defaults to false.
Telemetry	Array	Array of strings for events that should be logged. If not specified, defaults to Everything (unless EnableForkAndExitLogging is false in which case Fork and Exit will not be logged). Allowed values: Everything, Execution, Fork, Exit, Close, Rename, Unlink, Link, ExchangeData, Disk, Bundle, Allowlist, FileAccess, CodesigningInvalidated, LoginWindowSession, LoginLogout, ScreenSharing, OpenSSH, Authentication, None
IgnoreOtherEndpointSecurityClients	Bool	If true, Santa will not process events that are generated by other EndpointSecurity clients that may be installed on the system. Defaults to false.
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.
DismissText	String	The text to display on the button that dismisses the binary block dialog. The default text is “Dismiss”.
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.
SyncEnableProtoTransfer	Bool	If true, sync will happen using binary protos instead of JSON. Defaults to false.
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.northpolesec.santa.newsyslog.conf with the new path.
SpoolDirectory	String	If EventLogType is set to protobuf, SpoolDirectory will provide 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 true, this appends the MachineID to the end of each log line. Defaults to false.
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 true, the client will upload all execution events to the sync server, including those that were explicitly allowed. Defaults to false.
DisableUnknownEventUpload	Bool	If true, the client will not upload events for executions of unknown binaries allowed in monitor mode. Defaults to false.
BlockUSBMount	Bool	If 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.
OnStartUSBOptions	String	If set, defines the action that should be taken on existing USB mounts when Santa starts up. Supported values are “Unmount”, “ForceUnmount”, “Remount”, and “ForceRemount” (note: “remounts” are implemented by first unmounting and then mounting the device again). Existing mounts with mount flags that are a superset of RemountUSBMode are unaffected and left mounted.
BannedUSBBlockMessage	String	Message to display when a USB device is prevented from being mounted.
RemountUSBBlockMessage	String	Message to display when a USB device is allowed to be mounted with a subset of the requested flags as defined by RemountUSBMode.
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.
FileAccessBlockMessage	String	This is the message shown to the user when a access to a file is blocked because of a rule defined by FileAccessPolicy if that rule doesn’t provide a custom message. If this is not configured a reasonable default is provided.
OverrideFileAccessAction	String	Defines a global override policy that applies to the enforcement of all FileAccessPolicy rules. Allowed values are: AUDIT_ONLY (no access will be blocked, only logged), DISABLE (no access will be blocked or logged), none (enforce policy as defined in each rule). Defaults to NONE. Note: AUDITONLY without an underscore is deprecated.
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.
EnableDebugLogging	Bool	If true, the client will log additional debug messages to the Apple Unified Log. For example, transitive rule creation logs can be viewed with log stream --predicate 'sender=="com.northpolesec.santa.daemon"'. Defaults to false.
EntitlementsPrefixFilter	Array	Array of strings of entitlement prefixes that should not be logged (for example: com.apple.private). No default.
EntitlementsTeamIDFilter	Array	Array of TeamID strings. Entitlements from processes with a matching TeamID in the code signature will not be logged. Use the value platform to filter entitlements from platform binaries. No default.
StaticRules	Array	Array of rule dictionaries. The rules defined in this key take precedence over any rules in the rules database.

*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
%file_bundle_id%	The bundle ID that this binary is part of, if any.
%team_id%	The team ID that signed this binary, if any.
%signing_id%	The signing ID of this binary, if any.
%cdhash%	The binary’s CDHash, if any.
%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%

AllowedPathRegex/BlockedPathRegex

These regexes can be used to allow/block binaries based on the executable path. We strongly discourage the use of this as it can be relatively trivial to bypass but there are some circumstances where it is the only option.

It’s important to note that the path matched against these regexes is the full absolute path of the binary file. Symlinks in the path will have already been followed by the time Santa processes the execution and matches against the regex.

Static Rules

Static rules are rules that are defined inline in the Santa configuration. These rules take precedence over any rules delivered via a sync server or set via santactl. The relative rule order precedence is the same for the static rule types as they are for traditional rules.

The allowed keys/values for defining static rules are the same as for rules that are sent via the sync server. Details on this structure are defined in the Sync Protocol documentation.

Additionally, the example configuration has a demonstration on how to define static rules.

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.northpolesec.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.northpolesec.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.northpolesec.santa</string>
	<key>PayloadDisplayName</key>
	<string>com.northpolesec.santa</string>
	<key>PayloadIdentifier</key>
	<string>com.northpolesec.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

The following configuration keys can be set by the sync server and override the local configuration value. Unless otherwise noted to be held only in memory, the values set by the sync server are persisted across restarted of the Santa daemon. For additional information regarding default values and action taken by the daemon if the key is not set, please refer to the Sync Protocol Preflight Response documentation.

Key	Value Type	Description
client_mode	String	MONITOR or LOCKDOWN.
clean_sync**	Bool	If set to True Santa will clear all local rules and download a fresh copy from the sync server.
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.
allowed_path_regex	String	Same as the “Local Configuration” AllowedPathRegex.
blocked_path_regex	String	Same as the “Local Configuration” BlockedPathRegex.
full_sync_interval*	Integer	The max time to wait before performing a full sync with the server.
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.
enable_transitive_rules	Bool	If set to True the transitive rule feature is enabled.
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.
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.
override_file_access_action	String	Defines a global override policy that applies to the enforcement of all FileAccessPolicy rules. Allowed values are: AUDIT_ONLY (no access will be blocked, only logged), DISABLE (no access will be blocked or logged), NONE (enforce policy as defined in each rule).

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

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

†The Firebase Cloud Messaging (FCM) based Push Notification system is only available on the internal Google deployment of Santa at this time

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.