File Access Rules

File Access rules enable Santa to control which processes can read and write files on macOS systems. This powerful feature allows administrators to monitor, log, and block file access attempts based on flexible policies.

:::info Requirements

File Access rules require macOS 13 or later.

:::

Overview

File access authorization provides fine-grained control over file system access by allowing you to:

• Log access events for audit and compliance
• Block unauthorized access to sensitive files
• Define policies based on both files and processes

File Access rules configure the policies that Santa uses to decide which files and processes to monitor and control access to.

Rule Types

File Access supports four distinct rule types, categorized by orientation:

Data-Centric Rules

These rules focus on protecting specific files or directories:

Paths with Allowed Processes

Specifies which processes are allowed to access particular files or directories. Only the listed processes can access the protected paths, while all others are denied.

Use case: Protecting sensitive configuration files by allowing only specific system processes to access them.

Paths with Denied Processes

Blocks designated processes from accessing specific files or directories. All processes except those listed are allowed to access the paths.

Use case: Preventing a particular application from accessing user documents or sensitive data.

Process-Centric Rules

These rules focus on controlling what a process can access:

Processes with Allowed Paths

Defines which paths a process is allowed to access. The process can only access the specified paths and is denied access to all others.

Use case: Sandboxing an untrusted application to only access specific directories.

Processes with Denied Paths

Restricts a process from accessing specific paths. The process can access anything except the denied paths.

Use case: Preventing an application from accessing system directories or other users’ home folders.

Rule Options

Allow Read Access

When checked, read access will be allowed.

Block Violations

When unchecked, this rule will be in ‘audit-only’ mode, where violations will trigger events to be sent to Workshop but the access will not be blocked.

This is useful for testing policies before enforcement.

Silencing Notifications

By default the user is notified when access is blocked. Block rules can silence the GUI dialog and/or the terminal (TTY) message independently:

• GUI: Suppress the graphical block notification shown to the user. This can be useful for preventing background processes from accessing files without interrupting the user, but care should be taken not to use this in cases where the user is expecting the access to work.
• Terminal (TTY): Suppress the message printed to the terminal when a command-line process is blocked.

Use silencing sparingly — silent blocks give the user no feedback about why an access failed, which can be confusing and increase support load.

Per-Process Overrides

Every option above applies to the whole rule. A per-process override changes those options for a single process in the rule’s process list, without splitting the rule in two.

The most common use is a silent deny: a background process that constantly touches a protected path is blocked, but the user is never notified. This keeps the allow list short without drowning the user in notifications they cannot act on.

Each process row has an Overrides control that opens a panel. The panel is the only place per-process overrides are set, and it always offers an Action. Under the two path-centric rule types it also mirrors the rule’s own settings; the process-centric types offer the Action alone (see “Which settings each rule type offers” below). The cog on the collapsed row is marked when the process carries any override, and hovering it summarizes them, so an overridden process is visible without opening it.

The Action list always starts with whatever the rule itself would do to a process it lists, named for that outcome rather than labelled “rule default”:

The process-centric types have no single equivalent action — being governed by them is path-scoped — which is why their first option is worded rather than named after an action.

The remaining options are the concrete actions:

Whichever concrete action the first option already stands for is not listed twice. Leaving a process on that first option records no override for it, so the process keeps following the rule if you later change the rule type or turn Block Violations off. Choosing an action that matches what the rule already does is treated the same way, since it says nothing the rule does not already say.

Which Settings Each Rule Type Offers

Under the two path-centric rule types, the panel also overrides the rule’s settings for that one process: allow read access, silent mode, silent TTY mode, block message, event detail URL, and event detail text. Anything left on “inherit” uses the rule’s own value.

These settings only appear when the process ends up denied — either because its Action is Deny, or because the rule’s own outcome for a listed process is a deny. Every one of them describes a block: what to silence, whether reads are covered, and what the user is shown. While the access is permitted there is nothing for them to change, so the panel offers the Action alone.

Turning Block Violations off on a deny-list rule therefore hides them, because the rule then records rather than blocks.

The two process-centric types offer the Action only, since these settings carry far less weight there.

Whenever a setting’s control is not shown — for either reason — a value already set through the API or a rule pack still applies. The form lists those values in the panel with a button to clear them, rather than hiding a setting that is still in force.

Note that silencing is not an action. To block a process without notifying the user, set Action to Deny and Silent mode to On. They are separate because they are separate settings on the rule too, and folding them into one option would mean picking an action silently rewrites your notification settings.

Because a silently denied process gives the user no feedback at all, document why the override exists. A user who runs the blocked operation deliberately has no way to discover that the rule is the cause.

What Allow Means

Allow does not mean the same thing in both families of rule type, so Workshop labels it differently in each.

Under the two path-centric types (paths with allowed processes, paths with denied processes), the process list decides whether a process may reach the paths. Allow there means what it says: permit this process’s access.

Under the two process-centric types (processes with allowed paths, processes with denied paths), the process list names the processes the rule governs, and the paths carry the allow/deny sense. Allowing a process there does not permit one access — it releases the process from the rule entirely, so the rule never denies it, wherever it goes. Workshop labels this Exempt from rule to keep the two apart.

Staging a Rollout

A per-process override has no separate audit-only switch; it inherits the rule’s Block Violations setting. Set a process to Audit to get audit-only behavior for that one process while the rest of the rule enforces.

This makes a staged rollout expressible in a single rule: turn Block Violations on, then set the processes you are still unsure about to Audit. They keep generating events without blocking anyone, and you move them back to the rule’s own outcome one at a time as the events come back clean.

Denying Reads as Well as Writes

A process set to Deny can still read, unless its Allow read access is also off.

This catches people out because the rule-level Allow read access defaults to on, and an unset per-process override inherits it. To deny a process both reads and writes, set Action to Deny and set Allow read access to Off in that process’s overrides panel. Workshop flags the combination inline when a deny would otherwise still permit reads.

Santa Version Requirements

Per-process overrides need Santa 2026.8 or newer.

Older agents are still sent the rule, but they cannot apply a per-process override. All Workshop can do is choose whether to list the process at all, so only the allow/deny dimension survives, and it survives differently in each family.

Under a path-centric rule, the process list is the verdict, so a process is sent only when plain membership is the outcome the override asks for. A silently denied process under a “paths with allowed processes” rule is left out, which makes the rule’s handling of an unlisted process apply: still blocked, but the user gets the notification.

Under a process-centric rule, the list decides whether the rule governs the process at all, so the fallback flips. A denied process stays in the list, because withholding it would leave an older agent applying no restriction to it whatsoever. An exempted process is withheld, which is exactly what exempting it means. A process set to Audit is withheld too: an older agent cannot record an audited access, so the closest it can manage is to stop applying the rule to that process.

:::warning Two overrides cannot reach an older agent at all

Membership carries no settings, so these are silently lost below Santa 2026.8 and the agent uses the rule’s own value instead:

• Deny under an audit-only rule. With Block Violations off, an older agent audits the access rather than blocking it. The override enforces only on 2026.8 and newer.
• Allow read access set to Off. An older agent keeps the rule’s value, so the process can still read.

If either matters for a rule, check your fleet’s Santa versions before relying on it.

:::

Paths

File Access supports flexible path matching, using either literals (with optional wildcards) or prefixes.

Some rules to be aware of:

• All paths are case-sensitive
• Paths must reference resolved filesystem locations
• Symbolic links are not supported - use the actual resolved path
• Always use absolute paths, not relative paths

Path Literals

Specify exact file or directory paths:

/etc/sudoers
/Users/admin/.ssh/id_rsa

You can also use standard wildcards for pattern matching:

/Users/*/Documents/*
/Applications/*.app

Standard libc glob(3) patterns are supported (excluding extended patterns like **):

/etc/*.conf
/var/log/app-[0-9]*.log

Path Prefixes

Enable recursive directory monitoring:

/Users/admin/Documents/

Processes

Processes can be matched using multiple identification methods, for flexibility when writing rules. You should use signing identifiers (Signing ID, Team ID, CDHash) rather than file paths, whenever possible. File paths can easily be changed, while code signing identifiers provide stronger security guarantees.

Binary Paths

Match by full executable path:

/Applications/TextEdit.app/Contents/MacOS/TextEdit

Signing ID

The code signing identifier assigned to the application, prefixed with the Apple developer team ID of the organization that signed it:

ABCDE12345:com.example.myapp

Use the special team ID platform for platform binaries that are part of the OS:

platform:com.apple.less

Team ID

The Apple Developer Team ID:

ABCDE12345

CDHash

The CDHash of the signed binary:

a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Leaf Certificate Hash

The SHA-256 hash of the leaf certificate that was used to sign the binary:

1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Best Practices

Start with Audit-Only Monitoring

Before enforcing rules, enable audit-only mode to:

• Understand normal access patterns
• Identify legitimate processes that need access
• Avoid accidentally blocking critical system operations

Maintain Specific Path Patterns

Use the most specific path patterns possible:

• Avoid overly broad wildcards like /*
• Target specific directories or file types
• Use prefix matching judiciously for large directory trees

Test Thoroughly

Before deploying to production:

• Test rules on non-critical systems first
• Monitor logs for unexpected denials
• Verify legitimate operations still work
• Check for performance impact

Related Documentation

For more detailed information about file access authorization configuration and examples, visit the Santa File Access Documentation.