{"id":26608139,"url":"https://github.com/mobydeck/suex","last_synced_at":"2026-03-02T07:09:38.389Z","repository":{"id":281369007,"uuid":"945062675","full_name":"mobydeck/suex","owner":"mobydeck","description":"Collection of lightweight utilities written in C for privilege management and system information","archived":false,"fork":false,"pushed_at":"2025-03-21T19:56:58.000Z","size":1959,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T23:40:13.083Z","etag":null,"topics":["su","sudo"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mobydeck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-08T15:17:02.000Z","updated_at":"2025-03-22T15:26:26.000Z","dependencies_parsed_at":"2025-03-23T23:38:24.308Z","dependency_job_id":"b04f4ac1-94dd-450d-9237-e08191e32891","html_url":"https://github.com/mobydeck/suex","commit_stats":null,"previous_names":["mobydeck/suex"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/mobydeck/suex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobydeck%2Fsuex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobydeck%2Fsuex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobydeck%2Fsuex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobydeck%2Fsuex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mobydeck","download_url":"https://codeload.github.com/mobydeck/suex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobydeck%2Fsuex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29994632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["su","sudo"],"created_at":"2025-03-23T23:38:16.329Z","updated_at":"2026-03-02T07:09:38.383Z","avatar_url":"https://github.com/mobydeck.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `suex` \u0026 `sush` - Lightweight Privilege Management Tools\n\nA collection of lightweight utilities written in C for privilege management and system information, with a focus on simplicity and security.\nThey 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.\nIdeal for developers, DevOps workflows, CI/CD pipelines, and containerized applications where reliability and performance at scale are paramount.\n\n## Core Utilities\n\n### suex\n\nA lightweight privilege switching tool for executing commands with different user and group permissions. Think of it as a streamlined alternative to `sudo` and `su`.\n\n### sush\n\nA 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.\n\n## Additional Utilities\n\n### usrx\n\nA utility for querying user information from system files (`/etc/passwd`, `/etc/group`, and `/etc/shadow`).\n\n### uarch\n\nA simple utility for displaying system architecture names in a standardized format, particularly useful for cross-platform development and build scripts.\n\n## Core Utilities in Detail\n\n### suex - Command Execution with Different Privileges\n\n`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.\n\n#### Key Features\n\n- Direct program execution (not spawning child processes)\n- Dual privilege management model:\n    - For root users: Ability to step down to lower privileges (similar to `su`)\n    - For non-root users in the `suex` group: Ability to elevate to specific privileges or switch to any other user\n- Support for both username/group names and numeric uid/gid\n- Group-based access control (users in the `suex` group can execute commands with elevated privileges)\n- Better TTY and signal handling than traditional alternatives\n- Simpler and more streamlined than traditional `su`/`sudo`\n- Login mode (`-l`) for full login environment simulation, similar to `su -`\n- Extremely useful in dynamic development environments, build and test containers, and ephemeral systems\n\n#### Usage\n\nBasic syntax:\n```shell\nsuex [-l] [USER[:GROUP]] COMMAND [ARGUMENTS...]\n```\n\nWhere:\n- `-l`: Login mode — clear the inherited environment and set up a clean login environment (HOME, USER, LOGNAME, SHELL, MAIL, PATH). Working directory is unchanged.\n- `USER`: Username or numeric uid (optional for non-root users, defaults to root)\n- `GROUP`: (Optional) Group name or numeric gid\n- `COMMAND`: The program to execute\n- `ARGUMENTS`: Any additional arguments for the command\n\nYou can also use the `@` or `+` prefix for the USER specification:\n```shell\nsuex [-l] [@|+]USER[:GROUP] COMMAND [ARGUMENTS...]\n```\n\n#### Examples\n\nFor root users (stepping down in privileges):\n```shell\n# Run as a non-privileged user\nsuex nobody /bin/program\n\n# Run with specific user and group\nsuex nginx:www-data /usr/sbin/nginx -c /etc/nginx/nginx.conf\n```\n\nFor non-root users in the `suex` group (elevating or switching privileges):\n```shell\n# Elevate to root\nsuex /bin/program\n\n# Switch to a different user\nsuex webadmin /usr/bin/configure-site\n\n# Use with prefix notation\nsuex @deploy:deploygroup /usr/bin/deploy-app\n```\n\nUsing numeric IDs:\n```shell\nsuex 100:1000 /bin/program\n```\n\nWith login mode (clean environment, similar to `su - user -c cmd`):\n```shell\n# Run a command in the target user's clean login environment\nsuex -l www-data /usr/bin/configure-site\n\n# Start a login shell for another user\nsuex -l deploy /bin/bash\n```\n\n#### Setup\n\n`suex` requires root privileges to operate as it performs uid/gid changes. To set it up:\n\n```shell\n# Create the suex group if it doesn't exist\ngroupadd --system suex\n\n# Set the appropriate permissions on the suex binary\nchown root:suex suex\nchmod 4750 suex\n\n# Add users who should be able to use suex\nusermod -a -G suex username\n```\n\n### sush - Interactive Shell with Different Privileges\n\nWhile `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.\n\n#### Key Features\n\n- Launches an interactive login shell as another user (equivalent to `su -`)\n- Sets up a clean login environment: HOME, USER, LOGNAME, SHELL, MAIL, PATH, TERM\n- PATH is always a system-default path plus the target user's `~/.local/bin`\n- Supports custom shell specification\n- Uses the same permission model as `suex` (requires membership in the `suex` group)\n- Changes to the target user's home directory\n\n#### Usage\n\nBasic syntax:\n```shell\nsush [OPTIONS] [USERNAME]\n```\n\nOptions:\n- `-s SHELL`: Use a specific shell instead of the user's default\n\nIf no username is specified, defaults to root.\n\n#### Examples\n\nLaunch a shell as root:\n```shell\nsush\n```\n\nLaunch a shell as another user:\n```shell\nsush username\n```\n\nLaunch a specific shell as another user:\n```shell\nsush -s /bin/zsh username\n```\n\n#### Setup\n\n`sush` requires root privileges similar to `suex`. To set it up:\n\n```shell\n# Create the suex group if it doesn't exist\ngroupadd --system suex\n\n# Set the appropriate permissions on the sush binary\nchown root:suex sush\nchmod 4750 sush\n\n# Add users who should be able to use suex\nusermod -a -G suex username\n```\n\n#### How `suex` and `sush` Complement Each Other\n\n`suex` and `sush` are designed to work together as a comprehensive privilege management solution:\n\n- **suex**: For running specific commands with different privileges\n- **sush**: For interactive shell sessions with different privileges\n\nBoth utilities:\n- Share the same permission model (the `suex` group)\n- Provide direct execution for better TTY and signal handling\n- Offer a simpler alternative to traditional `su`/`sudo`\n\n## Advantages Over su/sudo\n\nThe 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.\n\nExample comparison:\n```shell\n# with su\n$ docker run -it --rm alpine:edge su postgres -c 'ps aux'\nPID   USER     TIME   COMMAND\n    1 postgres   0:00 ash -c ps aux\n   12 postgres   0:00 ps aux\n\n# with suex\n$ docker run -it --rm -v $PWD/suex:/sbin/suex:ro alpine:edge suex postgres ps aux\nPID   USER     TIME   COMMAND\n    1 postgres   0:00 ps aux\n```\n\n## Additional Utilities in Detail\n\n### usrx - User Information Utility\n\n`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.\n\n#### Key Features\n\n- Comprehensive user information querying from system files\n- Support for all standard user attributes (home, shell, groups, etc.)\n- Fast and efficient group membership resolution\n- Root-level access to shadow password information\n- Formatted output for both single values and complete user profiles\n\n#### Usage\n\nBasic syntax:\n```shell\nusrx COMMAND [OPTIONS] USER\n```\n\nFor detailed usage information, see the [usrx documentation](#usrx-usage) below.\n\n### uarch - Architecture Display Utility\n\n`uarch` is a simple utility for displaying system architecture names in a standardized format, particularly useful for cross-platform development and build scripts.\n\n#### Key Features\n\n- Maps system architecture to unofficial Linux architecture names\n- Handles special cases for macOS architecture reporting\n- Supports displaying original system architecture names\n- Works consistently across Linux and macOS platforms\n\n#### Usage\n\nBasic syntax:\n```shell\nuarch [-a]\n```\n\nFor detailed usage information, see the [uarch documentation](#uarch-usage) below.\n\n## Detailed Documentation\n\n### usrx usage\n\nBasic syntax:\n```shell\nusrx COMMAND [OPTIONS] USER\n```\n\n### `/etc/passwd` explained\n\n![/etc/passwd](assets/passwd.png)\n\n### `/etc/shadow` explained\n\n![/etc/shadow](assets/shadow.png)\n\n#### Options\n\nFor `info` command:\n- `-j` - Output information in JSON format\n- `-i` - Skip encrypted password in output (useful for secure information display)\n\n#### Available Commands\n\nStandard commands (available to all users):\n- `info` - Display all available information about the user\n  ```shell\n  # Standard output\n  $ usrx info username\n  \n  # JSON output\n  $ usrx info -j username\n  \n  # Skip sensitive information\n  $ usrx info -i username\n  \n  # JSON output without sensitive information\n  $ usrx info -j -i username\n  ```\n- `home` - Print user's home directory\n- `shell` - Print user's login shell\n- `gecos` - Print user's GECOS field\n- `id` - Print user's UID\n- `gid` - Print user's primary GID\n- `group` - Print user's primary group name\n- `groups` - Print all groups the user belongs to\n\nRoot-only commands (requires root privileges):\n- `passwd` - Print user's encrypted password\n- `days` - Print detailed password aging information\n- `check USER [PASSWORD]` - Verify if the provided password is correct\n  - If PASSWORD is omitted, reads password securely from stdin\n  - Returns exit code 0 if password is correct, 1 if incorrect\n\n#### JSON Output Format\n\nWhen using the `-j` option with the `info` command, the output is structured as follows:\n\n```json\n{\n  \"user\": \"username\",\n  \"group\": \"primary_group\",\n  \"uid\": 1000,\n  \"gid\": 1000,\n  \"home\": \"/home/username\",\n  \"shell\": \"/bin/bash\",\n  \"gecos\": \"Full Name\",\n  \"groups\": [\n    {\"name\": \"group1\", \"gid\": 1000},\n    {\"name\": \"group2\", \"gid\": 1001}\n  ],\n  \"shadow\": {\n    \"encrypted_password\": \"...\",\n    \"last_change\": 19168,\n    \"min_days\": 0,\n    \"max_days\": 99999,\n    \"warn_days\": 7,\n    \"inactive_days\": -1,\n    \"expiration\": -1\n  }\n}\n```\n\nNote: The `shadow` section is only included when running as root, and the `encrypted_password` field is omitted when using the `-i` option.\n\n#### Examples\n\nGet user's home directory:\n```shell\n$ usrx home username\n/home/username\n```\n\nList all groups for a user:\n```shell\n$ usrx groups username\nusers suex docker developers\n```\n\nGet comprehensive user information (as root):\n```shell\n$ suex usrx info username\nUser Information for 'username':\n------------------------\nUsername: username\nUser ID: 1000\nPrimary group ID: 1000\nPrimary group name: username\nHome directory: /home/username\nShell: /bin/bash\nGECOS: John Doe\nGroups: username(1000), suex(27), docker(998)\n\nShadow Information (root only):\n-----------------------------\n[password and aging information]\n```\n\nGet user info in standard format:\n```shell\n$ usrx info username\n```\n\nGet user info in JSON format:\n```shell\n$ usrx info -j username\n```\n\nGet user info without sensitive data:\n```shell\n$ usrx info -i username\n```\n\n### Password Verification Examples\n\n1. Exit codes:\n```shell\n# Returns exit code 0 if password is correct, 1 if incorrect\n$ suex usrx check username correctpassword\n$ echo $?\n0\n\n$ suex usrx check username wrongpassword\n$ echo $?\n1\n```\n\n2. Interactive password prompt:\n```shell\n$ suex usrx check username\nPassword: [hidden input]\n```\n\n3. Password from command line (less secure):\n```shell\n$ suex usrx check username mypassword\n```\n\n4. Password from file:\n```shell\n$ suex usrx check username \u003cpassword.txt\n```\n\n5. Password from pipe:\n```shell\n$ echo \"mypassword\" | suex usrx check username\n```\n\nNote: The `check` command does not produce any output - it only sets the exit code.\nFor scripting, you can use it like this:\n\n```shell\nif suex usrx check username userpassword; then\n    echo \"Password is correct\"\nelse\n    echo \"Password is incorrect\"\nfi\n```\n\n### Security Notes\n\n- The `passwd` and `days` commands require root privileges as they access `/etc/shadow`\n- When installed setuid root (`suex chmod u+s usrx`), these commands become available to all users\n- Consider the security implications before setting the setuid bit\n- The `check` command receives password as a command line argument which may expose it in:\n    - Process listings (ps, top, etc.)\n    - Shell history\n    - System logs\n    - Other system monitoring tools\n    - When using file redirection or pipes, ensure that:\n        - The password file has appropriate permissions (600 or more restrictive)\n        - The password file is stored in a secure location\n        - The file is securely deleted after use\n        - The command is not visible in shell history\n- For production use, consider more secure password verification methods\n\n### `uarch` usage\n```shell\nuarch [-a]\n```\n\nOptions:\n- `-a` - Print the original system architecture name instead of the unofficial name\n- `-h` - Show help message\n\n#### Examples\n\nPrint unofficial system architecture name:\n```shell\n$ uarch\namd64\n```\n\nPrint original system architecture name:\n```shell\n$ uarch -a\nx86_64\n```\n\n## Attribution\n\n`suex` is a reimplementation of [`su-exec`](https://github.com/ncopa/su-exec),\nenhanced for improved usability and maintainability.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobydeck%2Fsuex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmobydeck%2Fsuex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobydeck%2Fsuex/lists"}