diff options
| -rw-r--r-- | HACKING.mdwn | 65 | ||||
| -rw-r--r-- | HACKING.rst | 69 | ||||
| -rw-r--r-- | README.mdwn | 163 | ||||
| -rw-r--r-- | README.rst | 182 | ||||
| -rw-r--r-- | setup.cfg | 2 |
5 files changed, 252 insertions, 229 deletions
diff --git a/HACKING.mdwn b/HACKING.mdwn deleted file mode 100644 index 4dcdc3b..0000000 --- a/HACKING.mdwn +++ /dev/null @@ -1,65 +0,0 @@ -The 'sandboxlib' library uses the PEP-8 coding style, as a guide. - -# Release process - -Basically, tag the commit you're going to release, build and upload a source -distribution tarball to [PyPI], and then increment the version number. - -You need - - an account on PyPI with access to the 'sandboxlib' project - - push access to <https://github.com/codethinklabs/sandboxlib> - -Process: - -1. Run tests: `sudo tox` -2. Create source distribution tarball: `python ./setup.py sdist` -3. Upload to PyPI: `twine upload -u $PYPI_USERNAME -p $PYPI_PASSWORD dist/sandboxlib-0.0.0.tar.gz` -4. Create and push tag: `git tag --annotate -m "sandboxlib version 0.0.0" 0.0.0 && git push --tags` - -I intend to follow [semantic versioning](http://www.semver.org/) and [PEP -440](https://www.python.org/dev/peps/pep-0440/) when numbering versions of this -library. - -For background on realising to the Python Package Index (PyPI), see: -<https://packaging.python.org/en/latest/distributing.html>. - -[PyPI]: http://pypi.python.org/ - -# Running the automated test suite - -Use `tox`. You'll need 'py.test', 'tox' and their dependencies available. - -Note that a lot of the tests will be skipped or fail if you don't run as -'root', because some of the sandboxing backends only work when you are the -'root' user. The test suite could handle this better than it does. - -You can also run `PYTHONPATH=. py.test`, which is quicker but only tests with -a single version of Python, and runs in your host environment rather than a -clean one managed by 'virtualenv'. - -# Testing that a sandbox conforms to the App Container spec - -The [App Container project] provides an 'ace' package containing a -[validator application for App Container Executors (ACEs)]. - -If you want to test whether a particular sandbox 'exec' module conforms to the -App Container spec, try this. You'll need a [golang] compiler available, and you -might need to set the `GOPATH` environment variable to point to a path where -you're happy for Go to install dependencies. - -First build the `ace-validator-main.aci` and `ace-validator-sidekick.aci` App -Container images. - - git clone git://github.com/appc/spec appc-spec - cd appc-spec - ace/build - cd - - -Then, use the `run-sandbox` program from this repository to run the image: - - run-sandbox appc-spec/ace/build/ace-validator-main.aci -e linux-user-chroot - - -[App Container project]: https://github.com/appc/spec -[validator application for App Container Executors (ACEs)]: https://github.com/appc/spec#validating-app-container-executors-aces -[golang]: https://golang.org/doc/install diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 0000000..a122fd0 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,69 @@ +The 'sandboxlib' library uses the PEP-8 coding style, as a guide. + +Release process +--------------- + +Basically, tag the commit you're going to release, build and upload a source +distribution tarball to PyPI_, and then increment the version number. + +You need +- an account on PyPI with access to the 'sandboxlib' project +- push access to https://github.com/codethinklabs/sandboxlib + +Process: + +1. Run tests: ``sudo tox`` +2. Create source distribution tarball: ``python ./setup.py sdist`` +3. Upload to PyPI: ``twine upload -u $PYPI_USERNAME -p $PYPI_PASSWORD dist/sandboxlib-0.0.0.tar.gz`` +4. Create and push tag: ``git tag --annotate -m "sandboxlib version 0.0.0" 0.0.0 && git push --tags`` + +I intend to follow `semantic versioning`_ and `PEP 440`_ when numbering +versions of this library. + +For background on realising to the Python Package Index (PyPI), see: +https://packaging.python.org/en/latest/distributing.html. + +.. _semantic versioning: <http://www.semver.org/> +.. _PEP 440: https://www.python.org/dev/peps/pep-0440/ +.. _PyPI: http://pypi.python.org/ + +Running the automated test suite +-------------------------------- + +Use ``tox``. You'll need 'py.test', 'tox' and their dependencies available. + +Note that a lot of the tests will be skipped or fail if you don't run as +'root', because some of the sandboxing backends only work when you are the +'root' user. The test suite could handle this better than it does. + +You can also run ``PYTHONPATH=. py.test``, which is quicker but only tests with +a single version of Python, and runs in your host environment rather than a +clean one managed by 'virtualenv'. + +Testing that a sandbox conforms to the App Container spec +--------------------------------------------------------- + +The `App Container project`_ provides an 'ace' package containing a +`validator application for App Container Executors (ACEs)`_. + +If you want to test whether a particular sandbox 'exec' module conforms to the +App Container spec, try this. You'll need a golang_ compiler available, and you +might need to set the ``GOPATH`` environment variable to point to a path where +you're happy for Go to install dependencies. + +First build the ``ace-validator-main.aci`` and ``ace-validator-sidekick.aci`` App +Container images:: + + git clone git://github.com/appc/spec appc-spec + cd appc-spec + ace/build + cd - + +Then, use the ``run-sandbox`` program from this repository to run the image:: + + run-sandbox appc-spec/ace/build/ace-validator-main.aci -e linux-user-chroot + + +.. _App Container project: https://github.com/appc/spec +.. _validator application for App Container Executors (ACEs)`: https://github.com/appc/spec#validating-app-container-executors-aces +.. _golang: https://golang.org/doc/install diff --git a/README.mdwn b/README.mdwn deleted file mode 100644 index 04a0ed8..0000000 --- a/README.mdwn +++ /dev/null @@ -1,163 +0,0 @@ -# sandboxlib: a lightweight library for running programs/commands in a sandbox - -This project is a total work in progress, no documentation yet. - -It is being developed as part of the [Baserock] project. - -The goal of this library is to provide the sandboxing functionality that is -already present in the build tools [Morph] and [YBD]. We want this new library -to be usable without depending on [linux-user-chroot], so that it can be used -on Mac OS X, and hopefully other platforms too. - -A longer term goal is to become a useful, generic, cross-platform tool for -running commands in an environment that is partially isolated from the host -system in some way. - -The library is implemented in Python currently. This is mostly because it is -an adaptation of existing Python code, not because of any desire to exclude -other languages. Maybe we could rewrite it as a C library with Python bindings. - -SANDBOXLIB DOES NOT GUARANTEE YOU ANY KIND OF SECURITY. Its main purpose is -for isolating software builds from the host system, to ensure that builds -are not contacting the network, or reading or writing files outside the build -environment. - -[Baserock]: http://www.baserock.org/ -[Morph]: http://wiki.baserock.org/Morph/ -[YBD]: https://github.com/devcurmudgeon/ybd/ -[linux-user-chroot]: https://git.gnome.org/browse/linux-user-chroot/tree/ - -# Current backends - - - chroot: any POSIX OS - - [linux-user-chroot] (plus `unshare`): Linux-only - -# Possible future backends - - - [Security Enhanced Linux] (SELinux): see <https://danwalsh.livejournal.com/28545.html> - - [systemd-nspawn] - -[Security Enhanced Linux]: http://selinuxproject.org/page/Main_Page -[systemd-nspawn]: http://www.freedesktop.org/software/systemd/man/systemd-nspawn.html - -# Relationship to other projects - -## Sandboxing - -### libsandbox / pysandbox - -The [libsandbox] library is a Linux-specific implementation of process -sandboxing, which supports intercepting syscalls, calling setrlimit(), -and dropping certain privileges. - -[libsandbox]: https://github.com/openjudge/sandbox - -### PRoot - -The [PRoot] tool provids features similar to [linux-user-chroot], plus some -extra code to allow running programs for a different architecture using -virtualisation. The PRoot tool is -[discontinued](https://plus.google.com/107605112469213359575/posts/NA5GxX2DAHe). - -[PRoot]: http://proot.me/ - -### seccomp - -The Linux kernel provides [seccomp] mode. This is a very restrictive sandbox -in which most programs would not work at all. It is [used by Google -Chrome](https://code.google.com/p/chromium/wiki/LinuxSandboxing#The_seccomp-bpf_sandbox), -among other things. - -[seccomp]: https://en.wikipedia.org/wiki/Seccomp - -### Further reading - - - [Sandboxing for multi-tenant applications](https://web.archive.org/web/20121129121538/http://blog.technologyofcontent.com/2011/04/sandboxing-for-multi-tenant-applications) (archived) - - [StackOverflow question "Run an untrusted C program in a sandbox in Linux that prevents it from opening files, forking, etc.?"](https://stackoverflow.com/questions/4249063/run-an-untrusted-c-program-in-a-sandbox-in-linux-that-prevents-it-from-opening-f) - - [StackOverflow question "How to "jail" a process without being root?"](https://unix.stackexchange.com/questions/6433/how-to-jail-a-process-without-being-root) - -## Containerisation - -There is a lot of overlap between the topics of 'containerisation' and -'sandboxing'. Many tools that work with 'containers' expect that containers -are long-lived things, where the 'sandboxlib' library treats a sandbox as a -much more lightweight, temporary thing. - -### App Container spec - -I have been using the [App Container spec] as a reference during development. -The scope of 'sandboxlib' is different to that of the App Container spec: -'sandboxlib' only deals with a single, isolated sandbox (which may or may -not be a 'container'), where the App Container spec is focused on multiple -containers. However, 'sandboxlib' would be a useful building block for -implementing a complete App Container runtime, and simple App Container images -(.acis) should be runnable with the `run-sandbox` tool directly. - -[App Container spec]: https://github.com/appc/spec/ - -### Docker - -[Docker] allows managing multiple prebuilt container systems. While it [can -support multiple platform-specific backends](https://blog.docker.com/2014/03/docker-0-9-introducing-execution-drivers-and-libcontainer/) -for running containers, I am only aware of Linux-specific backends at the time -of writing. - -[Docker]: http://www.docker.io/ - -### schroot - -The use case for the [schroot] tool is 'I want to define a contained -environment once, and use it many times.' The 'sandboxlib' library is more -about dynamically creating sandboxes. If [schroot] suits your needs, just -use it directly without any abstraction layer. - -[schroot]: https://launchpad.net/schroot - -## Python-specific Sandboxing - -The 'sandboxlib' library is for sandboxing *any* program, at the operating -system level. - -If you want to do language-level sandboxing (i.e. run untrusted Python code -within a larger Python program), there are some ways to do it. - -The concensus seems to be that Python language-level sandboxing is pretty much -impossible with the default 'cpython' Python runtime: - - - <https://mail.python.org/pipermail/python-dev/2013-November/130132.html> - - <https://programmers.stackexchange.com/questions/191623/best-practices-for-execution-of-untrusted-code> - -However, other Python runtimes do support language-level sandboxing. [PyPy] is one: - - - <https://pypy.readthedocs.org/en/latest/sandbox.html> - -[PyPy]: http://www.pypy.org/ - -## Build tools - -### Bazel - -The [Bazel] build tool contains a [Linux-specific sandbox -implementation](https://github.com/google/bazel/blob/master/src/main/tools/namespace-sandbox.c). - -[Bazel]: http://bazel.io/ - -### Morph - -The [Morph] build tool (from [Baserock]) is the original source of the -'sandboxlib' linux_user_chroot backend. Hopefully Morph will adopt the -'sandboxlib' library in future. - -### YBD - -The [YBD] build tool (from [Baserock]) [triggered the creation of the -'sandboxlib' library](https://github.com/devcurmudgeon/ybd/issues/32). - -# License - -License is GPLv2 but other licensing can be considered on request - -Most of the copyright is currently Codethink but don't let that put you off. -There's no intent to keep this as a Codethink-only project, nor will there be -any attempt to get folks to sign a contributor agreement. Contributors retain -their own copyright. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..c577200 --- /dev/null +++ b/README.rst @@ -0,0 +1,182 @@ +============================================================================ +sandboxlib: a lightweight library for running programs/commands in a sandbox +============================================================================ + +This project is a total work in progress, no documentation yet. + +It is being developed as part of the Baserock_ project. + +The goal of this library is to provide the sandboxing functionality that is +already present in the build tools Morph_ and YBD_. We want this new library +to be usable without depending on linux-user-chroot_, so that it can be used +on Mac OS X, and hopefully other platforms too. + +A longer term goal is to become a useful, generic, cross-platform tool for +running commands in an environment that is partially isolated from the host +system in some way. + +The library is implemented in Python currently. This is mostly because it is +an adaptation of existing Python code, not because of any desire to exclude +other languages. Maybe we could rewrite it as a C library with Python bindings. + +SANDBOXLIB DOES NOT GUARANTEE YOU ANY KIND OF SECURITY. Its main purpose is +for isolating software builds from the host system, to ensure that builds +are not contacting the network, or reading or writing files outside the build +environment. + +.. _Baserock: http://www.baserock.org/ +.. _Morph: http://wiki.baserock.org/Morph/ +.. _YBD: https://github.com/devcurmudgeon/ybd/ +.. _linux-user-chroot: https://git.gnome.org/browse/linux-user-chroot/tree/ + +Current backends +================ + +- chroot: any POSIX OS +- linux-user-chroot_ (plus ``unshare``): Linux-only + +Possible future backends +======================== + +- `Security Enhanced Linux`_ (SELinux): see https://danwalsh.livejournal.com/28545.html +- systemd-nspawn_ + +.. _Security Enhanced Linux: http://selinuxproject.org/page/Main_Page +.. _systemd-nspawn: http://www.freedesktop.org/software/systemd/man/systemd-nspawn.html + +Relationship to other projects +============================== + +Sandboxing +---------- + +libsandbox / pysandbox +~~~~~~~~~~~~~~~~~~~~~~ + +The libsandbox_ library is a Linux-specific implementation of process +sandboxing, which supports intercepting syscalls, calling setrlimit(), +and dropping certain privileges. + +.. _libsandbox: https://github.com/openjudge/sandbox + +PRoot +~~~~~ + +The PRoot_ tool provids features similar to linux-user-chroot_, plus some +extra code to allow running programs for a different architecture using +virtualisation. The PRoot tool is `discontinued <https://plus.google.com/107605112469213359575/posts/NA5GxX2DAHe>`_. + +.. _PRoot: http://proot.me/ + +seccomp +~~~~~~~ + +The Linux kernel provides seccomp_ mode. This is a very restrictive sandbox +in which most programs would not work at all. It is `used by Google Chrome +<https://code.google.com/p/chromium/wiki/LinuxSandboxing#The_seccomp-bpf_sandbox>`_, +among other things. + +.. _seccomp: https://en.wikipedia.org/wiki/Seccomp + +Further reading +~~~~~~~~~~~~~~~ + +- `Sandboxing for multi-tenant applications <https://web.archive.org/web/20121129121538/http://blog.technologyofcontent.com/2011/04/sandboxing-for-multi-tenant-applications>`_ (archived) +- `StackOverflow question "Run an untrusted C program in a sandbox in Linux that prevents it from opening files, forking, etc.? <https://stackoverflow.com/questions/4249063/run-an-untrusted-c-program-in-a-sandbox-in-linux-that-prevents-it-from-opening-f>`_ +- `StackOverflow question "How to "jail" a process without being root? <https://unix.stackexchange.com/questions/6433/how-to-jail-a-process-without-being-root>`_ + +Containerisation +---------------- + +There is a lot of overlap between the topics of 'containerisation' and +'sandboxing'. Many tools that work with 'containers' expect that containers +are long-lived things, where the 'sandboxlib' library treats a sandbox as a +much more lightweight, temporary thing. + +App Container spec +~~~~~~~~~~~~~~~~~~ + +I have been using the `App Container spec`_ as a reference during development. +The scope of 'sandboxlib' is different to that of the App Container spec: +'sandboxlib' only deals with a single, isolated sandbox (which may or may +not be a 'container'), where the App Container spec is focused on multiple +containers. However, 'sandboxlib' would be a useful building block for +implementing a complete App Container runtime, and simple App Container images +(.acis) should be runnable with the ``run-sandbox`` tool directly. + +.. _App Container spec: https://github.com/appc/spec/ + +Docker +~~~~~~ + +Docker_ allows managing multiple prebuilt container systems. While it `can +support multiple platform-specific backends <https://blog.docker.com/2014/03/docker-0-9-introducing-execution-drivers-and-libcontainer/>`_ +for running containers, I am only aware of Linux-specific backends at the time +of writing. + +.. _Docker: http://www.docker.io/ + +schroot +~~~~~~~ + +The use case for the schroot_ tool is 'I want to define a contained +environment once, and use it many times.' The 'sandboxlib' library is more +about dynamically creating sandboxes. If schroot_ suits your needs, just +use it directly without any abstraction layer. + +.. _schroot: https://launchpad.net/schroot + +Python-specific Sandboxing +-------------------------- + +The 'sandboxlib' library is for sandboxing *any* program, at the operating +system level. + +If you want to do language-level sandboxing (i.e. run untrusted Python code +within a larger Python program), there are some ways to do it. + +The concensus seems to be that Python language-level sandboxing is pretty much +impossible with the default 'cpython' Python runtime: + +- https://mail.python.org/pipermail/python-dev/2013-November/130132.html +- https://programmers.stackexchange.com/questions/191623/best-practices-for-execution-of-untrusted-code + +However, other Python runtimes do support language-level sandboxing. PyPy_ is one: + +- https://pypy.readthedocs.org/en/latest/sandbox.html + +.. _PyPy: http://www.pypy.org/ + +Build tools +----------- + +Bazel +~~~~~ + +The Bazel_ build tool contains a `Linux-specific sandbox implementation +<https://github.com/google/bazel/blob/master/src/main/tools/namespace-sandbox.c>`_. + +.. _Bazel: http://bazel.io/ + +Morph +~~~~~ + +The Morph_ build tool (from Baserock_) is the original source of the +'sandboxlib' linux_user_chroot backend. Hopefully Morph will adopt the +'sandboxlib' library in future. + +YBD +~~~ + +The YBD_ build tool (from Baserock_) `triggered the creation of the +'sandboxlib' library <https://github.com/devcurmudgeon/ybd/issues/32>`_. + +License +------- + +License is GPLv2 but other licensing can be considered on request + +Most of the copyright is currently Codethink but don't let that put you off. +There's no intent to keep this as a Codethink-only project, nor will there be +any attempt to get folks to sign a contributor agreement. Contributors retain +their own copyright. @@ -3,7 +3,7 @@ name = sandboxlib version = 0.1.0 summary = Sandboxing Library for Python description-file = - README.mdwn + README.rst [files] packages = |