macOS: System Extension Configuration
The macOS System Extension (KeeperSystemExtension) is the kernel-level component that gives KEPM visibility into privilege elevation requests and package installations on macOS. It uses Apple's Endpoint Security Framework to intercept authorization petitions — the same mechanism macOS uses for UAC-like elevation prompts — and routes them through the KEPM policy engine before allowing or denying them.
This page covers what the System Extension does, how to configure it, how to deploy it via MDM, and how to troubleshoot common issues.
How it Works
When a user attempts to run a command with sudo, install a .pkg file, or trigger any other authorization petition on a managed Mac, the System Extension intercepts the request before macOS processes it. It sends the request to the KEPM policy engine via the internal MQTT broker, waits for a policy decision, and responds accordingly — allowing, denying, or triggering a control flow (justification, MFA, or approval).
For .dmg disk image opens, the System Extension coalesces burst events: regardless of how many open events macOS generates for the same file, the user sees exactly one policy prompt and the agent processes exactly one policy request per mount operation.
The System Extension runs at kernel level and requires explicit user approval (or MDM pre-approval) before it can be installed.
Full Disk Access
The System Extension and the KeeperPrivilegeManager app both require Full Disk Access to monitor file operations and intercept authorization events.
Interactive install: When a user is logged in at the console, the installer automatically opens System Settings to the Full Disk Access pane and displays a floating alert listing the two items that need approval:
Keeper Endpoint Privilege Manager ExtensionKeeper Endpoint Privilege Manager(/Library/Keeper/KeeperPrivilegeManager.app)
MDM / headless install: When deployed via MDM (no interactive terminal), the installer skips the FDA dialog automatically. Grant Full Disk Access using the Privacy Preferences Policy Control payload below.
MDM configuration profile for Full Disk Access
xml
Configuration File
The System Extension is configured via SystemExtension.json, located at:
All settings have defaults and the file does not need to exist for the System Extension to operate normally. Override only the settings that need to differ from the defaults.
MQTT Outage Behavior
By default, if the System Extension loses its connection to the internal MQTT broker (which can happen briefly during service restarts), it will allow authorization petitions to proceed rather than blocking all elevation requests. This is a deliberate fail-open behavior to prevent the machine from becoming unusable if the KEPM service is temporarily unavailable.
mqtt.failsafe.enabled
true
When true, petitions are allowed during MQTT outages
mqtt.failsafe.maxOutageDurationSeconds
300
After this many seconds of MQTT unavailability, the failsafe activates
mqtt.reconnect.initialIntervalMs
1000
Initial reconnect attempt interval
mqtt.reconnect.maxIntervalMs
30000
Maximum reconnect attempt interval (exponential backoff cap)
Security note: If your security posture requires fail-closed behavior (deny all during MQTT outages), set mqtt.failsafe.enabled to false. Be aware that this means any KEPM service interruption will block all privilege elevation on the affected Mac until the service is restored.
Policy Response Timeout
If the policy engine does not respond to an authorization petition within the configured timeout, the System Extension must decide what to do with the pending petition.
policy.response.timeoutSeconds
300
Seconds to wait for a policy decision before applying the timeout action
policy.response.timeoutAction
"allow"
Action on timeout: "allow" or "deny"
A 5-minute timeout is appropriate for approval-gated workflows where a user must wait for an approver to respond. For environments where approval requests are not used, you can reduce this to 30–60 seconds to prevent elevation requests from hanging indefinitely.
Path Filtering
The System Extension monitors file access events across the system. To reduce performance impact, you can configure path exclusions to skip evaluation of directories that do not need policy coverage.
filtering.excludedPaths
[]
Array of path prefixes to exclude from policy evaluation
filtering.excludeSystemPaths
true
Automatically excludes known macOS system paths from monitoring
Example — exclude a specific application directory:
json
Only exclude paths you are confident do not need policy coverage. Excluding too broadly may create gaps in your policy enforcement.
Updating Settings via Policy
System Extension settings can also be pushed from the Admin Console using an UpdateSettings policy, without requiring manual file edits on each endpoint. This is the recommended approach for fleet-wide configuration changes. See Update Settings Policy Type for details.
Checking Extension Status
bash
The Keeper extension should appear with status [activated enabled]. If it shows [terminated waiting for user], it requires user approval in System Settings → Privacy & Security.
Troubleshooting
The extension is installed but privilege elevation is not being intercepted. Confirm Full Disk Access has been granted to both the extension and the app. In System Settings → Privacy & Security → Full Disk Access, both Keeper Endpoint Privilege Manager Extension and Keeper Endpoint Privilege Manager should be listed and enabled.
Authorization petitions are timing out and users are blocked. Either the KEPM service is not running, or the policy engine is not responding. Check that the service is running and that the KeeperPolicy plugin is in a Running state. If the service is healthy, check whether the timeout is set to a value that is too short for your approval workflow.
Package installations are not being intercepted. Verify the extension is in [activated enabled] state via systemextensionsctl list. If it is activated but packages are not being intercepted, confirm the KEPM service was running at the time of the installation attempt and review the service log for MQTT-level errors.
The extension appears in systemextensionsctl list as terminated. This typically happens after a macOS upgrade. Re-open the KeeperPrivilegeManager application from /Library/Keeper/ to trigger re-installation of the extension, then approve it in System Settings.
Last updated