doc: Initial doc for lua sandbox

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index 0d075ea3c9738554cb29229d0cff8dea6f6d73cd..f050cba971b6486714f7bed5f73979c27c39459f 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -2784,11 +2784,14 @@ Beyond suricata.yaml, other ways to harden Suricata are
 - compilation : enabling ASLR and other exploit mitigation techniques.
 - environment : running Suricata on a device that has no direct access to Internet.
 
+.. _suricata-yaml-lua-config:
+
 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:
 
 ::
 
@@ -2797,3 +2800,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
index 80c926e135d1b9886c836c65a7b2cbeb2c86e77e..56412cb7d59ea41404b4231783f55abc90ddeb53 100644 (file)
--- 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-lua-config`
+
+.. 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).