diff options
-rw-r--r-- | README | 32 |
1 files changed, 21 insertions, 11 deletions
@@ -2,18 +2,28 @@ 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 whitelisted Lua modules -may be loaded, and they are all loaded *before* any untrusted code is run. The -developer implementing Supple in their project is responsible for ensuring that -any modules loaded into the subprocess cannot break the sandbox. +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. -In order to reduce 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. +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. |