README: Add a bunch of info

1 files changed, 133 insertions, 5 deletions

diff --git a/README.mdwn b/README.mdwn
index 4cdf2ec..04a0ed8 100644
--- a/README.mdwn
+++ b/README.mdwn
@@ -9,6 +9,82 @@ 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
@@ -17,13 +93,65 @@ 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/
 
-[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/
+### Docker
 
-[App Container spec]: https://github.com/appc/spec/
+[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