Santa

https://northpole.dev
Admin
Santa is a high-performance open-source security agent for macOS that provides binary and...
Tokens:53,101
Snippets:538
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Munki PkgInfo for Santa

Source: https://northpole.dev/deployment/install-package

Example PkgInfo plist to import into a Munki catalog. It defines the Santa package with version 2025.3, installs check for /Applications/Santa.app, and includes a placeholder for installer_item_location. The blocking_applications array is empty because the package handles upgrades even if Santa.app is running.

```xml
<?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>name</key>

    <string>Santa</string>

    <key>version</key>

    <string>2025.3</string>

    <key>description</key>

    <string>Santa, the friendly security tool for macOS</string>

    <key>installs</key>

    <array>

        <dict>

            <key>type</key>

            <string>application</string>

            <key>path</key>

            <string>/Applications/Santa.app</string>

            <key>CFBundleIdentifier</key>

            <string>com.northpolesec.santa</string>

            <key>CFBundleName</key>

            <string>Santa</string>

            <key>CFBundleShortVersionString</key>

            <string>2025.3</string>

        </dict>

    </array>

    <key>blocking_applications</key>

    <array>

      <!-- The Santa package will handle upgrades even if Santa.app is running -->

    </array>

    <key>receipts</key>

    <array>

        <dict>

            <key>packageid</key>

            <string>com.northpolesec.santa</string>

            <key>version</key>

            <string>2025.3</string>

        </dict>

    </array>

    <key>installer_item_hash</key>

    <string>06a33253a015be318503523df054771786a2d71d99f5e679329f32968d808cc1</string>

    <key>installer_item_location</key>

    <string> ~ you must populate this with the path to santa-2025.3.pkg ~ </string>

    <key>uninstallable</key>

    <false/>

    <key>unattended_install</key>

    <true/>

</dict>

</plist>
```

--------------------------------

### santactl fileinfo for CERTIFICATE rule example

Source: https://northpole.dev/features/binary-authorization

Example command to inspect a binary's signing information, showing the SHA-256 fingerprint of the leaf certificate and the signing chain. The output includes the certificate details used for CERTIFICATE rules.

```bash
» santactl fileinfo /Applications/Santa.app  

Path                   : /Applications/Santa.app/Contents/MacOS/Santa  

SHA-256                : 66acf5c808ddb86c10137b5ae4c72cd14985ed2f90e5850d8e26ab962cb93c70  

SHA-1                  : 259f6b0ffc9cccc069eab2aee1496f5a12072ee7  

Bundle Name            : Santa  

Bundle Version         : 2025.3.97  

Bundle Version Str     : 2025.3  

Team ID                : ZMCG7MLDV9  

Signing ID             : ZMCG7MLDV9:com.northpolesec.santa  

CDHash                 : ea7c2330699c760b2d6c2c3e703fde01ca54e9b4  

Type                   : Executable (arm64, x86_64)  

Code-signed            : Yes  

Rule                   : Allowed (SigningID)  

Signing Chain:  

    1. SHA-256             : 1afd16f5b920f0d3b5f841aace6e948d6190ea8b5156b02deb36572d1d082f64  

       SHA-1               : 42890bc8a2a8becda00d63bdf9a89a6756a0da49  

       Common Name         : Developer ID Application: North Pole Security, Inc. (ZMCG7MLDV9)  

       Organization        : North Pole Security, Inc.  

       Organizational Unit : ZMCG7MLDV9  

       Valid From          : 2024/10/11 21:24:15 -0400  

       Valid Until         : 2027/02/01 17:12:15 -0500  

  

    2. SHA-256             : 7afc9d01a62f03a2de9637936d4afe68090d2de18d03f29c88cfb0b1ba63587f  

       SHA-1               : 3b166c3b7dc4b751c9fe2afab9135641e388e186  

       Common Name         : Developer ID Certification Authority  

       Organization        : Apple Inc.  

       Organizational Unit : Apple Certification Authority  

       Valid From          : 2012/02/01 17:12:15 -0500  

       Valid Until         : 2027/02/01 17:12:15 -0500  

  

    3. SHA-256             : b0b1730ecbc7ff4505142c49f1295e6eda6bcaed7e2c68c5be91b5a11001f024  

       SHA-1               : 611e5b662c593a08ff58d14ae22452d198df6c60  

       Common Name         : Apple Root CA  

       Organization        : Apple Inc.  

       Organizational Unit : Apple Certification Authority  

       Valid From          : 2006/04/25 17:40:36 -0400  

       Valid Until         : 2035/02/09 16:40:36 -0500  

  

```

--------------------------------

### santactl fileinfo for TEAMID rule example

Source: https://northpole.dev/features/binary-authorization

Example command to inspect a binary's signing information, showing the Team ID and other details. The output includes the Team ID used for TEAMID rules.

```bash
» santactl fileinfo /Applications/Santa.app  

Path                   : /Applications/Santa.app/Contents/MacOS/Santa  

SHA-256                : 66acf5c808ddb86c10137b5ae4c72cd14985ed2f90e5850d8e26ab962cb93c70  

SHA-1                  : 259f6b0ffc9cccc069eab2aee1496f5a12072ee7  

Bundle Name            : Santa  

Bundle Version         : 2025.3.97  

Bundle Version Str     : 2025.3  

Team ID                : ZMCG7MLDV9  

Signing ID             : ZMCG7MLDV9:com.northpolesec.santa  

CDHash                 : ea7c2330699c760b2d6c2c3e703fde01ca54e9b4  

Type                   : Executable (arm64, x86_64)  

Code-signed            : Yes  

Rule                   : Allowed (SigningID)  

  

```

--------------------------------

### Manually install the network extension with santactl

Source: https://northpole.dev/deployment/network-extension

Run this command to immediately install the network extension. It tears down existing network connections and can interrupt active network operations, so use with care.

```bash
sudo santactl install --network-extension  
```

--------------------------------

### Telemetry Configuration Example

Source: https://northpole.dev/features/telemetry

A complete configuration example for telemetry, including event types, log paths, file change monitoring, and entitlement filtering.

```xml
<key>Telemetry</key>  

<array>  

    <string>Execution</string>  

    <string>Authentication</string>  

    <string>FileAccess</string>  

</array>  

<key>EventLogType</key>  

<string>filelog</string>  

<key>EventLogPath</key>  

<string>/var/log/santa/events.log</string>  

<key>FileChangesRegex</key>  

<string>^/Users/.*\.sh$</string>  

<key>FileChangesPrefixFilters</key>  

<array>  

    <string>/private/tmp/</string>  

</array>  

<key>EnableMachineIDDecoration</key>  

<true/>  

<key>EntitlementsPrefixFilter</key>  

<array>  

    <string>com.apple.private</string>  

</array>  

<key>EntitlementsTeamIDFilter</key>  

<array>  

    <string>platform</string>  

</array>
```

--------------------------------

### Install Bazelisk with Homebrew

Source: https://northpole.dev/development/building

Installs Bazelisk via Homebrew, which automatically downloads the correct Bazel version. Adds both bazelisk and bazel to your PATH.

```bash
brew install bazelisk
```

--------------------------------

### Manual Install with installer command

Source: https://northpole.dev/deployment/install-package

Command to manually install the Santa package on a small number of machines without an MDM. Uses sudo installer with the package file and target root.

```bash
sudo installer -pkg santa-2025.3.pkg -tgt /
```

--------------------------------

### Example log message for EventLogType syslog or file

Source: https://northpole.dev/features/faa

This is an example of the log format produced when EventLogType is configured to syslog or file.

```text
action=FILE_ACCESS|policy_version=v0.1-experimental|policy_name=UserFoo|path=/Users/local/tmp/foo/text.txt|access_type=OPEN|decision=AUDIT_ONLY|pid=12|ppid=56|process=cat|processpath=/bin/cat|uid=-2|user=nobody|gid=-1|group=nogroup|machineid=my_id
```

--------------------------------

### Example santa-configuration.mobileconfig

Source: https://northpole.dev/deployment/profile-configuration

A sample configuration profile for Santa, demonstrating a subset of available keys including sync settings, machine identification, and static rules.

```xml
<?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>ClientMode</key>  

			<integer>1</integer>  

			<key>EnableSilentMode</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>StaticRules</key>  

			<array>  

				<dict>  

					<!-- Always allow files signed by North Pole Security Inc -->  

					<key>identifier</key>  

					<string>ZMCG7MLDV9</string>  

					<key>policy</key>  

					<string>ALLOWLIST</string>  

					<key>rule_type</key>  

					<string>TEAMID</string>  

				</dict>  

				<dict>  

					<!-- Always BLOCK the BundleExample.app binary in Santa's testdata files, for testing -->  

					<key>identifier</key>  

					<string>b7c1e3fd640c5f211c89b02c2c6122f78ce322aa5c56eb0bb54bc422a8f8b670</string>  

					<key>policy</key>  

					<string>BLOCKLIST</string>  

					<key>rule_type</key>  

					<string>BINARY</string>  

				</dict>  

			</array>  

			<key>SyncBaseURL</key>  

			<string>https://sync-server-hostname/api/santa/</string>  

			<key>PayloadDisplayName</key>  

			<string>Santa Configuration</string>  

			<key>PayloadIdentifier</key>  

			<string>com.mycompany.santa.359E3C7D-396F-4C45-99E7-F429620B9B21</string>  

			<key>PayloadType</key>  

			<string>com.northpolesec.santa</string>  

			<key>PayloadVersion</key>  

			<integer>1</integer>  

		</dict>  

	</array>  

	<key>PayloadDescription</key>  

	<string>Manages Santa's configuration</string>  

	<key>PayloadDisplayName</key>  

	<string>Santa: Configuration</string>  

	<key>PayloadIdentifier</key>  

	<string>com.mycompany.santa</string>  

	<key>PayloadOrganization</key>  

	<string>My Company</string>  

	<key>PayloadRemovalDisallowed</key>  

	<true/>  

	<key>PayloadScope</key>  

	<string>System</string>  

	<key>PayloadType</key>  

	<string>Configuration</string>  

	<key>PayloadUUID</key>  

	<string>AFA02DE3-ACA6-49C4-9980-A3664E22E446</string>  

	<key>PayloadVersion</key>  

	<integer>1</integer>  

</dict>  

</plist>
```

--------------------------------

### Check Santa version with santactl version

Source: https://northpole.dev/deployment/install-package

Run 'santactl version' to display the installed versions of santad, santactl, and SantaGUI. The output shows the build number and commit hash for each component.

```bash
santactl version
```

```text
santad          | 2025.3 (build 97, commit 10bdfcc2)  

santactl        | 2025.3 (build 97, commit 10bdfcc2)  

SantaGUI        | 2025.3 (build 97, commit 10bdfcc2)  

```

--------------------------------

### Configure kill_on_expiry policy

Source: https://northpole.dev/features/time-based-rules

Use kill_on_expiry to ensure processes started within a time window are terminated when the window closes.

```text
policy_for_range(weekdays(), "09:00", "17:00", kill_on_expiry(ALLOWLIST), BLOCKLIST)
```

--------------------------------

### Block publisher, allow specific app with santactl

Source: https://northpole.dev/features/binary-authorization

Creates a TeamID block rule for all applications from publisher ABCDEF1234, then a higher-precedence SigningID allow rule for the specific cloud-storage product com.acme-example.cloud-storage. This is the inverse of the previous example: block everything from the publisher except the allowed application.

```bash
santactl rule --block --teamid --identifier ABCDEF1234  

  

santactl rule --allow \  
              --signingid \  
              --identifier ABCDEF1234:com.acme-example.cloud-storage  
```

--------------------------------

### Timed access counted from launch

Source: https://northpole.dev/cookbook/cel

Sets a 30-minute duration window starting from the moment of execution, requiring Touch ID and terminating the process upon expiry. Requires Workshop 2026.8 or later and Santa 2026.8 or later.

```cel
policy_for_range(duration("30m"), kill_on_expiry(require_touchid_with_cooldown_minutes(30)))
```

--------------------------------

### Install Santa via Homebrew

Source: https://northpole.dev/deployment/install-package

Installs Santa from Homebrew. You will likely be prompted for your sudo password because Santa cannot be installed in a user folder like normal Homebrew packages. The cask is not maintained by the Santa team.

```bash
brew install santa
```

--------------------------------

### List system extensions with systemextensionsctl

Source: https://northpole.dev/deployment/troubleshooting

Check the output to confirm the Santa system extension is loaded. Look for a line item for com.northpolesec.santa.daemon with the expected version and state 'activated enabled'. If the state is 'activated waiting for the user', the extension must be approved in System Settings.

```bash
/usr/bin/systemextensionsctl list com.apple.system_extension.endpoint_security  
```

--------------------------------

### Build Santa with make

Source: https://northpole.dev/development/building

Runs the default make target in the root of the Santa repo, which invokes useful Bazel commands to ensure changes are formatted correctly and build.

```bash
make
```

--------------------------------

### Configure BrandingCompanyLogo with file URL

Source: https://northpole.dev/configuration/branding

Sets a logo image using a local file path. The image must be readable by all users.

```xml
<key>BrandingCompanyLogo</key>  

<string>file:///Library/Application%20Support/Acme/logo.png</string>
```

--------------------------------

### SpotlightImporterProtection: block unauthorized Spotlight plugins

Source: https://northpole.dev/cookbook/faa

Blocks unauthorized Spotlight plugin installations, addressing the Sploitlight exploit. Allows read access and enables silent mode, with `RuleType` set to `PathsWithAllowedProcesses`. The allowed processes include `com.apple.mds`, `com.apple.mdworker`, `com.apple.mdworker_shared`, `com.apple.mdimport`, and `com.apple.installer` (the comment notes removing the installer entry for more security).

```xml
<!-- Block unauthorized Spotlight plugin installations (Sploitlight protection) -->  

<key>SpotlightImporterProtection</key>  

<dict>  

	<key>Paths</key>  

	<array>  

		<dict>  

			<key>Path</key>  

			<string>/Users/*/Library/Spotlight</string>  

			<key>IsPrefix</key>  

			<true/>  

		</dict>  

		<dict>  

			<key>Path</key>  

			<string>/Library/Spotlight</string>  

			<key>IsPrefix</key>  

			<true/>  

		</dict>  

	</array>  

	<key>Options</key>  

	<dict>  

		<key>AllowReadAccess</key>  

		<true/>  

		<key>AuditOnly</key>  

		<false/>  

		<key>EnableSilentMode</key>  

		<true/>  

		<key>RuleType</key>  

		<string>PathsWithAllowedProcesses</string>  

	</dict>  

	<key>Processes</key>  

	<array>  

		<dict>  

			<key>SigningID</key>  

			<string>com.apple.mds</string>  

			<key>PlatformBinary</key>  

			<true/>  

		</dict>  

		<dict>  

			<key>SigningID</key>  

			<string>com.apple.mdworker</string>  

			<key>PlatformBinary</key>  

			<true/>  

		</dict>  

		<dict>  

			<key>SigningID</key>  

			<string>com.apple.mdworker_shared</string>  

			<key>PlatformBinary</key>  

			<true/>  

		</dict>  

		<dict>  

			<key>SigningID</key>  

			<string>com.apple.mdimport</string>  

			<key>PlatformBinary</key>  

			<true/>  

		</dict>  

		<!-- Remove this for more security -->  

		<dict>  

			<key>SigningID</key>  

			<string>com.apple.installer</string>  

			<key>PlatformBinary</key>  

			<true/>  

		</dict>  

	</array>  

</dict>  


```

--------------------------------

### Terminal block message example

Source: https://northpole.dev/configuration/branding

Displays how the company name appears in a terminal block message.

```text
Santa  

  

The following application has been blocked from executing  

because its trustworthiness cannot be determined  

  

Reason:      No matching rule  

Path:        /Applications/Malware.app/Contents/MacOS/Malware  

Identifier:  60055b1f6fb276bfacf61f91505a72201987f20ad8b6867cce3058f4c0f0f5e5  

Parent:      bash (2511)  

  

Managed by: Acme Corporation
```

--------------------------------

### Basic FAA plist configuration example

Source: https://northpole.dev/configuration/faa

A complete plist configuration for FAA with a watch item 'UserFoo' that monitors /Users/*/tmp/foo with prefix matching, audit-only mode, and a process restriction for Google Chrome helper. The EventDetailURL uses placeholders for hostname, rule name, and file identifier.

```xml
<?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>Version</key>

	<string>v0.1</string>

	<key>EventDetailURL</key>

	<string>https://my-server/faa/%hostname%/%rule_name%/%file_identifier%</string>

	<key>WatchItems</key>

	<dict>

		<key>UserFoo</key>

		<dict>

			<key>Paths</key>

			<array>

				<dict>

					<key>Path</key>

					<string>/Users/*/tmp/foo</string>

					<key>IsPrefix</key>

					<true/>

				</dict>

			</array>

			<key>Options</key>

			<dict>

				<key>AllowReadAccess</key>

				<false/>

				<key>AuditOnly</key>

				<true/>

				<key>RuleType</key>

				<string>PathsWithAllowedProcesses</string>

			</dict>

			<key>Processes</key>

			<array>

				<dict>

					<key>TeamID</key>

					<string>EQHXZ8M8AV</string>

					<key>SigningID</key>

					<string>com.google.Chrome.helper</string>

				</dict>

			</array>

		</dict>

	</dict>

</dict>

</plist>
```

--------------------------------

### Duration-Based Window

Source: https://northpole.dev/features/time-based-rules

Defines a window starting at the moment of execution for a specific duration. Requires kill_on_expiry to set an expiry.

```text
policy_for_range(duration("30m"), kill_on_expiry(ALLOWLIST))
```

--------------------------------

### Stream Santa daemon logs with log stream

Source: https://northpole.dev/deployment/troubleshooting

Stream debug logs from the Santa daemon to diagnose issues, especially if it fails to start.

```bash
/usr/bin/log stream --level debug --predicate 'sender == "com.northpolesec.santa.daemon"'  
```

--------------------------------

### Verify system extensions after migration

Source: https://northpole.dev/deployment/migration

Run `systemextensionsctl list` to confirm NPS Santa is active and Google Santa is terminated. The output shows Google Santa as 'terminated waiting to uninstall on reboot' and NPS Santa as 'activated enabled'.

```bash
$ systemextensionsctl list  

2 extension(s)  

--- com.apple.system_extension.endpoint_security  

enabled	active	teamID	bundleID (version)	name	[state]  

		EQHXZ8M8AV	com.google.santa.daemon (2024.9/2024.9.674285143)	santad	[terminated waiting to uninstall on reboot]  

*	*	ZMCG7MLDV9	com.northpolesec.santa.daemon (2024.10/2024.10.49)	santad	[activated enabled]  


```

--------------------------------

### Verify NPS Santa version with santactl

Source: https://northpole.dev/deployment/migration

Run `santactl version` to confirm the installed NPS Santa version. The output shows the version for santad, santactl, and SantaGUI.

```bash
$ santactl version  

santad          | 2025.3 (build 94, commit 63bc558d)  

santactl        | 2025.3 (build 94, commit 63bc558d)  

SantaGUI        | 2025.3 (build 94, commit 63bc558d)  


```
Tokens:
Raw