From 04d7d87d6ad709fa62e5ecd200a8d2d2871227c7 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Sat, 4 Aug 2012 22:02:10 +0100 Subject: Change README with new intro --- README | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/README b/README index 75acc11..8ba7057 100644 --- a/README +++ b/README @@ -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. -- cgit v1.2.1