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:
/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
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.
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:
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:
/System
macOS system root and all subdirectories
/bin
Essential system binaries
/sbin
System administration binaries
/usr/bin
User-facing system utilities
/usr/sbin
System administration utilities
/private/etc
System configuration files
/Library/Security
Security framework
/Applications/Utilities
Built-in utility applications
/Applications
All applications in the main Applications directory
/System/Applications
Built-in macOS applications
See macOS Protected Path Design Intent for the design rationale behind /Applications and /System/Applications being protected.
Last updated