Generic Lua sandbox for dynamic data analysis. More...

#include "luasandbox/error.h"
#include "luasandbox/lua.h"

Include dependency graph for luasandbox.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	LSB_EXPORT

#define	LSB_ERROR_SIZE 256

#define	LSB_SHUTTING_DOWN "shutting down"

#define	LSB_CONFIG_TABLE "lsb_config"

#define	LSB_THIS_PTR "lsb_this_ptr"

#define	LSB_MEMORY_LIMIT "memory_limit"

#define	LSB_INSTRUCTION_LIMIT "instruction_limit"

#define	LSB_INPUT_LIMIT "input_limit"

#define	LSB_OUTPUT_LIMIT "output_limit"

#define	LSB_LOG_LEVEL "log_level"

#define	LSB_LUA_PATH "path"

#define	LSB_LUA_CPATH "cpath"

#define	LSB_NIL_ERROR "<nil error message>"

Typedefs
typedef struct lsb_lua_sandbox	lsb_lua_sandbox

Enumerations
enum	lsb_state { LSB_UNKNOWN = 0, LSB_RUNNING = 1, LSB_TERMINATED = 2, LSB_STOP = 3 }

enum	lsb_usage_stat { LSB_US_LIMIT = 0, LSB_US_CURRENT = 1, LSB_US_MAXIMUM = 2, LSB_US_MAX }

enum	lsb_usage_type { LSB_UT_MEMORY = 0, LSB_UT_INSTRUCTION = 1, LSB_UT_OUTPUT = 2, LSB_UT_MAX }

Functions
LSB_EXPORT lsb_lua_sandbox *	lsb_create (void parent, const char lua_file, const char cfg, lsb_logger logger)
	Allocates and initializes the structure around the Lua sandbox allowing full specification of the sandbox configuration using a Lua configuration string. More...

LSB_EXPORT lsb_err_value	lsb_init (lsb_lua_sandbox lsb, const char state_file)
	Initializes the Lua sandbox and loads/runs the Lua script that was specified in lua_create_sandbox. More...

LSB_EXPORT void	lsb_stop_sandbox_clean (lsb_lua_sandbox *lsb)
	Changes the sandbox state to LSB_STOP to allow for a clean exit. More...

LSB_EXPORT void	lsb_stop_sandbox (lsb_lua_sandbox *lsb)
	Aborts the running sandbox from a different thread of execution. More...

LSB_EXPORT char *	lsb_destroy (lsb_lua_sandbox *lsb)
	Frees the memory associated with the sandbox. More...

LSB_EXPORT size_t	lsb_usage (lsb_lua_sandbox *lsb, lsb_usage_type utype, lsb_usage_stat ustat)
	Retrieve the sandbox usage statistics. More...

LSB_EXPORT lsb_state	lsb_get_state (lsb_lua_sandbox *lsb)
	Retrieve the current sandbox status. More...

LSB_EXPORT const char *	lsb_get_error (lsb_lua_sandbox *lsb)
	Return the last error in human readable form. More...

LSB_EXPORT void	lsb_set_error (lsb_lua_sandbox lsb, const char err)
	Sets the last error string. More...

LSB_EXPORT lua_State *	lsb_get_lua (lsb_lua_sandbox *lsb)
	Access the Lua pointer. More...

LSB_EXPORT const char *	lsb_get_lua_file (lsb_lua_sandbox *lsb)
	Returns the filename of the Lua source. More...

LSB_EXPORT void *	lsb_get_parent (lsb_lua_sandbox *lsb)
	Access the parent pointer stored in the sandbox. More...

LSB_EXPORT const lsb_logger *	lsb_get_logger (lsb_lua_sandbox *lsb)
	Access the logger struct stored in the sandbox. More...

LSB_EXPORT void	lsb_add_function (lsb_lua_sandbox lsb, lua_CFunction func, const char func_name)
	Create a CFunction for use by the Sandbox. More...

LSB_EXPORT lsb_err_value	lsb_pcall_setup (lsb_lua_sandbox lsb, const char func_name)
	Helper function to load the Lua function and set the instruction limits. More...

LSB_EXPORT void	lsb_pcall_teardown (lsb_lua_sandbox *lsb)
	Helper function to update the statistics after the call. More...

LSB_EXPORT void	lsb_terminate (lsb_lua_sandbox lsb, const char err)
	Change the sandbox state to LSB_TERMINATED due to a fatal error. More...

Variables
LSB_EXPORT lsb_err_id	LSB_ERR_INIT

LSB_EXPORT lsb_err_id	LSB_ERR_LUA

LSB_EXPORT lsb_err_id	LSB_ERR_TERMINATED

Detailed Description

Generic Lua sandbox for dynamic data analysis.

Definition in file luasandbox.h.

Macro Definition Documentation

#define LSB_CONFIG_TABLE "lsb_config"

Definition at line 31 of file luasandbox.h.

#define LSB_ERROR_SIZE 256

Definition at line 28 of file luasandbox.h.

#define LSB_EXPORT

Definition at line 24 of file luasandbox.h.

#define LSB_INPUT_LIMIT "input_limit"

Definition at line 35 of file luasandbox.h.

#define LSB_INSTRUCTION_LIMIT "instruction_limit"

Definition at line 34 of file luasandbox.h.

#define LSB_LOG_LEVEL "log_level"

Definition at line 37 of file luasandbox.h.

#define LSB_LUA_CPATH "cpath"

Definition at line 39 of file luasandbox.h.

#define LSB_LUA_PATH "path"

Definition at line 38 of file luasandbox.h.

#define LSB_MEMORY_LIMIT "memory_limit"

Definition at line 33 of file luasandbox.h.

#define LSB_NIL_ERROR "<nil error message>"

Definition at line 40 of file luasandbox.h.

#define LSB_OUTPUT_LIMIT "output_limit"

Definition at line 36 of file luasandbox.h.

#define LSB_SHUTTING_DOWN "shutting down"

Definition at line 30 of file luasandbox.h.

#define LSB_THIS_PTR "lsb_this_ptr"

Definition at line 32 of file luasandbox.h.

Typedef Documentation

typedef struct lsb_lua_sandbox lsb_lua_sandbox

Definition at line 65 of file luasandbox.h.

Enumeration Type Documentation

enum lsb_state

Enumerator
LSB_UNKNOWN
LSB_RUNNING
LSB_TERMINATED
LSB_STOP

Definition at line 42 of file luasandbox.h.

enum lsb_usage_stat

Enumerator
LSB_US_LIMIT
LSB_US_CURRENT
LSB_US_MAXIMUM
LSB_US_MAX

Definition at line 49 of file luasandbox.h.

enum lsb_usage_type

Enumerator
LSB_UT_MEMORY
LSB_UT_INSTRUCTION
LSB_UT_OUTPUT
LSB_UT_MAX

Definition at line 57 of file luasandbox.h.

Function Documentation

LSB_EXPORT void lsb_add_function	(	lsb_lua_sandbox *	lsb,
		lua_CFunction	func,
		const char *	func_name
	)

Create a CFunction for use by the Sandbox.

The Lua sandbox pointer is pushed to upvalue index 1.

Parameters

lsb	Pointer to the sandbox.
func	Lua CFunction pointer.
func_name	Function name exposed to the Lua sandbox.

LSB_EXPORT lsb_lua_sandbox* lsb_create	(	void *	parent,
		const char *	lua_file,
		const char *	cfg,
		lsb_logger *	logger
	)

Allocates and initializes the structure around the Lua sandbox allowing full specification of the sandbox configuration using a Lua configuration string.

memory_limit = 1024*1024*1 instruction_limit = 10000 output_limit = 64*1024 path = '/modules/?.lua' cpath = '/modules/?.so' remove_entries = { [''] = {'collectgarbage','coroutine','dofile','load','loadfile','loadstring', 'newproxy','print'}, os = {'getenv','execute','exit','remove','rename','setlocale','tmpname'} } disable_modules = {io = 1}

Parameters

parent	Pointer to associate the owner to this sandbox.
lua_file	Filename of the Lua script to run in this sandbox.
cfg	Lua structure defining the full sandbox restrictions (may contain optional host configuration options, everything is available to the sandbox through the read_config API.
logger	Struct for error reporting/debug printing (NULL to disable)

Returns: lsb_lua_sandbox Sandbox pointer or NULL on failure.

LSB_EXPORT char* lsb_destroy ( lsb_lua_sandbox * lsb )

Frees the memory associated with the sandbox.

Parameters

lsb	Sandbox pointer to discard.

Returns: NULL on success, pointer to an error message on failure that MUST BE FREED by the caller.

LSB_EXPORT const char* lsb_get_error ( lsb_lua_sandbox * lsb )

Return the last error in human readable form.

Parameters

lsb	Pointer to the sandbox.

Returns: const char* error message

LSB_EXPORT const lsb_logger* lsb_get_logger ( lsb_lua_sandbox * lsb )

Access the logger struct stored in the sandbox.

The logger callback is only available to modules in debug mode (same as print).

Parameters

lsb	Pointer to the sandbox.

Returns: lsb_logger Pointer to the logger struct

LSB_EXPORT lua_State* lsb_get_lua ( lsb_lua_sandbox * lsb )

Access the Lua pointer.

Parameters

lsb	Pointer to the sandbox.

Returns: lua_State* The lua_State pointer.

LSB_EXPORT const char* lsb_get_lua_file ( lsb_lua_sandbox * lsb )

Returns the filename of the Lua source.

Parameters

lsb	Pointer to the sandbox.

Returns: const char* filename.

LSB_EXPORT void* lsb_get_parent ( lsb_lua_sandbox * lsb )

Access the parent pointer stored in the sandbox.

Parameters

lsb	Pointer to the sandbox.

Returns: void* The parent pointer passed to init.

LSB_EXPORT lsb_state lsb_get_state ( lsb_lua_sandbox * lsb )

Retrieve the current sandbox status.

Parameters

lsb	Pointer to the sandbox.

Returns: lsb_state code

LSB_EXPORT lsb_err_value lsb_init	(	lsb_lua_sandbox *	lsb,
		const char *	state_file
	)

Initializes the Lua sandbox and loads/runs the Lua script that was specified in lua_create_sandbox.

Parameters

lsb Pointer to the sandbox.

state_file Filename where the global data is read. Use a NULL or empty string for no data restoration. The global _PRESERVATION_VERSION variable will be examined during restoration; if the previous version does not match the current version the restoration will be aborted and the sandbox will start cleanly. _PRESERVATION_VERSION should be incremented any time an incompatible change is made to the global data schema. If no version is set the check will always succeed and a version of zero is assigned.

Returns: lsb_err_value NULL on success error message on failure

LSB_EXPORT lsb_err_value lsb_pcall_setup	(	lsb_lua_sandbox *	lsb,
		const char *	func_name
	)

Helper function to load the Lua function and set the instruction limits.

Parameters

lsb	Pointer to the sandbox.
func_name	Name of the function to load

Returns: lsb_err_value NULL on success error message on failure

LSB_EXPORT void lsb_pcall_teardown ( lsb_lua_sandbox * lsb )

Helper function to update the statistics after the call.

Parameters

lsb	Pointer to the sandbox.

LSB_EXPORT void lsb_set_error	(	lsb_lua_sandbox *	lsb,
		const char *	err
	)

Sets the last error string.

Parameters

lsb	Pointer to the sandbox.
err	Error message.

Returns: const char* error message

LSB_EXPORT void lsb_stop_sandbox ( lsb_lua_sandbox * lsb )

Aborts the running sandbox from a different thread of execution.

A "shutting down" Lua error message is generated.

Parameters

lsb	sandbox to abort

Returns

LSB_EXPORT void lsb_stop_sandbox_clean ( lsb_lua_sandbox * lsb )

Changes the sandbox state to LSB_STOP to allow for a clean exit.

This call is not thread safe.

Parameters

lsb	sandbox to clean stop

Returns

LSB_EXPORT void lsb_terminate	(	lsb_lua_sandbox *	lsb,
		const char *	err
	)

Change the sandbox state to LSB_TERMINATED due to a fatal error.

Parameters

lsb	Pointer to the sandbox.
err	Reason for termination

LSB_EXPORT size_t lsb_usage	(	lsb_lua_sandbox *	lsb,
		lsb_usage_type	utype,
		lsb_usage_stat	ustat
	)

Retrieve the sandbox usage statistics.

Parameters

lsb	Pointer to the sandbox.
utype	Type of statistic to retrieve i.e. memory.
ustat	Type of statistic to retrieve i.e. current.

Returns: size_t Count or number of bytes depending on the statistic.

Variable Documentation

LSB_EXPORT lsb_err_id LSB_ERR_INIT

LSB_EXPORT lsb_err_id LSB_ERR_LUA

LSB_EXPORT lsb_err_id LSB_ERR_TERMINATED

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation