--- title: "Config Generator - Santa Docs" description: "Config Generator - Open source binary authorization for macOS. Configure, deploy, and extend the agent that powers Workshop." doc_version: "1" last_updated: "2026-05-22" canonical: "https://northpole.security/docs/santa/configuration/generator" --- # Config Generator Use this form to generate a valid Santa configuration, ready to put inside a configuration profile and deploy to your machines. The generator will ensure that the configuration is valid and help storing default values. ## General ClientMode The client mode that Santa should operate in. FailClosed 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. EnableStandalonePasswordFallback If true, Santa will fallback to password authorization for Standalone mode. IgnoreOtherEndpointSecurityClients If true, Santa will not process events that are generated by other EndpointSecurity clients that may be installed on the system EnableStatsCollection 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 StatsOrganizationID This key should only be set for organizations that have a contract with North Pole Security. See Stats documentation for complete details --- ## Sync SyncBaseURL The base URL of the sync server SyncEnableProtoTransfer If true, sync will happen using binary protos instead of JSON SyncProxyConfiguration The proxy configuration to use when syncing. See the Apple Documentation for details on the keys that can be used in this dictionary This key is not yet supported by the generator SyncEnableCleanSyncEventUpload If true, events will be uploaded to the sync server even if a clean sync is requested ClientAuthCertificateFile If set, this contains the location of a PKCS#12 certificate to be used for sync authentication ClientAuthCertificatePassword Contains the password for the PKCS#12 certificate ClientAuthCertificateCN 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 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 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 This key is not yet supported by the generator ServerAuthRootsFile The same as the above but is a path to a file on disk containing the PEM data MachineOwner The machine owner MachineOwnerGroups Groups the machine owner is a member of Add Item MachineID 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. MachineOwnerPlist The path to a plist that contains the `MachineOwnerKey` / value pair MachineOwnerKey The key to use on `MachineOwnerPlist` MachineOwnerGroupsKey The key to use on `MachineOwnerPlist` to access defined groups MachineIDPlist The path to a plist that contains the `MachineOwnerKey` / value pair MachineIDKey The key to use on `MachineIDPlist` EnableAllEventUpload If true, the client will upload all execution events to the sync server, including those that were explicitly allowed DisableUnknownEventUpload If true, the client will not upload events for executions of unknown binaries allowed in monitor mode SyncClientContentEncoding Sets the Content-Encoding header for requests sent to the sync service SyncExtraHeaders 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 This key is not yet supported by the generator --- ## GUI EnableSilentMode If true, Santa will not display a GUI dialog when this rule is violated EnableSilentTTYMode If true, Santa will not post a message to the controlling TTY when this rule is violated EnableMenuItem If true, Santa will show an item in the macOS menu bar to allow syncing and management of temporary monitor mode by default. Users are able to show/hide the menu item from the About window. AboutText The text to display when the user opens Santa.app. If unset, the default text will be displayed MoreInfoURL The URL to open when the user clicks “More Info…” when opening Santa.app. If unset, the button will not be displayed EventDetailURL Rule-specific URL that overrides the top-level `EventDetailURL` EventDetailText Rule-specific button text that overrides the top-level `EventDetailText` DismissText The text to display on the button that dismisses the binary block dialog. The default text is "Dismiss" UnknownBlockMessage In Lockdown/Standalone 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 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 The notification text to display when the client goes into Monitor mode. ModeNotificationLockdown The notification text to display when the client goes into Lockdown mode. BannedUSBBlockMessage Message to display when a USB device is prevented from being mounted RemountUSBBlockMessage Message to display when a USB device is allowed to be mounted with a subset of the requested flags as defined by `RemountUSBMode` FileAccessBlockMessage 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 EnableNotificationSilences If false, the user will not be presented with an option to silence notifications BrandingCompanyName The company name to display on Santa GUIs as well as in messages written to the TTY. For GUI windows, this setting is ignored if `BrandingCompanyLogo` is set. BrandingCompanyLogo A URL referencing a logo image to display on Santa UIs. The image will be scaled down appropriately to fit within image bounds (currently 84x28 pixels). If set, this overrides `BrandingCompanyName`. **Supported URL schemes:** - `file://` - Local file path (e.g., `file:///Library/Application%20Support/MyOrg/logo.png`) - `data:` - Base64-encoded image data (e.g., `data:image/png;base64,iVBORw0KG...`) **Note:** HTTP/HTTPS URLs are not supported. BrandingCompanyLogoDark A URL referencing a logo image to display on Santa UIs. When the UI is displayed in dark mode and this is set, it overrides both `BrandingCompanyLogo` and `BrandingCompanyName`. The image will be scaled down appropriately to fit within image bounds (currently 84x28 pixels). **Supported URL schemes:** - `file://` - Local file path (e.g., `file:///Library/Application%20Support/MyOrg/logo-dark.png`) - `data:` - Base64-encoded image data (e.g., `data:image/png;base64,iVBORw0KG...`) **Note:** HTTP/HTTPS URLs are not supported. FunFontsOnSpecificDays If true, the Santa UI will use special images/fonts on certain holidays. --- ## FAA FileAccessPolicyPlist Path to a file access configuration plist. This is ignored if `FileAccessPolicy` is also set. See [File Access Authorization](https://northpole.security/docs/santa/features/faa) for configuration details. FileAccessPolicy 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 This key is not yet supported by the generator FileAccessPolicyUpdateIntervalSec Number of seconds between re-reading the file access policy config and policies/monitored paths updated. The minimum value is 15 seconds. OverrideFileAccessAction Defines a global override policy that applies to the enforcement of all FileAccessPolicy rules. FileAccessGlobalLogsPerSec Sets the average logs per second that will be emitted by File Access Authorization rule violations. Setting to 0 will disable log rate limiting. Rate limiting only applies to logging. FAA rules that are not audit only will still block operations that violate the rule. FileAccessGlobalWindowSizeSec Sets the window size over which the FileAccessGlobalLogsPerSec setting is applied in order to allow for burts of logs. Setting to 0 will disable log rate limiting. Rate limiting only applies to logging. FAA rules that are not audit only will still block operations that violate the rule. --- ## Rules AllowedPathRegex A regex to allow if the binary, certificate, or Team ID scopes did not allow/block execution. Regexes are specified in ICU format. BlockedPathRegex 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 If true, binaries with a bad signing chain will be blocked even in `MONITOR` mode, **unless** the binary is allowed by an explicit rule. EnablePageZeroProtection 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. EnableTransitiveRules If true, Santa will respect compiler rules and create allow rules for the executables they produce. StaticRules 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](https://northpole.security/docs/santa/features/binary-authorization) 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. This key is not yet supported by the generator --- ## Telemetry FileChangesRegex The regex of paths to log file changes. Regexes are specified in ICU format FileChangesPrefixFilters 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 Add Item Telemetry Array of strings for events that should be logged Everything EventLogType 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. EventLogPath 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 SpoolDirectory If `EventLogType` is set to `protobuf`, SpoolDirectory will provide the base directory used to save files according to a maildir-like format SpoolDirectoryFileSizeThresholdKB 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) SpoolDirectorySizeThresholdMB 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 SpoolDirectoryEventMaxFlushTimeSec 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 EnableMachineIDDecoration If this key is true, the `MachineID` will be added to each log entry. EntitlementsPrefixFilter Entitlement prefixes that should not be logged (for example: `com.apple.private`). Add Item EntitlementsTeamIDFilter 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. Add Item --- ## Removable Media (e.g. USB mass storage device) BlockUSBMount If true, blocking USB Mass storage feature is enabled. RemountUSBMode Array of strings for arguments to pass to `mount -o` when forcibly remounting devices. OnStartUSBOptions 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 MetricFormat Format to export metrics as. MetricURL URL describing where monitoring metrics should be exported MetricExportInterval Number of seconds to wait between exporting metrics MetricExportTimeout Number of seconds to wait before a timeout occurs when exporting metrics MetricExtraLabels 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. This key is not yet supported by the generator --- ## Generate Click the button to generate and download the generated configuration file. Generate ## Sitemap - [Home](https://northpole.security/index.md) - [Workshop](https://northpole.security/workshop.md) - [Santa](https://northpole.security/santa.md) - [Features](https://northpole.security/features.md) - [Cookbook](https://northpole.security/cookbook.md) - [Docs](https://northpole.security/docs.md) - [Blog](https://northpole.security/blog.md) - [Glossary](https://northpole.security/glossary.md) - [About](https://northpole.security/about.md) - [Contact](https://northpole.security/contact.md)