{"id":13508426,"url":"https://github.com/vi/dive","last_synced_at":"2025-04-15T11:32:51.179Z","repository":{"id":3331191,"uuid":"4374890","full_name":"vi/dive","owner":"vi","description":"Start programs inside unshare/lxc namespaces easily using UNIX sockets + easy access to capabilities, namespaces, chroot and others.","archived":false,"fork":false,"pushed_at":"2023-03-27T14:25:17.000Z","size":273,"stargazers_count":57,"open_issues_count":1,"forks_count":8,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-28T21:02:48.739Z","etag":null,"topics":["capabilities","chroot","linux","namespaces","prctl","security","setns"],"latest_commit_sha":null,"homepage":"","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/vi.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":"2012-05-19T01:03:20.000Z","updated_at":"2024-11-01T17:37:00.000Z","dependencies_parsed_at":"2024-10-16T13:10:57.607Z","dependency_job_id":null,"html_url":"https://github.com/vi/dive","commit_stats":{"total_commits":247,"total_committers":2,"mean_commits":123.5,"dds":0.004048582995951455,"last_synced_commit":"bcdc4ba113f8a0ec4326a0a7f116ae987e5f5a41"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vi%2Fdive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vi%2Fdive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vi%2Fdive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vi%2Fdive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vi","download_url":"https://codeload.github.com/vi/dive/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249061203,"owners_count":21206467,"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","chroot","linux","namespaces","prctl","security","setns"],"created_at":"2024-08-01T02:00:52.891Z","updated_at":"2025-04-15T11:32:50.908Z","avatar_url":"https://github.com/vi.png","language":"C","readme":"Start processes in other network/mount/whatever namespace, as created by `unshare` or `lxc-start` \n(as long as there is a shared filesytem between the host and container and you use recent enough Linux kernel). \nAlso allow users execute programs in other user account or in chroot in controlled way \n(like sudo, but without setuid-bit in filesystem).\n\nWorks by sending file descriptors over UNIX socket. \n\n\u003cstrong\u003eSee various usage examples and pre-built dive[d] versions at the [github page](https://vi.github.io/dive/).\u003c/strong\u003e\n    \n**Usage**\n\n```\n$ dived\nDive server v1.8.1 (proto 1100) https://github.com/vi/dive/\nListen UNIX socket and start programs for each connected client, redirecting fds to client.\nUsage: dived {socket_path|@abstract_address|-i|-J} [-p pidfile] [-u user] [-e effective_user] [-C mode] [-U user:group] [{-R directory | -V newroot putold}] [-r [-W]] [-s smth1,smth2,...] [-a \"program\"] [{-B cap_smth1,cap_smth2|-b cap_smth1,cap_smth2}] [-m cap_smth1,...] [-X] [-c 'cap_smth+eip cap_smth2+i'] [-N /proc/.../ns/net [-N ...]] [-l res_name1=hard1,4=0,res_name2=hard2:soft2,...] [-t filename content][various other argumentless options] [-- prepended commandline parts]\n          -d --detach           detach\n          -i --inetd            serve once, interpred stdin as client socket\n          -J --just-execute     don't mess with sockets at all, just execute the program.\n                                Other options does apply.\n          -j --just-execute2    Alias of -J -S -T -P\n          -D --children-daemon  call daemon(0,0) in children\n          -F --no-fork          no fork, serve once\n                                this is for debugging or for starting init process in PID unshare\n          -P --no-setuid        no setuid/setgid/etc\n          -u --user             setuid to this user instead of the client\n          -g --groups           setgid/setgroups to this comma-separated groups. The first one is primary.\n          -e --effective-user   seteuid to this user instead of the client\n          -B --retain-capabilities Remove all capabilities from bounding set\n                                   except of specified ones\n          -b --remove-capabilities Remove capabilities from bounding set\n          -m --ambient-capabilities Set these capabilities as ambient\n          -c --set-capabilities cap_set_proc the argument (like 'cap_smth+eip cap_smth2+i')\n          -X --no-new-privs     set PR_SET_NO_NEW_PRIVS\n          -L --lock-securebits  set and lock SECBIT_NO_SETUID_FIXUP and SECBIT_NOROOT\n          -a --authenticate     start this program for authentication\n              The program is started using \"system\" after file descriptors are received\n              from client, but before everything else (root, current dir, environment) is received.\n              Nonzero exit code =\u003e rejected client.\n          -l --rlimit           Set resource limits (comma-separated key=val list)\n                                  as,cpu,fsize,data,stack,core,locks,sigpending,msgqueue,nice,rtprio,rttime,nofile,nproc,memlock\n          -S --no-setsid        no setsid\n          -T --no-csctty        no ioctl TIOCSCTTY\n          -N --setns file       open this file and do setns(2); can be specified multiple times.\n          -R --chroot           chroot to this directory \n          -h --chdir            chdir to this directory (prior to chroot)\n              Note that current directory stays on unchrooted filesystem; use -W option to prevent.\n          -V --pivot-root       pivot_root to this directory, putting old root to the second argument\n          -r --client-chroot    Allow arbitrary chroot from client\n          -W --root-to-current  Set server's root directory as current directory\n                                (implies -H; useful with -r)\n          -s --unshare          Unshare specified namespaces (comma-separated list); also detaches\n                                ipc,net,fs,pid,uts,user,cgroup\n          -t  --write-content   write specified string to specified file after namespaces setup, \n                                (can be specified multiple times)\n          -tt --setup-uidgidmap Automatically write /proc/self/{uidmap,setgroup,gidmap}\n          -p --pidfile          save PID to this file; can be specified multiple times\n                                can also be used to append to cgroup's tasks. Happens early.\n          -C --chmod            chmod the socket to this mode (like '0777')\n          -U --chown            chown the socket to this user:group\n          -E --no-environment   Don't let client set environment variables\n          -A --no-argv          Don't let client set [part of] command line\n          -H --no-chdir         Don't let client set current directory\n          -O --no-fds           Don't let client set file descriptors\n          -M --no-umask         Don't let client set umask\n          -n --signals          Transfer all signals from dive\n             --signals-pgid     Transfer all signals from dive to the process group\n          -w --no-wait          Don't fork and wait for exit code\n          --                    prepend this to each command line ('--' is mandatory)\n              Note that the program being started using \"--\" with '-e' or '-u' or '-P' options should be\n              as secure as suid programs, unless additional options like -E, -M, -O, -H or -A are in use.\n\n\n$ dive\nUsage: dive socket_path [program arguments]\n```\n\n    \n**Features**\n    \n* Absence of any filesystem permission tricks (no \"chmod +s\" required)\n* Secure preserving of user id and groups (requires root access)\n* Preserving of current directory\n* Preserving of all file descriptors (not only stdin/stdout/stderr)\n* Setting session ID and controlling terminal, for clean bash without \"no job control\" (requires root access)\n* Preserving of environment variables\n* Preserving of exit code\n* Selective disabling of \"preserving\" parts above\n* Chroot / CLONE_NEW... / forced command line\n* Setting of DIVE_USER and other variables according to client credentials\n* Allowing clients to set it's own root directory (\"-r\" option)\n* Setting of PR_SET_NO_NEW_PRIVS to turn off filesystem-based permission elevations. If you want just this without the rest dive features, use this: https://gist.github.com/vi/f977cc3097d47b07c3ad\n* Setting Linux capabilities, including ambient.\n* \"Just execute\" feature to use capabilities, chroot, PR_SET_NO_NEW_PRIVS\n setup; \"authenticate\", pidfile and so on without any \"remote startup\" thought\n socket at all\n* Joining namespaces with setns(2)\n* Setting resource limits with setrlimit(2)\n\nFor less feature-creep version see \"nocreep\" branch\n\n\n**Notes**\n\n* For clean interactive shell access dived need to be started as root (for setsid/TIOCSCTTY)\n    * Without TIOCSCTTY, use `socat -,raw,echo=0 exec:bash,pty,setsid,stderr` (there's a hint in `dive`'s usage message) as the program to start to have nicer bash\n    * With TIOCSCTTY it steams controlling terminal from the previous process (leaving it \"homeless\"), so \"exec dive socket bash\" is preferred (or workaround with [reptyr](https://github.com/nelhage/reptyr) \u003e= v0.4 is needed).\n* Current directory can be \"smuggled\" into the chroot or unshare where that part of filesystem is not mounted (can be prevented using -W or -H options)\n* dived sets up groups for user, but it does not provide fully fledged PAM-like login. For example, resource limits are just inherited, not set up using `/etc/security/limits.conf`.\n \n\nFor pre-build versions of dive and dived see \"Releases\". Note that some of pre-built versions may lack features.\n\nProcess attributes\n---\nA table of what happens to various process attributes when process is started \n\"remotely\" over dive/dived compared to just `exec`ing directly.\n\"not preserved\" means \"like in dived\" or \"whatever\", \"preserved\" means \"like in dive\" \nor \"like if we executed the program directly\".\n\n\u003ctable\u003e\n  \u003ctr\u003e\u003cth\u003eAttribute\u003c/th\u003e\u003cth\u003eWhat happens\u003c/th\u003e\u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003ePID\u003c/td\u003e\u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003eparent PID\u003c/td\u003e\u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003efile descriptors\u003c/td\u003e\u003ctd\u003e preserved (unless -O) \u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003eresource limits\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003euid\u003c/td\u003e \u003ctd\u003epreserved if possible (unless -P or -u)\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003egroup list\u003c/td\u003e \u003ctd\u003einitialized by `initgroups` (unless -P or -u)\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003econtrolling terminal\u003c/td\u003e \u003ctd\u003ehopefully preserved (unless -T)\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003esession id/process group\u003c/td\u003e \u003ctd\u003enot preserved, new session leader (unless -S)\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003enamespaces memberships\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003ecgroup membership\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003ecoredump_filter\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003ecurrent working directory\u003c/td\u003e \u003ctd\u003epreserved (unless -H)\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003e/proc/.../exe\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003eoom_score_adj\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003eroot directory\u003c/td\u003e \u003ctd\u003enot preserved (unless -r)\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003enice value/priority\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003eCPU affinity\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003ecapabilities\u003c/td\u003e \u003ctd\u003enot preserved\u003c/td\u003e \u003c/tr\u003e\n  \u003ctr\u003e\u003ctd\u003eumask\u003c/td\u003e \u003ctd\u003epreserved (unless -M)\u003c/td\u003e \u003c/tr\u003e\n\u003c/table\u003e\n","funding_links":[],"categories":["C","security"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvi%2Fdive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvi%2Fdive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvi%2Fdive/lists"}