LuaSandbox

LuaSandbox is an extension for PHP 5, PHP 7, and HHVM to allow safely running untrusted Lua 5.1 code from within PHP, which will generally be faster than shelling out to a Lua binary and using inter-process communication.

The extension makes some assumptions about the call stack that can be hard to satisfy. This might cause problems during unit tests with PHPunit. The same problem might not exist in production code. Use the Lua standalone engine for testing if necessary.

Prepackaged
LuaSandbox is available in Debian 9 and Ubuntu 18.04 LTS. Install with the following command:

Note Debian 9 users may need to add  to their sources.list.

Requirements
Install the headers and library files for PHP and Lua 5.1.
 * For Debian-derived Linux distributions, such as Ubuntu:
 * For Centos/Redhat-derived Linux distributions:
 * For Mac OS X:

Download
Download the source code into an appropriate directory from git:

Or and unpack.

Build
here is the directory that luasandbox git repository was cloned to.

Then add  to the PHP configuration in an appropriate place. For example, in modern Debian-derived distributions you'd add a file to  (where   is the version of PHP for which you complied LuaSandbox) and use the   command to enable it.

If you're using HHVM instead, build with

Then add hhvm.enable_zend_compat = true hhvm.dynamic_extension_path=/usr/lib/x86_64-linux-gnu/hhvm/extensions/20150212 hhvm.dynamic_extensions[luasandbox]=luasandbox.so to. You will need to replace the path to   with whatever install path was reported by.

In both PHP and HHVM, if you're using LuaSandbox with a web application such as MediaWiki, you'll need to restart your webserver or php-fpm for PHP to load the extension. After such reload, you should see LuaSandbox in the output of  and   (and, for MediaWiki with Scribunto installed, Special:Version).

Documentation
Generated documentation for classes provided by the extension is available at https://doc.wikimedia.org/mediawiki-php-luasandbox/master/.

Stub files with documentation in PHPDoc format are available in the LuaSandbox repository.

Differences from standard Lua
LuaSandbox provides a sandboxed environment which differs in some ways from standard Lua 5.1.

The following functions and packages are not available:
 * ,, and the package, as they allow direct filesystem access. If needed, filesystem access should be done via PHP callbacks.
 * The package, including  and , as it depends heavily on direct filesystem access. A pure-Lua rewrite such as that used in Scribunto may be used instead.
 * and, to allow for static analysis of Lua code.
 * , since it outputs to standard output. If needed, output should be done via PHP callbacks.
 * Most of the package, as it allows manipulation of the process and executing of other processes.
 * ,,  , and   remain available.
 * Most of the package, as it allows manipulation of Lua state and metadata in ways that can break sandboxing.
 * remains available.
 * , as it may expose internal data.
 * ,, and the package have not been reviewed for security.

The following features have been modified:
 * and cannot catch certain errors, particularly timeout errors.
 * does not include pointer addresses.
 * has been patched to limit the recursion depth and to periodically check for a timeout.
 * and are replaced with versions that don't share state with PHP's.
 * The Lua 5.2 and  metamethods are supported by   and.

History
Over the years, MediaWiki's wikitext template "language" gained more features and grew more complicated. As early as 2009, MediaWiki developers began discussing the idea of embedding a real scripting language instead of continuing to make wikitext more complex.

Requirements for such a project included a strong sandbox and strict limitations on memory and CPU time usage, since it would be executing untrusted user code on production servers. It would need to be usable by shelling out to a standalone binary, with the ability to be run in-process via a PHP extension for better performance being a major benefit.

When development started in earnest circa 2011, four candidate languages were identified: Lua, JavaScript, PHP, or a hypothetical "WikiScript" language to be developed. Lua had several advantages: The main disadvantage was that it wasn't known as widely as JavaScript.
 * Small (170K standalone) and fast. The existence of LuaJIT was also considered a benefit.
 * Designed for embedding, including easy hooks for CPU and memory limiting.
 * Easy sandboxing, no internal globals.
 * Detailed reference manual, including instructions on embedding.

JavaScript, in the form of the V8 engine at the time, had several disadvantages:
 * Minimal documentation on embedding.
 * Continued support for embedding unclear.
 * No allocation hook.
 * Huge standalone binary.

The Rhino engine was worse, as being written in Java it couldn't sanely be embedded in PHP at all. PHP itself was rejected since proper embedding and sandboxing would have been extremely difficult and pre-parsing would have been slow, and "WikiScript" would have been a much larger project in that it would have required developing an interpreter (or two) from scratch.

Thus, Lua was chosen, specifically version 5.1 that was available at the time, and this PHP extension was developed. The changes made to function environment handling in 5.2 have prevented a simple upgrade since, see T178146 for details.