{"id":25344569,"url":"https://github.com/bitmeal/cap-grant-ld","last_synced_at":"2025-04-08T15:20:28.772Z","repository":{"id":184005031,"uuid":"671154079","full_name":"bitmeal/cap-grant-ld","owner":"bitmeal","description":"run executables with capabilities, while using shared libraries from locations in $LD_LIBRARY_PATH, as non-root user","archived":false,"fork":false,"pushed_at":"2023-09-21T10:52:45.000Z","size":18,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-14T11:43:03.869Z","etag":null,"topics":["capabilities","dynamic-linking","ld-library-path","libcap-ng","linux-capabilities","ros","ros2","setcap"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitmeal.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":"2023-07-26T16:58:16.000Z","updated_at":"2024-03-11T07:25:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"2d84d427-5313-4769-9d11-b1207bed575b","html_url":"https://github.com/bitmeal/cap-grant-ld","commit_stats":null,"previous_names":["bitmeal/cap-grant-ld"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitmeal%2Fcap-grant-ld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitmeal%2Fcap-grant-ld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitmeal%2Fcap-grant-ld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitmeal%2Fcap-grant-ld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitmeal","download_url":"https://codeload.github.com/bitmeal/cap-grant-ld/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247867362,"owners_count":21009240,"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":["capabilities","dynamic-linking","ld-library-path","libcap-ng","linux-capabilities","ros","ros2","setcap"],"created_at":"2025-02-14T11:36:29.599Z","updated_at":"2025-04-08T15:20:28.765Z","avatar_url":"https://github.com/bitmeal.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cap grant LD\n\u003e *🚨 security risk incoming!*\n\n\nRun executables with ***capabilities***, while using ***shared libraries*** from locations in ***`$LD_LIBRARY_PATH`***, as ***non-root*** user!\n\n* [intro](#intro)\n* [what it does](#what-it-does)\n* [usage](#usage)\n* [building](#building)\n* [use with ROS2](#use-with-ros2)\n    * [ROS2 usage](#ros2-usage)\n    * [ROS2 building](#ros2-building)\n    * [ROS2 library](#ros2-library)\n\n\n\n## intro\nWorking on embedded devices, with special hardware or on realtime systems, at times requires additional capabilities for a process to fulfill its task. Either while developing, or when using frameworks with their default install location not in system directories (looking at you *ROS*!), dynamic loading of libraries in `$LD_LIBRARY_PATH` is a frequent requirement (or at least convenient).\n\nSetting capabilities on executables is straightforward, with one pitfall: When capabilites are set on an executable, `$LD_LIBRARY_PATH` is removed from the processes environment for security reasons; keep in mind these are good reasons! The solutions for overcoming this, as hard baking library paths, installing libraries to system locations, or running applications as root, may be a higher risk or just less desirable than the calculated risk of injection of malicious shared libraries with known capabilities and privileges. Enter *cap grant LD*!\n\n## what it does\nBy not setting capabilities on the target executable directly, we can inject `$LD_LIBRARY_PATH` - without it being removed - into the processes environment, while granting capabilities at runtime:\n\n1. *cap grant LD* clones all permissions from its *PERMITTED* or *EFFECTIVE* set as `eip` to the ambient set of the callee process\n2. injects `$LD_LIBRARY_PATH` from it's parents (!) initial (!) environment to the callee process\n\n**Important:** Make sure the parent process of `cap_grant_ld` has `$LD_LIBRARY_PATH` in its initial environment, readable using *procps* (in *procfs*, `/proc/\u003cppid\u003e/environ`)!\n\n\n## usage\n1. set capabilities to give to process on `cap_grant_ld` executable\n2. run `cap_grant_ld \u003cexecutable\u003e [\u003carguments\u003e [...]]`\n\nOptions\n* `-v` don't be silent; tell what's happening\n* `-p` clone permitted capabilities to ambient set *(default)*\n* `-e` clone effective capabilities to ambient set\n* `-l` disable `$LD_LIBRARY_PATH` injection\n\n```bash\n# EXAMPLE capsh\n\n$ ./cap_grant_ld -v capsh --has-p=cap_net_raw\ncloning PERMITTED caps:\ninjecting environment from [\u003cppid\u003e]:\n- LD_LIBRARY_PATH=/some/path\nexecuting: capsh --has-p=cap_net_raw\ncap[cap_net_raw] not permitted\n\n\n# with caps\n$ sudo setcap cap_net_raw,cap_net_admin,cap_sys_nice+ep ./cap_grant_ld\n$ ./cap_grant_ld -v capsh --has-p=cap_net_raw\ncloning PERMITTED caps:\n- [12] net_admin\n- [13] net_raw\n- [23] sys_nice\ninjecting environment from [\u003cppid\u003e]:\n- LD_LIBRARY_PATH=/some/path\nexecuting: capsh --has-p=cap_net_raw\n# empty stdout indicates success of capsh --has-p\n```\n\n## building\nrequirement:\n* `libcap-ng-dev`\n* `libprocps-dev`\n\n```bash\n# \"raw\"\ngcc cap_grant_ld.c -lcap-ng -lprocps -o cap_grant_ld\n\n# make\nmake install\n\n# cmake\ncmake -B build .\ncmake --build build --target install\n```\n\n## use with ROS2\n### ROS2 usage\nset permissions on the executable, find its path using:\n```bash\n$ readlink -f `ros2 pkg prefix cap_grant_ld`/lib/cap_grant_ld/cap_grant_ld\n```\n\nuse as:\n* `prefix='ros2 run cap_grant_ld cap_grant_ld'` with ROS2 **launchfiles**\n* `ros2 run cap_grant_ld cap_grant_ld`\n* *standalone* from install path\n\n### ROS2 building\nThe `CMakeLists.txt` detects if it is used within a ROS2 colcon/ament workspace and builds for ROS2 automatically. The workspace has to be configured correctl, i.e. its `setup.bash` has to be sourced prior!\n\n### ROS2 library\nThe package exports a static library and CMake target. These allow you to easily provide a copy of *cap_grant_ld*  with custom name, in your package, to set the required capabilities for your application onyl. Neat, is it?\n\nFind an example including a post-install script to set permissions in `ros2_lib_demo/cap_alias`.\n\n```xml\n\u003c!-- package.xml /--\u003e\n\n\u003cbuild_depend\u003ecap-grant-ld\u003c/build_depend\u003e\n```\n```cmake\n# CMakeLists.txt\n\nadd_executable(${PROJECT_NAME}_grant /dev/null)\ntarget_link_libraries(${PROJECT_NAME}_grant cap_grant_ld::libcap_grant_ld)\nset_target_properties(${PROJECT_NAME}_grant PROPERTIES LINKER_LANGUAGE C)\n```\nThe library `cap_grant_ld::libcap_grant_ld` includes all functionality (including `main()`) and link rules to `cap-ng` and `procps`. `add_executable()` needs at least one source file for an executable target. Using `/dev/null` as source does not allow CMake to deduce the language type, thus we have to set it manually.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitmeal%2Fcap-grant-ld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitmeal%2Fcap-grant-ld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitmeal%2Fcap-grant-ld/lists"}