Skip to main content Link Menu Expand (external link) Document Search Copy Copied

(BETA) File Access Authorization

IMPORTANT: This feature is in beta. Configuration and log formats are subject to change.

IMPORTANT: This feature is only supported on macOS 13 and above.

File Access Authorization allows admins to configure Santa to monitor filesystem paths for potentially unwanted access and optionally deny the operation.

Enabling the Feature

To enable this feature, the FileAccessPolicyPlist key in the main Santa configuration must contain the path to a configuration file. See the format specified in the Configuration section below. The Santa configuration can also contain the FileAccessPolicyUpdateIntervalSec that dictates how often the File Access Authorization configuration is re-applied (see the details on Path Globs for more information on what happens during updates).


Key Parent Type Required Santa Version Description
Version <Root> String Yes v2023.1+ Version of the configuration. Will be reported in events.
WatchItems <Root> Dictionary No v2023.1+ The set of configuration items that will be monitored by Santa.
<Name> WatchItems Dictionary No v2023.1+ A unique name that identifies a single watch item rule. This value will be reported in events. The name must be a legal C identifier (i.e., must conform to the regex [A-Za-z_][A-Za-z0-9_]*).
Paths <Name> Array Yes v2023.1+ A list of either String or Dictionary types that contain path globs to monitor. String type entires will have default values applied for the attributes that can be manually set with the Dictionary type.
Path Paths String Yes v2023.1+ The path glob to monitor.
IsPrefix Paths Boolean No v2023.1+ Whether or not the path glob represents a prefix path. (Default = false)
Options <Name> Dictionary No v2023.1+ Customizes the actions for a given rule.
AllowReadAccess Options Boolean No v2023.1+ If true, indicates the rule will not be applied to actions that are read-only access (e.g., opening a watched path for reading, or cloning a watched path). If false, the rule will apply both to read-only access and access that could modify the watched path. (Default = false)
AuditOnly Options Boolean No v2023.1+ If true, operations violating the rule will only be logged. If false, operations violating the rule will be denied and logged. (Default = true)
Processes <Name> Array No v2023.1+ A list of dictionaries defining processes that are allowed to access paths matching the globs defined with the Paths key. For a process performing the operation to be considered a match, it must match all defined attributes of at least one entry in the list.
BinaryPath Processes String No v2023.1+ A path literal that an instigating process must be executed from.
TeamID Processes String No v2023.1+ Team ID of the instigating process.
CertificateSha256 Processes String No v2023.1+ SHA256 of the leaf certificate of the instigating process.
CDHash Processes String No v2023.1+ CDHash of the instigating process.
SigningID Processes String No v2023.1+ Signing ID of the instigating process.
PlatformBinary Processes Boolean No v2023.2+ Whether or not the instigating process is a platform binary.

Example Configuration

This is an example configuration conforming to the specification outlined above:

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">


Rule Matching

When an operation occurs on a path that matches multiple configured path globs, the rule containing the “most specific” matching path glob is applied (i.e., the longest matching path).

For example, consider the configured rules and paths:

RULE_1: /tmp/foo     [IsPrefix=true]
RULE_2: /tmp/foo.txt [IsPrefix=false]
RULE_3: /tmp         [IsPrefix=true]

The following table demonstrates which rule will be applied for operations on a given path:

Operation Path Rule Applied Reason
/tmp/foo RULE_1 Matches prefix, more specific than RULE_3
/tmp/foo/bar RULE_1 Matches prefix, more specific than RULE_3
/tmp/bar RULE_3 Matches prefix
/tmp/foo.txt RULE_2 Matches literal, more specific than RULE_1
/tmp/foo.txt.tmp RULE_1 Matches prefix, more specific than RULE_3, literal match doesn’t apply
/foo N/A No rules match operations on this path

IMPORTANT: If a configuration contains multiple rules with duplicate configured paths, only one rule will be applied to the path. It is undefined which configured rule will be used. Administrators should take care not to define configurations that may have duplicate paths.

Path Globs

Configured path globs represent a point in time. That is, path globs are expanded when a configuration is applied to generate the set of monitored paths. This is not a “live” representation of the filesystem. For instance, if a new file or directory is added that would match a glob after the configuration is applied, it is not immediately monitored.

Within the main Santa configuration, the FileAccessPolicyUpdateIntervalSec key controls how often any changes to the configuration are applied as well as re-evaluating configured path globs to match the current state of the filesystem.

Prefix and Glob Path Evaluation

Combining path globs and the IsPrefix key in a configuration gives greater control over the paths that rules should match. Consider the configured path globs:

PG_1: /tmp/*         [IsPrefix = false]
PG_2: /tmp/*         [IsPrefix = true]
PG_3: /tmp/          [IsPrefix = true]
PG_4: /tmp/file1.txt [IsPrefix = false]

And a filesystem that contains:


Now, assume the configuration is applied, and moments later a new file (/tmp/file3_new.txt) and a new directory (/tmp/dir2_new) are both created:

  • PG_1 will match against the two original files within /tmp and the one directory dir1 itself (but not nested contents).
  • PG_2 will match against the two original files within /tmp and the one directory dir1 (as well as nested contents).
  • PG_3 will match against all original and newly created files and directories within /tmp (as well as nested contents).
  • PG_4 will only match /tmp/file1.txt.

Case Sensitivity

All configured paths are case sensitive (i.e., paths specified in both the Paths and BinaryPath configuration keys). The case must match the case of the path as stored on the filesystem.

Due to platform limitations, it is not feasible for Santa to know all links for a given path. To help mitigate bypasses to this feature, Santa will not allow hard links to be created for monitored paths. If hard links previously existed to monitored paths, Santa cannot guarantee that access to watched resources via these other links will be monitored.

Configured path globs must refer to resolved paths only. It is not supported to monitor access on symbolic links. For example, consider the configured path globs:

PG_1: /var/audit/          [IsPrefix = true]
PG_2: /private/var/audit/  [IsPrefix = true]

PG_1 will not match any operations because /var is a symbolic link. PG_2 however is properly configured and will match on access to items in the configured directory.


When an operation matches a defined rule, and the instigating process did not match any of the defined exceptions in the Processes key, the operation will be logged. Both string and protobuf logging are supported.

When the EventLogType configuration key is set to syslog or file, an example log message will look like:


When the EventLogType configuration key is set to protobuf, a log is emitted to match the FileAccess message in the santa.proto schema.