doc: Initial doc for lua sandbox

J0eJ0h · Feb 5, 2024 · 678c84f · 678c84f
1 parent 19a55dc
commit 678c84f
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 3 deletions.
diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
@@ -2752,8 +2752,9 @@ Beyond suricata.yaml, other ways to harden Suricata are
 Lua
 ~~~
 
-Suricata 7.0 disables Lua rules by default. Lua rules can be enabled
-in the ``security.lua`` section of the configuration file:
+Suricata 8.0 sandboxes Lua rules by default. The restrictions on the sandbox for Lua rules can be
+modified in the ``security.lua`` section of the configuration file.  Additionally, Lua rules 
+can be completely disabled the same as the Suricata 7.0 default:
 
 ::
 
@@ -2762,3 +2763,12 @@ in the ``security.lua`` section of the configuration file:
        # Allow Lua rules. Disabled by default.
        #allow-rules: false
 
+       # Upper bound of allocations by a Lua rule before it will fail
+       #max-bytes: 500000 
+
+       # Upper bound of lua instructions by a Lua rule before it will fail
+       #max-instructions: 500000
+
+       # Allow dangerous lua operations like external packages and file io
+       #allow-restricted-functions: false
+
diff --git a/doc/userguide/rules/lua-detection.rst b/doc/userguide/rules/lua-detection.rst
@@ -15,7 +15,8 @@ Syntax:
 
 The script filename will be appended to your default rules location.
 
-The script has 2 parts, an init function and a match function. First, the init.
+The script has 2 parts, an init function and a match function. First, the init.  
+Additionally, the script will run in a limited sandbox by default.
 
 Init function
 -------------
@@ -100,5 +101,28 @@ Entire script:
 
   return 0
 
+Sandbox and Available functions
+-------------------------------
+
+By default, the maximum memory and lua instruction count per execution of a detection rule will be limited.  Additionally,
+The following libraries and functions are blocked:
+* package
+* coroutine
+* io
+* os
+* collectgarbage
+* dofile
+* getmetatable
+* loadfile
+* load
+* pcall
+* setmetatable
+* xpcall
+* string.rep
+
+This behavior can be modified via the ``security.lua`` section of :ref:`suricata-yaml`
+
+.. note:: Suricata 8.0 has moved to Lua 5.4 and has builtin support for bitwise and utf8 operations now.
+
 A comprehensive list of existing lua functions -  with examples - can be found at :ref:`lua-functions` (some of them, however,
 work only for the lua-output functionality).