How Omarchy Manages sudo secure_path for Isolated Privilege Escalation

Omarchy controls the secure_path used by sudo through a dedicated setup script that generates a custom sudoers fragment at /etc/sudoers.d/omarchy-secure-path, restricting privileged execution to trusted directories including the Omarchy binary path.

The sudo secure_path is a critical security parameter that defines which directories sudo searches for executables when running commands as root. In the Omarchy repository, this configuration is carefully engineered to prevent privilege escalation while enabling seamless Docker and system operations. By scoping the secure_path to the %omarchy user group, the system ensures that elevated commands access only vetted binaries from standard system locations and the Omarchy installation directory.

The Omarchy sudo secure_path Architecture

Core Configuration File

The foundation of Omarchy's secure_path management resides in bin/omarchy-setup-security-sudoless-docker. This script generates a sudoers fragment that explicitly sets the Defaults!%omarchy secure_path variable. The configuration combines the standard system directories (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin) with the Omarchy-specific binary directory referenced via $OMARCHY_PATH/bin.

This fragment is validated using visudo -c before installation, ensuring syntactic correctness and preventing sudo configuration lockouts. Once deployed, the sudo daemon immediately applies the restricted path to any user belonging to the omarchy group.

Group-Based Scoping

Unlike system-wide secure_path modifications, Omarchy's approach isolates the configuration to the %omarchy group using the Defaults!%omarchy directive. This design means ordinary users retain the default system secure_path while Omarchy-specific operations execute within a constrained environment. The isolation prevents non-Omarchy users from inadvertently accessing the restricted binary set, and ensures that Omarchy's privileged workflows remain independent of system-wide sudo policy changes.

Implementation in the Source Code

The setup script bin/omarchy-setup-security-sudoless-docker performs the complete installation of the secure_path configuration. When executed during initial Omarchy setup, it writes the sudoers fragment to /etc/sudoers.d/omarchy-secure-path with the following pattern:

# Install the secure_path fragment (run once during initial Omarchy setup)

omarchy-setup-security-sudoless-docker

# Verify that the fragment was created and syntax is valid

sudo cat /etc/sudoers.d/omarchy-secure-path

# Example output showing the secure_path directive

# Defaults!%omarchy secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/omarchy/bin"

If the Omarchy installation directory changes (such as during version upgrades), re-running this script regenerates the fragment with updated paths, maintaining synchronization between the filesystem layout and sudo security policies.

Utility Scripts Supporting secure_path

Timestamp Management with omarchy-sudo-keepalive

Long-running Omarchy operations that require elevated privileges could trigger password prompts when sudo credentials expire. The bin/omarchy-sudo-keepalive utility runs as a background process that periodically invokes sudo -v to refresh the authentication timestamp. Because this helper operates within the Omarchy secure_path context, it ensures that all renewal commands execute using the same restricted binary environment.

# Keep the sudo timestamp refreshed during long-running operations

omarchy-sudo-keepalive &   # runs in background, periodically calls `sudo -v`

Passwordless sudo Configuration

For automated workflows requiring elevated access without interactive authentication, Omarchy provides bin/omarchy-sudo-passwordless. This utility configures password-less sudo for specific trusted Omarchy commands while maintaining the restricted secure_path environment. The combination ensures that even unattended elevated operations cannot execute binaries outside the approved directory list.

# Enable password-less sudo for a specific Omarchy command

omarchy-sudo-passwordless omarchy-docker-upgrade

Security Benefits of the secure_path Design

The explicit secure_path configuration in Omarchy serves multiple security objectives. By limiting executable search paths to $OMARCHY_PATH/bin and standard system directories, the system mitigates PATH hijacking attacks where malicious binaries in user-writable directories (like /tmp or ~/.local/bin) could be substituted for legitimate system utilities. The group-scoped implementation further reduces the attack surface by applying these restrictions only to users performing Omarchy-specific administrative tasks.

Automated validation through test/shell.d/sudo-docker-test.sh continuously verifies that the secure_path configuration functions correctly within Docker-related workflows, ensuring that privilege escalation paths remain confined across Omarchy updates and system modifications.

Summary

• Omarchy manages sudo secure_path through bin/omarchy-setup-security-sudoless-docker, which generates a sudoers fragment at /etc/sudoers.d/omarchy-secure-path.
• The configuration uses Defaults!%omarchy to scope the restriction to the Omarchy user group, leaving system-wide sudo settings unchanged.
• The secure_path includes standard system directories plus $OMARCHY_PATH/bin, preventing execution of rogue binaries.
• Helper utilities (omarchy-sudo-keepalive and omarchy-sudo-passwordless) operate within this restricted environment to maintain security during extended or automated operations.

Frequently Asked Questions

What is sudo secure_path and why does Omarchy customize it?

The sudo secure_path environment variable defines the directories that sudo searches when executing commands as root. Omarchy customizes this setting to prevent privilege escalation attacks where an attacker might place a malicious binary in a user-writable directory that appears earlier in the PATH. By explicitly setting the secure_path to include only standard system directories and the Omarchy binary folder, the system ensures that elevated operations run only trusted executables.

How does Omarchy isolate the secure_path configuration from other users?

Omarchy uses the Defaults!%omarchy directive in the sudoers fragment rather than a global Defaults line. This means only members of the omarchy group receive the restricted secure_path when using sudo. Regular users and system administrators continue using the default system-wide secure_path defined in the main /etc/sudoers file or other fragments, ensuring that Omarchy's security policies do not interfere with general system administration workflows.

Where is the Omarchy sudo secure_path configuration stored?

The configuration resides in the file /etc/sudoers.d/omarchy-secure-path, which is generated by the setup script bin/omarchy-setup-security-sudoless-docker. This file contains the secure_path definition scoped to the %omarchy group. The location follows standard sudo conventions for drop-in configuration fragments, allowing the setting to persist across system updates while remaining modular and easy to audit.

How does Omarchy maintain the secure_path during updates?

If the Omarchy installation directory changes (for example, during a version upgrade that modifies $OMARCHY_PATH), administrators can re-run omarchy-setup-security-sudoless-docker to regenerate the sudoers fragment. The script automatically updates the secure_path to reflect the current binary location, ensuring that the security configuration remains synchronized with the actual filesystem layout without requiring manual editing of sudoers files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}