Package org.codehaus.groovy.control.customizers

Class SecureASTCustomizer

java.lang.Object
org.codehaus.groovy.control.customizers.CompilationCustomizer
org.codehaus.groovy.control.customizers.SecureASTCustomizer
All Implemented Interfaces:
CompilationUnit.IPrimaryClassNodeOperation
public class SecureASTCustomizer extends CompilationCustomizer
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 SecureASTCustomizer.StatementChecker interface or SecureASTCustomizer.ExpressionChecker interface then register your handlers thanks to the addExpressionCheckers(ExpressionChecker...) and addStatementCheckers(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,
             REMAINDER,
             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)

Note: SecureASTCustomizer allows you to lock down the grammar of scripts but by itself isn't intended to be the complete solution of all security issues when running scripts on the JVM. You might also want to consider setting the groovy.grape.enable System property to false, augmenting use of the customizer with additional techniques, and following standard security principles for JVM applications. Accordingly, the Apache Groovy threat model treats this customizer as a hardening aid rather than a security boundary (see its "security properties the project does NOT provide" section): a report that merely demonstrates a bypass is by design, not a vulnerability.

For more information, please read:

  • Improved sandboxing of Groovy scripts
  • Oracle's Secure Coding Guidelines
  • 10 Java security best practices
  • Thirteen rules for developing secure Java applications
  • 12 Java Security Best Practices
    • Since:
    1.8.0

    • Constructor Details

      • SecureASTCustomizer

        public SecureASTCustomizer()
        Creates a secure AST customizer that runs during canonicalization.

    • Method Details

      • isMethodDefinitionAllowed

        public boolean isMethodDefinitionAllowed()
        Indicates whether explicit method definitions are allowed.
        Returns:
        true if method definitions are allowed

      • setMethodDefinitionAllowed

        public void setMethodDefinitionAllowed(boolean methodDefinitionAllowed)
        Sets whether explicit method definitions are allowed.
        Parameters:
        methodDefinitionAllowed - true to allow method definitions

      • isPackageAllowed

        public boolean isPackageAllowed()
        Indicates whether package declarations are allowed.
        Returns:
        true if package declarations are allowed

      • isClosuresAllowed

        public boolean isClosuresAllowed()
        Indicates whether closures are allowed.
        Returns:
        true if closures are allowed

      • setClosuresAllowed

        public void setClosuresAllowed(boolean closuresAllowed)
        Sets whether closures are allowed.
        Parameters:
        closuresAllowed - true to allow closures

      • setPackageAllowed

        public void setPackageAllowed(boolean packageAllowed)
        Sets whether package declarations are allowed.
        Parameters:
        packageAllowed - true to allow package declarations

      • getDisallowedImports

        public List<String> getDisallowedImports()
        Returns the list of explicitly disallowed imports.
        Returns:
        the disallowed imports, or null

      • getImportsBlacklist

        @Deprecated public List<String> getImportsBlacklist()
        Deprecated.
        Legacy alias for getDisallowedImports()

      • setDisallowedImports

        public void setDisallowedImports(List<String> disallowedImports)
        Sets the list of explicitly disallowed imports.
        Parameters:
        disallowedImports - the imports to reject

      • setImportsBlacklist

        @Deprecated public void setImportsBlacklist(List<String> disallowedImports)
        Deprecated.
        Legacy alias for setDisallowedImports(List)

      • getAllowedImports

        public List<String> getAllowedImports()
        Returns the list of explicitly allowed imports.
        Returns:
        the allowed imports, or null

      • getImportsWhitelist

        @Deprecated public List<String> getImportsWhitelist()
        Deprecated.
        Legacy alias for getAllowedImports()

      • setAllowedImports

        public void setAllowedImports(List<String> allowedImports)
        Sets the list of explicitly allowed imports.
        Parameters:
        allowedImports - the imports to allow

      • setImportsWhitelist

        @Deprecated public void setImportsWhitelist(List<String> allowedImports)
        Deprecated.
        Legacy alias for setAllowedImports(List)

      • getDisallowedStarImports

        public List<String> getDisallowedStarImports()
        Returns the list of disallowed star imports.
        Returns:
        the disallowed star imports, or null

      • getStarImportsBlacklist

        @Deprecated public List<String> getStarImportsBlacklist()
        Deprecated.
        Legacy alias for getDisallowedStarImports()

      • setDisallowedStarImports

        public void setDisallowedStarImports(List<String> disallowedStarImports)
        Sets the list of disallowed star imports.
        Parameters:
        disallowedStarImports - the star imports to reject

      • setStarImportsBlacklist

        @Deprecated public void setStarImportsBlacklist(List<String> disallowedStarImports)
        Deprecated.
        Legacy alias for setDisallowedStarImports(List)

      • getAllowedStarImports

        public List<String> getAllowedStarImports()
        Returns the list of allowed star imports.
        Returns:
        the allowed star imports, or null

      • getStarImportsWhitelist

        @Deprecated public List<String> getStarImportsWhitelist()
        Deprecated.
        Legacy alias for getAllowedStarImports()

      • setAllowedStarImports

        public void setAllowedStarImports(List<String> allowedStarImports)
        Sets the list of allowed star imports.
        Parameters:
        allowedStarImports - the star imports to allow

      • setStarImportsWhitelist

        @Deprecated public void setStarImportsWhitelist(List<String> allowedStarImports)
        Deprecated.
        Legacy alias for setAllowedStarImports(List)

      • getDisallowedStaticImports

        public List<String> getDisallowedStaticImports()
        Returns the list of disallowed static imports.
        Returns:
        the disallowed static imports, or null

      • getStaticImportsBlacklist

        @Deprecated public List<String> getStaticImportsBlacklist()
        Deprecated.
        Legacy alias for getDisallowedStaticImports()

      • setDisallowedStaticImports

        public void setDisallowedStaticImports(List<String> disallowedStaticImports)
        Sets the list of disallowed static imports.
        Parameters:
        disallowedStaticImports - the static imports to reject

      • setStaticImportsBlacklist

        @Deprecated public void setStaticImportsBlacklist(List<String> disallowedStaticImports)
        Deprecated.
        Legacy alias for setDisallowedStaticImports(List)

      • getAllowedStaticImports

        public List<String> getAllowedStaticImports()
        Returns the list of allowed static imports.
        Returns:
        the allowed static imports, or null

      • getStaticImportsWhitelist

        @Deprecated public List<String> getStaticImportsWhitelist()
        Deprecated.
        Legacy alias for getAllowedStaticImports()

      • setAllowedStaticImports

        public void setAllowedStaticImports(List<String> allowedStaticImports)
        Sets the list of allowed static imports.
        Parameters:
        allowedStaticImports - the static imports to allow

      • setStaticImportsWhitelist

        @Deprecated public void setStaticImportsWhitelist(List<String> allowedStaticImports)
        Deprecated.
        Legacy alias for setAllowedStaticImports(List)

      • getDisallowedStaticStarImports

        public List<String> getDisallowedStaticStarImports()
        Returns the list of disallowed static star imports.
        Returns:
        the disallowed static star imports, or null

      • getStaticStarImportsBlacklist

        @Deprecated public List<String> getStaticStarImportsBlacklist()
        Deprecated.
        Legacy alias for getDisallowedStaticStarImports()

      • setDisallowedStaticStarImports

        public void setDisallowedStaticStarImports(List<String> disallowedStaticStarImports)
        Sets the list of disallowed static star imports.
        Parameters:
        disallowedStaticStarImports - the static star imports to reject

      • setStaticStarImportsBlacklist

        @Deprecated public void setStaticStarImportsBlacklist(List<String> disallowedStaticStarImports)
        Deprecated.
        Legacy alias for setDisallowedStaticStarImports(List)

      • getAllowedStaticStarImports

        public List<String> getAllowedStaticStarImports()
        Returns the list of allowed static star imports.
        Returns:
        the allowed static star imports, or null

      • getStaticStarImportsWhitelist

        @Deprecated public List<String> getStaticStarImportsWhitelist()
        Deprecated.
        Legacy alias for getAllowedStaticStarImports()

      • setAllowedStaticStarImports

        public void setAllowedStaticStarImports(List<String> allowedStaticStarImports)
        Sets the list of allowed static star imports.
        Parameters:
        allowedStaticStarImports - the static star imports to allow

      • setStaticStarImportsWhitelist

        @Deprecated public void setStaticStarImportsWhitelist(List<String> allowedStaticStarImports)
        Deprecated.
        Legacy alias for setAllowedStaticStarImports(List)

      • getDisallowedExpressions

        public List<Class<? extends Expression>> getDisallowedExpressions()
        Returns the list of disallowed expression node types.
        Returns:
        the disallowed expression types, or null

      • getExpressionsBlacklist

        @Deprecated public List<Class<? extends Expression>> getExpressionsBlacklist()
        Deprecated.
        Legacy alias for getDisallowedExpressions()

      • setDisallowedExpressions

        public void setDisallowedExpressions(List<Class<? extends Expression>> disallowedExpressions)
        Sets the list of disallowed expression node types.
        Parameters:
        disallowedExpressions - the expression types to reject

      • setExpressionsBlacklist

        @Deprecated public void setExpressionsBlacklist(List<Class<? extends Expression>> disallowedExpressions)
        Deprecated.
        Legacy alias for setDisallowedExpressions(List)

      • getAllowedExpressions

        public List<Class<? extends Expression>> getAllowedExpressions()
        Returns the list of allowed expression node types.
        Returns:
        the allowed expression types, or null

      • getExpressionsWhitelist

        @Deprecated public List<Class<? extends Expression>> getExpressionsWhitelist()
        Deprecated.
        Legacy alias for getAllowedExpressions()

      • setAllowedExpressions

        public void setAllowedExpressions(List<Class<? extends Expression>> allowedExpressions)
        Sets the list of allowed expression node types.
        Parameters:
        allowedExpressions - the expression types to allow

      • setExpressionsWhitelist

        @Deprecated public void setExpressionsWhitelist(List<Class<? extends Expression>> allowedExpressions)
        Deprecated.
        Legacy alias for setAllowedExpressions(List)

      • getDisallowedStatements

        public List<Class<? extends Statement>> getDisallowedStatements()
        Returns the list of disallowed statement node types.
        Returns:
        the disallowed statement types, or null

      • getStatementsBlacklist

        @Deprecated public List<Class<? extends Statement>> getStatementsBlacklist()
        Deprecated.
        Legacy alias for getDisallowedStatements()

      • setDisallowedStatements

        public void setDisallowedStatements(List<Class<? extends Statement>> disallowedStatements)
        Sets the list of disallowed statement node types.
        Parameters:
        disallowedStatements - the statement types to reject

      • setStatementsBlacklist

        @Deprecated public void setStatementsBlacklist(List<Class<? extends Statement>> disallowedStatements)
        Deprecated.
        Legacy alias for setDisallowedStatements(List)

      • getAllowedStatements

        public List<Class<? extends Statement>> getAllowedStatements()
        Returns the list of allowed statement node types.
        Returns:
        the allowed statement types, or null

      • getStatementsWhitelist

        @Deprecated public List<Class<? extends Statement>> getStatementsWhitelist()
        Deprecated.
        Legacy alias for getAllowedStatements()

      • setAllowedStatements

        public void setAllowedStatements(List<Class<? extends Statement>> allowedStatements)
        Sets the list of allowed statement node types.
        Parameters:
        allowedStatements - the statement types to allow

      • setStatementsWhitelist

        @Deprecated public void setStatementsWhitelist(List<Class<? extends Statement>> allowedStatements)
        Deprecated.
        Legacy alias for setAllowedStatements(List)

      • isIndirectImportCheckEnabled

        public boolean isIndirectImportCheckEnabled()
        Indicates whether indirect import checks are enabled.
        Returns:
        true if indirect import checks are enabled

      • 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

      • getDisallowedTokens

        public List<Integer> getDisallowedTokens()
        Returns the list of disallowed token types.
        Returns:
        the disallowed token types, or null

      • getTokensBlacklist

        @Deprecated public List<Integer> getTokensBlacklist()
        Deprecated.
        Legacy alias for getDisallowedTokens()

      • setDisallowedTokens

        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

      • setTokensBlacklist

        @Deprecated public void setTokensBlacklist(List<Integer> disallowedTokens)
        Deprecated.
        Legacy alias for setDisallowedTokens(List).

      • getAllowedTokens

        public List<Integer> getAllowedTokens()
        Returns the list of allowed token types.
        Returns:
        the allowed token types, or null

      • getTokensWhitelist

        @Deprecated public List<Integer> getTokensWhitelist()
        Deprecated.
        Legacy alias for getAllowedTokens()

      • setAllowedTokens

        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

      • setTokensWhitelist

        @Deprecated public void setTokensWhitelist(List<Integer> allowedTokens)
        Deprecated.
        Legacy alias for setAllowedTokens(List)

      • addStatementCheckers

        public void addStatementCheckers(SecureASTCustomizer.StatementChecker... checkers)
        Adds statement checkers consulted in addition to the allow/disallow lists.
        Parameters:
        checkers - the statement checkers to add

      • addExpressionCheckers

        public void addExpressionCheckers(SecureASTCustomizer.ExpressionChecker... checkers)
        Adds expression checkers consulted in addition to the allow/disallow lists.
        Parameters:
        checkers - the expression checkers to add

      • getDisallowedConstantTypes

        public List<String> getDisallowedConstantTypes()
        Returns the list of disallowed constant or variable types.
        Returns:
        the disallowed constant types, or null

      • getConstantTypesBlackList

        @Deprecated public List<String> getConstantTypesBlackList()
        Deprecated.
        Legacy alias for getDisallowedConstantTypes()

      • setConstantTypesBlackList

        public void setConstantTypesBlackList(List<String> constantTypesBlackList)
        Sets the list of disallowed constant or variable types.
        Parameters:
        constantTypesBlackList - the type names to reject

      • getAllowedConstantTypes

        public List<String> getAllowedConstantTypes()
        Returns the list of allowed constant or variable types.
        Returns:
        the allowed constant types, or null

      • getConstantTypesWhiteList

        @Deprecated public List<String> getConstantTypesWhiteList()
        Deprecated.
        Legacy alias for getAllowedStatements()

      • setAllowedConstantTypes

        public void setAllowedConstantTypes(List<String> allowedConstantTypes)
        Sets the list of allowed constant or variable types.
        Parameters:
        allowedConstantTypes - the type names to allow

      • setConstantTypesWhiteList

        @Deprecated public void setConstantTypesWhiteList(List<String> allowedConstantTypes)
        Deprecated.
        Legacy alias for setAllowedConstantTypes(List)

      • setAllowedConstantTypesClasses

        public void setAllowedConstantTypesClasses(List<Class> allowedConstantTypes)
        An alternative way of setting constant types.
        Parameters:
        allowedConstantTypes - a list of classes.

      • setConstantTypesClassesWhiteList

        @Deprecated public void setConstantTypesClassesWhiteList(List<Class> allowedConstantTypes)
        Deprecated.
        Legacy alias for setAllowedConstantTypesClasses(List)

      • setDisallowedConstantTypesClasses

        public void setDisallowedConstantTypesClasses(List<Class> disallowedConstantTypes)
        An alternative way of setting constant types.
        Parameters:
        disallowedConstantTypes - a list of classes.

      • setConstantTypesClassesBlackList

        @Deprecated public void setConstantTypesClassesBlackList(List<Class> disallowedConstantTypes)
        Deprecated.
        Legacy alias for setDisallowedConstantTypesClasses(List)

      • getDisallowedReceivers

        public List<String> getDisallowedReceivers()
        Returns the list of receiver types on which calls are disallowed.
        Returns:
        the disallowed receiver types, or null

      • getReceiversBlackList

        @Deprecated public List<String> getReceiversBlackList()
        Deprecated.
        Legacy alias for getDisallowedReceivers()

      • setDisallowedReceivers

        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

      • setReceiversBlackList

        @Deprecated public void setReceiversBlackList(List<String> disallowedReceivers)
        Deprecated.
        Legacy alias for setDisallowedReceivers(List)

      • setDisallowedReceiversClasses

        public void setDisallowedReceiversClasses(List<Class> disallowedReceivers)
        An alternative way of setting receiver classes.
        Parameters:
        disallowedReceivers - a list of classes.

      • setReceiversClassesBlackList

        @Deprecated public void setReceiversClassesBlackList(List<Class> disallowedReceivers)
        Deprecated.
        Legacy alias for setDisallowedReceiversClasses(List).

      • getAllowedReceivers

        public List<String> getAllowedReceivers()
        Returns the list of receiver types on which calls are allowed.
        Returns:
        the allowed receiver types, or null

      • getReceiversWhiteList

        @Deprecated public List<String> getReceiversWhiteList()
        Deprecated.
        Legacy alias for getAllowedReceivers()

      • setAllowedReceivers

        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

      • setReceiversWhiteList

        @Deprecated public void setReceiversWhiteList(List<String> allowedReceivers)
        Deprecated.
        Legacy alias for setAllowedReceivers(List)

      • setAllowedReceiversClasses

        public void setAllowedReceiversClasses(List<Class> allowedReceivers)
        An alternative way of setting receiver classes.
        Parameters:
        allowedReceivers - a list of classes.

      • setReceiversClassesWhiteList

        @Deprecated public void setReceiversClassesWhiteList(List<Class> allowedReceivers)
        Deprecated.
        Legacy alias for setAllowedReceiversClasses(List)

      • call

        public void call(SourceUnit source, GeneratorContext context, ClassNode classNode) throws CompilationFailedException
        Verifies the configured security rules against the current source unit and class.
        Parameters:
        source - the source unit being customized
        context - the current generator context
        classNode - the class node being customized
        Throws:
        CompilationFailedException - if verification fails

      • createGroovyCodeVisitor

        protected GroovyCodeVisitor createGroovyCodeVisitor()
        Creates the visitor that enforces statement and expression restrictions.
        Returns:
        the security-checking visitor

      • checkMethodDefinitionAllowed

        protected void checkMethodDefinitionAllowed(ClassNode owner)
        Ensures the supplied class does not declare methods when such definitions are forbidden.
        Parameters:
        owner - the class to inspect

      • filterMethods

        protected static List<MethodNode> filterMethods(ClassNode owner)
        Returns the non-synthetic methods declared directly by the supplied class.
        Parameters:
        owner - the class to inspect
        Returns:
        the directly declared, non-synthetic methods

      • assertStarImportIsAllowed

        protected void assertStarImportIsAllowed(String packageName)
        Verifies that a star import is allowed by the current configuration.
        Parameters:
        packageName - the star import to check

      • assertImportIsAllowed

        protected void assertImportIsAllowed(String className)
        Verifies that a regular import is allowed by the current configuration.
        Parameters:
        className - the imported class name

      • assertStaticImportIsAllowed

        protected void assertStaticImportIsAllowed(String member, String className)
        Verifies that a static import is allowed by the current configuration.
        Parameters:
        member - the imported member name
        className - the declaring class name