# lshell
lshell is a limited shell coded in Python, that lets you restrict a user's environment to limited sets of commands, choose to enable/disable any command over SSH (e.g. SCP, SFTP, rsync, etc.), log user's commands, implement timing restriction, and more.
## Installation
### Install via pip
To install `limited-shell` directly via `pip`, use the following command:
```bash
pip install limited-shell
```
This will install limited-shell from PyPI along with all its dependencies.
To uninstall, you can run:
```bash
pip uninstall limited-shell
```
### Build from source and install locally
If you'd like to build and install limited-shell from the source code (useful if you're making modifications or testing new features), you can follow these steps:
```
python3 -m pip install build --user
python3 -m build
pip install . --break-system-packages
```
### Uninstall lshell
To uninstall, you can run:
```bash
pip uninstall limited-shell
```
## Usage
### Via binary
To launch lshell, just execute lshell specifying the location of your configuration file:
```bash
lshell --config /path/to/configuration/file
```
### Using `lshell` in Scripts
You can use `lshell` directly within a script by specifying the lshell path in the shebang. Ensure your script has a `.lsh` extension to indicate it is for lshell, and make sure to include the shebang `#!/usr/bin/lshell` at the top of your script.
For example:
```bash
#!/usr/bin/lshell
echo "test"
```
## Configuration
### User shell configuration
In order to log a user, you will have to add them to the lshell group:
```bash
usermod -aG lshell username
```
In order to configure a user account to use lshell by default, you must:
```bash
chsh -s /usr/bin/lshell user_name
```
You might need to ensure that lshell is listed in /etc/shells.
### lshell.conf
#### Allowed list
lshell.conf presents a template configuration file. See `etc/lshell.conf` or the man file for more information.
You can allow commands specifying commands with exact arguments in the `allowed` list. This means you can define specific commands along with their arguments that are permitted. Commands without arguments can also be specified, allowing any arguments to be passed.
For example:
```
allowed: ['ls', 'echo asd', 'telnet localhost']
```
This will:
- Allow the `ls` command with any arguments.
- Allow `echo asd` but will reject `echo` with any other arguments (e.g., `echo qwe` will be rejected).
- Allow `telnet localhost`, but not `telnet` with other hosts (e.g., `telnet 192.168.0.1` will be rejected).
Commands that do not include arguments (e.g., `ls`) can be used with any arguments, while commands specified with arguments (e.g., `echo asd`) must be used exactly as specified.
#### User profiles
A [default] profile is available for all users using lshell. Nevertheless, you can create a [username] section or a [grp:groupname] section to customize users' preferences.
Order of priority when loading preferences is the following:
1. User configuration
2. Group configuration
3. Default configuration
The primary goal of lshell, is to be able to create shell accounts with ssh access and restrict their environment to a couple a needed commands and path.
#### Example
For example User 'foo' and user 'bar' both belong to the 'users' UNIX group:
- User 'foo':
- must be able to access /usr and /var but not /usr/local
- use all commands in their PATH except 'su'
- has a warning counter set to 5
- has their home path set to '/home/users'
- User 'bar':
- must be able to access /etc and /usr but not /usr/local
- is allowed default commands plus 'ping' minus 'ls'
- strictness is set to 1 (meaning he is not allowed to type an unknown command)
In this case, my configuration file will look something like this:
# CONFIGURATION START
[global]
logpath : /var/log/lshell/
loglevel : 2
[default]
allowed : ['ls','pwd']
forbidden : [';', '&', '|']
warning_counter : 2
timer : 0
path : ['/etc', '/usr']
env_path : ':/sbin:/usr/foo'
scp : 1 # or 0
sftp : 1 # or 0
overssh : ['rsync','ls']
aliases : {'ls':'ls --color=auto','ll':'ls -l'}
[grp:users]
warning_counter : 5
overssh : - ['ls']
[foo]
allowed : 'all' - ['su']
path : ['/var', '/usr'] - ['/usr/local']
home_path : '/home/users'
[bar]
allowed : + ['ping'] - ['ls']
path : - ['/usr/local']
strict : 1
scpforce : '/home/bar/uploads/'
# CONFIGURATION END
## More information
More information can be found in the manpage: `man -l man/lshell.1` or `man lshell`.
## Running Tests in Docker Containers
You can run the tests in parallel across multiple Linux distributions using Docker Compose. This is helpful for ensuring compatibility and consistency across environments. The following command will launch test services for Ubuntu, Debian, Fedora, and Alpine distributions simultaneously:
```bash
docker-compose up ubuntu_tests debian_tests fedora_tests alpine_tests
```
Each service will run in parallel and execute the `pytest`, `pylint`, and `flake8` tests specified in the docker-compose.yml.
## Contributions
To contribute, open an issue or send a pull request.
Please use github for all requests: https://github.com/ghantoos/lshell/issues
Raw data
{
"_id": null,
"home_page": "https://github.com/ghantoos/lshell",
"name": "limited-shell",
"maintainer": "Ignace Mouzannar",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "ghantoos@ghantoos.org",
"keywords": "limited, shell, security, python",
"author": "Ignace Mouzannar",
"author_email": "ghantoos@ghantoos.org",
"download_url": "https://files.pythonhosted.org/packages/4a/76/81e2055a2519c2d5567b3bf4eef2efd252ea9658eb450ab84801698ff461/limited_shell-0.10.10.tar.gz",
"platform": "UNIX",
"description": "\n\n\n\n\n# lshell\n\nlshell is a limited shell coded in Python, that lets you restrict a user's environment to limited sets of commands, choose to enable/disable any command over SSH (e.g. SCP, SFTP, rsync, etc.), log user's commands, implement timing restriction, and more.\n\n\n## Installation\n\n### Install via pip\n\nTo install `limited-shell` directly via `pip`, use the following command:\n\n```bash\npip install limited-shell\n```\n\nThis will install limited-shell from PyPI along with all its dependencies.\n\nTo uninstall, you can run:\n\n```bash\npip uninstall limited-shell\n```\n\n### Build from source and install locally\n\nIf you'd like to build and install limited-shell from the source code (useful if you're making modifications or testing new features), you can follow these steps:\n\n```\npython3 -m pip install build --user\npython3 -m build\npip install . --break-system-packages\n```\n\n### Uninstall lshell\n\nTo uninstall, you can run:\n\n```bash\npip uninstall limited-shell\n```\n\n## Usage\n### Via binary\nTo launch lshell, just execute lshell specifying the location of your configuration file:\n\n```bash\nlshell --config /path/to/configuration/file\n```\n\n### Using `lshell` in Scripts\n\nYou can use `lshell` directly within a script by specifying the lshell path in the shebang. Ensure your script has a `.lsh` extension to indicate it is for lshell, and make sure to include the shebang `#!/usr/bin/lshell` at the top of your script.\n\nFor example:\n\n```bash\n#!/usr/bin/lshell\necho \"test\"\n```\n\n\n## Configuration\n### User shell configuration\nIn order to log a user, you will have to add them to the lshell group:\n\n```bash\nusermod -aG lshell username\n```\n\nIn order to configure a user account to use lshell by default, you must: \n\n```bash\nchsh -s /usr/bin/lshell user_name\n```\n\nYou might need to ensure that lshell is listed in /etc/shells.\n\n### lshell.conf\n\n#### Allowed list\nlshell.conf presents a template configuration file. See `etc/lshell.conf` or the man file for more information.\n\nYou can allow commands specifying commands with exact arguments in the `allowed` list. This means you can define specific commands along with their arguments that are permitted. Commands without arguments can also be specified, allowing any arguments to be passed.\n\nFor example:\n```\nallowed: ['ls', 'echo asd', 'telnet localhost']\n```\n\nThis will:\n- Allow the `ls` command with any arguments.\n- Allow `echo asd` but will reject `echo` with any other arguments (e.g., `echo qwe` will be rejected).\n- Allow `telnet localhost`, but not `telnet` with other hosts (e.g., `telnet 192.168.0.1` will be rejected).\n\nCommands that do not include arguments (e.g., `ls`) can be used with any arguments, while commands specified with arguments (e.g., `echo asd`) must be used exactly as specified.\n\n#### User profiles\n\nA [default] profile is available for all users using lshell. Nevertheless, you can create a [username] section or a [grp:groupname] section to customize users' preferences.\n\nOrder of priority when loading preferences is the following:\n\n1. User configuration\n2. Group configuration\n3. Default configuration\n\nThe primary goal of lshell, is to be able to create shell accounts with ssh access and restrict their environment to a couple a needed commands and path.\n\n#### Example\n\nFor example User 'foo' and user 'bar' both belong to the 'users' UNIX group:\n\n- User 'foo': \n - must be able to access /usr and /var but not /usr/local\n - use all commands in their PATH except 'su'\n - has a warning counter set to 5\n - has their home path set to '/home/users'\n\n- User 'bar':\n - must be able to access /etc and /usr but not /usr/local\n - is allowed default commands plus 'ping' minus 'ls'\n - strictness is set to 1 (meaning he is not allowed to type an unknown command)\n\nIn this case, my configuration file will look something like this:\n\n # CONFIGURATION START\n [global]\n logpath : /var/log/lshell/\n loglevel : 2\n\n [default]\n allowed : ['ls','pwd']\n forbidden : [';', '&', '|'] \n warning_counter : 2\n timer : 0\n path : ['/etc', '/usr']\n env_path : ':/sbin:/usr/foo'\n scp : 1 # or 0\n sftp : 1 # or 0\n overssh : ['rsync','ls']\n aliases : {'ls':'ls --color=auto','ll':'ls -l'}\n\n [grp:users]\n warning_counter : 5\n overssh : - ['ls']\n\n [foo]\n allowed : 'all' - ['su']\n path : ['/var', '/usr'] - ['/usr/local']\n home_path : '/home/users'\n\n [bar]\n allowed : + ['ping'] - ['ls'] \n path : - ['/usr/local']\n strict : 1\n scpforce : '/home/bar/uploads/'\n # CONFIGURATION END\n\n## More information\n\nMore information can be found in the manpage: `man -l man/lshell.1` or `man lshell`.\n\n\n## Running Tests in Docker Containers\n\nYou can run the tests in parallel across multiple Linux distributions using Docker Compose. This is helpful for ensuring compatibility and consistency across environments. The following command will launch test services for Ubuntu, Debian, Fedora, and Alpine distributions simultaneously:\n\n```bash\ndocker-compose up ubuntu_tests debian_tests fedora_tests alpine_tests\n```\n\nEach service will run in parallel and execute the `pytest`, `pylint`, and `flake8` tests specified in the docker-compose.yml.\n\n## Contributions\n\nTo contribute, open an issue or send a pull request.\n\nPlease use github for all requests: https://github.com/ghantoos/lshell/issues\n",
"bugtrack_url": null,
"license": "GPL-3",
"summary": "lshell - Limited Shell",
"version": "0.10.10",
"project_urls": {
"Changelog": "https://github.com/ghantoos/lshell/blob/master/CHANGELOG.md",
"GitHub": "https://github.com/ghantoos/lshell",
"Homepage": "https://github.com/ghantoos/lshell"
},
"split_keywords": [
"limited",
" shell",
" security",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "564aee0cbc3c841849b6114dce3c3d532ea8d3f6584d422998d22886f82a9072",
"md5": "c07b098b155d1aa2b9ddc60f27d21f4f",
"sha256": "59124fb8e58a4896b64c23fc4d0c474be9070aa31de6e33a249558a6389128e8"
},
"downloads": -1,
"filename": "limited_shell-0.10.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c07b098b155d1aa2b9ddc60f27d21f4f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 72709,
"upload_time": "2024-12-01T12:08:30",
"upload_time_iso_8601": "2024-12-01T12:08:30.320607Z",
"url": "https://files.pythonhosted.org/packages/56/4a/ee0cbc3c841849b6114dce3c3d532ea8d3f6584d422998d22886f82a9072/limited_shell-0.10.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a7681e2055a2519c2d5567b3bf4eef2efd252ea9658eb450ab84801698ff461",
"md5": "04de1a03d560b5baef8bb5cdd5bd865c",
"sha256": "6c3f7e925fb88965e04163c348e8b423bd99703df44c87e36571c35c7edbe1b1"
},
"downloads": -1,
"filename": "limited_shell-0.10.10.tar.gz",
"has_sig": false,
"md5_digest": "04de1a03d560b5baef8bb5cdd5bd865c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 66134,
"upload_time": "2024-12-01T12:08:35",
"upload_time_iso_8601": "2024-12-01T12:08:35.623622Z",
"url": "https://files.pythonhosted.org/packages/4a/76/81e2055a2519c2d5567b3bf4eef2efd252ea9658eb450ab84801698ff461/limited_shell-0.10.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-01 12:08:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ghantoos",
"github_project": "lshell",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "limited-shell"
}
JSON
