About

l8ash is a command line shell which is designed to have the least attack surface on its command line interface.

If you need to leash shells and shell users, you would like to permit certain operation only on your shells with pre-defined operational procedures, which contain a set of commands and corresponding arguments, without any unnecessary statements including shell variables, variable expansions, inline command invocation, declaration of shell functions nor command expansions.

l8ash provides very limited shell features but strong support to restrict command invocation. You can permit users only to do typical administration tasks with pre-defined pipelines and its environments. To enable this feature, a runtime configuration file (~/.l8ashrc) is required and its whitelist table must contain named pipelines (pipeline alias) for target operations. Optionally, l8ash can also check the integrity of command binaries when it is invoked on the shell (as a pre-defined pipeline).

l8ash empowers you to protect systems and assets you should keep it always safe.

Installation

cargo install l8ash

(Be careful, binary name is l8ash, not l8ash!)

Or you can install binary, building from your local source code:

cd path/to/this/repo
make
sudo make install

If you do not have permission to access to the system path, you can install it under your home directory:

make
PREFIX=$HOME/local make install

# set your PATH if you need
# echo PATH=\$HOME/local/bin:\$PATH | tee -a $HOME/.bashrc

Quick start

1. Simply invoke it as a program

$ l8ash

2. Feed an acceptable shell script

$ cat some_l8ash_script.sh
#!/bin/sh
ls -l | tr -d \\\n 
$  cat some_l8ash_script.sh | l8ash

3. Feed shell script as the argument

$  l8ash some_l8ash_script.sh 

4. Set l8ash as the user's default shell

{ 
  [ -x /bin/l8ash ] || {
    echo l8ash not found >&2
    false
  } &&
  grep /bin/l8ash /etc/shells > /dev/null || {
    echo failed to set l8ash as your default shell. consider to add `/bin/l8ash` to your /etc/shells. >&2
    false
  } 
} && chsh -s /bin/l8ash 

5. Play.

ls -l | awk {gsub("-","neko",$0);print;} | tr 0  @ | tee -a something.funny | bzip2 | dd of=sf.bz2

Features

• Generic commandline interface to invoke commands with raw argument, without any shell variables and shell functions.

• Some of POSIX shell functionalities are NOT IMPLEMENTED to achieve the hardened shell experience. The l8ash has:

  • No builtin commands (no echo, printf, cd, kill nor exit as a builtin. No other builtins in the world too.)
  • No shell variable var=val and $var
  • No expansion (no path expansion with * or other special glob characters, neither variable nor command expansion.)
  • No command alias alias name="cmd arg1 arg2"
  • No shell function function f1 { ... }, f1(){ ... } nor function f1 () { ... }
  • No string literal '...' nor "..."
  • No subcommand (...)
  • No group command {...}
  • No background tasks cmd &
  • No redirection cmd > file nor cmd >> file
  • No indirection cmd < file
  • No command termination with semicolon cmd1; cmd2; cmd3

• No string literals (said again). A whitespace is always recognized as a word separater.

• Pipeline: Ordinal pipeline for system shell. It is only the way to modify temporary input/output in a shell session.

• Runtime configuration: You can write operation whitelist and other configuration in ~/.l8ashrc.

• Command whitelist: l8ash prohibits any commands other than listed names (named pipeline) on the whitelist table.

• named pipeline / pipeline alias: permitted operations can be declared as named pipelines in a configuration file.

• Environmental variables: Environmental variable for a pipeline can be specified and applied to all command in the pipeline.

• Integrity checker: l8ash can check the integrity of command binaries which composes a pipeline.

Configuration Tips

Make whitelist only to permit specific programs

To run l8ash in restricted mode, create ~/.l8ashrc and declare [[whitelist]] in that:

[[whitelist]]
name = "ls"
command_line = "/bin/ls"
env = []
integrity = []

With this configuration, user on the l8ash session cannot execute program, other than /bin/ls. For an operation with a single program like this case, command_line fields should be a full path of the program and its arguments.

ATTENTION

The path of .l8ashrc can be switched with LEASH_CONF environmental variable. If l8ash binary is invoked with preset LEASH_CONF, it refers customized path for the runtime configuration.

Set pipeline aliases (or named pipeline) on the whitelist

You can declare command alias in a whitelist table. For the previous example, set an alias in the name field for the operation:

[[whitelist]]
name = "l"
command_line = "/bin/ls"
env = []
integrity = []

With this configuration, you can invoke /bin/ls with the name (alias) l, but not with its real name ls. You cannot invoke /bin/ls with its full path or its real name. (and you cannot invoke the program named l, if it exists in your PATH).

Also, you can declare pipeline alias with the same mechanism. Set pipeline statement in the command attribute like following:

[[whitelist]]
name = "count_files"
command_line = "/bin/ls | wc -l"
env = []
integrity = []

Pass environmental variables for a pipeline

[[whitelist]]
name = "kci"
command_line = "/home/mofuzawa/bin/kubectl cluster-info"
env = ["KUBECONFIG=/var/conf/dist/your-kube-config"]
integrity = []

Check integrity for each command for a pipeline

[[whitelist]]
name = "lstr"
command_line = "/bin/ls -l | /bin/tr - o"
env = []
integrity = [
        "a3604f3968fda1471dfdb51a3a4454d8a1b6c3dead99e84f442b515b9b49da53",
        "3138ff15c875f111613407f39261babafbfe8cdc77a4c1cebb834334b78b9f0b",
]

ATTENTION

For integrity checking, all command must be spelled with its full path, unless the command is not invokable because of failure on path discovery.

Design concept

See the second clause of the Features above. Each condition, which means the lack of the generic shell feature, is a building block of the l8ash security model.

Specification	Description (especially for the security)
No builtins	No hack with shell builtins
No shell variable	No worry about any dangerous contents inside variables
No expansion	No worry about unexpected expansion to be evaluated as malformed commands or strings
No command aliases	No new set of attack codes in the shell session
No shell functions	No new set of attack codes in the shell session
No string literal	No confusion of several equivalent text expressions. Escape character is the only permitted way.
No subcommand	No fork in the shell by itself. Only processes are spawned by the shell in a pipeline
No group command	No bundle of stdout/stderr. A command has single I/O in a pipeline.
No background tasks	No unmanaged processes which is hanged up after the spawning.
No redirection nor indirection	No read/write operation for the shell itself. Filesystem I/O is only permitted for commands.
No semicolon	EOL is the only-one op code for the list evaluation. Thus, a list must be a pipeline in the l8ash.

In addition, l8ash ensures users only to invoke trusted programs via whitelist.

ATTENTION

Leash does not cover the protection of filesystem or its contents. It is recommended to use other mechanisms to protect filesystem from potentially malicious programs or exploits. The risk of overwriting or replacing l8ashrc/l8ash itself, is a critical factor for the l8ash safety.

Bug reports

Make issues, thanks!