# 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`.
Raw data
{
"_id": null,
"home_page": "https://github.com/wrr/venvjail",
"name": "venvjail",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "venvjail",
"author": "Jan Wrobel",
"author_email": "jan@mixedbit.org",
"download_url": "https://files.pythonhosted.org/packages/32/26/1a9f60c09f1d2df52a8177e03b15a64822f87d596a67c80c2ea8886d3ae4/venvjail-0.0.0.tar.gz",
"platform": null,
"description": "# venvjail: Python virtual environment which jails executed programs.\n\n**Development status: Planning**\n\n## Overview\n\n`venvjail` allows to install and run python programs without giving\nthem full access to the user's account. The goal is to limit harm a\ncompromised dependency can make without sacrificing the user\u2019s\nconvenience. `venvjail` offers very similar workflow to the standard\nPython `venv`, in most cases you should not notice and be affected by\nthe additional limitations applied in the jailed venv.\n\n`venvjail` uses Linux namespaces and runs without root privileges. It\nrequires a Linux kernel with user namespaces enabled (for example,\nUbuntu 22 default kernel).\n\nThe following restrictions are applied to the jailed processes by default:\n\n* The processes can write only to files in the directory subtree in\n which the `venvjail` was created. The exception are the\n `venvjail` activation and configuration files, which are not\n accessible in the jail.\n\n* The whole content of the home directory is hidden in the jail with\n the exception of an explicit list of configuration files which are\n available read-only. By default this list includes `.bashrc`,\n `.profile`, `.bash_profile` and can be modified via a\n `~/.dirjailconfig` file.\n\n* The processes are allowed to create new files in the home directory\n (for example program config files), but all these created files are\n in fact stored in the `./home` sub directory of the virtual\n environment.\n\n* The processes can read and write to the `/tmp` directory. Outside of\n the jail this directory points to the `/tmp/dirjail-XXXXXX`.\n\n* The process can see only processes that are executed in the same jail.\n\n* Most files in `/proc` and all files in `/run/user/UID` are not\n readable in `venvjail`.\n\n* Suid programs can not be executed in the jail.\n\n* All other files that you can normally read and execute are also\n readable and executable in the jail (but not writable). This can be\n also adjusted via the `~/.dirjailconfig` file.\n\nCompared to running a program in a separate virtual machine or a\nDocker instance, the following conveniences improve the user\nexperience:\n\n* The jail runs on top of your current distribution, so you can run\n all the programs that you have available on your machine. Of course,\n these executed programs are also jailed, so for example `ls ~` will\n only list files visible in the jail.\n\n* Your username is preserved in the jail. You are not a `root`, and\n files owned and created by you are listed as such in the jail.\n\n* An explicitly selected list of config file are exposed to the\n jail in read-only mode. Shell configuration, helper functions,\n aliases continue to work normally while in the jail.\n\n* Your current working directory path and most of the directory\n structure is preserved in the jail.\n\n* File system modifications done in the jail are limited to the jailed\n directory subtree, so you can be sure that removing this program\n directory removes all the files that the program created. This helps\n to keep the system tidy.\n\n# Installation and usage\n\nTo install run:\n\n pip install venvjail\n\nTo create a virtual environment in a `venv` directory:\n\n python -m venvjail venv\n\nTo start a new shell with the jailed virtual environment activated:\n\n ./venv/bin/activate-new-shell\n\nOr:\n\n source ./venv/bin/activate-new-shell\n\n\nLike with the standard Python `venv`, you can run any program from the\n`venv/bin` directly without activating `venv` first, and all these\nprograms are executed in the jail. For example:\n\n ./venv/bin/python\n >>> import os, pathlib\n >>> os.listdir(pathlib.Path.home());\n # You can see that most of the files in your home dir are hidden in the jail:\n ['.bashrc', '.profile, ...]\n\n\n# Where is the `./venv/bin/activate` script and how to run scripts that source this file?\n\n`/venv/bin/activate` script of the standard Python `venv` module\nactivates the virtual environment in the current shell, this is why\nthis script should be sourced and not executed. Because it is not\npossible to jail an already existing process, `venvjail` needs to\ncreate a new shell process, to avoid confusion the activation script\nis called `./venv/bin/activate-new-shell`.\n\nOnce the `venvjail` is active, `venv/bin/activate` script becomes\navailable, sourcing it is a no-op, because the `venv` is already\nactivate, but it allows to run existing shell scripts that call\n`source/venv/activate`.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Python virtual environment which jails executed programs.",
"version": "0.0.0",
"project_urls": {
"Homepage": "https://github.com/wrr/venvjail"
},
"split_keywords": [
"venvjail"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5599c8761cc1bfaed47f873f5a2d7e2852df2539d1156d45523ac9409b64b9b",
"md5": "46fa963f5706eaee07dd98e1477e7587",
"sha256": "f5f859c1d7ad47edaa2df3660d484d10ad554a78f53ecaf1553a8d43778bbd6f"
},
"downloads": -1,
"filename": "venvjail-0.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "46fa963f5706eaee07dd98e1477e7587",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 5229,
"upload_time": "2024-03-29T18:39:43",
"upload_time_iso_8601": "2024-03-29T18:39:43.797839Z",
"url": "https://files.pythonhosted.org/packages/b5/59/9c8761cc1bfaed47f873f5a2d7e2852df2539d1156d45523ac9409b64b9b/venvjail-0.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "32261a9f60c09f1d2df52a8177e03b15a64822f87d596a67c80c2ea8886d3ae4",
"md5": "16c8b050d1395fe7f6c490c63adc04f3",
"sha256": "1e114b6727f3fdacb46528c6242437417ec6a4fb58b5e67e9a7627312f06615e"
},
"downloads": -1,
"filename": "venvjail-0.0.0.tar.gz",
"has_sig": false,
"md5_digest": "16c8b050d1395fe7f6c490c63adc04f3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11099,
"upload_time": "2024-03-29T18:39:45",
"upload_time_iso_8601": "2024-03-29T18:39:45.046254Z",
"url": "https://files.pythonhosted.org/packages/32/26/1a9f60c09f1d2df52a8177e03b15a64822f87d596a67c80c2ea8886d3ae4/venvjail-0.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 18:39:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wrr",
"github_project": "venvjail",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "venvjail"
}
JSON
