README


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

Sandbox (for) Untrusted Procedure Partitioning (in) Lua Engine - Supple
=======================================================================

Supple is a tool for sandboxing untrusted code and providing security
partitioning. It deliberately operates by first forking a subprocess which is
strictly limited in what it can do. For example, only the Supple Lua modules
may be loaded, and they are all loaded before any untrusted code is run. The
developer interfacing with Supple in their project is responsible for ensuring
that any functions/objects passed into the subprocess cannot break the sandbox
in ways the project author did not intend.

For example, if you you're passing a file handle across, it's probably best if
it's read-only.  If you have an object representing a lot of sensitive stuff,
it's probably best to have a proxy object in the host which acts as a security
guard only allowing the sandbox to call pre-approved methods and access
pre-approved data.

In order to support the above while still reducing the chance of anything
breaking the sandbox, Supple always presents remote objects as userdata and
forces the use of a file descriptor in order to allow calls back and forth
between the two ends of the sandbox connection. This means that, for example,
methods can be called and passed callback functions which can thread back and
forth with only a strict nesting requirement.

Supple can also be asked to soft-limit the Lua VM opcodes and/or memory
in-use-by-lua more tightly than the hard process limits compiled into Supple.

For examples of using Supple, please see the examples/ directory.

If you acquired Supple via git, you may need to initialise the submodules:

    $ git submodule init
    $ git submodule update