{"id":19269689,"url":"https://github.com/pymumu/jail-shell","last_synced_at":"2025-04-21T20:33:13.460Z","repository":{"id":61812839,"uuid":"100507193","full_name":"pymumu/jail-shell","owner":"pymumu","description":"Jail-shell is a linux security tool mainly using chroot, namespaces technologies, limiting users to perform specific commands, and access sepcific directories. ","archived":true,"fork":false,"pushed_at":"2022-12-08T14:44:25.000Z","size":369,"stargazers_count":121,"open_issues_count":18,"forks_count":21,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-15T21:14:34.825Z","etag":null,"topics":["chroot","jail","linux","linux-namespaces","security","security-hardening","shell","ssh"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pymumu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-16T15:57:45.000Z","updated_at":"2025-03-05T06:24:41.000Z","dependencies_parsed_at":"2023-01-25T14:00:41.046Z","dependency_job_id":null,"html_url":"https://github.com/pymumu/jail-shell","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/pymumu%2Fjail-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pymumu%2Fjail-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pymumu%2Fjail-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pymumu%2Fjail-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pymumu","download_url":"https://codeload.github.com/pymumu/jail-shell/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250128437,"owners_count":21379510,"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":["chroot","jail","linux","linux-namespaces","security","security-hardening","shell","ssh"],"created_at":"2024-11-09T20:21:14.380Z","updated_at":"2025-04-21T20:33:13.171Z","avatar_url":"https://github.com/pymumu.png","language":"C","funding_links":["https://paypal.me/PengNick/"],"categories":[],"sub_categories":[],"readme":"Jail-Shell\n==============\n[![Build Status](https://travis-ci.org/pymumu/jail-shell.svg?branch=master)](https://travis-ci.org/pymumu/jail-shell)  \n\n[中文REAMDME请看这里](README_zh-CN.md)\n\nJail-shell is a Linux security tool mainly using chroot, namespaces technologies, limiting users to perform specific commands, and access specific directories.  \n\nUsers can login through SSH, SCP, SFTP, Telnet, terminals, etc. and be restricted to a secure operating enviroment.  \n\nJail-shell can be used for webhost ssh access control, enterprise Administrator's privilege hierarchy management.  \n\nFeatures\n==============\n- **Easy to use**\n\nThrough the configuration file jail-shell automatically generates the chroot running environment. Through jail-shell management commands it's very easy to add, list, delete, restrict users, and easy to install, delete chroot running environment. \n\n- **Chroot technology limits user access**\n\nThe Linux chroot technology is used to restrict the user's directory access, to avoid users accessing restricted directories and to prevent users from destroying the system.\n\n- **Directory read-only protection**\n\nThe chroot running enviroment is readonly, this prevents users from deleting protected directories and files, creating device files, and accessing restricted files.\n\n- **Namespace limit user Visible range**\n\nUse Linux namespace technology, limit the visible range of user PID, Mount directories, and avoid information leakage.\n\n- **System command channel**\n\nProvides a system command-and-proxy channel that allows users to execute a real system's restricted command in a chroot environment, protecting the system in the event that it provides the necessary functionality. \n\n- **Automatic processing of chroot Environment command library dependencies**\n\nOnly a list of commands is required to automatically copy the dynamic library that the command relies on to the chroot environment, avoiding the cumbersome work of copying the dynamic library manually.\n\n- **Capabilities Restrictions**\n\nDiscard critical capabilities privileges to avoid the system, and the chroot running environment, being cracked by rootkit.\n\n- **Multi-Linux operating system support**\n\nSupports Redhat, SLEs, Debian and their derivative operating systems.\n\nArchitecture\n==============\n![Architecture](docs/Architecture.png)\nJail-shell contains 3 parts, Pam Plugins, jail-cmd command agents, Jail-shell command tools.\n\n- **pam_jail_shell Plugins**\n\nMainly control the login of users. according to the configuration list, use chroot and namespace technology to restrict the login users to a specific restricted directory.\n\n- **jail-cmd command-and-proxy**\n\nIt forwards specific command to the real system, such as `passwd`, or other user-related business commands, and it also prevents command injection.\n\n- **jail-shell commandline tool**\n\nMainly provides the ability to manage the restricted security shell, making it easier for administrators to use, including user's add, delete, shell's configuration, installation, deletion, etc.\n\n**Instructions**\n1. According to the configuration, pam_jail_shell limits users to the specified chroot enviroment.\n2. Administrators use jail-shell command to manage the list of restricted users, manage the list of commands for the chroot enviroment, and manage the access range of directories.\n3. Jail-cmd proxies specific command, to help implement the necessary business functions.\n\n\nCompile and install \n==============\n**Compile**\n```\ngit clone https://github.com/pymumu/jail-shell.git\ncd jail-shell\nmake \n```\n\n**Install**\n```\nsudo make install\n```\n\n**Uninstall**\n```\nsudo /usr/local/jail-shell/install -u\n```\n\nUsage\n==============\nAfter installation, you can use `jail-shell` command to manage jails, `jail-shell -h` for help.  \nIn use, the steps are as follows:  \n1. Use `useradd username` command to add user to the system.\n2. Use `jail-shell jail` command to create a chroot enviroment.\n3. Use `jail-shell user` command to add user to the jails.\n\n\nExample\n-------------\nThe following is an example of adding  user `test`  to a jail named `test-jail`.  \n1. add user `test`，and set password\n```shell\nsudo useradd test -s /bin/bash\nsudo passwd test\n```\n\n2. create chroot enviroment\n```shell\nsudo jail-shell jail -e test-jail\n```\nAfter executing the above command, a new jail configuration will be created from the template, and it is opened by `vi`, you can edit it, after that, remember to save the configuration with vi command `:w!`.\n\n3. install chroot enviroment\n```shell\nsudo jail-shell jail -i test-jail\n```\n\n4. add user `test` to jail `test-jail`\n```shell\nsudo jail-shell user -a test -j test-jail\n```\n\n5. connect and test whether `test` is jailed.\n```shell\nssh test@127.0.0.1\n```\n![Example](https://github.com/pymumu/backup/raw/master/image/example.gif)\n\nJail Config file format description\n-------------\nThe jail config file is located at `/etc/jail-shell/jail-config/`, and file suffix is `.cfg`    \nThe configuration supports the following commands: \n- **dir**\n  * DESC:  \ncreate a directory into jail\n  * COMMAND:  \n`dir PATH MODE OWNER`\n  * EXAMPLE:  \n`dir /bin/ 0755 root:root`\n\n- **file:**\n  * DESC:  \ncopy a file into jail\n  * COMMAND:  \n`file SRC DEST MODE OWNER`\n  * EXAMPLE:  \n`file /etc/nsswitch.conf /etc/nsswitch.conf 0644 root:root`\n\n- **hlink:**\n  * DESC:  \ncreate a hardlink file into jail\n  * COMMAND:  \n`file SRC DEST MODE OWNER`\n  * EXAMPLE:   \n`file /etc/nsswitch.conf /etc/nsswitch.conf 0644 root:root`\n\n- **slink:**\n  * DESC:  \ncreate a symbolic link into jail\n  * COMMAND:   \n`slink TARGET LINKNAME`\n  * EXAMPLE:   \n`slink /bin/bash /bin/sh`\n\n- **clink:**\n  * DESC:  \nTry to create hardlinks instead of copying the files. If linking fails it falls back to copying\n  * COMMAND:   \n`clink TARGET LINKNAME`\n  * EXAMPLE:   \n`clink /etc/localtime /etc/localtime`\n\n- **node:**\n  * DESC:  \ncreate device file.\n  * COMMAND:   \n`node PATH TYPE MAJON MINOR MODE OWNER`\n  * EXAMPLE:  \n`node /dev/null c 1 3 666 root:root`\n  * NOTE: security tips  \n           should avoid adding block device files. \n \n- **bind:**\n  * DESC:  \nbind a directory to jail\n  * COMMAND:  \n`bind [SRC] DEST OPTION`  \n  * OPTION: rw,ro,dev,nodev,exec,noexec, refer to (man mount) for the parameter description   \n%u in path '[SRC] DEST' will be replaced as user name  \n  * EXAMPLE:  \n`bind / ro,nodev,nosuid`  \n`bind /opt/ /opt/ ro,nodev,noexec`  \n`bind /opt/upload /opt/upload rw,nodev,noexec,nosuid`  \n`bind /opt/%u /opt/upload ro,nodev,noexec,nosuid`  \n\n- **cmd:**\n  * DESC:  \nexecutes commands within the system which outside jail.\n  * COMMAND:   \n`cmd SRC DEST RUN_AS_USER` \n  * RUN_AS_USER: User who executes system commands, -:- means user in jail  \n  * EXAMPLE:  \n           `cmd /usr/bin/passwd /usr/bin/passwd -:- `  \n           `cmd /some/root/command /some/root/command root:root`  \n           `cmd /some/user/command /some/user/command user:user `  \n  * NOTE: security tips\n           This channel may lead users to escape jail, should avoid adding command which can be shell-inject,  \n           For example, read the commands entered by the user  \n\nSecurity Tips\n==============\nWhen using jail-shell, the minimum security authorization principle should be adopted. In the premise of ensuring the use of functions, reduce user rights.\n1. `bind` tips\n  * Except `/dev` directory, it is recommended to add `nodev` parameters, /dev directory must set to `ro, noexec` (read-only, disable executable) permissions.\n  * For the chroot environment directory, it is recommended to set `ro, nodev, nosuid` (read only, prohibit device files, and prohibit suid files) permissions. \n  * For writable bind directories, it is recommended to set `nodev, noexec, nosuid` (disable device files, disable executable files, disable suid files) permissions. \n\n2. avoid commands\n  * avoid: debug commands such as `gdb, mount, strace`, etc.. \n\n\nFile Directory Description\n==============\n| directory                           |description                                                      |\n|-------------------------------------|-----------------------------------------------------------------|\n| `/etc/jail-shell/`                  | Configure file Directory                                        |\n| `/etc/jail-shell/jail-shell. conf`  | Restricted User Configuration list file                         |\n| `/etc/jail-shell/jail-config/`      | The directory where the jail shell configuration file is located, and the suffix. cfg file is recognized as a jail configuration file. |\n| `/var/local/jail-shell/`            | Jail-shell Data Directory |\n| `/var/local/jail-shell/jails`       | Jail-shell chroot Environment Directory |\n| `/usr/local/jail-shell`             | Jail-shell program Directory |\n\nDebugging the chroot environment\n==============\nWhen you copy a command to the chroot environment, if the copy command fails, you need to debug to find the missing dependent files, and add them to the chroot environment.  \nCopy the `strace` command into the chroot environment, and then use `strace` to execute the commands that need to be debugged to find the missing dependent files.   \nThe following debugging commands are as follows \n```shell \nstrace -F -eopen command\n```\n-eopen represents a list of files that the trace process opens.  \nAfter executing the above command, troubleshoot to find the open file list.\n```shell\nopen (\"/etc/ld.so.preload\", \"O_RDONLY\") = -1 ENOENT (No, such, file, or, directory)\n```\nAs indicated above, the `/etc/ld-so.preload` file does not exist when reading, and may need to add the above files to the chroot environment. At this point, you can use the `clink`, `file` command to add missing files to the chroot environment. \n\nLicense\n==============\nJail-shell using GPL-V2 License.\n\nDonate\n==============\n[![Support via PayPal](https://cdn.rawgit.com/twolfson/paypal-github-button/1.0.0/dist/button.svg)](https://paypal.me/PengNick/)\n\nSimilar tools\n==============\n[jailkit https://olivier.sessink.nl/jailkit/](https://olivier.sessink.nl/jailkit/)  \n[rshell https://en.wikipedia.org/wiki/Restricted_shell](https://en.wikipedia.org/wiki/Restricted_shell)  \n[firejail https://github.com/netblue30/firejail](https://github.com/netblue30/firejail)   \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpymumu%2Fjail-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpymumu%2Fjail-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpymumu%2Fjail-shell/lists"}