# 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 Extension`
* `Keeper 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

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadType</key>
  <string>com.apple.TCC.configuration-profile-policy</string>
  <key>PayloadUUID</key>
  <string><!-- generate a UUID --></string>
  <key>Services</key>
  <dict>
    <key>SystemPolicyAllFiles</key>
    <array>
      <dict>
        <key>Identifier</key>
        <string>com.keeper.endpoint-privilege-manager.extension</string>
        <key>IdentifierType</key>
        <string>bundleID</string>
        <key>CodeRequirement</key>
        <string>anchor apple generic and identifier "com.keeper.endpoint-privilege-manager.extension"</string>
        <key>Allowed</key>
        <true/>
        <key>StaticCode</key>
        <false/>
      </dict>
      <dict>
        <key>Identifier</key>
        <string>com.keeper.endpoint-privilege-manager</string>
        <key>IdentifierType</key>
        <string>bundleID</string>
        <key>CodeRequirement</key>
        <string>anchor apple generic and identifier "com.keeper.endpoint-privilege-manager"</string>
        <key>Allowed</key>
        <true/>
        <key>StaticCode</key>
        <false/>
      </dict>
    </array>
  </dict>
</dict>
</plist>
```

## Configuration File

The System Extension is configured via `SystemExtension.json`, located at:

```
/Library/Keeper/sbin/Plugins/SystemExtension.json
```

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.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="356.33331298828125">Setting</th><th width="96.3333740234375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>mqtt.failsafe.enabled</code></td><td><code>true</code></td><td>When <code>true</code>, petitions are allowed during MQTT outages</td></tr><tr><td><code>mqtt.failsafe.maxOutageDurationSeconds</code></td><td><code>300</code></td><td>After this many seconds of MQTT unavailability, the failsafe activates</td></tr><tr><td><code>mqtt.reconnect.initialIntervalMs</code></td><td><code>1000</code></td><td>Initial reconnect attempt interval</td></tr><tr><td><code>mqtt.reconnect.maxIntervalMs</code></td><td><code>30000</code></td><td>Maximum reconnect attempt interval (exponential backoff cap)</td></tr></tbody></table>

**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.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>policy.response.timeoutSeconds</code></td><td><code>300</code></td><td>Seconds to wait for a policy decision before applying the timeout action</td></tr><tr><td><code>policy.response.timeoutAction</code></td><td><code>"allow"</code></td><td>Action on timeout: <code>"allow"</code> or <code>"deny"</code></td></tr></tbody></table>

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.

<table data-header-hidden="false" data-header-sticky><thead><tr><th>Setting</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>filtering.excludedPaths</code></td><td><code>[]</code></td><td>Array of path prefixes to exclude from policy evaluation</td></tr><tr><td><code>filtering.excludeSystemPaths</code></td><td><code>true</code></td><td>Automatically excludes known macOS system paths from monitoring</td></tr></tbody></table>

### **Example — exclude a specific application directory:**

json

```json
{
  "id": "KeeperSystemExtension",
  "settings": {
    "filtering.excludedPaths": [
      "/private/var/folders",
      "/System/Library/Caches"
    ],
    "filtering.excludeSystemPaths": true
  }
}
```

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](https://docs.keeper.io/en/keeperpam/endpoint-privilege-manager/policies/policy-types/advanced-policy-types/update-settings-policy-type) for details.

## Checking Extension Status

bash

```bash
# List all loaded system extensions and their status
systemextensionsctl list

# Check System Extension approval status
spctl --status
```

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.


---

# 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/en/keeperpam/endpoint-privilege-manager/reference/macos-system-extension-configuration.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.