Add Groovy sandbox whitelist

source/includes/groovy-grape-install.rst

@@ -0,0 +1,19 @@
+Administrators can install new grapes from the command line.
+To install, go to the ``CRAFTER_HOME/bin`` directory, then run the following command:
+
+.. code-block:: bash
+    :caption: *Install new grapes from the command line*
+
+    ./groovy/bin/grape -Dgrape.root=. install <GROUP ID> <ARTIFACT ID> <VERSION>
+
+For example, to install `Semver4j version 3.1.0 <https://github.com/vdurmont/semver4j>`__ from the command line, we'll
+use the following values:
+
+- <GROUP ID>: ``com.vdurmont``
+- <ARTIFACT ID>: ``semver4j``
+- <VERSION>: ``3.1.0``
+
+.. code-block:: bash
+    :caption: *Example installing semver4j (new grape) from the command line*
+
+    ./groovy/bin/grape -Dgrape.root=. install com.vdurmont semver4j 3.1.0

source/includes/groovy-sandbox-configuration.rst

@@ -1,16 +1,20 @@
-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 to prevent operations that could compromise the system.
+Depending on your installation, validation may use a whitelist (allowed expressions), a blacklist (blocked expressions),
+or both. If both are enabled, an expression must be allowed by the whitelist and must not match the blacklist.
+
+When you try to execute a script that contains an expression not included in the whitelist, or an expression blocked by
+the blacklist , you’ll see an error similar to the following:
 
 .. 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. 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.

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,16 +1017,111 @@ 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/config/groovy/whitelist``
+
+#. Add, remove or comment (adding a ``#`` at the beginning of the line) 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 expressions 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: false
+
+|
+
 """""""""""""""""""
 Grape Configuration
 """""""""""""""""""
 .. include:: /includes/groovy-grape-configuration.rst
 
+|
+
+"""""""""""""""
+Grapes Download
+"""""""""""""""
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+The following allows you to enable or disable automatic Groovy dependency (grapes) downloads for scripts (@grab):
+
+.. code-block:: yaml
+    :caption: *CRAFTER_HOME/bin/crafter-deployer/config/application.yaml*
+    :emphasize-lines: 8
+
+    deployer:
+        main:
+            scripting:
+                grapes:
+                    # Indicates if grapes automatic downloading should be enabled for all targets
+                    # If false, already downloaded grapes will be used, but no new grapes will be downloaded
+                    download:
+                        enabled: false
+
+Automatic grapes download is disabled by default. Set ``deployer.main.scripting.grapes.download.enabled`` to true to
+enable automatic grapes download.
+
+|
+
+"""""""""""""""""""""""""""""""""""""""
+Installing Grapes from the Command Line
+"""""""""""""""""""""""""""""""""""""""
+.. include:: /includes/groovy-grape-install.rst
+
+|
+
 """""""""""""""
 Important Notes
 """""""""""""""
 .. include:: /includes/groovy-sandbox-important-notes.rst
 
+|
+
 ^^^^^^^^^^^^^^^^^^^^
 Cipher Configuration
 ^^^^^^^^^^^^^^^^^^^^

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,11 +3815,95 @@ 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``
+
+#. Add, remove or comment (adding a ``#`` at the beginning of the line) 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
 """""""""""""""""""
 .. include:: /includes/groovy-grape-configuration.rst
 
+|
+
+"""""""""""""""
+Grapes Download
+"""""""""""""""
+.. version_tag::
+    :label: Since
+    :version: 4.5.0
+
+The following allows you to enable or disable automatic Groovy dependency (grapes) downloads for scripts (@grab):
+
+.. code-block:: properties
+    :caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
+    :emphasize-lines: 3
+
+    # Indicates if @Grab annotations should download grapes
+    # If false, only already downloaded grapes will be available
+    crafter.engine.groovy.grapes.download.enabled=false
+
+Automatic grapes download is disabled by default. Set ``crafter.engine.groovy.grapes.download.enabled`` to true to
+ enable automatic grapes download.
+
+|
+
+"""""""""""""""""""""""""""""""""""""""
+Installing Grapes from the Command Line
+"""""""""""""""""""""""""""""""""""""""
+.. include:: /includes/groovy-grape-install.rst
+
+|
+
 """""""""""""""
 Important Notes
 """""""""""""""