Change README with new intro

1 files 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.