Metadata-Version: 2.1
Name: limited-shell
Version: 0.10.2
Summary: lshell - Limited Shell
Home-page: https://github.com/ghantoos/lshell
Author: Ignace Mouzannar
Author-email: ghantoos@ghantoos.org
Maintainer: Ignace Mouzannar
Maintainer-email: ghantoos@ghantoos.org
License: GPL-3
Project-URL: GitHub, https://github.com/ghantoos/lshell
Project-URL: Changelog, https://github.com/ghantoos/lshell/blob/master/CHANGELOG.md
Keywords: limited,shell,security,python
Platform: UNIX
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: System :: Shells
Classifier: Topic :: System :: System Shells
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: COPYING

# 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

lshell.conf presents a template configuration file. See etc/lshell.conf or man file for more information.

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.
 
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`.


## Contributions

To contribute, open an issue or send a pull request.

Please use github for all requests: https://github.com/ghantoos/lshell/issues
