suricata
util-lua-sandbox.h
Go to the documentation of this file.
1 /* Copyright (C) 2023-2024 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author Jo Johnson <pyrojoe314@gmail.com>
22  */
23 
24 #ifndef SURICATA_UTIL_LUA_SANDBOX_H
25 #define SURICATA_UTIL_LUA_SANDBOX_H
26 
27 #include "lua.h"
28 #include "suricata-common.h"
29 
30 /*
31  * Lua sandbox usage: The only needed changes to use the sandboxed lua state are
32  * to replace calls to lua_newstate and lua_close with SCLuaSbStateNew and SCLuaSbStateClose
33  * Additionally, SCLuaSbLoadRestricted can be used to load a restricted set of packages
34  * that prevent side effecting outside of the lua runtime
35  */
36 
37 /*
38  * Struct to store a lua_state and the additional metadata required to sandbox it
39  */
40 typedef struct SCLuaSbState {
42 
43  /* Allocation limits */
44  size_t alloc_bytes;
45  uint64_t alloc_limit;
46  uint64_t alloc_limit_cfg;
47  uint64_t alloc_baseline;
49  /* gross bytes allocated while the current call is open (between the
50  * Reset and the Update): the engine's setup pushes are not script
51  * memory; the gross count keeps a GC step during the setup from
52  * undercounting them via the previous call's reclaims */
54  /* lifetime gross bytes allocated; never decremented */
56 
57  /* Execution Limits */
60  // used by lua_sethook
62 
63  /* Errors. */
67 
68  /* invocation generation: bumped once per script invocation
69  * (LuaStateSetThreadVars); the dnp3 points cursor compares it to
70  * know its cached pointers are inside the invocation that set them */
71  uint64_t invocation_gen;
73 
74 /*
75  * Replaces luaL_newstate. Sets an upper bound for allocations and bytecode
76  * instructions for the lua runtime on this state.
77  *
78  * alloclimit - maximium number of bytes lua can allocate before receiving out of memory.
79  * A value of zero will not limit allocations
80  * instructionlimit - maximum number of lua bytecode instructions before an error is thrown
81  * A value of zero will not limit the number of instructions
82  */
83 lua_State *SCLuaSbStateNew(uint64_t alloclimit, uint64_t instructionlimit);
84 
85 /*
86  * Replaces lua_close. Handles freeing the SCLuaSbState
87  */
89 
90 /**
91  * Retreive the SCLuaSbState from a lua_State.
92  */
94 
95 /*
96  * Resets the instruction counter for the sandbox to 0
97  */
99 
100 /*
101  * Replaces luaL_openlibs. Only opens allowed packages for the sandbox and
102  * masks out dangerous functions from the base.
103  */
104 void SCLuaSbLoadLibs(lua_State *L);
105 
106 /* alloc_limit (max-bytes) handling. The cap is the configured limit on
107  * top of the state's setup-time baseline (loaded libs, the script chunk
108  * and whatever thread_init() stored), captured once on first use, plus
109  * the call's own inputs (the inspected buffer and args table, pushed
110  * between the Reset and the Update). Per-call working memory and values
111  * the script retains between calls both count against the configured
112  * limit, while the baseline and the call's own inputs do not. To give
113  * the setup code the freedom to push buffers without failing the cap, the
114  * limit is temporarily disabled while the per-call data is prepared and
115  * then restored.
116  *
117  * ```
118  * // get configured limit and reset active limit to 0
119  * const uint64_t cfg_limit = SCLuaSbResetBytesLimit(tlua->luastate);
120  * // push some data to the state
121  * LuaPushStringBuffer(tlua->luastate, input, (size_t)input_len);
122  * // restore the limit
123  * SCLuaSbRestoreBytesLimit(tlua->luastate, cfg_limit);
124  * // fix the cap at baseline + configured limit; the data pushed
125  * // between the Reset and the Update (the call's own inputs) stays exempt
126  * SCLuaSbUpdateBytesLimit(tlua->luastate);
127  *
128  * ... run script, lua_pcall...
129  *
130  * while (lua_gettop(tlua->luastate) > 0) {
131  * lua_pop(tlua->luastate, 1);
132  * }
133  * // restore the original alloc_limit
134  * SCLuaSbRestoreBytesLimit(tlua->luastate, cfg_limit);
135  * ```
136  */
137 
138 /*
139  * Resets the byte limit and returns the existing limit.
140  * Meant to be used to temporarily disable the limit during preparation
141  * time for a script to run. */
142 uint64_t SCLuaSbResetBytesLimit(lua_State *L);
143 
144 /*
145  * Fixes the cap at baseline + configured limit; the Reset->Update delta
146  * (the call's own inputs) stays exempt.
147  */
149 
150 /*
151  * Set the bytes limit. Meant to be used with the value returned from
152  * `SCLuaSbResetBytesLimit`
153  */
154 void SCLuaSbRestoreBytesLimit(lua_State *L, const uint64_t cfg_limit);
155 
156 #endif /* SURICATA_UTIL_LUA_SANDBOX_H */
SCLuaSbStateClose
void SCLuaSbStateClose(lua_State *sb)
Definition: util-lua-sandbox.c:384
SCLuaSbState::memory_limit_error
bool memory_limit_error
Definition: util-lua-sandbox.h:66
SCLuaSbState::alloc_baseline
uint64_t alloc_baseline
Definition: util-lua-sandbox.h:47
SCLuaSbUpdateBytesLimit
void SCLuaSbUpdateBytesLimit(lua_State *L)
Definition: util-lua-sandbox.c:429
SCLuaSbState
Definition: util-lua-sandbox.h:40
SCLuaSbState::hook_instruction_count
int hook_instruction_count
Definition: util-lua-sandbox.h:61
SCLuaSbState::L
lua_State * L
Definition: util-lua-sandbox.h:41
SCLuaSbLoadLibs
void SCLuaSbLoadLibs(lua_State *L)
Definition: util-lua-sandbox.c:290
SCLuaSbResetBytesLimit
uint64_t SCLuaSbResetBytesLimit(lua_State *L)
Definition: util-lua-sandbox.c:408
SCLuaSbState
struct SCLuaSbState SCLuaSbState
lua_State
struct lua_State lua_State
Definition: suricata-common.h:527
SCLuaSbRestoreBytesLimit
void SCLuaSbRestoreBytesLimit(lua_State *L, const uint64_t cfg_limit)
Definition: util-lua-sandbox.c:462
SCLuaSbState::invocation_gen
uint64_t invocation_gen
Definition: util-lua-sandbox.h:71
SCLuaSbResetInstructionCounter
void SCLuaSbResetInstructionCounter(lua_State *sb)
Definition: util-lua-sandbox.c:473
SCLuaSbState::alloc_baseline_done
bool alloc_baseline_done
Definition: util-lua-sandbox.h:48
SCLuaSbState::instruction_count
uint64_t instruction_count
Definition: util-lua-sandbox.h:58
SCLuaSbState::alloc_since_start
uint64_t alloc_since_start
Definition: util-lua-sandbox.h:53
SCLuaSbState::blocked_function_error
bool blocked_function_error
Definition: util-lua-sandbox.h:64
suricata-common.h
SCLuaSbState::instruction_limit
uint64_t instruction_limit
Definition: util-lua-sandbox.h:59
SCLuaSbState::alloc_bytes_allocated
uint64_t alloc_bytes_allocated
Definition: util-lua-sandbox.h:55
SCLuaSbState::alloc_bytes
size_t alloc_bytes
Definition: util-lua-sandbox.h:44
SCLuaSbState::alloc_limit
uint64_t alloc_limit
Definition: util-lua-sandbox.h:45
SCLuaSbState::instruction_count_error
bool instruction_count_error
Definition: util-lua-sandbox.h:65
SCLuaSbGetContext
SCLuaSbState * SCLuaSbGetContext(lua_State *L)
Definition: util-lua-sandbox.c:375
SCLuaSbStateNew
lua_State * SCLuaSbStateNew(uint64_t alloclimit, uint64_t instructionlimit)
Allocate a new Lua sandbox.
Definition: util-lua-sandbox.c:342
SCLuaSbState::alloc_limit_cfg
uint64_t alloc_limit_cfg
Definition: util-lua-sandbox.h:46