Keys
This page describes all of the available configuration options recognized by Santa.
The configuration keys are broken down into sections to make it easier to find what you're looking for but in the configuration profile all the keys should be set together.
Some keys (or available values for a key) will have a badge showing which Santa version they were added or deprecated in. Where a key has been deprecated, the description will list an alternative if one is available.
A key with next to the type can be overridden by a sync server.
General
General options
ClientModeinteger
1(Monitor): Executions of binaries not covered by a rule will be allowed2(Lockdown): Executions of binaries not covered by a rule will be blocked3(Standalone): Executions of binaries not covered by a rule will trigger an authorization dialog 2024.11
The client mode that Santa should operate in.
FailClosedbool
If true and the ClientMode is in 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.
EnableStandalonePasswordFallbackbool
If true, Santa will fallback to password authorization for Standalone mode.
IgnoreOtherEndpointSecurityClientsbool
If true, Santa will not process events that are generated by other EndpointSecurity clients that may be installed on the system
EnableDebugLoggingbool
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"'
EnableStatsCollectionbool
If true, Santa will periodically collect and send basic, non-identifying stats to the maintainers at North Pole Security to help better support Santa. See Stats documentation for complete details
StatsOrganizationIDstring
This key should only be set for organizations that have a contract with North Pole Security. See Stats documentation for complete details
Sync
Options related to syncing
SyncBaseURLstring
The base URL of the sync server
SyncEnableProtoTransferbool
If true, sync will happen using binary protos instead of JSON
SyncProxyConfigurationdict
The proxy configuration to use when syncing. See the Apple Documentation for details on the keys that can be used in this dictionary
SyncEnableCleanSyncEventUploadbool
If true, events will be uploaded to the sync server even if a clean sync is requested
ClientAuthCertificateFilestring
If set, this contains the location of a PKCS#12 certificate to be used for sync authentication
ClientAuthCertificatePasswordstring
Contains the password for the PKCS#12 certificate
ClientAuthCertificateCNstring
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
ClientAuthCertificateIssuerCNstring
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
ServerAuthRootsDatadata
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
ServerAuthRootsFilestring
The same as the above but is a path to a file on disk containing the PEM data
MachineOwnerstring
The machine owner
MachineIDstring
The machine ID. Care should be taken if overriding the default value. Using it incorrectly with a sync server that implements progressive syncing could lead to incomplete rules.
MachineOwnerPliststring
The path to a plist that contains the MachineOwnerKey / value pair
MachineOwnerKeystring
The key to use on MachineOwnerPlist
MachineIDPliststring
The path to a plist that contains the MachineOwnerKey / value pair
MachineIDKeystring
The key to use on MachineIDPlist
EnableAllEventUploadbool
If true, the client will upload all execution events to the sync server, including those that were explicitly allowed
DisableUnknownEventUploadbool
If true, the client will not upload events for executions of unknown binaries allowed in monitor mode
SyncClientContentEncodingstring
deflategzipnone
Sets the Content-Encoding header for requests sent to the sync service
SyncExtraHeadersdict
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
GUI
Options controlling how the GUI functions
EnableSilentModebool
If true, Santa will not post any GUI notifications. This can be a very confusing experience for users, use with caution
EnableSilentTTYModebool
If true, Santa will not post any TTY notifications. This can be a very confusing experience for users, use with caution
AboutTextstring
The text to display when the user opens Santa.app. If unset, the default text will be displayed
MoreInfoURLstring
The URL to open when the user clicks “More Info…” when opening Santa.app. If unset, the button will not be displayed
EventDetailURLstring
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 URL will be used for all rules unless overridden by a rule-specific option.
This property supports several placeholders in the string that will be replaced before the URL is constructefd to be turned into the URL to send them to. The following sequences will be replaced in the final URL:
| Placeholder | 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_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 |
Example: https://sync-server-hostname/%machine_id%/%file_identifier%
EventDetailTextstring
Related to the above property, this string represents the text to show on the button
DismissTextstring
The text to display on the button that dismisses the binary block dialog. The default text is "Dismiss"
UnknownBlockMessagestring
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
BannedBlockMessagestring
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
ModeNotificationMonitorstring
The notification text to display when the client goes into Monitor mode.
ModeNotificationLockdownstring
The notification text to display when the client goes into Lockdown mode.
BannedUSBBlockMessagestring
Message to display when a USB device is prevented from being mounted
RemountUSBBlockMessagestring
Message to display when a USB device is allowed to be mounted with a subset of the requested flags
as defined by RemountUSBMode
FileAccessBlockMessagestring
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
EnableNotificationSilencesbool 2025.2
If false, the user will not be presented with an option to silence notifications
FAA
Options controlling file-access authorization
FileAccessPolicyPliststring 2023.1
Path to a file access configuration plist. This is ignored if FileAccessPolicy is also set.
See File Access Authorization for configuration details.
FileAccessPolicydict 2023.1
A complete file access configuration policy embedded in the main Santa config.
If set, FileAccessPolicyPlist will be ignored. See File Access Authorization for configuration details
FileAccessPolicyUpdateIntervalSecinteger
Number of seconds between re-reading the file access policy config and policies/monitored paths updated
OverrideFileAccessActionstring
AUDIT_ONLY: no access will be blocked, only loggedDISABLE: no access will be blocked or loggednone: enforce policy as defined in each rule
Defines a global override policy that applies to the enforcement of all FileAccessPolicy rules.
Rules
Options controlling binary authorization rules
AllowedPathRegexstring
A regex to allow if the binary, certificate, or Team ID scopes did not allow/block execution. Regexes are specified in ICU format.
BlockedPathRegexstring
A regex to block if the binary, certificate, or Team ID scopes did not allow/block an execution. Regexes are specified in ICU format.
EnableBadSignatureProtectionbool
If true, binaries with a bad signing chain will be blocked even in MONITOR mode, unless
the binary is allowed by an explicit rule.
EnablePageZeroProtectionbool
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.
EnableTransitiveRulesbool
If true, Santa will respect compiler rules and create allow rules for the executables they produce.
StaticRulesArray of dicts
A static set of rules to always apply to the host. These rules always take precedence over any
configured by a sync server. Having this key set will also prevent local configuration of rules using the
santactl rule command.
Within the set of rules configured as StaticRules, the normal rule precedence order applies.
The intended use-case for StaticRules is for a small hardcoded set of rules that every host at a company will need to run even in emergencies, such as management tools. Santa heavily caches these rules and we've seen hosts with a few thousand static rules working correctly, but we don't recommend using StaticRules for this.
Telemetry
Options controlling the output of telemetry data
FileChangesRegexstring
The regex of paths to log file changes. Regexes are specified in ICU format
FileChangesPrefixFiltersArray of strings
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
TelemetryArray of strings 2024.11
EverythingExecutionForkExitCloseRenameUnlinkLinkExchangeDataDiskBundleAllowlistFileAccessCodesigningInvalidatedLoginWindowSessionLoginLogoutScreenSharingOpenSSHAuthenticationCloneCopyfileGatekeeperOverrideLaunchItemNone
Array of strings for events that should be logged
EnableForkAndExitLoggingbool 2024.11
If true, Santa will log FORK and EXIT events.
Use the new Telemetry key instead.
EventLogTypestring
syslog: Sent to the macOS Unified Logging Systenfile: Sent to a file on diskprotobuf: (BETA) Sent to file on disk using a maildir-like formatjson: (BETA) Same as file but output is one JSON object per linenull: Don't output any event logs
Defines how event logs are stored.
Note: The protobuf and JSON formats are in BETA and subject to change. We will call out any
changes in the release notes of any future release that changes them.
EventLogPathstring
If EventLogType is set to file or json, EventLogPath will provide the path to save logs.
If you change this value ensure you also update com.northpolesec.santa.newsyslog.conf with the new path
SpoolDirectorystring
If EventLogType is set to protobuf, SpoolDirectory will provide the base directory used to
save files according to a maildir-like format
SpoolDirectoryFileSizeThresholdKBinteger
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)
SpoolDirectorySizeThresholdMBinteger
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
SpoolDirectoryEventMaxFlushTimeSecinteger
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
EnableMachineIDDecorationbool
If EventLogType is set to file and this key is true, the MachineID to the end of
each log line.
EntitlementsPrefixFilterArray of strings
Entitlement prefixes that should not be logged (for example: com.apple.private).
EntitlementsTeamIDFilterArray of 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.
USB
Options controlling the USB mount control feature
BlockUSBMountbool
If true, blocking USB Mass storage feature is enabled.
RemountUSBModeArray of strings
rdonlynoexecnosuidnobrowsenoownersnodevasync-j
Array of strings for arguments to pass to mount -o when forcibly remounting devices.
OnStartUSBOptionsstring
UnmountForceUnmountRemountForceRemount
If set, defines the action that should be taken on existing USB mounts when Santa starts up.
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 as-is.
Metrics
Options controlling the export of agent metrics
MetricFormatstring
rawjson: A single JSON blob containing all metricsmonarchjson: A format consumable by Google's internal Monarch tooling.
Format to export metrics as.
MetricURLstring
URL describing where monitoring metrics should be exported
MetricExportIntervalinteger
Number of seconds to wait between exporting metrics
MetricExportTimeoutinteger
Number of seconds to wait before a timeout occurs when exporting metrics
MetricExtraLabelsdict
A map of key value pairs to add to all metric root labels. If a previously set key (e.g. host_name is set to "" then the key is removed from the metric root labels. Alternatively if a value is set for an existing key then the new value will override the old.