{"id":21531921,"url":"https://github.com/matrixai/privilege-elevation","last_synced_at":"2025-03-17T19:27:55.922Z","repository":{"id":151338798,"uuid":"72765527","full_name":"MatrixAI/Privilege-Elevation","owner":"MatrixAI","description":"Demo of using Polkit for Privilege Elevation using File Descriptor Passing over Unix Domain Sockets","archived":false,"fork":false,"pushed_at":"2017-07-18T13:14:09.000Z","size":102,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-24T06:29:45.634Z","etag":null,"topics":["file-descriptor","nix","pkexec","polkit","privilege-elevation","serial-ports","unix-domain-socket"],"latest_commit_sha":null,"homepage":"https://matrix.ai","language":"C","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/MatrixAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2016-11-03T16:37:00.000Z","updated_at":"2017-05-31T07:57:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"3a0cb998-2b95-4dae-b1f4-7c2e2ea6f341","html_url":"https://github.com/MatrixAI/Privilege-Elevation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2FPrivilege-Elevation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2FPrivilege-Elevation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2FPrivilege-Elevation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2FPrivilege-Elevation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixAI","download_url":"https://codeload.github.com/MatrixAI/Privilege-Elevation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244095980,"owners_count":20397318,"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":["file-descriptor","nix","pkexec","polkit","privilege-elevation","serial-ports","unix-domain-socket"],"created_at":"2024-11-24T02:18:11.675Z","updated_at":"2025-03-17T19:27:55.914Z","avatar_url":"https://github.com/MatrixAI.png","language":"C","readme":"Privilege-Elevation\n===================\n\nExecuting `privilege-elevation` should demonstrate privilege elevation in terms of opening of a serial port. This is to achieve least-privilege when it comes to accessing rs232 peripherals like Arduino devices.\n\nYou pass in serial port path, it will first try to open it using an unprivileged child process, if it fails, it will make use of the Polkit infrastructure and `pkexec` the child process to open it. If the appropriate action file is installed, Polkit will prompt the user to authorise this opening the serial port action. If this succeeds, the file descriptor to the serial port is passed back to the parent process using a unix domain socket. The child process is kept simple and terminates immediately, the superuser privileges only exist temporally for this action and is not kept around. This child process opening code is intentionally kept small. This reduces the surface area of any potential compromise unlike setuid binaries, allowing easier auditing of privileged code.\n\nThis is different from normal Polkit programs who have a long running daemon.\nAs that would mean the daemon is the one that is already authorised with superuser\nprivileges, and a client program attempts a task by asking the daemon. The daemon\nuses Polkit to check whether the client is allowed, and if allowed performs the task. Using a daemon would be more suitable for long running tasks that require repeated authorised actions, but for single one-off actions, this achieves least-privilege better.\n\nAlthough this is bound to Linux Polkit, the same principle exists on Windows with UAC.\n\nUsage\n-----\n\nYou need `socat` to create virtual serial ports, `picocom` to act as terminals to the serial ports, `polkit` as the daemon to manage privilege elevation, and a `polkit` agent running in your desktop environment to provide GUI prompt for user authorisation. If you cannot run a GUI `polkit` agent, you can use `pkttyagent --process $$` but then make sure the PID passed into the `--process` option is the PID of the terminal process where you'll run `privilege-elevation`. Also `sudo` is required to make the virtual serial ports owned by `root` which forces elevated open.\n\nOpen 3 terminals. On the first one run (this will tell you the path to serial ports):\n\n```sh\nsudo socat -d -d pty,raw,echo=0 pty,raw,echo=0\n```\n\nOn the second terminal, run:\n\n```sh\nsudo picocom --baud 9600 --echo \u003cpath/to/serial/port1\u003e\n``` \n\nOn the third terminal, run:\n\n```sh\nprivilege-elevation --baud=9600 \u003c/path/to/serial/port2\u003e\n```\n\nAlso use: \n\n```sh\npkaction --action-id ai.matrix.pkexec.privilege-elevation.open-serial-device\n```\n\nThis will check whether `pkexec` can find the appropriate action policy file. It will still work even without the action file being installed, but you won't get a nice polkit prompt message.\n\nInstallation\n-------------\n\n### If on Nix:\n\nDownload the release tarball or `git clone`:\n\n```sh\ncd ./Privilege-Elevation\nnix-build\n./result/bin/Privilege-Elevation/privilege-elevation\n```\n\nThe above will build into the NixOS store and leave a symlink to access the built folder.\n\nTo actually install it into your profile (so you can call it from PATH):\n\n```sh\nnix-env --file ./Privilege-Elevation --install privilege-elevation\n```\n\nTo uninstall it:\n\n```sh\nnix-env --uninstall privilege-elevation\n```\n\nNote that installing it using `nix-env` will not make use of the polkit policy file, because this would be a security vulnerability (however, it will still work). To make use of the polkit policy file, you would need to install it as part of your system packages in your `configuration.nix`. For more information see: https://github.com/MatrixAI/Privilege-Elevation/issues/2\n\n### Not on Nix:\n\nDownload the release tarball:\n\n```sh\ntax xvfz ./privilege-elevation-X.X.X.tar.gz\ncd privilege-elevation-X.X.X\n./configure\nmake\nmake install\n```\n\nGit clone:\n\n```sh\ngit clone https://github.com/MatrixAI/Privilege-Elevation.git \ncd Privilege-Elevation\n./bootstrap\n./configure\nmake\nmake install\n```\n\nTo uninstall it:\n\n```sh\nmake uninstall\n```\n\nDevelopment\n------------\n\nOn Nix supported system, first setup the Nix shell by running `nix-shell` inside the root of this repository. Still trying to make `nix-shell` run `./bootstrap` and `./configure` prior to launching.\n\nRun these at the root of the project:\n\n```sh\n./bootstrap\n./configure\nmake distcheck\nmake dist\n```\n\nTo check if Nix building works:\n\n```sh\nmake clean\nnix-build\n```\n\nIf you don't clean the root, `nix-build` won't compile again, and this may result in incorrect environment variables or macros being used. Repeated invocations of `nix-build` will replace the old `./result` symlink, however the store path will still exist and will need to be manually deleted with `nix-store --delete` or through garbage collection.\n\nThere's an issue with setuid binaries inside `nix-shell`, so we have to exit the `nix-shell` to properly execute `pkexec`. This also means `polkit` is not a build input to he `shell.nix`, even though it is to the `default.nix`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fprivilege-elevation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixai%2Fprivilege-elevation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fprivilege-elevation/lists"}