venvjail 0.0.0
Python virtual environment which jails executed programs.
License: MIT license
Requires Python: >=3.8
Keywords: venvjail

# venvjail: Python virtual environment which jails executed programs.

**Development status: Planning**

## Overview

`venvjail` allows to install and run python programs without giving
them full access to the user's account. The goal is to limit harm a
compromised dependency can make without sacrificing the user’s
convenience. `venvjail` offers very similar workflow to the standard
Python `venv`, in most cases you should not notice and be affected by
the additional limitations applied in the jailed venv.

`venvjail` uses Linux namespaces and runs without root privileges. It
requires a Linux kernel with user namespaces enabled (for example,
Ubuntu 22 default kernel).

The following restrictions are applied to the jailed processes by default:

* The processes can write only to files in the directory subtree in
   which the `venvjail` was created. The exception are the
  `venvjail` activation and configuration files, which are not
  accessible in the jail.

* The whole content of the home directory is hidden in the jail with
  the exception of an explicit list of configuration files which are
  available read-only. By default this list includes `.bashrc`,
  `.profile`, `.bash_profile` and can be modified via a
  `~/.dirjailconfig` file.

* The processes are allowed to create new files in the home directory
  (for example program config files), but all these created files are
  in fact stored in the `./home` sub directory of the virtual
  environment.

* The processes can read and write to the `/tmp` directory. Outside of
  the jail this directory points to the `/tmp/dirjail-XXXXXX`.

* The process can see only processes that are executed in the same jail.

* Most files in `/proc` and all files in `/run/user/UID` are not
  readable in `venvjail`.

* Suid programs can not be executed in the jail.

* All other files that you can normally read and execute are also
  readable and executable in the jail (but not writable). This can be
  also adjusted via the `~/.dirjailconfig` file.

Compared to running a program in a separate virtual machine or a
Docker instance, the following conveniences improve the user
experience:

* The jail runs on top of your current distribution, so you can run
  all the programs that you have available on your machine. Of course,
  these executed programs are also jailed, so for example `ls ~` will
  only list files visible in the jail.

* Your username is preserved in the jail. You are not a `root`, and
  files owned and created by you are listed as such in the jail.

* An explicitly selected list of config file are exposed to the
  jail in read-only mode. Shell configuration, helper functions,
  aliases continue to work normally while in the jail.

* Your current working directory path and most of the directory
  structure is preserved in the jail.

* File system modifications done in the jail are limited to the jailed
  directory subtree, so you can be sure that removing this program
  directory removes all the files that the program created. This helps
  to keep the system tidy.

# Installation and usage

To install run:

    pip install venvjail

To create a virtual environment in a `venv` directory:

    python -m venvjail venv

To start a new shell with the jailed virtual environment activated:

    ./venv/bin/activate-new-shell

Or:

    source ./venv/bin/activate-new-shell


Like with the standard Python `venv`, you can run any program from the
`venv/bin` directly without activating `venv` first, and all these
programs are executed in the jail. For example:

      ./venv/bin/python
       >>> import os, pathlib
       >>> os.listdir(pathlib.Path.home());
       # You can see that most of the files in your home dir are hidden in the jail:
       ['.bashrc', '.profile, ...]


# Where is the `./venv/bin/activate` script and how to run scripts that source this file?

`/venv/bin/activate` script of the standard Python `venv` module
activates the virtual environment in the current shell, this is why
this script should be sourced and not executed. Because it is not
possible to jail an already existing process, `venvjail` needs to
create a new shell process, to avoid confusion the activation script
is called `./venv/bin/activate-new-shell`.

Once the `venvjail` is active, `venv/bin/activate` script becomes
available, sourcing it is a no-op, because the `venv` is already
activate, but it allows to run existing shell scripts that call
`source/venv/activate`.