Groovy Documentation

## org.codehaus.groovy.control.customizers
[Java] Class SecureASTCustomizer

    java.lang.Object
      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 securization 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 recommanded 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 StatementChecker interface or 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)

Authors:
  Cedric Champeau
  Guillaume Laforge
  Hamlet D'Arcy

Since:
  1.8.0

Nested Class Summary
`static interface` | `SecureASTCustomizer.ExpressionChecker`
`static interface` | `SecureASTCustomizer.StatementChecker`

Constructor Summary
`SecureASTCustomizer()`

Method Summary
`void` | `addExpressionCheckers(SecureASTCustomizer.ExpressionChecker... checkers)`
`void` | `addStatementCheckers(SecureASTCustomizer.StatementChecker... checkers)`
`void` | `call(SourceUnit source, GeneratorContext context, ClassNode classNode)`
`java.util.List` | `getConstantTypesBlackList()`
`java.util.List` | `getConstantTypesWhiteList()`
`java.util.List` | `getExpressionsBlacklist()`
`java.util.List` | `getExpressionsWhitelist()`
`java.util.List` | `getImportsBlacklist()`
`java.util.List` | `getImportsWhitelist()`
`java.util.List` | `getReceiversBlackList()` Sets the list of classes which deny method calls.
`java.util.List` | `getReceiversWhiteList()` Sets the list of classes which may accept method calls.
`java.util.List` | `getStarImportsBlacklist()`
`java.util.List` | `getStarImportsWhitelist()`
`java.util.List` | `getStatementsBlacklist()`
`java.util.List` | `getStatementsWhitelist()`
`java.util.List` | `getStaticImportsBlacklist()`
`java.util.List` | `getStaticImportsWhitelist()`
`java.util.List` | `getStaticStarImportsBlacklist()`
`java.util.List` | `getStaticStarImportsWhitelist()`
`java.util.List` | `getTokensBlacklist()`
`java.util.List` | `getTokensWhitelist()`
`boolean` | `isClosuresAllowed()`
`boolean` | `isIndirectImportCheckEnabled()`
`boolean` | `isMethodDefinitionAllowed()`
`boolean` | `isPackageAllowed()`
`void` | `setClosuresAllowed(boolean closuresAllowed)`
`void` | `setConstantTypesBlackList(java.util.List constantTypesBlackList)`
`void` | `setConstantTypesClassesBlackList(java.util.List constantTypesBlackList)`
`void` | `setConstantTypesClassesWhiteList(java.util.List constantTypesWhiteList)`
`void` | `setConstantTypesWhiteList(java.util.List constantTypesWhiteList)`
`void` | `setExpressionsBlacklist(java.util.List expressionsBlacklist)`
`void` | `setExpressionsWhitelist(java.util.List expressionsWhitelist)`
`void` | `setImportsBlacklist(java.util.List importsBlacklist)`
`void` | `setImportsWhitelist(java.util.List importsWhitelist)`
`void` | `setIndirectImportCheckEnabled(boolean indirectImportCheckEnabled)` Sets the list of tokens which are blacklisted.
`void` | `setMethodDefinitionAllowed(boolean methodDefinitionAllowed)`
`void` | `setPackageAllowed(boolean packageAllowed)`
`void` | `setReceiversBlackList(java.util.List receiversBlackList)` An alternative way of setting receiver classes.
`void` | `setReceiversClassesBlackList(java.util.List receiversBlacklist)`
`void` | `setReceiversClassesWhiteList(java.util.List receiversWhitelist)`
`void` | `setReceiversWhiteList(java.util.List receiversWhiteList)` An alternative way of setting receiver classes.
`void` | `setStarImportsBlacklist(java.util.List starImportsBlacklist)`
`void` | `setStarImportsWhitelist(java.util.List starImportsWhitelist)` Ensures that every star import ends with .* as this is the expected syntax in import checks.
`void` | `setStatementsBlacklist(java.util.List statementsBlacklist)`
`void` | `setStatementsWhitelist(java.util.List statementsWhitelist)`
`void` | `setStaticImportsBlacklist(java.util.List staticImportsBlacklist)`
`void` | `setStaticImportsWhitelist(java.util.List staticImportsWhitelist)`
`void` | `setStaticStarImportsBlacklist(java.util.List staticStarImportsBlacklist)`
`void` | `setStaticStarImportsWhitelist(java.util.List staticStarImportsWhitelist)`
`void` | `setTokensBlacklist(java.util.List tokensBlacklist)`
`void` | `setTokensWhitelist(java.util.List tokensWhitelist)`

Methods inherited from class CompilationCustomizer
getPhase

Constructor Detail

### SecureASTCustomizer

    public SecureASTCustomizer()

Method Detail

### addExpressionCheckers

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

### addStatementCheckers

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

### call

    assertImportIsAllowed(className);
    public void call(SourceUnit source, GeneratorContext context, ClassNode classNode)

### getConstantTypesBlackList

    public java.util.List getConstantTypesBlackList()

### getConstantTypesWhiteList

    public java.util.List getConstantTypesWhiteList()

### getExpressionsBlacklist

    public java.util.List getExpressionsBlacklist()

### getExpressionsWhitelist

    public java.util.List getExpressionsWhitelist()

### getImportsBlacklist

    public java.util.List getImportsBlacklist()

### getImportsWhitelist

    public java.util.List getImportsWhitelist()

### getReceiversBlackList

    public java.util.List getReceiversBlackList()

  Sets the list of classes which deny method calls.
  Parameters:
    `receiversBlackList` - the list of refused classes, as fully qualified names

### getReceiversWhiteList

    public java.util.List getReceiversWhiteList()

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

### getStarImportsBlacklist

    public java.util.List getStarImportsBlacklist()

### getStarImportsWhitelist

    public java.util.List getStarImportsWhitelist()

### getStatementsBlacklist

    public java.util.List getStatementsBlacklist()

### getStatementsWhitelist

    public java.util.List getStatementsWhitelist()

### getStaticImportsBlacklist

    public java.util.List getStaticImportsBlacklist()

### getStaticImportsWhitelist

    public java.util.List getStaticImportsWhitelist()

### getStaticStarImportsBlacklist

    public java.util.List getStaticStarImportsBlacklist()

### getStaticStarImportsWhitelist

    public java.util.List getStaticStarImportsWhitelist()

### getTokensBlacklist

    public java.util.List getTokensBlacklist()

### getTokensWhitelist

    public java.util.List getTokensWhitelist()

### isClosuresAllowed

    public boolean isClosuresAllowed()

### isIndirectImportCheckEnabled

    public boolean isIndirectImportCheckEnabled()

### isMethodDefinitionAllowed

    public boolean isMethodDefinitionAllowed()

### isPackageAllowed

    public boolean isPackageAllowed()

### setClosuresAllowed

    public void setClosuresAllowed(boolean closuresAllowed)

### setConstantTypesBlackList

    public void setConstantTypesBlackList(java.util.List constantTypesBlackList)

### setConstantTypesClassesBlackList

    public void setConstantTypesClassesBlackList(java.util.List constantTypesBlackList)

### setConstantTypesClassesWhiteList

    public void setConstantTypesClassesWhiteList(java.util.List constantTypesWhiteList)

### setConstantTypesWhiteList

    public void setConstantTypesWhiteList(java.util.List constantTypesWhiteList)

### setExpressionsBlacklist

    public void setExpressionsBlacklist(java.util.List expressionsBlacklist)

### setExpressionsWhitelist

    public void setExpressionsWhitelist(java.util.List expressionsWhitelist)

### setImportsBlacklist

    public void setImportsBlacklist(java.util.List importsBlacklist)

### setImportsWhitelist

    public void setImportsWhitelist(java.util.List importsWhitelist)

### setIndirectImportCheckEnabled

    public void setIndirectImportCheckEnabled(boolean indirectImportCheckEnabled)

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

### setMethodDefinitionAllowed

    public void setMethodDefinitionAllowed(boolean methodDefinitionAllowed)

### setPackageAllowed

    public void setPackageAllowed(boolean packageAllowed)

### setReceiversBlackList

    public void setReceiversBlackList(java.util.List receiversBlackList)

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

### setReceiversClassesBlackList

    public void setReceiversClassesBlackList(java.util.List receiversBlacklist)

### setReceiversClassesWhiteList

    public void setReceiversClassesWhiteList(java.util.List receiversWhitelist)

### setReceiversWhiteList

    public void setReceiversWhiteList(java.util.List receiversWhiteList)

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

### setStarImportsBlacklist

    public void setStarImportsBlacklist(java.util.List starImportsBlacklist)

### setStarImportsWhitelist

    public void setStarImportsWhitelist(java.util.List starImportsWhitelist)

  Ensures that every star import ends with .* as this is the expected syntax in import checks.

### setStatementsBlacklist

    public void setStatementsBlacklist(java.util.List statementsBlacklist)

### setStatementsWhitelist

    public void setStatementsWhitelist(java.util.List statementsWhitelist)

### setStaticImportsBlacklist

    public void setStaticImportsBlacklist(java.util.List staticImportsBlacklist)

### setStaticImportsWhitelist

    public void setStaticImportsWhitelist(java.util.List staticImportsWhitelist)

### setStaticStarImportsBlacklist

    public void setStaticStarImportsBlacklist(java.util.List staticStarImportsBlacklist)

### setStaticStarImportsWhitelist

    public void setStaticStarImportsWhitelist(java.util.List staticStarImportsWhitelist)

### setTokensBlacklist

    public void setTokensBlacklist(java.util.List tokensBlacklist)

### setTokensWhitelist

    public void setTokensWhitelist(java.util.List tokensWhitelist)

Groovy Documentation