Welcome to the Santa documentation

Santa is a binary and file access authorization system for macOS. It consists of a system extension that allows or denies attempted executions using a set of rules stored in a local database, a GUI agent that notifies the user in case of a block decision, a sync daemon responsible for syncing the database, and a server, and a command-line utility for managing the system.

It is named Santa because it keeps track of binaries that are naughty or nice.

The project and the latest release is available on GitHub.

Features

  • Multiple modes: In the default MONITOR mode, all binaries except those marked as blocked will be allowed to run, while logged and recorded in the events database. In LOCKDOWN mode, only listed binaries are allowed to run.
  • Event logging: All binary launches are logged. When in either mode, all unknown or denied binaries are stored in the database to enable later aggregation.
  • Several supported rule types: Executions can be allowed or denied by specifying rules based on several attributes. The supported rule types, in order of highest to lowest precedence are: CDHash, binary hash, Signing ID, certificate hash, or Team ID. Since multiple rules can apply to a given binary, Santa will apply the rule with the highest precedence (i.e. you could use a Team ID rule to allow all binaries from some organization, but also add a Signing ID rule to deny a specific binary). Rules based on code signature properties (Signing ID, certificate hash, and Team ID) only apply if a binary’s signature validates correctly.
  • Path-based rules (via NSRegularExpression/ICU): Binaries can be allowed/blocked based on the path they are launched from by matching against a configurable regex.
  • Failsafe cert rules: You cannot put in a deny rule that would block the certificate used to sign launchd, a.k.a. pid 1, and therefore all components used in macOS. The binaries in every OS update (and in some cases entire new versions) are therefore automatically allowed. This does not affect binaries from Apple’s App Store, which uses various certs that change regularly for common apps. Likewise, you cannot block Santa itself.
  • Components validate each other: Each of the components (the daemons, the GUI agent, and the command-line utility) communicate with each other using XPC and check that their signing certificates are identical before any communication is accepted.
  • Caching: Allowed binaries are cached, so the processing required to make a request is only done if the binary hasn’t already been cached.

Documentation overview

Introduction

The following pages provide an overview of how Santa accomplishes authorization at an enterprise scale.

  • Binary Authorization: How Santa makes allow or deny decisions for any execution taking place.
  • Syncing: How configuration and rules are applied from a sync server.

Deployment

  • Getting Started: A quick guide to setting up your deployment.
  • Configuration: The local and sync server configuration options, along with example needed mobileconfig files.
  • File Access Authorization: Guide to enabling the feature and details about its configuration and operation.
  • Sync Servers: A list of open-source sync servers.
  • Troubleshooting: How to troubleshoot issues with your Santa deployment.

Concepts

Additional documentation on the concepts that support the operation of the main components:

  • mode: An operating mode, either Monitor or Lockdown.
  • events: Represents an execve() that was blocked, or would have been blocked, depending on the mode.
  • rules: Represents allow or deny decisions for a given execve(). Can either be a binary’s SHA-256 hash or a leaf code-signing certificate’s SHA-256 hash.
  • scopes: The level at which an execve() was allowed or denied from taking place.
  • ipc: How all the components of Santa communicate. duction/syncing-overview.
  • logs: What and where Santa logs.

Binaries

The following pages describe the main components that make up Santa:

  • santad: A root daemon that makes decisions.
  • santactl: A command-line utility for inspecting the state and managing local configuration of Santa.
  • santa-gui: A GUI daemon that displays notifications when an execution is blocked.
  • santabundleservice: A root daemon that finds binaries within a bundle to allow for easier rule-creation of bundled applications.

Development

  • Building Santa: How to build and load Santa for testing on a development machine.
  • Contributing: How to contribute a bug fix or new feature to Santa.