The sandbox Lua libray allows a Lua script creates new lua_States and offers them a protected environment.

In the following text, host means the "normal" lua_State and box is a sandbox instanced inside the host.

The intention with protected environment, here, is to protect the host from being tricked by a box. In the current version, much of this goal is already fulfilled, but it has known weaknesses that they can be observed in the weaknesses item.

This library interface was designed to prevent or minimize the need of data copy between lua_States as copys reduce the performance of the solution. This topic is very important because, in Lua, strings are constants.

Currently, there is not a reference sanbox project like the Apache HTTP Server is to web servers. An initial difficulty of this project was to design an interface between host and box and for such, Unix processes were used as model.

The author - I - consider undeniably pretty and very good the Unix process model. If the reader knows this model well, change the words kernel and processes to host and box may help. If this model isn't known, is enough not to focus on "whys" at the beginning.


Strengths and weaknesses

Libraries available for a sandbox

All libraries written 100% in Lua should run without problems inside of sandbox and are safe!

A C library can also be executed inside of sandbox. However, since from language C the code has full control of the process, this kind of library might open security holes that can be explored from the Lua code!

The ways to make a Lua lib with link a C lib: disable some functions in sandbox or to limit its fire power, redefine functions, or to give sandbox's host ability to determine what can be done.

Problematic functions examples: os.exit, print, loadlib.

Problematic libraries examples: sandbox.

Security directive to be followed by C libraries or libraries that have bond with C libraries availables inside sandbox:

- It cannot have uncontrolled leaking of process's information for sandbox, example: os.getenv.

- The userdatas created by the library shoudn't allocate much memory, or allocation of this external memory cannot grow with calls of its methods or functions. Example: sandbox.

- Possibility of stack overflow due to nesting of package's functions should be evaluated. Example: L:luaopen().

- It must be evaluated if is given bigger access than is allowed inside the sandbox, example, allows file acess which is vetoed inside sandbox.

Comunication between host and sandbox

Forgetting the communication between processes and the OS API, in Unix Process Model (UPM), the processes communicate with kernel and other processes with parameter passages, special filehandles (stdin, stdout, stderr), enviroment and return code.

Parameter passage. A chunk in Lua is a function that does not return parameters, and it's not interesting to dirty the sandbox environment with functions with this use only, would be an unnecessary twist.

Special filehandlers. This way is the most explored in the sandbox model constructed here. The three special filehandles are supported.

Enviroment. The POSIX model supported. So, the box is not allowed to change the environment, nor lists it, only consult it through a key.

Return code. Not implemented. It's still not clear if this should be implemented, because Lua values can be very complicated.

As the development of this project, it's possible that the need of ways of communication others than the UPM arises. For the moment, only the listed forms are available.


The great discussions about sandbox

This topic lists and, as far as it can, describes and discuss the main problems in the implementation of a sandbox. Only problems which good solution was still not found, implemented and validated are discussed.

Pointers in C code

To help reading the C code, it's worth to use the image below:

Download and install



Michel Machado

sandbox package copyright and license

sandbox package is licensed under the GNU General Public License (GPL).

Copyright (c) 2003 Digirati.