# macOS Two-Layer Bypass Architecture

### How the macOS Agent Handles File Access Policy Evaluation

On macOS, file access policy evaluation involves two separate bypass layers. Understanding both is important when designing policies and interpreting agent logs.

#### **Layer 1 — System Extension Allow Paths (kernel-level, before policy evaluation)**

The macOS System Extension runs a kernel-level exec filter. Before a request reaches the KeeperPolicy evaluation engine, the extension checks the executable path against a configured `fileAccess.allowPaths` list in `SystemExtension.json`. If the path matches, the extension returns an immediate ALLOW response with no round-trip to KeeperPolicy.

This filter exists as a performance optimization. Without it, a macOS login session can generate upwards of 750 policy evaluation requests — averaging 300–400ms each — resulting in login times of approximately 10 minutes. With the filter in place, the majority of system framework and service requests are resolved at the kernel level in under 1ms.

The default `fileAccess.allowPaths` list includes:

| Path                                | Description                    |
| ----------------------------------- | ------------------------------ |
| `/System/Library/PrivateFrameworks` | Private system frameworks      |
| `/System/Library/Frameworks`        | Public system frameworks       |
| `/System/Library/CoreServices`      | Core system services           |
| `/System/Applications`              | Built-in macOS applications    |
| `/usr/libexec`                      | System daemons and utilities   |
| `/usr/sbin`                         | System administration binaries |
| `/Library/Keeper`                   | Keeper agent utilities         |

{% hint style="info" %}
Executables in these paths are allowed immediately and their authorization decision is cached system-wide for all users until the executable is modified or the machine is rebooted. Only add paths to this list where the decision should apply uniformly to all users.
{% endhint %}

#### **Layer 2 — KeeperPolicy Engine Protected Paths (policy-level)**

If a request passes through Layer 1 and reaches the KeeperPolicy evaluation engine, the engine applies its own protected path logic. When an executable path falls within a protected directory and the matching policy is wildcard-based, the engine bypasses all wildcard policy controls and grants execution — unless an explicit, exact-path policy is also present for that executable.

This is reflected in agent logs as:

```
[PROTECTED_PATH_BYPASS_ALL_CONTROLS] [POLICY <ID>] [NONE] [POLICY_EXECUTION_GRANT]
```

The `[POLICY <ID>]` field confirms that a policy *was* matched. The bypass is not a failure to find a policy — it is the engine deliberately overriding a wildcard match because the path is protected. An exact-path policy for the same executable would be honored.

#### **Protected paths at the KeeperPolicy engine level on macOS include:**

<table><thead><tr><th width="261.48486328125">Path</th><th>Description</th></tr></thead><tbody><tr><td><code>/System</code></td><td>macOS system root and all subdirectories</td></tr><tr><td><code>/bin</code></td><td>Essential system binaries</td></tr><tr><td><code>/sbin</code></td><td>System administration binaries</td></tr><tr><td><code>/usr/bin</code></td><td>User-facing system utilities</td></tr><tr><td><code>/usr/sbin</code></td><td>System administration utilities</td></tr><tr><td><code>/private/etc</code></td><td>System configuration files</td></tr><tr><td><code>/Library/Security</code></td><td>Security framework</td></tr><tr><td><code>/Applications/Utilities</code></td><td>Built-in utility applications</td></tr><tr><td><code>/Applications</code></td><td>All applications in the main Applications directory</td></tr><tr><td><code>/System/Applications</code></td><td>Built-in macOS applications</td></tr></tbody></table>

{% hint style="info" %}
See [macOS Protected Path Design Intent](/keeperpam/endpoint-privilege-manager/reference/macos-protected-path-design-intent.md) for the design rationale behind `/Applications` and `/System/Applications` being protected.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/reference/macos-two-layer-bypass-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.