Skip to content

Commit 902ed95

Browse files
author
git_repo_user
committed
Add Groovy sandbox whitelist
1 parent 5361a6c commit 902ed95

File tree

4 files changed

+195
-11
lines changed

4 files changed

+195
-11
lines changed

source/includes/groovy-sandbox-configuration.rst

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,19 @@
1-
When a Groovy script is executed all code is validated against a blacklist of insecure expressions to prevent code that could
2-
compromise the system. When you try to execute a script that contains insecure expressions you will see an error
3-
similar to this:
1+
When a Groovy script is executed all code is validated against either a whitelist of allowed expressions and/or a blacklist
2+
of insecure expressions, depending on what is used by your installation, to prevent code that could compromise the system.
3+
4+
When you try to execute a script that contains insecure expressions from the blacklist, or contains an expression not in
5+
the whitelist depending on your configuration, you will see an error similar to this:
46

57
.. code-block:: none
68
:caption: *Error message encountered for scripts containing insecure expressions*
79
8-
UnsupportedOperationException: Insecure call staticMethod java.lang.Runtime getRuntime ...
10+
UnsupportedOperationException: Insecure call to staticMethod java.lang.Runtime getRuntime ...
911
1012
|
1113
12-
It is recommended to keep the default configuration if possible. However, if access to one or more of the blacklisted expressions
13-
is required, it is possible to override the blacklist configuration. Configuration is global and affects all scripts on the server.
14+
It is recommended to keep the default configuration if possible. However, if access to one or more of the blacklisted
15+
expressions is required, or access to one or more expressions not in the whitelist is required, it is possible to
16+
override the blacklist and/or whitelist configuration. Configuration is global and affects all scripts on the server.
1417

1518
.. warning:: When you allow a script to make an insecure call you should make sure it can only be executed with known
1619
arguments and **never** with unverified user input.

source/reference/modules/deployer.rst

Lines changed: 70 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
:is-up-to-date: True
2-
:last-updated: 4.2.2
3-
:orphan:
2+
:last-updated: 4.5.0
43

54
.. index:: Modules; Crafter Deployer
65

@@ -942,6 +941,7 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
942941
.. code-block:: yaml
943942
:linenos:
944943
:caption: *CRAFTER_HOME/bin/crafter-deployer/config/application.yaml*
944+
:emphasize-lines: 6
945945
946946
deployer:
947947
main:
@@ -956,6 +956,16 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
956956
# The location of the blacklist to use for all targets
957957
# (this will have no effect if the sandbox is disabled)
958958
path: 'classpath:groovy/blacklist'
959+
whitelist:
960+
# Indicates if the whitelist should be enabled for all targets
961+
# (this will have no effect if the sandbox is disabled)
962+
enabled: true
963+
# The location of the whitelist to use for all targets
964+
# (this will have no effect if the sandbox is disabled)
965+
path: 'file:${deployer.main.config.folderPath}/groovy/whitelist,classpath:groovy/whitelist'
966+
# List of patterns for that is allowed to call as `staticMethod java.lang.System getenv java.lang.String` parameter (regexes separated by commas)
967+
# NOTE: This property is applied even if the whitelist is disabled
968+
getenvRegex: crafter_.*
959969
960970
|
961971
@@ -987,6 +997,8 @@ To use a custom blacklist follow these steps:
987997

988998
Now you can execute the same script without any issues.
989999

1000+
|
1001+
9901002
"""""""""""""""""""""""""""""""
9911003
Disabling the Sandbox Blacklist
9921004
"""""""""""""""""""""""""""""""
@@ -1005,6 +1017,62 @@ restrictions. To disable the blacklist for all targets update the ``application.
10051017
10061018
|
10071019
1020+
""""""""""""""""""""""""
1021+
Using a Custom Whitelist
1022+
""""""""""""""""""""""""
1023+
.. version_tag::
1024+
:label: Since
1025+
:version: 4.5.0
1026+
1027+
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.
1028+
1029+
To use a custom whitelist follow these steps:
1030+
1031+
#. Copy the default whitelist file to your classpath, for example:
1032+
1033+
``CRAFTER_HOME/bin/crafter-deployer/groovy/whitelist``
1034+
1035+
#. Remove or comment (adding a ``#`` at the beginning of the line) or add the expressions that your scripts require
1036+
#. Update the ``application.yaml`` configuration file to load the custom whitelist:
1037+
1038+
.. code-block:: yaml
1039+
:caption: ``CRAFTER_HOME/bin/crafter-deployer/config/application.yaml``
1040+
1041+
sandbox:
1042+
whitelist:
1043+
# The location of the whitelist to use for all targets
1044+
# (this will have no effect if the sandbox is disabled)
1045+
path: 'file:${deployer.main.config.folderPath}/groovy/whitelist,classpath:groovy/whitelist'
1046+
1047+
#. Restart CrafterCMS
1048+
1049+
Now you can execute the same script without any issues.
1050+
1051+
|
1052+
1053+
"""""""""""""""""""""""""""""""
1054+
Disabling the Sandbox Whitelist
1055+
"""""""""""""""""""""""""""""""
1056+
.. version_tag::
1057+
:label: Since
1058+
:version: 4.5.0
1059+
1060+
It is possible to disable the whitelist to allow the execution of most expressions, in
1061+
case you need to use a considerable number of the expression not included in the whitelist while keeping some basic
1062+
restrictions.
1063+
1064+
To disable the whitelist for all targets update the ``application.yaml`` configuration file:
1065+
1066+
.. code-block:: yaml
1067+
:caption: *CRAFTER_HOME/bin/crafter-deployer/config/application.yaml*
1068+
1069+
sandbox:
1070+
whitelist:
1071+
# Indicates if the whitelist should be enabled for all targets
1072+
# (this will have no effect if the sandbox is disabled)
1073+
enabled: true
1074+
1075+
10081076
"""""""""""""""""""
10091077
Grape Configuration
10101078
"""""""""""""""""""

source/reference/modules/engine.rst

Lines changed: 61 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
:is-up-to-date: True
2-
:last-updated: 4.3.1
2+
:last-updated: 4.5.0
33

44
.. _crafter-engine:
55

@@ -3754,13 +3754,18 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
37543754
.. code-block:: properties
37553755
:linenos:
37563756
:caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
3757+
:emphasize-lines: 2
37573758
37583759
# Indicates if the sandbox should be enabled for all sites
37593760
crafter.engine.groovy.sandbox.enable=true
37603761
# Indicates if the blacklist should be enabled for all sites (this will have no effect if the sandbox is disabled)
37613762
crafter.engine.groovy.sandbox.blacklist.enable=true
37623763
# The location of the default blacklist to use for all sites (this will have no effect if the sandbox is disabled)
37633764
crafter.engine.groovy.sandbox.blacklist.path=classpath:crafter/engine/groovy/blacklist
3765+
# Indicates if the whitelist should be enabled for all sites (this will have no effect if the sandbox is disabled)
3766+
crafter.engine.groovy.sandbox.whitelist.enable=true
3767+
# The location of the default whitelist to use for all sites (this will have no effect if the sandbox is disabled)
3768+
crafter.engine.groovy.sandbox.whitelist.path=classpath:crafter/engine/groovy/whitelist
37643769
37653770
|
37663771
@@ -3792,6 +3797,8 @@ To use a custom blacklist follow these steps:
37923797
37933798
Now you can execute the same script without any issues.
37943799
3800+
|
3801+
37953802
"""""""""""""""""""""""""""""""
37963803
Disabling the Sandbox Blacklist
37973804
"""""""""""""""""""""""""""""""
@@ -3808,6 +3815,59 @@ restrictions. To disable the blacklist for all projects/sites update the server
38083815
38093816
|
38103817
3818+
""""""""""""""""""""""""
3819+
Using a Custom Whitelist
3820+
""""""""""""""""""""""""
3821+
.. version_tag::
3822+
:label: Since
3823+
:version: 4.5.0
3824+
3825+
Crafter Engine includes a default whitelist that you can find
3826+
`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.
3827+
3828+
To use a custom whitelist follow these steps:
3829+
3830+
#. Copy the default whitelist file to your classpath, for example:
3831+
3832+
``CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/groovy/whitelist``
3833+
3834+
#. Remove or comment (adding a ``#`` at the beginning of the line) or add the expressions that your scripts require
3835+
#. Update the :ref:`server-config.properties <engine-configuration-files>` configuration file to load the custom whitelist:
3836+
3837+
.. code-block:: properties
3838+
:caption: ``CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties``
3839+
3840+
# The location of the whitelist to use for all sites (this will have no effect if the sandbox is disabled)
3841+
crafter.engine.groovy.sandbox.whitelist.path=classpath:crafter/engine/extension/groovy/whitelist
3842+
3843+
#. Restart CrafterCMS
3844+
3845+
Now you can execute the same script without any issues.
3846+
3847+
|
3848+
3849+
"""""""""""""""""""""""""""""""
3850+
Disabling the Sandbox Whitelist
3851+
"""""""""""""""""""""""""""""""
3852+
.. version_tag::
3853+
:label: Since
3854+
:version: 4.5.0
3855+
3856+
It is possible to disable the whitelist to allow the execution of most expressions, in
3857+
case you need to use a considerable number of the expression not included in the whitelist while keeping some basic
3858+
restrictions.
3859+
3860+
To disable the whitelist for all projects/sites update the server configuration file
3861+
:ref:`server-config.properties <engine-configuration-files>`:
3862+
3863+
.. code-block:: properties
3864+
:caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties*
3865+
3866+
# Indicates if the whitelist should be enabled for all sites (this will have no effect if the sandbox is disabled)
3867+
crafter.engine.groovy.sandbox.whitelist.enable=false
3868+
3869+
|
3870+
38113871
"""""""""""""""""""
38123872
Grape Configuration
38133873
"""""""""""""""""""

source/reference/modules/studio.rst

Lines changed: 55 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
:is-up-to-date: True
2-
:last-updated: 4.4.3
2+
:last-updated: 4.5.0
33

44
.. highlight:: xml
55

@@ -5192,7 +5192,7 @@ The Groovy sandbox is enabled by default and can be disabled by changing the pro
51925192
Using a Custom Blacklist
51935193
~~~~~~~~~~~~~~~~~~~~~~~~
51945194
Crafter Studio includes a default blacklist that you can find
5195-
`here <https://github.com/craftercms/studio/blob/support/4.x/src/main/resources/crafter/studio/groovy/blacklist>`_.
5195+
`here <https://github.com/craftercms/studio/blob/support/4.x/src/main/resources/crafter/studio/groovy/blacklist>`__.
51965196
Make sure you review the branch/tag you're using.
51975197

51985198
To use a custom blacklist follow these steps:
@@ -5214,6 +5214,8 @@ To use a custom blacklist follow these steps:
52145214

52155215
Now you can execute the same script without any issues.
52165216

5217+
|
5218+
52175219
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52185220
Disabling the Sandbox Blacklist
52195221
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -5229,6 +5231,57 @@ the blacklist for all projects/sites update the ``studio-config-override.yaml``
52295231
52305232
|
52315233
5234+
~~~~~~~~~~~~~~~~~~~~~~~~
5235+
Using a Custom Whitelist
5236+
~~~~~~~~~~~~~~~~~~~~~~~~
5237+
.. version_tag::
5238+
:label: Since
5239+
:version: 4.5.0
5240+
5241+
Crafter Studio includes a default whitelist that you can find
5242+
`here <https://github.com/craftercms/studio/blob/support/4.x/src/main/resources/crafter/studio/groovy/whitelist>`__.
5243+
Make sure you review the branch/tag you're using.
5244+
5245+
To use a custom whitelist follow these steps:
5246+
5247+
#. Copy the default whitelist file to your classpath, for example:
5248+
5249+
``CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/groovy/whitelist``
5250+
5251+
#. Remove or comment (adding a ``#`` at the beginning of the line) the expressions that your scripts require
5252+
#. Update the ``studio-config-override.yaml`` configuration file to load the custom whitelist:
5253+
5254+
.. code-block:: yaml
5255+
:caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml*
5256+
5257+
# The location of the default whitelist to use (this will have no effect if the sandbox is disabled)
5258+
studio.scripting.sandbox.blacklist.path: classpath:crafter/studio/groovy/whitelist
5259+
5260+
#. Restart CrafterCMS
5261+
5262+
Now you can execute the same script without any issues.
5263+
5264+
|
5265+
5266+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5267+
Disabling the Sandbox Whitelist
5268+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5269+
.. version_tag::
5270+
:label: Since
5271+
:version: 4.5.0
5272+
5273+
It is possible to disable the whitelist to allow the execution of most expressions, in case you need to use a
5274+
considerable number of expressions not included in the whitelist while keeping some basic restrictions. To disable
5275+
the whitelist for all projects/sites update the ``studio-config-override.yaml`` configuration file:
5276+
5277+
.. code-block:: yaml
5278+
:caption: *CRAFTER_HOME/bin/apache-tomcat/shared/classes/crafter/studio/extension/studio-config-override.yaml*
5279+
5280+
# Indicates if the whitelist should be enabled (this will have no effect if the sandbox is disabled)
5281+
studio.scripting.sandbox.whitelist.enable: false
5282+
5283+
|
5284+
52325285
~~~~~~~~~~~~~~~~~~~
52335286
Grape Configuration
52345287
~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)