Execution Rules

The Execution Rules interface provides a comprehensive view of all rules that control execution of binaries across your organization. This centralized dashboard allows administrators to create, monitor, and manage Santa execution rules at scale.

Overview

The Execution Rules dashboard displays information about each rule:

• Identifier: The unique identifier for the rule (hash, certificate, etc.)
• Comment: Description or purpose of the rule
• Rule Type: Type of rule (Binary, Certificate, Team ID, Signing ID, CDHash)
• Policy: Action to take when the rule is matched (Allowlist, Blocklist, etc.)

Rule Types

Santa supports several types of execution rules:

• Binary: Rules based on the cryptographic hash of a binary
• Certificate: Rules based on the code signing certificate
• Team ID: Rules based on Apple Developer Team IDs
• Signing ID: Rules based on signing information
• CDHash: Rules based on the CodeDirectory hash of a binary

Rule Policies

Each rule can be configured with one of the following policies:

• Allowlist: Explicitly allow execution
• Allowlist Compiler: Special rule for compiler processes
• Blocklist (Malicious): Block execution due to malicious content
• Blocklist (Policy): Block execution due to policy violation
• Silent Blocklist (Malicious): Block without notification due to malicious content
• Silent Blocklist (Policy): Block without notification due to policy violation

Creating Rules

To create a new rule, click the "Create Rule" button and fill in the required information:

• Rule type
• Identifier (hash, certificate, etc.)
• Policy action
• Optional comment to describe the rule's purpose

Scoping Rules to Tags

Rules can optionally be scoped to one or more tags. When creating a rule, use the tag selector to pick which tags the rule applies to. If no tag is selected, the rule applies globally.

To scope a rule to a specific host, check Show host tags and search by hostname or primary user — you don't need to know the host UUID.

warning

Rules take effect immediately after creation. Ensure you've verified the identifier before creating a rule.

Rule Deployment

Once created, rules are automatically distributed to Santa clients during their next sync. The timing depends on your sync server configuration.

For more detailed information about Santa rules and configuration options, visit the Santa Documentation.

CEL Policy Rules

CEL (Common Expression Language) rules provide a flexible, expression-based way to make execution decisions in Santa. Unlike traditional rules that match a single identifier (hash, certificate, etc.), CEL rules evaluate an expression against properties of the binary and its execution context to determine whether to allow, block, or require additional authorization.

CEL rules are evaluated by the Santa agent on-device at execution time. Workshop validates CEL expressions before they are saved, ensuring they compile and return a valid decision type.

info

You can test CEL expressions interactively using the CEL Playground before deploying them as rules.

Creating CEL Rules

CEL rules are created like other execution rules but with the policy set to CEL and a CEL expression provided. The expression is validated at creation time and must:

• Compile successfully against the CEL environment
• Return either a boolean or a valid return value (see below)
• Not reference UNSPECIFIED (only fallback rules may use UNSPECIFIED)

CEL rules can be scoped to tags just like other execution rules.

Input Variables

CEL expressions have access to the following variables, which represent properties of the binary being executed and its runtime context.

target — Executable File Properties

The target variable contains static properties of the executable file. Rules that only use target fields produce cacheable results, meaning Santa can remember the decision and skip re-evaluation for subsequent executions of the same binary.

Field	Type	Description
target.signing_id	string	The signing ID of the binary, if validly signed
target.team_id	string	The Apple Developer Team ID, if validly signed
target.signing_time	timestamp	Timestamp of when the binary was signed (set by the developer, not verified)
target.secure_signing_time	timestamp	Timestamp certified by Apple's timestamp authority (trustworthy)
target.is_platform_binary	bool	Whether this is an Apple platform binary
target.entitlements	map(string, string)	The binary's entitlements. Values are JSON strings — use "true" or "false" for boolean entitlements

path — Executable Path

Field	Type	Description
path	string	The full resolved path of the executable

Requires Santa 2026.3+. Using this field makes the result non-cacheable.

args — Command-Line Arguments

Field	Type	Description
args	list(string)	The command-line arguments passed to the new process

Using this field makes the result non-cacheable.

envs — Environment Variables

Field	Type	Description
envs	map(string, string)	The environment variables passed to the new process

Using this field makes the result non-cacheable.

info

For environment variable keys that contain periods (e.g. com.apple.dt.Xcode.SourcePathRemapping), use the in operator or bracket syntax instead of the has() macro:

// ✅ Correct
'com.apple.dt.Xcode.SourcePathRemapping' in envs
envs['com.apple.dt.Xcode.SourcePathRemapping'] == '5'

// ❌ Will not compile
has(envs.com.apple.dt.Xcode.SourcePathRemapping)

euid — Effective User ID

Field	Type	Description
euid	int	The effective user ID of the executing user

Requires Santa 2025.12+. Using this field makes the result non-cacheable.

cwd — Current Working Directory

Field	Type	Description
cwd	string	The current working directory of the process being executed

Requires Santa 2025.12+. Using this field makes the result non-cacheable.

ancestors — Process Ancestry

Field	Type	Description
ancestors	list(Ancestor)	The process ancestry chain. The first element is the immediate parent, followed by its parent, up to launchd

Each Ancestor has the following fields:

Field	Type	Description
path	string	The executable path of the ancestor process
signing_id	string	The signing ID, if validly signed
team_id	string	The Team ID, if validly signed
cdhash	string	The CDHash, if validly signed
args	list(string)	The command-line arguments for the ancestor process

Requires Santa 2026.2+. Using this field makes the result non-cacheable.

fds — Open File Descriptors

Field	Type	Description
fds	list(FileDescriptor)	The open file descriptors associated with the process

Each FileDescriptor has the following fields:

Field	Type	Description
fd	int	The file descriptor number
type	FDType	The type of the file descriptor

Available FDType values:

FD_TYPE_UNKNOWN, FD_TYPE_ATALK, FD_TYPE_VNODE, FD_TYPE_SOCKET, FD_TYPE_PSHM, FD_TYPE_PSEM, FD_TYPE_KQUEUE, FD_TYPE_PIPE, FD_TYPE_FSEVENTS, FD_TYPE_NETPOLICY, FD_TYPE_CHANNEL, FD_TYPE_NEXUS

Requires Santa 2026.3+. Using this field makes the result non-cacheable.

Return Values

CEL expressions must return either a boolean or a return value enum.

Boolean Returns

Value	Decision
true	Equivalent to ALLOWLIST — allow execution
false	Equivalent to BLOCKLIST — block execution

Return Value Enum

These values can be used directly as keywords in CEL expressions:

Value	Description
ALLOWLIST	Allow the process to execute
ALLOWLIST_COMPILER	Allow execution and, if transitive allowlisting is enabled, locally allowlist any files created by this binary
BLOCKLIST	Block the process from executing
SILENT_BLOCKLIST	Block execution without showing a GUI notification to the user
REQUIRE_TOUCHID	Hold execution until the user authorizes via biometrics (or password if EnableStandalonePasswordFallback is enabled). Requires Santa 2026.1+
REQUIRE_TOUCHID_ONLY	Like REQUIRE_TOUCHID but skips the Santa block dialog and goes straight to TouchID authorization. Requires Santa 2026.1+

warning

SILENT_BLOCKLIST should be used sparingly — silently blocked applications can be very confusing for users.

TouchID with Cooldown

Instead of returning REQUIRE_TOUCHID or REQUIRE_TOUCHID_ONLY directly, use the cooldown functions to specify how long the authorization should remain valid:

require_touchid_with_cooldown_minutes(5)
require_touchid_only_with_cooldown_minutes(10)

The cooldown value (in minutes) controls how long after a successful authorization the user can re-execute the binary without being prompted again.

TouchID return values are always non-cacheable. Requires Santa 2026.1+.

Cacheability

Santa can cache the result of a CEL expression to avoid re-evaluating it on every execution of the same binary. A result is cacheable only when the expression exclusively uses static target fields.

Using any of the following makes the result non-cacheable:

• args, envs, euid, cwd, ancestors, path, fds
• REQUIRE_TOUCHID, REQUIRE_TOUCHID_ONLY, or the cooldown functions

Workshop displays a cacheability indicator when creating or editing CEL rules so you can understand the performance implications of your expression.

CEL Fallback Rules

In addition to standard CEL rules, CEL expressions can be configured as fallback rules in Sync Settings. Fallback rules are evaluated when no other rule matches and can optionally return UNSPECIFIED to pass the decision to the next fallback rule in the chain.

CEL fallback rules require Santa 2026.3 or later.

Key differences from standard CEL rules:

• Configured per-tag in Sync Settings (not as standalone rules)
• May return UNSPECIFIED to defer the decision
• Maximum of 10 fallback rules per sync setting
• Can include a custom message and URL shown to the user on block

Minimum Santa Version Requirements

Workshop automatically calculates the minimum Santa version required for a CEL rule based on the variables and functions it uses:

Feature	Minimum Version
Basic CEL (target fields only)	No minimum
euid, cwd	Santa 2025.12+
REQUIRE_TOUCHID, REQUIRE_TOUCHID_ONLY, cooldown functions	Santa 2026.1+
ancestors	Santa 2026.2+
path, fds	Santa 2026.3+

Hosts running older versions of Santa will not evaluate rules that use features they don't support.

Available Operations

CEL expressions support standard CEL operations including (see celbyexample.com for a full reference):

• Comparison: ==, !=, <, >, <=, >=
• Logical: &&, ||, !
• Arithmetic: +, -, *, /, %
• Ternary: condition ? value_if_true : value_if_false
• Membership: in
• String functions: startsWith(), endsWith(), contains(), join(), size()
• List macros: exists(), all(), filter(), map(), size()
• Optional field access: has()
• Timestamp: timestamp() for constructing timestamps for comparison

CEL Examples

Allow binaries signed after a specific date

target.secure_signing_time > timestamp('2025-01-01T00:00:00Z')

Block a binary when run with a specific argument

'--inspect' in args ? BLOCKLIST : ALLOWLIST

Allow only when launched from a specific parent process

ancestors.exists(a, a.signing_id == 'platform:com.apple.Terminal')

Block when running as root from a non-standard directory

euid == 0 && !cwd.startsWith('/Applications') ? BLOCKLIST : ALLOWLIST

Block hypervisors

target.entitlements.exists(k,
    k == 'com.apple.security.hypervisor' ||
    k == 'com.apple.security.virtualization')
  ? BLOCKLIST
  : UNSPECIFIED

This example uses UNSPECIFIED and is only valid as a fallback rule. To create exclusions, allowlist a specific virtualization tool by Team ID or Signing ID — the allowlist rule will take priority over this fallback rule.

Check for specific file descriptor types

fds.exists(f, f.type == FD_TYPE_SOCKET) ? BLOCKLIST : ALLOWLIST

Check environment variables with fallback

'DEVELOPER_MODE' in envs && envs['DEVELOPER_MODE'] == '1'
  ? ALLOWLIST
  : BLOCKLIST