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:

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.

Last updated