[Java] Class SecureASTCustomizer

org.codehaus.groovy.control.customizers.SecureASTCustomizer

This customizer allows securing source code by controlling what code constructs are permitted. This is typically done when using Groovy for its scripting or domain specific language (DSL) features. 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 allowed or disallowed lists. This means that, for a single option, you can set an allowed list OR a disallowed list, but not both. You can mix allowed/disallowed strategies for different options. For example, you can have an allowed import list and a disallowed tokens list.

The recommended way of securing shells is to use allowed lists because it is guaranteed that future features of the Groovy language won't be accidentally allowed unless explicitly added to the allowed list. Using disallowed lists, you can limit the features of the language constructs supported by your shell by opting out, but new language features are then implicitly also available and this may not be desirable. The implication is that you might need to update your configuration with each new release.

If neither an allowed list nor a disallowed list is set, then everything is permitted.

Combinations of import and star import constraints are authorized as long as you use the same type of list for both. For example, you may use an import allowed list and a star import allowed list together, but you cannot use an import allowed list with a star import disallowed list. Static imports are handled separately, meaning that disallowing an import does not prevent from allowing 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

         allowedImports = []
         allowedStaticImports = []
         allowedStaticStarImports = ['java.lang.Math'] // only java.lang.Math is allowed

         allowedTokens = [
                 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()

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

         allowedReceiversClasses = [
                 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

Nested Class Summary

Nested classes
Modifiers	Name	Description
`interface`	`SecureASTCustomizer.ExpressionChecker`	This interface allows the user to provide a custom expression checker if the dis/allowed expression lists are not sufficient
`interface`	`SecureASTCustomizer.StatementChecker`	This interface allows the user to provide a custom statement checker if the dis/allowed statement lists are not sufficient

Properties Summary

Properties
Type	Name and description
`List<String>`	`allowedConstantTypes`
`List<Class<? extends Expression>>`	`allowedExpressions`
`List<String>`	`allowedImports`
`List<String>`	`allowedReceivers`
`List<String>`	`allowedStarImports`
`List<Class<? extends Statement>>`	`allowedStatements`
`List<String>`	`allowedStaticImports`
`List<String>`	`allowedStaticStarImports`
`List<Integer>`	`allowedTokens`
`boolean`	`closuresAllowed`
`List<String>`	`constantTypesBlackList`
`List<String>`	`constantTypesWhiteList`
`List<Class<? extends Expression>>`	`disallowedExpressions`
`List<String>`	`disallowedImports`
`List<String>`	`disallowedReceivers`
`List<String>`	`disallowedStarImports`
`List<Class<? extends Statement>>`	`disallowedStatements`
`List<String>`	`disallowedStaticImports`
`List<String>`	`disallowedStaticStarImports`
`List<Integer>`	`disallowedTokens`
`List<Class<? extends Expression>>`	`expressionsBlacklist`
`List<Class<? extends Expression>>`	`expressionsWhitelist`
`List<String>`	`importsBlacklist`
`List<String>`	`importsWhitelist`
`boolean`	`indirectImportCheckEnabled`
`boolean`	`methodDefinitionAllowed`
`boolean`	`packageAllowed`
`List<String>`	`receiversBlackList`
`List<String>`	`receiversWhiteList`
`List<String>`	`starImportsBlacklist`
`List<String>`	`starImportsWhitelist`
`List<Class<? extends Statement>>`	`statementsBlacklist`
`List<Class<? extends Statement>>`	`statementsWhitelist`
`List<String>`	`staticImportsBlacklist`
`List<String>`	`staticImportsWhitelist`
`List<String>`	`staticStarImportsBlacklist`
`List<String>`	`staticStarImportsWhitelist`
`List<Integer>`	`tokensBlacklist`
`List<Integer>`	`tokensWhitelist`

Constructor Summary

Constructors
Constructor and description
`SecureASTCustomizer ()`

Methods Summary

Methods
Type Params	Return Type	Name and description
	`void`	`addExpressionCheckers(SecureASTCustomizer.ExpressionChecker... checkers)`
	`void`	`addStatementCheckers(SecureASTCustomizer.StatementChecker... checkers)`
	`void`	`call(SourceUnit source, GeneratorContext context, ClassNode classNode)`
	`List<String>`	`getAllowedConstantTypes()`
	`List<Class<? extends Expression>>`	`getAllowedExpressions()`
	`List<String>`	`getAllowedImports()`
	`List<String>`	`getAllowedReceivers()`
	`List<String>`	`getAllowedStarImports()`
	`List<Class<? extends Statement>>`	`getAllowedStatements()`
	`List<String>`	`getAllowedStaticImports()`
	`List<String>`	`getAllowedStaticStarImports()`
	`List<Integer>`	`getAllowedTokens()`
	`List<String>`	`getConstantTypesBlackList()` Legacy alias for getDisallowedConstantTypes()
	`List<String>`	`getConstantTypesWhiteList()` Legacy alias for getAllowedStatements()
	`List<String>`	`getDisallowedConstantTypes()`
	`List<Class<? extends Expression>>`	`getDisallowedExpressions()`
	`List<String>`	`getDisallowedImports()`
	`List<String>`	`getDisallowedReceivers()`
	`List<String>`	`getDisallowedStarImports()`
	`List<Class<? extends Statement>>`	`getDisallowedStatements()`
	`List<String>`	`getDisallowedStaticImports()`
	`List<String>`	`getDisallowedStaticStarImports()`
	`List<Integer>`	`getDisallowedTokens()`
	`List<Class<? extends Expression>>`	`getExpressionsBlacklist()` Legacy alias for getDisallowedExpressions()
	`List<Class<? extends Expression>>`	`getExpressionsWhitelist()` Legacy alias for getAllowedExpressions()
	`List<String>`	`getImportsBlacklist()` Legacy alias for getDisallowedImports()
	`List<String>`	`getImportsWhitelist()` Legacy alias for getAllowedImports()
	`List<String>`	`getReceiversBlackList()` Legacy alias for getDisallowedReceivers()
	`List<String>`	`getReceiversWhiteList()` Legacy alias for getAllowedReceivers()
	`List<String>`	`getStarImportsBlacklist()` Legacy alias for getDisallowedStarImports()
	`List<String>`	`getStarImportsWhitelist()` Legacy alias for getAllowedStarImports()
	`List<Class<? extends Statement>>`	`getStatementsBlacklist()` Legacy alias for getDisallowedStatements()
	`List<Class<? extends Statement>>`	`getStatementsWhitelist()` Legacy alias for getAllowedStatements()
	`List<String>`	`getStaticImportsBlacklist()` Legacy alias for getDisallowedStaticImports()
	`List<String>`	`getStaticImportsWhitelist()` Legacy alias for getAllowedStaticImports()
	`List<String>`	`getStaticStarImportsBlacklist()` Legacy alias for getDisallowedStaticStarImports()
	`List<String>`	`getStaticStarImportsWhitelist()` Legacy alias for getAllowedStaticStarImports()
	`List<Integer>`	`getTokensBlacklist()` Legacy alias for getDisallowedTokens()
	`List<Integer>`	`getTokensWhitelist()` Legacy alias for getAllowedTokens()
	`boolean`	`isClosuresAllowed()`
	`boolean`	`isIndirectImportCheckEnabled()`
	`boolean`	`isMethodDefinitionAllowed()`
	`boolean`	`isPackageAllowed()`
	`void`	`setAllowedConstantTypes(List<String> allowedConstantTypes)`
	`void`	`setAllowedConstantTypesClasses(List<Class> allowedConstantTypes)` An alternative way of setting constant types.
	`void`	`setAllowedExpressions(List<Class<? extends Expression>> allowedExpressions)`
	`void`	`setAllowedImports(List<String> allowedImports)`
	`void`	`setAllowedReceivers(List<String> allowedReceivers)` Sets the list of classes which may accept method calls.
	`void`	`setAllowedReceiversClasses(List<Class> allowedReceivers)` An alternative way of setting receiver classes.
	`void`	`setAllowedStarImports(List<String> allowedStarImports)`
	`void`	`setAllowedStatements(List<Class<? extends Statement>> allowedStatements)`
	`void`	`setAllowedStaticImports(List<String> allowedStaticImports)`
	`void`	`setAllowedStaticStarImports(List<String> allowedStaticStarImports)`
	`void`	`setAllowedTokens(List<Integer> allowedTokens)` Sets the list of tokens which are permitted.
	`void`	`setClosuresAllowed(boolean closuresAllowed)`
	`void`	`setConstantTypesBlackList(List<String> constantTypesBlackList)`
	`void`	`setConstantTypesClassesBlackList(List<Class> disallowedConstantTypes)` Legacy alias for setDisallowedConstantTypesClasses(List)
	`void`	`setConstantTypesClassesWhiteList(List<Class> allowedConstantTypes)` Legacy alias for setAllowedConstantTypesClasses(List)
	`void`	`setConstantTypesWhiteList(List<String> allowedConstantTypes)` Legacy alias for setAllowedConstantTypes(List)
	`void`	`setDisallowedConstantTypesClasses(List<Class> disallowedConstantTypes)` An alternative way of setting constant types.
	`void`	`setDisallowedExpressions(List<Class<? extends Expression>> disallowedExpressions)`
	`void`	`setDisallowedImports(List<String> disallowedImports)`
	`void`	`setDisallowedReceivers(List<String> disallowedReceivers)` Sets the list of classes which deny method calls.
	`void`	`setDisallowedReceiversClasses(List<Class> disallowedReceivers)` An alternative way of setting receiver classes.
	`void`	`setDisallowedStarImports(List<String> disallowedStarImports)`
	`void`	`setDisallowedStatements(List<Class<? extends Statement>> disallowedStatements)`
	`void`	`setDisallowedStaticImports(List<String> disallowedStaticImports)`
	`void`	`setDisallowedStaticStarImports(List<String> disallowedStaticStarImports)`
	`void`	`setDisallowedTokens(List<Integer> disallowedTokens)` Sets the list of tokens which are not permitted.
	`void`	`setExpressionsBlacklist(List<Class<? extends Expression>> disallowedExpressions)` Legacy alias for setDisallowedExpressions(List)
	`void`	`setExpressionsWhitelist(List<Class<? extends Expression>> allowedExpressions)` Legacy alias for setAllowedExpressions(List)
	`void`	`setImportsBlacklist(List<String> disallowedImports)` Legacy alias for setDisallowedImports(List)
	`void`	`setImportsWhitelist(List<String> allowedImports)` Legacy alias for setAllowedImports(List)
	`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(List<String> disallowedReceivers)` Legacy alias for setDisallowedReceivers(List)
	`void`	`setReceiversClassesBlackList(List<Class> disallowedReceivers)` Legacy alias for setDisallowedReceiversClasses(List).
	`void`	`setReceiversClassesWhiteList(List<Class> allowedReceivers)` Legacy alias for setAllowedReceiversClasses(List)
	`void`	`setReceiversWhiteList(List<String> allowedReceivers)` Legacy alias for setAllowedReceivers(List)
	`void`	`setStarImportsBlacklist(List<String> disallowedStarImports)` Legacy alias for setDisallowedStarImports(List)
	`void`	`setStarImportsWhitelist(List<String> allowedStarImports)` Legacy alias for setAllowedStarImports(List)
	`void`	`setStatementsBlacklist(List<Class<? extends Statement>> disallowedStatements)` Legacy alias for setDisallowedStatements(List)
	`void`	`setStatementsWhitelist(List<Class<? extends Statement>> allowedStatements)` Legacy alias for setAllowedStatements(List)
	`void`	`setStaticImportsBlacklist(List<String> disallowedStaticImports)` Legacy alias for setDisallowedStaticImports(List)
	`void`	`setStaticImportsWhitelist(List<String> allowedStaticImports)` Legacy alias for setAllowedStaticImports(List)
	`void`	`setStaticStarImportsBlacklist(List<String> disallowedStaticStarImports)` Legacy alias for setDisallowedStaticStarImports(List)
	`void`	`setStaticStarImportsWhitelist(List<String> allowedStaticStarImports)` Legacy alias for setAllowedStaticStarImports(List)
	`void`	`setTokensBlacklist(List<Integer> disallowedTokens)` Alias for setDisallowedTokens(List).
	`void`	`setTokensWhitelist(List<Integer> allowedTokens)` Legacy alias for setAllowedTokens(List)

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class CompilationCustomizer`	`getPhase`

Property Detail

List<String> allowedConstantTypes

List<Class<? extends Expression>> allowedExpressions

List<String> allowedImports

List<String> allowedReceivers

List<String> allowedStarImports

List<Class<? extends Statement>> allowedStatements

List<String> allowedStaticImports

List<String> allowedStaticStarImports

List<Integer> allowedTokens

boolean closuresAllowed

List<String> constantTypesBlackList

List<String> constantTypesWhiteList

List<Class<? extends Expression>> disallowedExpressions

List<String> disallowedImports

List<String> disallowedReceivers

List<String> disallowedStarImports

List<Class<? extends Statement>> disallowedStatements

List<String> disallowedStaticImports

List<String> disallowedStaticStarImports

List<Integer> disallowedTokens

List<Class<? extends Expression>> expressionsBlacklist

List<Class<? extends Expression>> expressionsWhitelist

List<String> importsBlacklist

List<String> importsWhitelist

boolean indirectImportCheckEnabled

boolean methodDefinitionAllowed

boolean packageAllowed

List<String> receiversBlackList

List<String> receiversWhiteList

List<String> starImportsBlacklist

List<String> starImportsWhitelist

List<Class<? extends Statement>> statementsBlacklist

List<Class<? extends Statement>> statementsWhitelist

List<String> staticImportsBlacklist

List<String> staticImportsWhitelist

List<String> staticStarImportsBlacklist

List<String> staticStarImportsWhitelist

List<Integer> tokensBlacklist

List<Integer> tokensWhitelist

Constructor Detail

public SecureASTCustomizer()

Method Detail

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

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

@Override public void call(SourceUnit source, GeneratorContext context, ClassNode classNode)

public List<String> getAllowedConstantTypes()

public List<Class<? extends Expression>> getAllowedExpressions()

public List<String> getAllowedImports()

public List<String> getAllowedReceivers()

public List<String> getAllowedStarImports()

public List<Class<? extends Statement>> getAllowedStatements()

public List<String> getAllowedStaticImports()

public List<String> getAllowedStaticStarImports()

public List<Integer> getAllowedTokens()

public List<String> getConstantTypesBlackList()

Legacy alias for getDisallowedConstantTypes()

public List<String> getConstantTypesWhiteList()

Legacy alias for getAllowedStatements()

public List<String> getDisallowedConstantTypes()

public List<Class<? extends Expression>> getDisallowedExpressions()

public List<String> getDisallowedImports()

public List<String> getDisallowedReceivers()

public List<String> getDisallowedStarImports()

public List<Class<? extends Statement>> getDisallowedStatements()

public List<String> getDisallowedStaticImports()

public List<String> getDisallowedStaticStarImports()

public List<Integer> getDisallowedTokens()

public boolean isClosuresAllowed()

public boolean isIndirectImportCheckEnabled()

public boolean isMethodDefinitionAllowed()

public boolean isPackageAllowed()

public void setAllowedConstantTypes(List<String> allowedConstantTypes)

public void setAllowedConstantTypesClasses(List<Class> allowedConstantTypes)

An alternative way of setting constant types.

Parameters:: allowedConstantTypes - a list of classes.

public void setAllowedExpressions(List<Class<? extends Expression>> allowedExpressions)

public void setAllowedImports(List<String> allowedImports)

public void setAllowedReceivers(List<String> allowedReceivers)

Sets the list of classes which may accept method calls.

Parameters:: allowedReceivers - the list of accepted classes, as fully qualified names

public void setAllowedReceiversClasses(List<Class> allowedReceivers)

An alternative way of setting receiver classes.

Parameters:: allowedReceivers - a list of classes.

public void setAllowedStarImports(List<String> allowedStarImports)

public void setAllowedStatements(List<Class<? extends Statement>> allowedStatements)

public void setAllowedStaticImports(List<String> allowedStaticImports)

public void setAllowedStaticStarImports(List<String> allowedStaticStarImports)

public void setAllowedTokens(List<Integer> allowedTokens)

Sets the list of tokens which are permitted.

Parameters:: allowedTokens - the tokens. The values of the tokens must be those of Types

public void setClosuresAllowed(boolean closuresAllowed)

public void setConstantTypesBlackList(List<String> constantTypesBlackList)

public void setConstantTypesClassesBlackList(List<Class> disallowedConstantTypes)

Legacy alias for setDisallowedConstantTypesClasses(List)

public void setConstantTypesClassesWhiteList(List<Class> allowedConstantTypes)

Legacy alias for setAllowedConstantTypesClasses(List)

public void setConstantTypesWhiteList(List<String> allowedConstantTypes)

Legacy alias for setAllowedConstantTypes(List)

public void setDisallowedConstantTypesClasses(List<Class> disallowedConstantTypes)

An alternative way of setting constant types.

Parameters:: disallowedConstantTypes - a list of classes.

public void setDisallowedExpressions(List<Class<? extends Expression>> disallowedExpressions)

public void setDisallowedImports(List<String> disallowedImports)

public void setDisallowedReceivers(List<String> disallowedReceivers)

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 relatively simple to bypass any disallowed list unless the disallowed receivers list contains, at a minimum, Object, Script, GroovyShell, and Eval. Additionally, it is necessary to also have MethodPointerExpression in the disallowed expressions list for the disallowed receivers list to function as a security check.

Parameters:: disallowedReceivers - the list of refused classes, as fully qualified names

public void setDisallowedReceiversClasses(List<Class> disallowedReceivers)

An alternative way of setting receiver classes.

Parameters:: disallowedReceivers - a list of classes.

public void setDisallowedStarImports(List<String> disallowedStarImports)

public void setDisallowedStatements(List<Class<? extends Statement>> disallowedStatements)

public void setDisallowedStaticImports(List<String> disallowedStaticImports)

public void setDisallowedStaticStarImports(List<String> disallowedStaticStarImports)

public void setDisallowedTokens(List<Integer> disallowedTokens)

Sets the list of tokens which are not permitted.

Parameters:: disallowedTokens - the tokens. The values of the tokens must be those of Types

public void setExpressionsBlacklist(List<Class<? extends Expression>> disallowedExpressions)

Legacy alias for setDisallowedExpressions(List)

public void setExpressionsWhitelist(List<Class<? extends Expression>> allowedExpressions)

Legacy alias for setAllowedExpressions(List)

public void setImportsBlacklist(List<String> disallowedImports)

Legacy alias for setDisallowedImports(List)

public void setImportsWhitelist(List<String> allowedImports)

Legacy alias for setAllowedImports(List)

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

public void setMethodDefinitionAllowed(boolean methodDefinitionAllowed)

public void setPackageAllowed(boolean packageAllowed)

public void setReceiversBlackList(List<String> disallowedReceivers)

Legacy alias for setDisallowedReceivers(List)

public void setReceiversClassesBlackList(List<Class> disallowedReceivers)

Legacy alias for setDisallowedReceiversClasses(List).

public void setReceiversClassesWhiteList(List<Class> allowedReceivers)

Legacy alias for setAllowedReceiversClasses(List)

public void setReceiversWhiteList(List<String> allowedReceivers)

Legacy alias for setAllowedReceivers(List)

public void setStarImportsBlacklist(List<String> disallowedStarImports)

Legacy alias for setDisallowedStarImports(List)

public void setStarImportsWhitelist(List<String> allowedStarImports)

Legacy alias for setAllowedStarImports(List)

public void setStatementsBlacklist(List<Class<? extends Statement>> disallowedStatements)

Legacy alias for setDisallowedStatements(List)

public void setStatementsWhitelist(List<Class<? extends Statement>> allowedStatements)

Legacy alias for setAllowedStatements(List)

public void setStaticImportsBlacklist(List<String> disallowedStaticImports)

Legacy alias for setDisallowedStaticImports(List)

public void setStaticImportsWhitelist(List<String> allowedStaticImports)

Legacy alias for setAllowedStaticImports(List)

public void setStaticStarImportsBlacklist(List<String> disallowedStaticStarImports)

Legacy alias for setDisallowedStaticStarImports(List)

public void setStaticStarImportsWhitelist(List<String> allowedStaticStarImports)

Legacy alias for setAllowedStaticStarImports(List)

public void setTokensBlacklist(List<Integer> disallowedTokens)

Alias for setDisallowedTokens(List).

public void setTokensWhitelist(List<Integer> allowedTokens)

Legacy alias for setAllowedTokens(List)

© 2003-2020 The Apache Software Foundation
Licensed under the Apache license.
https://docs.groovy-lang.org/2.5.14/html/gapi/org/codehaus/groovy/control/customizers/SecureASTCustomizer.html