SecureASTCustomizer (Groovy 2.4.14)
Date: 2018-02-24

org.codehaus.groovy.control.customizers

## Class SecureASTCustomizer

- java.lang.Object
- - org.codehaus.groovy.control.CompilationUnit.PrimaryClassNodeOperation
  - - org.codehaus.groovy.control.customizers.CompilationCustomizer
    - - org.codehaus.groovy.control.customizers.SecureASTCustomizer

-     public class SecureASTCustomizer
      extends CompilationCustomizer

  This customizer allows securing source code by controlling what code constructs are allowed. For example, if you only want to allow arithmetic operations in a groovy shell, you can configure this customizer to restrict package imports, method calls and so on.

  Most of the security customization options found in this class work with either blacklist or whitelist. This means that, for a single option, you can set a whitelist OR a blacklist, but not both. You can mix whitelist/blacklist strategies for different options. For example, you can have import whitelist and tokens blacklist.

  The recommended way of securing shells is to use whitelists because it is guaranteed that future features of the Groovy language won't be allowed by defaut. Using blacklists, you can limit the features of the languages by opting out, but new language features would require you to update your configuration.

  If you set neither a whitelist nor a blacklist, then everything is authorized.

  Combinations of import and star imports constraints are authorized as long as you use the same type of list for both. For example, you may use an import whitelist and a star import whitelist together, but you cannot use an import white list with a star import blacklist. static imports are handled separately, meaning that blacklisting an import does not prevent from using a static import.

  Eventually, if the features provided here are not sufficient, you may implement custom AST filtering handlers, either implementing the `SecureASTCustomizer.StatementChecker` interface or `SecureASTCustomizer.ExpressionChecker` interface then register your handlers thanks to the `addExpressionCheckers(org.codehaus.groovy.control.customizers.SecureASTCustomizer.ExpressionChecker...)` and `addStatementCheckers(org.codehaus.groovy.control.customizers.SecureASTCustomizer.StatementChecker...)` methods.

  Here is an example of usage. We will create a groovy classloader which only supports arithmetic operations and imports the java.lang.Math classes by default.

       final ImportCustomizer imports = new ImportCustomizer().addStaticStars('java.lang.Math') // add static import of java.lang.Math
                   final SecureASTCustomizer secure = new SecureASTCustomizer()
                   secure.with {
                       closuresAllowed = false
                       methodDefinitionAllowed = false

                       importsWhitelist = []
                       staticImportsWhitelist = []
                       staticStarImportsWhitelist = ['java.lang.Math'] // only java.lang.Math is allowed

                       tokensWhitelist = [
                               PLUS,
                               MINUS,
                               MULTIPLY,
                               DIVIDE,
                               MOD,
                               POWER,
                               PLUS_PLUS,
                               MINUS_MINUS,
                               COMPARE_EQUAL,
                               COMPARE_NOT_EQUAL,
                               COMPARE_LESS_THAN,
                               COMPARE_LESS_THAN_EQUAL,
                               COMPARE_GREATER_THAN,
                               COMPARE_GREATER_THAN_EQUAL,
                       ].asImmutable()

                       constantTypesClassesWhiteList = [
                               Integer,
                               Float,
                               Long,
                               Double,
                               BigDecimal,
                               Integer.TYPE,
                               Long.TYPE,
                               Float.TYPE,
                               Double.TYPE
                       ].asImmutable()

                       receiversClassesWhiteList = [
                               Math,
                               Integer,
                               Float,
                               Double,
                               Long,
                               BigDecimal
                       ].asImmutable()
                   }
                   CompilerConfiguration config = new CompilerConfiguration()
                   config.addCompilationCustomizers(imports, secure)
                   GroovyClassLoader loader = new GroovyClassLoader(this.class.classLoader, config)

  Since:
    1.8.0
  Author:
    Cedric Champeau, Guillaume Laforge, Hamlet D'Arcy

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `SecureASTCustomizer.ExpressionChecker` This interface allows the user to plugin custom expression checkers if expression blacklist or whitelist are not sufficient
    `static interface` | `SecureASTCustomizer.StatementChecker` This interface allows the user to plugin custom statement checkers if statement blacklist or whitelist are not sufficient

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SecureASTCustomizer()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addExpressionCheckers(SecureASTCustomizer.ExpressionChecker... checkers)`
    `void` | `addStatementCheckers(SecureASTCustomizer.StatementChecker... checkers)`
    `void` | `call(SourceUnit source, GeneratorContext context, ClassNode classNode)`
    `java.util.List<java.lang.String>` | `getConstantTypesBlackList()`
    `java.util.List<java.lang.String>` | `getConstantTypesWhiteList()`
    `java.util.List<java.lang.Class<? extends Expression>>` | `getExpressionsBlacklist()`
    `java.util.List<java.lang.Class<? extends Expression>>` | `getExpressionsWhitelist()`
    `java.util.List<java.lang.String>` | `getImportsBlacklist()`
    `java.util.List<java.lang.String>` | `getImportsWhitelist()`
    `java.util.List<java.lang.String>` | `getReceiversBlackList()`
    `java.util.List<java.lang.String>` | `getReceiversWhiteList()`
    `java.util.List<java.lang.String>` | `getStarImportsBlacklist()`
    `java.util.List<java.lang.String>` | `getStarImportsWhitelist()`
    `java.util.List<java.lang.Class<? extends Statement>>` | `getStatementsBlacklist()`
    `java.util.List<java.lang.Class<? extends Statement>>` | `getStatementsWhitelist()`
    `java.util.List<java.lang.String>` | `getStaticImportsBlacklist()`
    `java.util.List<java.lang.String>` | `getStaticImportsWhitelist()`
    `java.util.List<java.lang.String>` | `getStaticStarImportsBlacklist()`
    `java.util.List<java.lang.String>` | `getStaticStarImportsWhitelist()`
    `java.util.List<java.lang.Integer>` | `getTokensBlacklist()`
    `java.util.List<java.lang.Integer>` | `getTokensWhitelist()`
    `boolean` | `isClosuresAllowed()`
    `boolean` | `isIndirectImportCheckEnabled()`
    `boolean` | `isMethodDefinitionAllowed()`
    `boolean` | `isPackageAllowed()`
    `void` | `setClosuresAllowed(boolean closuresAllowed)`
    `void` | `setConstantTypesBlackList(java.util.List<java.lang.String> constantTypesBlackList)`
    `void` | `setConstantTypesClassesBlackList(java.util.List<java.lang.Class> constantTypesBlackList)` An alternative way of setting constant types.
    `void` | `setConstantTypesClassesWhiteList(java.util.List<java.lang.Class> constantTypesWhiteList)` An alternative way of setting constant types.
    `void` | `setConstantTypesWhiteList(java.util.List<java.lang.String> constantTypesWhiteList)`
    `void` | `setExpressionsBlacklist(java.util.List<java.lang.Class<? extends Expression>> expressionsBlacklist)`
    `void` | `setExpressionsWhitelist(java.util.List<java.lang.Class<? extends Expression>> expressionsWhitelist)`
    `void` | `setImportsBlacklist(java.util.List<java.lang.String> importsBlacklist)`
    `void` | `setImportsWhitelist(java.util.List<java.lang.String> importsWhitelist)`
    `void` | `setIndirectImportCheckEnabled(boolean indirectImportCheckEnabled)` Set this option to true if you want your import rules to be checked against every class node.
    `void` | `setMethodDefinitionAllowed(boolean methodDefinitionAllowed)`
    `void` | `setPackageAllowed(boolean packageAllowed)`
    `void` | `setReceiversBlackList(java.util.List<java.lang.String> receiversBlackList)` Sets the list of classes which deny method calls.
    `void` | `setReceiversClassesBlackList(java.util.List<java.lang.Class> receiversBlacklist)` An alternative way of setting `receiver classes`.
    `void` | `setReceiversClassesWhiteList(java.util.List<java.lang.Class> receiversWhitelist)` An alternative way of setting `receiver classes`.
    `void` | `setReceiversWhiteList(java.util.List<java.lang.String> receiversWhiteList)` Sets the list of classes which may accept method calls.
    `void` | `setStarImportsBlacklist(java.util.List<java.lang.String> starImportsBlacklist)`
    `void` | `setStarImportsWhitelist(java.util.List<java.lang.String> starImportsWhitelist)`
    `void` | `setStatementsBlacklist(java.util.List<java.lang.Class<? extends Statement>> statementsBlacklist)`
    `void` | `setStatementsWhitelist(java.util.List<java.lang.Class<? extends Statement>> statementsWhitelist)`
    `void` | `setStaticImportsBlacklist(java.util.List<java.lang.String> staticImportsBlacklist)`
    `void` | `setStaticImportsWhitelist(java.util.List<java.lang.String> staticImportsWhitelist)`
    `void` | `setStaticStarImportsBlacklist(java.util.List<java.lang.String> staticStarImportsBlacklist)`
    `void` | `setStaticStarImportsWhitelist(java.util.List<java.lang.String> staticStarImportsWhitelist)`
    `void` | `setTokensBlacklist(java.util.List<java.lang.Integer> tokensBlacklist)` Sets the list of tokens which are blacklisted.
    `void` | `setTokensWhitelist(java.util.List<java.lang.Integer> tokensWhitelist)` Sets the list of tokens which are whitelisted.

    - ### Methods inherited from class org.codehaus.groovy.control.customizers.CompilationCustomizer

      `getPhase`

    - ### Methods inherited from class org.codehaus.groovy.control.CompilationUnit.PrimaryClassNodeOperation

      `needSortedInput`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SecureASTCustomizer

          public SecureASTCustomizer()

  - ### Method Detail

    - #### isMethodDefinitionAllowed

          public boolean isMethodDefinitionAllowed()

    - #### setMethodDefinitionAllowed

          public void setMethodDefinitionAllowed(boolean methodDefinitionAllowed)

    - #### isPackageAllowed

          public boolean isPackageAllowed()

    - #### isClosuresAllowed

          public boolean isClosuresAllowed()

    - #### setClosuresAllowed

          public void setClosuresAllowed(boolean closuresAllowed)

    - #### setPackageAllowed

          public void setPackageAllowed(boolean packageAllowed)

    - #### getImportsBlacklist

          public java.util.List<java.lang.String> getImportsBlacklist()

    - #### setImportsBlacklist

          public void setImportsBlacklist(java.util.List<java.lang.String> importsBlacklist)

    - #### getImportsWhitelist

          public java.util.List<java.lang.String> getImportsWhitelist()

    - #### setImportsWhitelist

          public void setImportsWhitelist(java.util.List<java.lang.String> importsWhitelist)

    - #### getStarImportsBlacklist

          public java.util.List<java.lang.String> getStarImportsBlacklist()

    - #### setStarImportsBlacklist

          public void setStarImportsBlacklist(java.util.List<java.lang.String> starImportsBlacklist)

    - #### getStarImportsWhitelist

          public java.util.List<java.lang.String> getStarImportsWhitelist()

    - #### setStarImportsWhitelist

          public void setStarImportsWhitelist(java.util.List<java.lang.String> starImportsWhitelist)

    - #### getStaticImportsBlacklist

          public java.util.List<java.lang.String> getStaticImportsBlacklist()

    - #### setStaticImportsBlacklist

          public void setStaticImportsBlacklist(java.util.List<java.lang.String> staticImportsBlacklist)

    - #### getStaticImportsWhitelist

          public java.util.List<java.lang.String> getStaticImportsWhitelist()

    - #### setStaticImportsWhitelist

          public void setStaticImportsWhitelist(java.util.List<java.lang.String> staticImportsWhitelist)

    - #### getStaticStarImportsBlacklist

          public java.util.List<java.lang.String> getStaticStarImportsBlacklist()

    - #### setStaticStarImportsBlacklist

          public void setStaticStarImportsBlacklist(java.util.List<java.lang.String> staticStarImportsBlacklist)

    - #### getStaticStarImportsWhitelist

          public java.util.List<java.lang.String> getStaticStarImportsWhitelist()

    - #### setStaticStarImportsWhitelist

          public void setStaticStarImportsWhitelist(java.util.List<java.lang.String> staticStarImportsWhitelist)

    - #### getExpressionsBlacklist

          public java.util.List<java.lang.Class<? extends Expression>> getExpressionsBlacklist()

    - #### setExpressionsBlacklist

          public void setExpressionsBlacklist(java.util.List<java.lang.Class<? extends Expression>> expressionsBlacklist)

    - #### getExpressionsWhitelist

          public java.util.List<java.lang.Class<? extends Expression>> getExpressionsWhitelist()

    - #### setExpressionsWhitelist

          public void setExpressionsWhitelist(java.util.List<java.lang.Class<? extends Expression>> expressionsWhitelist)

    - #### getStatementsBlacklist

          public java.util.List<java.lang.Class<? extends Statement>> getStatementsBlacklist()

    - #### setStatementsBlacklist

          public void setStatementsBlacklist(java.util.List<java.lang.Class<? extends Statement>> statementsBlacklist)

    - #### getStatementsWhitelist

          public java.util.List<java.lang.Class<? extends Statement>> getStatementsWhitelist()

    - #### setStatementsWhitelist

          public void setStatementsWhitelist(java.util.List<java.lang.Class<? extends Statement>> statementsWhitelist)

    - #### getTokensBlacklist

          public java.util.List<java.lang.Integer> getTokensBlacklist()

    - #### isIndirectImportCheckEnabled

          public boolean isIndirectImportCheckEnabled()

    - #### setIndirectImportCheckEnabled

          public void setIndirectImportCheckEnabled(boolean indirectImportCheckEnabled)

      Set this option to true if you want your import rules to be checked against every class node. This means that if someone uses a fully qualified class name, then it will also be checked against the import rules, preventing, for example, instantiation of classes without imports thanks to FQCN.
      Parameters:
        `indirectImportCheckEnabled` - set to true to enable indirect checks

    - #### setTokensBlacklist

          public void setTokensBlacklist(java.util.List<java.lang.Integer> tokensBlacklist)

      Sets the list of tokens which are blacklisted.
      Parameters:
        `tokensBlacklist` - the tokens. The values of the tokens must be those of `Types`

    - #### getTokensWhitelist

          public java.util.List<java.lang.Integer> getTokensWhitelist()

    - #### setTokensWhitelist

          public void setTokensWhitelist(java.util.List<java.lang.Integer> tokensWhitelist)

      Sets the list of tokens which are whitelisted.
      Parameters:
        `tokensWhitelist` - the tokens. The values of the tokens must be those of `Types`

    - #### addStatementCheckers

          public void addStatementCheckers(SecureASTCustomizer.StatementChecker... checkers)

    - #### addExpressionCheckers

          public void addExpressionCheckers(SecureASTCustomizer.ExpressionChecker... checkers)

    - #### getConstantTypesBlackList

          public java.util.List<java.lang.String> getConstantTypesBlackList()

    - #### setConstantTypesBlackList

          public void setConstantTypesBlackList(java.util.List<java.lang.String> constantTypesBlackList)

    - #### getConstantTypesWhiteList

          public java.util.List<java.lang.String> getConstantTypesWhiteList()

    - #### setConstantTypesWhiteList

          public void setConstantTypesWhiteList(java.util.List<java.lang.String> constantTypesWhiteList)

    - #### setConstantTypesClassesWhiteList

          public void setConstantTypesClassesWhiteList(java.util.List<java.lang.Class> constantTypesWhiteList)

      An alternative way of setting constant types.
      Parameters:
        `constantTypesWhiteList` - a list of classes.

    - #### setConstantTypesClassesBlackList

          public void setConstantTypesClassesBlackList(java.util.List<java.lang.Class> constantTypesBlackList)

      An alternative way of setting constant types.
      Parameters:
        `constantTypesBlackList` - a list of classes.

    - #### getReceiversBlackList

          public java.util.List<java.lang.String> getReceiversBlackList()

    - #### setReceiversBlackList

          public void setReceiversBlackList(java.util.List<java.lang.String> receiversBlackList)

      Sets the list of classes which deny method calls. Please note that since Groovy is a dynamic language, and this class performs a static type check, it will be reletively simple to bypass any blacklist unless the receivers blacklist contains, at a minimum, Object, Script, GroovyShell, and Eval. Additionally, it is necessary to also blacklist MethodPointerExpression in the expressions blacklist for the receivers blacklist to function as a security check.
      Parameters:
        `receiversBlackList` - the list of refused classes, as fully qualified names

    - #### setReceiversClassesBlackList

          public void setReceiversClassesBlackList(java.util.List<java.lang.Class> receiversBlacklist)

      An alternative way of setting `receiver classes`.
      Parameters:
        `receiversBlacklist` - a list of classes.

    - #### getReceiversWhiteList

          public java.util.List<java.lang.String> getReceiversWhiteList()

    - #### setReceiversWhiteList

          public void setReceiversWhiteList(java.util.List<java.lang.String> receiversWhiteList)

      Sets the list of classes which may accept method calls.
      Parameters:
        `receiversWhiteList` - the list of accepted classes, as fully qualified names

    - #### setReceiversClassesWhiteList

          public void setReceiversClassesWhiteList(java.util.List<java.lang.Class> receiversWhitelist)

      An alternative way of setting `receiver classes`.
      Parameters:
        `receiversWhitelist` - a list of classes.

    - #### call

          public void call(SourceUnit source,
                           GeneratorContext context,
                           ClassNode classNode)
                    throws CompilationFailedException

      Specified by:
        `call` in class `CompilationUnit.PrimaryClassNodeOperation`
      Throws:
        `CompilationFailedException`