--- title: "Execution Rules - Workshop Docs" description: "Execution Rules - Enterprise control plane for Santa. Manage rules, approvals, telemetry, and policies across your macOS fleet." doc_version: "1" last_updated: "2026-05-22" canonical: "https://northpole.security/docs/workshop/rules/execution-rules" --- # 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. ## 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](https://northpole.dev/deployment/configuration.html). ## 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. ### 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**. #### `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+ #### 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](https://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 ``` ## Sitemap - [Home](https://northpole.security/index.md) - [Workshop](https://northpole.security/workshop.md) - [Santa](https://northpole.security/santa.md) - [Features](https://northpole.security/features.md) - [Cookbook](https://northpole.security/cookbook.md) - [Docs](https://northpole.security/docs.md) - [Blog](https://northpole.security/blog.md) - [Glossary](https://northpole.security/glossary.md) - [About](https://northpole.security/about.md) - [Contact](https://northpole.security/contact.md)