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

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:

[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:

Path	Description
/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.