How sap/macos-enterprise-privileges works
1. Overall shape
- This repo is not a single app; it is a macOS product suite for temporary admin-rights management.
- The architecture is centered on one user-facing app plus several background components, a CLI, and a system-extension-style validation layer.
- Most targets are Objective-C macOS bundles that communicate through XPC and code-signing constraints.
2. User-facing control plane: Privileges
- source/Privileges is the main GUI application.
- It contains the main storyboard, settings controllers, a tab controller, and a reason-entry accessory view.
- This is the primary place where users request privileges, configure expiration behavior, and manage app settings.
3. Background user-session agent: PrivilegesAgent
- source/PrivilegesAgent is a per-user background component.
- Its classes show responsibilities for the menu bar/status item, local notifications, syslog, webhooks, and privilege expiration/status commands.
- It acts as the user-session orchestrator: displaying state, reacting to changes, and triggering notifications or integrations when privileges change.
4. Privileged system service: PrivilegesDaemon
- source/PrivilegesDaemon is the central privileged backend.
- It exposes an XPC protocol and is constrained by code-signing requirements, indicating it is a trusted service boundary.
- This component is the likely authority for the actual admin-rights state and related system-level operations.
5. Privileged helper path: PrivilegesHelper
- source/PrivilegesHelper is another privileged service, separate from the daemon.
- Its connection class suggests it brokers privileged operations from client components to system-level actions.
- In the architecture, this is likely the execution layer for operations that require elevated rights or installation/support tasks.
6. Validation and tamper-protection layer: PrivilegesExtension
- source/PrivilegesExtension contains process, parent-process, and process-validation classes.
- This is the security/verification boundary: it inspects request origin and validates process relationships before privileged actions proceed.
- The README’s tamper-protection feature aligns with this module being used to enforce trust and process integrity.
7. CLI entry point: PrivilegesCLI
- source/PrivilegesCLI is the command-line interface.
- It uses shared process-info logic, so it is not a separate backend; it is another client of the same privilege-management system.
- The README notes Touch ID support here, so the CLI is also part of the interactive authorization surface.
8. Shared domain and transport layer: source/Shared
- This folder holds the common model and communication classes used across targets.
- It includes identity, privileges, system info, checksum/code-signing helpers, syslog options, and connection wrappers for agent/helper interactions.
- Architecturally, this is the shared contract layer that keeps the GUI, agent, daemon, CLI, and extension aligned.
9. Monitoring / watcher component
- source/PrivilegesWatcher is a separate lightweight target with minimal code and its own launch metadata.
- It likely serves as a bootstrap/watchdog component to observe state or keep supporting services in sync.
- Because it is isolated from the main app UI, it belongs in the background supervision tier rather than the user-facing tier.
10. Deployment and management boundary
- application_management/ contains MDM configuration profiles and an uninstall script.
- These mobileconfig files let administrators enforce settings such as approval, authentication, expiration interval, allowed users/groups, and remote logging.
- This is a major external control plane: enterprise policy can configure the product without user interaction.
11. Cross-component trust and security
- The repo includes multiple *.coderequirement files and entitlements, showing that inter-process communication is tightly constrained by code identity.
- That matters architecturally because the system depends on trusted component-to-component messaging rather than open IPC.
- The project also ships distinct release/beta plist variants, suggesting multiple build channels with slightly different runtime behavior.
12. Runtime behavior and data flow
- A user or CLI client requests admin rights in the GUI or terminal.
- The request flows through shared connection objects into the privileged backend, where process validation and policy checks occur.
- The daemon/helper update the privilege state and expiration, while the agent reflects the current state in the menu bar, notifications, logs, and optional webhooks.
- Policy can also arrive from MDM profiles, which shape the allowed behavior before a request is even made.
13. What to draw as the main diagram boundaries
- Draw one boundary for client entry points: GUI app, CLI, and agent UI.
- Draw one boundary for privileged services: daemon and helper.
- Draw one boundary for security validation: extension/process-validation logic.
- Draw one boundary for shared infrastructure: common models, connections, and system-info utilities.
- Draw an external boundary for enterprise management: configuration profiles and uninstall/deployment scripts.
Main entry points: PrivilegesDaemon PrivilegesDaemon · example_profiles Profiles · Privileges Privileges · PrivilegesAgent PrivilegesAgent
Components 17
Client entry points
User-facing and command-line entry points that initiate privilege requests and surface state.
- Privileges · Main macOS application for requesting privileges and configuring behavior.
source/Privileges - Privileges CLI · Command-line entry point for interactive privilege requests.
source/PrivilegesCLI - PrivilegesAgent · Per-user background agent that shows status and triggers notifications or integrations.
source/PrivilegesAgent
Privileged services
Trusted backend components that perform elevated operations and maintain system-level state.
- PrivilegesDaemon · Central privileged service that owns admin-rights state and system-level operations.
source/PrivilegesDaemon - PrivilegesHelper · Elevated helper service used for privileged operations and support tasks.
source/PrivilegesHelper - PrivilegesXPC · XPC transport/service boundary used to broker privileged interactions.
source/PrivilegesXPC - PrivilegesWatcher · Lightweight supervision target that observes or keeps supporting services in sync.
source/PrivilegesWatcher
Security validation
Process and parent-process validation used as a trust boundary before privileged actions.
- PrivilegesExtension · Validation boundary that inspects processes and request origin before privileged actions proceed.
source/PrivilegesExtension - Process validation · Checks process identity, hierarchy, and request legitimacy.
source/PrivilegesExtension/Classes/MTProcessValidation.m - Process models · Process, parent-process, and detail objects used by the validation layer.
source/PrivilegesExtension/Classes/MTProcess.m
Shared infrastructure
Common models, transport wrappers, and system-information utilities used across targets.
- Shared models · Common identity, privilege, system-info, and logging configuration models.
source/Shared/Classes/MTPrivileges.m - Connections · Client connection wrappers for daemon, agent, helper, and extension interactions.
source/Shared/Classes/MTAgentConnection.m - Security utils · Checksum, code-signing, identity, and system-extension helper logic.
source/Shared/Classes/MTCodeSigning.m - System info · Shared system and logging helpers used by multiple targets.
source/Shared/Classes/MTSystemInfo.m
Enterprise management
MDM profiles and deployment scripts for policy enforcement and uninstall management.
- Application management · Enterprise profiles and uninstall scripts that configure and govern deployment.
application_management - Profiles · Example configuration profiles for approval, authentication, expiration, logging, and scoping.
application_management/example_profiles - Uninstall · Script used to remove the product from managed systems.
application_management/Privileges2_Uninstall.sh
Connections 22
- Privileges → Connections: uses · GUI uses shared IPC wrappers to reach backend services.
- Privileges → Shared models: reads · GUI shares the common privilege and settings domain.
- Privileges CLI → Shared models: uses · CLI relies on shared process and privilege metadata.
- PrivilegesAgent → Connections: uses · Agent talks to daemon/helper through common connection classes.
- PrivilegesAgent → System info: logs · Agent uses shared system and logging utilities.
- PrivilegesAgent → PrivilegesDaemon: monitors · Agent reflects privilege-state changes originating from the daemon.
- Privileges → PrivilegesDaemon: requests · GUI initiates privilege changes through the trusted backend.
- Privileges CLI → PrivilegesDaemon: requests · CLI issues the same privilege-management requests as the GUI.
- PrivilegesHelper → PrivilegesExtension: validates · Helper depends on extension-based request validation before privileged work.
- PrivilegesHelper → PrivilegesDaemon: supports · Helper assists the daemon path for elevated operations.
- PrivilegesXPC → PrivilegesDaemon: brokers · XPC service mediates privileged communication to the daemon boundary.
- PrivilegesXPC → PrivilegesHelper: brokers · XPC service also carries helper-oriented privileged operations.
- PrivilegesExtension → Process validation: contains · Extension encapsulates the validation policy implementation.
- PrivilegesExtension → Process models: uses · Extension uses process and parent-process metadata objects.
- Process validation → Security utils: uses · Validation depends on shared trust and code-signing helpers.
- PrivilegesDaemon → Security utils: enforces · Daemon applies code-signing and identity constraints at the trust boundary.
- PrivilegesDaemon → Connections: uses · Daemon participates in the shared IPC contract.
- Application management → Profiles: includes · Management boundary ships example policies as mobileconfig profiles.
- Application management → Uninstall: includes · Management boundary includes deployment/uninstall automation.
- Profiles → Privileges: configures · MDM profiles shape app policy, authentication, and expiration behavior.
- Profiles → PrivilegesDaemon: governs · Policy profiles constrain daemon-managed privilege behavior.
- Profiles → PrivilegesAgent: governs · Managed settings also affect agent-side status and logging behavior.