https://github.com/mobydeck/suex
Collection of lightweight utilities written in C for privilege management and system information
https://github.com/mobydeck/suex
su sudo
Last synced: 3 months ago
JSON representation
Collection of lightweight utilities written in C for privilege management and system information
- Host: GitHub
- URL: https://github.com/mobydeck/suex
- Owner: mobydeck
- License: mit
- Created: 2025-03-08T15:17:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-21T19:56:58.000Z (about 1 year ago)
- Last Synced: 2025-03-23T23:40:13.083Z (about 1 year ago)
- Topics: su, sudo
- Language: C
- Homepage:
- Size: 1.87 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `suex` & `sush` - Lightweight Privilege Management Tools
A collection of lightweight utilities written in C for privilege management and system information, with a focus on simplicity and security.
They provide essential functionality for privilege management, process execution, and system information gathering in environments where traditional solutions may be too heavyweight or introduce unwanted dependencies.
Ideal for developers, DevOps workflows, CI/CD pipelines, and containerized applications where reliability and performance at scale are paramount.
## Core Utilities
### suex
A lightweight privilege switching tool for executing commands with different user and group permissions. Think of it as a streamlined alternative to `sudo` and `su`.
### sush
A companion shell launcher for `suex` that provides an interactive shell with the privileges of another user. While `suex` is designed for running specific commands, `sush` is optimized for interactive shell sessions.
## Additional Utilities
### usrx
A utility for querying user information from system files (`/etc/passwd`, `/etc/group`, and `/etc/shadow`).
### uarch
A simple utility for displaying system architecture names in a standardized format, particularly useful for cross-platform development and build scripts.
## Core Utilities in Detail
### suex - Command Execution with Different Privileges
`suex` allows you to run commands with different user and group privileges. Unlike traditional tools like `su` or `sudo`, `suex` executes programs directly rather than as child processes, which provides better handling of TTY and signals.
#### Key Features
- Direct program execution (not spawning child processes)
- Dual privilege management model:
- For root users: Ability to step down to lower privileges (similar to `su`)
- For non-root users in the `suex` group: Ability to elevate to specific privileges or switch to any other user
- Support for both username/group names and numeric uid/gid
- Group-based access control (users in the `suex` group can execute commands with elevated privileges)
- Better TTY and signal handling than traditional alternatives
- Simpler and more streamlined than traditional `su`/`sudo`
- Login mode (`-l`) for full login environment simulation, similar to `su -`
- Extremely useful in dynamic development environments, build and test containers, and ephemeral systems
#### Usage
Basic syntax:
```shell
suex [-l] [USER[:GROUP]] COMMAND [ARGUMENTS...]
```
Where:
- `-l`: Login mode — clear the inherited environment and set up a clean login environment (HOME, USER, LOGNAME, SHELL, MAIL, PATH). Working directory is unchanged.
- `USER`: Username or numeric uid (optional for non-root users, defaults to root)
- `GROUP`: (Optional) Group name or numeric gid
- `COMMAND`: The program to execute
- `ARGUMENTS`: Any additional arguments for the command
You can also use the `@` or `+` prefix for the USER specification:
```shell
suex [-l] [@|+]USER[:GROUP] COMMAND [ARGUMENTS...]
```
#### Examples
For root users (stepping down in privileges):
```shell
# Run as a non-privileged user
suex nobody /bin/program
# Run with specific user and group
suex nginx:www-data /usr/sbin/nginx -c /etc/nginx/nginx.conf
```
For non-root users in the `suex` group (elevating or switching privileges):
```shell
# Elevate to root
suex /bin/program
# Switch to a different user
suex webadmin /usr/bin/configure-site
# Use with prefix notation
suex @deploy:deploygroup /usr/bin/deploy-app
```
Using numeric IDs:
```shell
suex 100:1000 /bin/program
```
With login mode (clean environment, similar to `su - user -c cmd`):
```shell
# Run a command in the target user's clean login environment
suex -l www-data /usr/bin/configure-site
# Start a login shell for another user
suex -l deploy /bin/bash
```
#### Setup
`suex` requires root privileges to operate as it performs uid/gid changes. To set it up:
```shell
# Create the suex group if it doesn't exist
groupadd --system suex
# Set the appropriate permissions on the suex binary
chown root:suex suex
chmod 4750 suex
# Add users who should be able to use suex
usermod -a -G suex username
```
### sush - Interactive Shell with Different Privileges
While `suex` is designed for running specific commands, `sush` provides an interactive shell with the privileges of another user. It's optimized for interactive use and properly sets up the shell environment.
#### Key Features
- Launches an interactive login shell as another user (equivalent to `su -`)
- Sets up a clean login environment: HOME, USER, LOGNAME, SHELL, MAIL, PATH, TERM
- PATH is always a system-default path plus the target user's `~/.local/bin`
- Supports custom shell specification
- Uses the same permission model as `suex` (requires membership in the `suex` group)
- Changes to the target user's home directory
#### Usage
Basic syntax:
```shell
sush [OPTIONS] [USERNAME]
```
Options:
- `-s SHELL`: Use a specific shell instead of the user's default
If no username is specified, defaults to root.
#### Examples
Launch a shell as root:
```shell
sush
```
Launch a shell as another user:
```shell
sush username
```
Launch a specific shell as another user:
```shell
sush -s /bin/zsh username
```
#### Setup
`sush` requires root privileges similar to `suex`. To set it up:
```shell
# Create the suex group if it doesn't exist
groupadd --system suex
# Set the appropriate permissions on the sush binary
chown root:suex sush
chmod 4750 sush
# Add users who should be able to use suex
usermod -a -G suex username
```
#### How `suex` and `sush` Complement Each Other
`suex` and `sush` are designed to work together as a comprehensive privilege management solution:
- **suex**: For running specific commands with different privileges
- **sush**: For interactive shell sessions with different privileges
Both utilities:
- Share the same permission model (the `suex` group)
- Provide direct execution for better TTY and signal handling
- Offer a simpler alternative to traditional `su`/`sudo`
## Advantages Over su/sudo
The main advantage of these utilities is their direct execution model. When using traditional tools like `su` or `sudo`, commands are executed as child processes, which can lead to complications with TTY handling and signal processing. The tools in this package avoid these issues by executing programs directly.
Example comparison:
```shell
# with su
$ docker run -it --rm alpine:edge su postgres -c 'ps aux'
PID USER TIME COMMAND
1 postgres 0:00 ash -c ps aux
12 postgres 0:00 ps aux
# with suex
$ docker run -it --rm -v $PWD/suex:/sbin/suex:ro alpine:edge suex postgres ps aux
PID USER TIME COMMAND
1 postgres 0:00 ps aux
```
## Additional Utilities in Detail
### usrx - User Information Utility
`usrx` provides a simple command-line interface to retrieve various user-related information from system files. It can query basic user information, group memberships, and (with root privileges) password-related data.
#### Key Features
- Comprehensive user information querying from system files
- Support for all standard user attributes (home, shell, groups, etc.)
- Fast and efficient group membership resolution
- Root-level access to shadow password information
- Formatted output for both single values and complete user profiles
#### Usage
Basic syntax:
```shell
usrx COMMAND [OPTIONS] USER
```
For detailed usage information, see the [usrx documentation](#usrx-usage) below.
### uarch - Architecture Display Utility
`uarch` is a simple utility for displaying system architecture names in a standardized format, particularly useful for cross-platform development and build scripts.
#### Key Features
- Maps system architecture to unofficial Linux architecture names
- Handles special cases for macOS architecture reporting
- Supports displaying original system architecture names
- Works consistently across Linux and macOS platforms
#### Usage
Basic syntax:
```shell
uarch [-a]
```
For detailed usage information, see the [uarch documentation](#uarch-usage) below.
## Detailed Documentation
### usrx usage
Basic syntax:
```shell
usrx COMMAND [OPTIONS] USER
```
### `/etc/passwd` explained
### `/etc/shadow` explained
#### Options
For `info` command:
- `-j` - Output information in JSON format
- `-i` - Skip encrypted password in output (useful for secure information display)
#### Available Commands
Standard commands (available to all users):
- `info` - Display all available information about the user
```shell
# Standard output
$ usrx info username
# JSON output
$ usrx info -j username
# Skip sensitive information
$ usrx info -i username
# JSON output without sensitive information
$ usrx info -j -i username
```
- `home` - Print user's home directory
- `shell` - Print user's login shell
- `gecos` - Print user's GECOS field
- `id` - Print user's UID
- `gid` - Print user's primary GID
- `group` - Print user's primary group name
- `groups` - Print all groups the user belongs to
Root-only commands (requires root privileges):
- `passwd` - Print user's encrypted password
- `days` - Print detailed password aging information
- `check USER [PASSWORD]` - Verify if the provided password is correct
- If PASSWORD is omitted, reads password securely from stdin
- Returns exit code 0 if password is correct, 1 if incorrect
#### JSON Output Format
When using the `-j` option with the `info` command, the output is structured as follows:
```json
{
"user": "username",
"group": "primary_group",
"uid": 1000,
"gid": 1000,
"home": "/home/username",
"shell": "/bin/bash",
"gecos": "Full Name",
"groups": [
{"name": "group1", "gid": 1000},
{"name": "group2", "gid": 1001}
],
"shadow": {
"encrypted_password": "...",
"last_change": 19168,
"min_days": 0,
"max_days": 99999,
"warn_days": 7,
"inactive_days": -1,
"expiration": -1
}
}
```
Note: The `shadow` section is only included when running as root, and the `encrypted_password` field is omitted when using the `-i` option.
#### Examples
Get user's home directory:
```shell
$ usrx home username
/home/username
```
List all groups for a user:
```shell
$ usrx groups username
users suex docker developers
```
Get comprehensive user information (as root):
```shell
$ suex usrx info username
User Information for 'username':
------------------------
Username: username
User ID: 1000
Primary group ID: 1000
Primary group name: username
Home directory: /home/username
Shell: /bin/bash
GECOS: John Doe
Groups: username(1000), suex(27), docker(998)
Shadow Information (root only):
-----------------------------
[password and aging information]
```
Get user info in standard format:
```shell
$ usrx info username
```
Get user info in JSON format:
```shell
$ usrx info -j username
```
Get user info without sensitive data:
```shell
$ usrx info -i username
```
### Password Verification Examples
1. Exit codes:
```shell
# Returns exit code 0 if password is correct, 1 if incorrect
$ suex usrx check username correctpassword
$ echo $?
0
$ suex usrx check username wrongpassword
$ echo $?
1
```
2. Interactive password prompt:
```shell
$ suex usrx check username
Password: [hidden input]
```
3. Password from command line (less secure):
```shell
$ suex usrx check username mypassword
```
4. Password from file:
```shell
$ suex usrx check username