{"id":22366748,"url":"https://github.com/vaeth/sudox","last_synced_at":"2025-06-14T09:05:58.524Z","repository":{"id":2073474,"uuid":"3012470","full_name":"vaeth/sudox","owner":"vaeth","description":"sudox is a wrapper for sudo which can pass X authority data and deal with screen and tmux","archived":false,"fork":false,"pushed_at":"2023-07-07T09:55:55.000Z","size":91,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-14T09:03:07.580Z","etag":null,"topics":["posix","shell","sudo","tmux","wrapper","xauthority"],"latest_commit_sha":null,"homepage":"http://www.mathematik.uni-wuerzburg.de/~vaeth/download/index.html#sudox","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vaeth.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2011-12-19T14:25:47.000Z","updated_at":"2023-09-08T03:24:57.000Z","dependencies_parsed_at":"2025-06-14T09:03:10.993Z","dependency_job_id":null,"html_url":"https://github.com/vaeth/sudox","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/vaeth/sudox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsudox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsudox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsudox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsudox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vaeth","download_url":"https://codeload.github.com/vaeth/sudox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vaeth%2Fsudox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259790457,"owners_count":22911546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["posix","shell","sudo","tmux","wrapper","xauthority"],"created_at":"2024-12-04T18:15:34.217Z","updated_at":"2025-06-14T09:05:58.508Z","avatar_url":"https://github.com/vaeth.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sudox\n\n(C) Martin Väth (martin at mvath.de).\nThis project is under the BSD license 2.0 (“3-clause BSD license”).\nSPDX-License-Identifier: BSD-3-Clause\n\nsudox is a POSIX shell script which acts as a wrapper for\n`sudo -H` [`-s`] which can pass X cookies.\n\nIt is possible to create temporary untrusted X permissions.\nMoreover, wayland is supported via acls, variable passing, and a wrapper.\nAlso some support for tty handling (e.g. screen and tmux) is provided.\n\nFor more details, see the output of `sudox -h`\n\nIf you want to change the user for the remainder of the whole shell session\nand are somewhat paranoic to do this by accident from a runnnig\nscreen or tmux session, you can use `sudoxe` in place of `sudox`:\nThis is essentially `exec sudox`, but checks your environment first.\nBe aware that when using `sudoxe` (or `exec sudox`) and `sudo` asks for a\npassword, a wrong password will terminate your session anyway.\n(Please let me know if you know a trick how to avoid this problem...)\n\n\n## Installation\n\nFor installation, copy `bin/*` to your `$PATH` and add code like\n```\nif SOME_VARIABLE=`sudoxe 2\u003e/dev/null`\nthen\teval \"$SOME_VARIABLE\"\nelse\techo 'sudoxe not found' \u003e\u00262\nfi\n```\nto your shell startup file. Alternatively, you can also simply use\n```\n. sudoxe\n```\nbut the latter has the disadvantage that your shell will die if sudoxe\ncannot be found.\n\nThe above code will define the shell functions `sudox()` and `sudoxe()`\n(`sudox()` calls sudox with a secure `PATH` setting). Alternatively, add these\nfunctions or modifications thereof directly to your shell startup file.\n\nTo obtain support for zsh completion, you can copy `zsh/*` to a directory\nof zsh's `$fpath`.\n\nYou need `push.sh` from https://github.com/vaeth/push (v2.0 or newer)\nin your `$PATH` as well.\n\nFor wayfire support, copy also\n```\nusr/share/wayland-sessions/wayfire-auth.desktop\n```\nto the wayland session directory of the display-manager\n(presumably `/usr/share/wayland-sessions`), see the next section.\n\nFor Gentoo, there is an ebuild in the mv overlay (available by layman).\n\n\n## Xwayland\n\nIn order for sudox to take effect on `Xwayland`, `Xwayland` must be run with\nthe options\n```\nXwayland $DISPLAY -auth $XAUTHORITY ...\n```\n(and the `$XAUTHORITY` file must have been created).\nDepending on the compositor and how it is initialized, this might not be true,\nautomatically.\n\nIn particular, for wlroots based compositors like sway or wayfire, this is\nusually not the case.\n\nA workaround for wayfire (and similarly for other wlroots based compositors)\nmay be to use the provided `wayfire-auth.desktop`. This works as follows:\n\nInstead of directly calling `wayfire`, this file calls `wayfire-auth`\nwhich is a script ending with\n```\nWLR_XWAYLAND=`command -v xwayland.auth`\nexport WLR_XWAYLAND\nexec wayfire \"$@\"\n```\nThe variable `WLR_XWAYLAND` means for wlroot that `xwayland.auth` is used\ninstead of `Xwayland`. And `xwayland.auth` in turn is a wrapper for `Xwayland`\nwhich fills `$HOME/.Xauthority` as a new `$XAUTHORITY` file and calls\n`Xwayland` in the way described above.\n\n\n## Security notes\n\nX cookies should be kept secret, because every user who knows them can access\nthe running X session. The main purpose of __sudox__ is to pass such X cookies\nto the freshly started __sudo__ process.\nBelow are described all 4 methods (and a method avoiding X cookie passing)\nwhich can be used by __sudox__ for this.\nEach of these methods has certain restrictions or security implications;\ntherefore you can choose by options.\nThe environment variable `SUDOX_OPT` can be used to set options which\npreselect some of these methods.\nSince __sudox-8.0.0__, the most secure option is the default; therefore,\n`SUDOX_OPT` should only be set if no other option can be used.\n`SUDOX_OPT` thus is a potential security issue and it will perhaps be\nignored in some future relase of __sudox__, so try to not rely on it.\n\n### 1. Best method: \"Environment variable\" method\n\nSince __sudox-8.0.0__, this method is the default with variable name `DISPLAY`.\nThis method requires that `sudo` is configured to keep the variable (`DISPLAY`)\nin the environment (see the comments in the provided `sudoers.d`).\nTo specify a different variable name, use the sudox option `-vVAR`\nIf the __sudo__ configuration cannot be modified and is not known and the\ndefault `DISPLAY` does not work, try one of the following values for `VAR`\nfirst:\n\n- `COLORS`\n- `HOSTNAME`\n- `LS_COLORS`\n- `PS1`\n- `PS2`\n- `XAUTHORITY`\n- `XAUTHORIZATION`\n\nLess optimal (though perhaps working) are __sudo__ checked variables like\nthese:\n\n- `COLORTERM`\n- `LANG`\n- `LANGUAGE`\n- `LC_*`\n- `LINGUAS`\n- `TERM`\n- `TZ`\n\nEvery name matching the regular expression `^[A-Z_a-z][A-Za-z0-9_]*`\ncan be used;\nexcluded are only those names which match `^sx_[a-z]` or which influence shell\nexecution like\n\n- `PATH`\n- `IFS`\n- `BASH_ENV`\n- `ENV`\n- `SHELL_OPTS`\n\nThe variable will only be used temporarily by __sudox__ for the transfer; the\noriginal content will be restored after this temporary usage (__sudox__ will\neven unset the variable if it was not in the original environment).\n\n__Security Implication__: Do not use this method if your system is such that\nthe (initial) process environment can be read by other users (on linux, check\ne.g. that `/proc/*/environment` is only user readable).\nOtherwise, your X cookies are leaked this way!\n\n### 2. Second best method: File descriptors\n\nIf the method above is not possible (e.g. because __sudo__ is configured to not\npass _any_ variable and you cannot change the configuration), __sudox__ can use\nan open file descriptor to pass X cookies. This method is secure, but only\nsuboptimal, because `sudox` still needs to keep a process running to fill\nthe descriptor and cannot terminate until the `sudo` program returns:\nThe `sudo` process becomes a child of the `sudox` process (with possible\nsecurity implications about sending signals to an unprivileged process).\nUse the `sudox` option `-F#` or `-F#,#a` to use this method with file\ndescriptor `#` as channel for X cookie passing and an auxiliary file\ndescriptor `#a`.\nAs `#` you can either use some unused descriptor (at least `3`) or the\nstandard input `0`. Depending on your shell, `#` and `#a` must be at most `9`.\n\n- If `#` is at least `3` then __sudo__ must be configured to not close this\n  file descriptor, e.g. by allowing `closefrom_override`\n  (see the provided `sudoers.d`) and passing a corresponding `-C` option.\n  To use this mode, also `#a` is needed which should be at least `3` and\n  not be used for another purpose (but which can be closed by `sudo`).\n  If `#a` is not specified or empty, then (`#` + 1) is chosen.\n  A typical example usage of this option is `-F3` (which is the same as\n  `-F3,4`).\n\n  Unless you configured __sudo__ to use `closefrom=4` (or higher), you have to\n  combine this example with the option `-C4` (which works only if sudo is\n  configured to allow `closefrom_override`):\n\n  `sudox -F3 -C4 user command`\n\n- If `#` is `0` then no special __sudo__ configuration is needed. However, the\n  executed command will have its standard input (`0`) closed. If you specify\n  `#a` as `0` then the `cat` command will be used to pipe standard input to the\n  standard input of the executed command, but the latter will break most\n  interactive programs and also has security implication (`cat` runs as the\n  calling user). Therefore, it is recommended to use `-F0` only with programs\n  which do not expect standard input. In this case, it is recommended to\n  combine this with `-T`.\n  To first transfer X cookies and then to call an interactive program you can\n  instead call sudox twice:\n\n  `sudox -TF0 user true \u0026\u0026 sudox -X user [command ...]`\n\n### 3. Not very secure method: FIFO\n\nIf none of the above methods can be used (e.g. because __sudo__ cannot be\nconfigured and does not pass any variable or file descriptor) and you\ndo not want to use the file descriptor `0` workaround by calling __sudox__\ntwice, __sudox__ can use a FIFO in a randomly generated temporary directory\n(whose name is transferred over a command line) to transfer X cookies.\nSince the FIFO has to be world readable, this method is insecure, because\nan attacker can read the X cookies from this FIFO until the freshly started\n`sudo` process reads it. Although __sudox__ will recognize this and stop\nwith an error about a Troyan, the attacker might misuse the X cookies already\nand hide the display of this information.\nHowever, the timeframe for the attacker to read the FIFO is only from the\ncall of `sudox` until the freshly started `sudo` process reads it.\n\nAnother disadvantage of the method is the same as that of 2:\n__sudox__ needs to keep a process running to fill the FIFO and cannot terminate\nuntil the `sudo` program returns: The `sudo` process bcomes a child of `sudox`.\nTo select this method with `sudox`, use the option `-F-` (which is the same\noption as for 2. but with `#` being `-`).\n\n### 4. Insecure method: Command line\n\nAs a final fallback, the X cookies can be passed by the command line.\nOn most systems, the command line of a process can be accessed by every user,\nso this is usually an insecure way of passing X cookies.\nTo select this method with sudox, use the option `-v-` (which is the same\noption as for the \"Environment Variable\" method but with the special\nvariable name `-`) (and do not use the `-F` option).\n\n### root mode alternative\n\nIf the destination user has the permission to access the calling user's\n`XAUTHORITY` file (default: `~/.Xauthority`), then `XAUTHORITY` can be set\nto that file. This has the implication that also all modifications of\npermissions go to that file. In particular, this method cannot be used\nto generate untrusted permissions for the destination user.\nThis method is used by `sudox` automatically if the destination user is root\nand no untrusted permissions are requested. To override this default, use\nthe options `-R` (to force root mode) or `-N` (to force non-root mode).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaeth%2Fsudox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaeth%2Fsudox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaeth%2Fsudox/lists"}