Add Groovy sandbox whitelist

git_repo_user · git_repo_user · commit 902ed9554130 · 2025-09-15T17:49:29.000-04:00
diff --git a/source/includes/groovy-sandbox-configuration.rst b/source/includes/groovy-sandbox-configuration.rst
@@ -1,16 +1,19 @@
-When a Groovy script is executed all code is validated against a blacklist of insecure expressions to prevent code that could
-compromise the system. When you try to execute a script that contains insecure expressions you will see an error
-similar to this:
+When a Groovy script is executed all code is validated against either a whitelist of allowed expressions and/or a blacklist
+of insecure expressions, depending on what is used by your installation, to prevent code that could compromise the system.
+
+When you try to execute a script that contains insecure expressions from the blacklist, or contains an expression not in
+the whitelist depending on your configuration, you will see an error similar to this:
 
 .. code-block:: none
     :caption: *Error message encountered for scripts containing insecure expressions*
 
-    UnsupportedOperationException: Insecure call staticMethod java.lang.Runtime getRuntime ...
+    UnsupportedOperationException: Insecure call to staticMethod java.lang.Runtime getRuntime ...
 
 |
 
-It is recommended to keep the default configuration if possible. However, if access to one or more of the blacklisted expressions
-is required, it is possible to override the blacklist configuration. Configuration is global and affects all scripts on the server.
+It is recommended to keep the default configuration if possible. However, if access to one or more of the blacklisted
+expressions is required, or access to one or more expressions not in the whitelist is required, it is possible to
+override the blacklist and/or whitelist configuration. Configuration is global and affects all scripts on the server.
 
 .. warning:: When you allow a script to make an insecure call you should make sure it can only be executed with known
              arguments and **never** with unverified user input.
diff --git a/source/reference/modules/deployer.rst b/source/reference/modules/deployer.rst
@@ -1,6 +1,5 @@
 :is-up-to-date: True
-:last-updated: 4.2.2
-:orphan:
+:last-updated: 4.5.0
 
 .. index:: Modules; Crafter Deployer
 
@@ -942,6 +941,7 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
 .. code-block:: yaml
     :linenos:
     :caption: *CRAFTER_HOME/bin/crafter-deployer/config/application.yaml*
+    :emphasize-lines: 6
 
     deployer:
       main:
@@ -956,6 +956,16 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
               # The location of the blacklist to use for all targets
               # (this will have no effect if the sandbox is disabled)
               path: 'classpath:groovy/blacklist'
+            whitelist:
+              # Indicates if the whitelist should be enabled for all targets
+              # (this will have no effect if the sandbox is disabled)
+              enabled: true
+              # The location of the whitelist to use for all targets
+              # (this will have no effect if the sandbox is disabled)
+              path: 'file:${deployer.main.config.folderPath}/groovy/whitelist,classpath:groovy/whitelist'
+              # List of patterns for that is allowed to call as `staticMethod java.lang.System getenv java.lang.String` parameter (regexes separated by commas)
+              # NOTE: This property is applied even if the whitelist is disabled
+              getenvRegex: crafter_.*
 
 |
 
@@ -987,6 +997,8 @@ To use a custom blacklist follow these steps:
 
 Now you can execute the same script without any issues.
 
+|
+
 """""""""""""""""""""""""""""""
 Disabling the Sandbox Blacklist
 """""""""""""""""""""""""""""""
@@ -1005,6 +1017,62 @@ restrictions. To disable the blacklist for all targets update the ``application.
 
 |
 
+""""""""""""""""""""""""
+Using a Custom Whitelist
+""""""""""""""""""""""""
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+Crafter Deployer includes a default whitelist that you can find `here <https://github.com/craftercms/deployer/blob/support/4.x/src/main/resources/groovy/whitelist>`__. Make sure you review the branch/tag you're using.
+
+To use a custom whitelist follow these steps:
+
+#. Copy the default whitelist file to your classpath, for example:
+
+    ``CRAFTER_HOME/bin/crafter-deployer/groovy/whitelist``
+
+#. Remove or comment (adding a ``#`` at the beginning of the line) or add the expressions that your scripts require
+#. Update the ``application.yaml`` configuration file to load the custom whitelist:
+
+    .. code-block:: yaml
+        :caption: ``CRAFTER_HOME/bin/crafter-deployer/config/application.yaml``
+
+        sandbox:
+          whitelist:
+            # The location of the whitelist to use for all targets
+            # (this will have no effect if the sandbox is disabled)
+            path: 'file:${deployer.main.config.folderPath}/groovy/whitelist,classpath:groovy/whitelist'
+
+#. Restart CrafterCMS
+
+Now you can execute the same script without any issues.
+
+|
+
+"""""""""""""""""""""""""""""""
+Disabling the Sandbox Whitelist
+"""""""""""""""""""""""""""""""
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+It is possible to disable the whitelist to allow the execution of most expressions, in
+case you need to use a considerable number of the expression not included in the whitelist while keeping some basic
+restrictions.
+
+To disable the whitelist for all targets update the ``application.yaml`` configuration file:
+
+.. code-block:: yaml
+    :caption: *CRAFTER_HOME/bin/crafter-deployer/config/application.yaml*
+
+    sandbox:
+      whitelist:
+        # Indicates if the whitelist should be enabled for all targets
+        # (this will have no effect if the sandbox is disabled)
+        enabled: true
+
+
 """""""""""""""""""
 Grape Configuration
 """""""""""""""""""
diff --git a/source/reference/modules/engine.rst b/source/reference/modules/engine.rst
@@ -1,5 +1,5 @@
 :is-up-to-date: True
-:last-updated: 4.3.1
+:last-updated: 4.5.0
 
 .. _crafter-engine:
 
@@ -3754,13 +3754,18 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
 .. code-block:: properties
    :linenos:
    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
+   :emphasize-lines: 2
 
    # Indicates if the sandbox should be enabled for all sites
    crafter.engine.groovy.sandbox.enable=true
    # Indicates if the blacklist should be enabled for all sites (this will have no effect if the sandbox is disabled)
    crafter.engine.groovy.sandbox.blacklist.enable=true
    # The location of the default blacklist to use for all sites (this will have no effect if the sandbox is disabled)
    crafter.engine.groovy.sandbox.blacklist.path=classpath:crafter/engine/groovy/blacklist
+   # Indicates if the whitelist should be enabled for all sites (this will have no effect if the sandbox is disabled)
+   crafter.engine.groovy.sandbox.whitelist.enable=true
+   # The location of the default whitelist to use for all sites (this will have no effect if the sandbox is disabled)
+   crafter.engine.groovy.sandbox.whitelist.path=classpath:crafter/engine/groovy/whitelist
 
 |
 
@@ -3792,6 +3797,8 @@ To use a custom blacklist follow these steps:
 
 Now you can execute the same script without any issues.
 
+|
+
 """""""""""""""""""""""""""""""
 Disabling the Sandbox Blacklist
 """""""""""""""""""""""""""""""
@@ -3808,6 +3815,59 @@ restrictions. To disable the blacklist for all projects/sites update the server
 
 |
 
+""""""""""""""""""""""""
+Using a Custom Whitelist
+""""""""""""""""""""""""
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+Crafter Engine includes a default whitelist that you can find
+`here <https://github.com/craftercms/engine/blob/support/4.x/src/main/resources/crafter/engine/groovy/whitelist>`__. Make sure you review the branch/tag you're using.
+
+To use a custom whitelist follow these steps:
+
+#. Copy the default whitelist file to your classpath, for example:
+
+    ``CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/groovy/whitelist``
+
+#. Remove or comment (adding a ``#`` at the beginning of the line) or add the expressions that your scripts require
+#. Update the :ref:`server-config.properties <engine-configuration-files>` configuration file to load the custom whitelist:
+
+   .. code-block:: properties
+       :caption: ``CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties``
+
+       # The location of the whitelist to use for all sites (this will have no effect if the sandbox is disabled)
+       crafter.engine.groovy.sandbox.whitelist.path=classpath:crafter/engine/extension/groovy/whitelist
+
+#. Restart CrafterCMS
+
+Now you can execute the same script without any issues.
+
+|
+
+"""""""""""""""""""""""""""""""
+Disabling the Sandbox Whitelist
+"""""""""""""""""""""""""""""""
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+It is possible to disable the whitelist to allow the execution of most expressions, in
+case you need to use a considerable number of the expression not included in the whitelist while keeping some basic
+restrictions.
+
+To disable the whitelist for all projects/sites update the server configuration file
+:ref:`server-config.properties <engine-configuration-files>`:
+
+.. code-block:: properties
+  :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
+
+  # Indicates if the whitelist should be enabled for all sites (this will have no effect if the sandbox is disabled)
+  crafter.engine.groovy.sandbox.whitelist.enable=false
+
+|
+
 """""""""""""""""""
 Grape Configuration
 """""""""""""""""""
diff --git a/source/reference/modules/studio.rst b/source/reference/modules/studio.rst
@@ -1,5 +1,5 @@
 :is-up-to-date: True
-:last-updated: 4.4.3
+:last-updated: 4.5.0
 
 .. highlight:: xml
 
@@ -5192,7 +5192,7 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
 Using a Custom Blacklist
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Crafter Studio includes a default blacklist that you can find
-`here <https://github.com/craftercms/studio/blob/support/4.x/src/main/resources/crafter/studio/groovy/blacklist>`_.
+`here <https://github.com/craftercms/studio/blob/support/4.x/src/main/resources/crafter/studio/groovy/blacklist>`__.
 Make sure you review the branch/tag you're using.
 
 To use a custom blacklist follow these steps:
@@ -5214,6 +5214,8 @@ To use a custom blacklist follow these steps:
 
 Now you can execute the same script without any issues.
 
+|
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Disabling the Sandbox Blacklist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -5229,6 +5231,57 @@ the blacklist for all projects/sites update the ``studio-config-override.yaml``
 
 |
 
+~~~~~~~~~~~~~~~~~~~~~~~~
+Using a Custom Whitelist
+~~~~~~~~~~~~~~~~~~~~~~~~
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+Crafter Studio includes a default whitelist that you can find
+`here <https://github.com/craftercms/studio/blob/support/4.x/src/main/resources/crafter/studio/groovy/whitelist>`__.
+Make sure you review the branch/tag you're using.
+
+To use a custom whitelist follow these steps:
+
+#. Copy the default whitelist file to your classpath, for example:
+
+    ``CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/groovy/whitelist``
+
+#. Remove or comment (adding a ``#`` at the beginning of the line) the expressions that your scripts require
+#. Update the ``studio-config-override.yaml`` configuration file to load the custom whitelist:
+
+    .. code-block:: yaml
+        :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml*
+
+        # The location of the default whitelist to use (this will have no effect if the sandbox is disabled)
+        studio.scripting.sandbox.blacklist.path: classpath:crafter/studio/groovy/whitelist
+
+#. Restart CrafterCMS
+
+Now you can execute the same script without any issues.
+
+|
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Disabling the Sandbox Whitelist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+It is possible to disable the whitelist to allow the execution of most expressions, in case you need to use a
+considerable number of expressions not included in the whitelist while keeping some basic restrictions. To disable
+the whitelist for all projects/sites update the ``studio-config-override.yaml`` configuration file:
+
+.. code-block:: yaml
+    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml*
+
+    # Indicates if the whitelist should be enabled (this will have no effect if the sandbox is disabled)
+    studio.scripting.sandbox.whitelist.enable: false
+
+|
+
 ~~~~~~~~~~~~~~~~~~~
 Grape Configuration
 ~~~~~~~~~~~~~~~~~~~
