Interface JexlPermissions
-
- All Known Implementing Classes:
JexlPermissions.ClassPermissions
,JexlPermissions.Delegate
,Permissions
public interface JexlPermissions
This interface describes permissions used by JEXL introspection that constrain which packages/classes/constructors/fields/methods are made visible to JEXL scripts.By specifying or implementing permissions, it is possible to constrain precisely which objects can be manipulated by JEXL, allowing users to enter their own expressions or scripts whilst maintaining tight control over what can be executed. JEXL introspection mechanism will check whether it is permitted to access a constructor, method or field before exposition to the
JexlUberspect
. The restrictions are applied in all cases, for anyJexlUberspect.ResolverStrategy
.This complements using a dedicated
ClassLoader
and/orSecurityManager
- being deprecated - and possiblyJexlSandbox
with a simpler mechanism. TheNoJexl
annotation processing is actually performed using the result of callingparse(String...)
with no arguments; implementations shall delegate calls to its methods forNoJexl
to be processed.A simple textual configuration can be used to create user-defined permissions using
parse(String...)
.To instantiate a JEXL engine using permissions, one should use a
JexlBuilder
and callJexlBuilder.permissions(JexlPermissions)
. Another approach would be to instantiate aJexlUberspect
with those permissions and callJexlBuilder.uberspect(JexlUberspect)
.To help migration from earlier versions, it is possible to revert to the JEXL 3.2 default lenient behavior by calling
JexlBuilder.setDefaultPermissions(JexlPermissions)
withUNRESTRICTED
as parameter before creating a JEXL engine instance.For the same reason, using JEXL through scripting, it is possible to revert the underlying JEXL behavior to JEXL 3.2 default by calling
JexlScriptEngine.setPermissions(JexlPermissions)
withUNRESTRICTED
as parameter.- Since:
- 3.3
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
JexlPermissions.ClassPermissions
A permission delegation that augments the RESTRICTED permission with an explicit set of classes.static class
JexlPermissions.Delegate
A base for permission delegation allowing functional refinement.
-
Field Summary
Fields Modifier and Type Field Description static JexlPermissions
RESTRICTED
A restricted singleton.static JexlPermissions
UNRESTRICTED
The unrestricted permissions.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description boolean
allow(java.lang.Class<?> clazz)
Checks whether a class allows JEXL introspection.boolean
allow(java.lang.Package pack)
Checks whether a package allows JEXL introspection.boolean
allow(java.lang.reflect.Constructor<?> ctor)
Checks whether a constructor allows JEXL introspection.boolean
allow(java.lang.reflect.Field field)
Checks whether a field explicitly disallows JEXL introspection.boolean
allow(java.lang.reflect.Method method)
Checks whether a method allows JEXL introspection.JexlPermissions
compose(java.lang.String... src)
Compose these permissions with a new set.static JexlPermissions
parse(java.lang.String... src)
Parses a set of permissions.default boolean
validate(java.lang.Class<?> clazz)
Checks that a class is valid for permission check.default boolean
validate(java.lang.Package pack)
Checks that a package is valid for permission check.default boolean
validate(java.lang.reflect.Constructor<?> constructor)
Checks that a constructor is valid for permission check.default boolean
validate(java.lang.reflect.Field field)
Checks that a field is valid for permission check.default boolean
validate(java.lang.reflect.Method method)
Checks that a method is valid for permission check.
-
-
-
Field Detail
-
UNRESTRICTED
static final JexlPermissions UNRESTRICTED
The unrestricted permissions.This enables any public class, method, constructor or field to be visible to JEXL and used in scripts.
- Since:
- 3.3
-
RESTRICTED
static final JexlPermissions RESTRICTED
A restricted singleton.The RESTRICTED set is built using the following allowed packages and denied packages/classes.
Of particular importance are the restrictions on the
System
,Runtime
,ProcessBuilder
,Class
and those onjava.net
,java.net
,java.io
andjava.lang.reflect
that should provide a decent level of isolation between the scripts and its host.As a simple guide, any line that ends with ".*" is allowing a package, any other is denying a package, class or method.
- java.nio.*
- java.io.*
- java.lang.*
- java.math.*
- java.text.*
- java.util.*
- org.w3c.dom.*
- org.apache.commons.jexl3.*
- org.apache.commons.jexl3 { JexlBuilder {} }
- org.apache.commons.jexl3.internal { Engine {} }
- java.lang { Runtime {} System {} ProcessBuilder {} Class {} }
- java.lang.annotation {}
- java.lang.instrument {}
- java.lang.invoke {}
- java.lang.management {}
- java.lang.ref {}
- java.lang.reflect {}
- java.net {}
- java.io { File { } }
- java.nio { Path { } Paths { } Files { } }
- java.rmi {}
-
-
Method Detail
-
parse
static JexlPermissions parse(java.lang.String... src)
Parses a set of permissions.In JEXL 3.3, the syntax recognizes 2 types of permissions:
- Allowing access to a wildcard restricted set of packages.
- Denying access to packages, classes (and inner classes), methods and fields
Wildcards specifications determine the set of allowed packages. When empty, all packages can be used. When using JEXL to expose functional elements, their packages should be exposed through wildcards. These allow composing the volume of what is allowed by addition.
Restrictions behave exactly like the
An example of a tight environment that would not allow scripts to wander could be:NoJexl
annotation; they can restrict access to package, class, inner-class, methods and fields. These allow refining the volume of what is allowed by extrusion.# allow a very restricted set of base classes java.math.* java.text.* java.util.* # deny classes that could pose a security risk java.lang { Runtime {} System {} ProcessBuilder {} Class {} } org.apache.commons.jexl3 { JexlBuilder {} }
- Syntax for wildcards is the name of the package suffixed by
.*
. - Syntax for restrictions is a list of package restrictions.
- A package restriction is a package name followed by a block (as in curly-bracket block {}) that contains a list of class restrictions.
- A class restriction is a class name prefixed by an optional
-
or+
sign followed by a block of member restrictions. - A member restriction can be a class restriction - to restrict
nested classes -, a field which is the Java field name suffixed with
;
, a method composed of its Java name suffixed with();
. Constructor restrictions are specified like methods using the class name as method name. - By default or when prefixed with a
-
, a class restriction is explicitly denying the members declared in its block (or the whole class) - When prefixed with a
+
, a class restriction is explicitly allowing the members declared in its block (or the whole class)
All overrides and overloads of a constructors or method are allowed or restricted at the same time, the restriction being based on their names, not their whole signature. This differs from the @NoJexl annotation.
# some wildcards java.lang.*; # java.lang is pretty much a must have my.allowed.package0.* another.allowed.package1.* # nojexl like restrictions my.package.internal {} # the whole package is hidden my.package { +class4 { theMethod(); } # only theMethod can be called in class4 class0 { class1 {} # the whole class1 is hidden class2 { class2(); # class2 constructors can not be invoked class3 { aMethod(); # aMethod can not be called aField; # aField can not be accessed } } # end of class2 class0(); # class0 constructors can not be invoked method(); # method can not be called field; # field can not be accessed } # end class0 } # end package my.package
- Parameters:
src
- the permissions source, the default (NoJexl aware) permissions if null- Returns:
- the permissions instance
- Since:
- 3.3
-
allow
boolean allow(java.lang.Class<?> clazz)
Checks whether a class allows JEXL introspection.If the class disallows JEXL introspection, none of its constructors, methods or fields as well as derived classes are visible to JEXL and can not be used in scripts or expressions. If one of its super-classes is not allowed, tbe class is not allowed either.
For interfaces, only methods and fields are disallowed in derived interfaces or implementing classes.
- Parameters:
clazz
- the class to check- Returns:
- true if JEXL is allowed to introspect, false otherwise
- Since:
- 3.3
-
allow
boolean allow(java.lang.reflect.Constructor<?> ctor)
Checks whether a constructor allows JEXL introspection.If a constructor is not allowed, the new operator can not be used to instantiate its declared class in scripts or expressions.
- Parameters:
ctor
- the constructor to check- Returns:
- true if JEXL is allowed to introspect, false otherwise
- Since:
- 3.3
-
allow
boolean allow(java.lang.reflect.Field field)
Checks whether a field explicitly disallows JEXL introspection.If a field is not allowed, it can not resolved and accessed in scripts or expressions.
- Parameters:
field
- the field to check- Returns:
- true if JEXL is allowed to introspect, false otherwise
- Since:
- 3.3
-
allow
boolean allow(java.lang.reflect.Method method)
Checks whether a method allows JEXL introspection.If a method is not allowed, it can not resolved and called in scripts or expressions.
Since methods can be overridden and overloaded, this also checks that no superclass or interface explicitly disallows this methods.
- Parameters:
method
- the method to check- Returns:
- true if JEXL is allowed to introspect, false otherwise
- Since:
- 3.3
-
allow
boolean allow(java.lang.Package pack)
Checks whether a package allows JEXL introspection.If the package disallows JEXL introspection, none of its classes or interfaces are visible to JEXL and can not be used in scripts or expression.
- Parameters:
pack
- the package- Returns:
- true if JEXL is allowed to introspect, false otherwise
- Since:
- 3.3
-
compose
JexlPermissions compose(java.lang.String... src)
Compose these permissions with a new set.This is a convenience method meant to easily give access to the packages JEXL is used to integrate with. For instance, using
would extend the restricted set of permissions by allowing the com.my.app package.RESTRICTED
.compose("com.my.app.*")- Parameters:
src
- the new constraints- Returns:
- the new permissions
-
validate
default boolean validate(java.lang.Class<?> clazz)
Checks that a class is valid for permission check.- Parameters:
clazz
- the class- Returns:
- true if the class is not null, false otherwise
-
validate
default boolean validate(java.lang.reflect.Constructor<?> constructor)
Checks that a constructor is valid for permission check.- Parameters:
constructor
- the constructor- Returns:
- true if constructor is not null and public, false otherwise
-
validate
default boolean validate(java.lang.reflect.Field field)
Checks that a field is valid for permission check.- Parameters:
field
- the constructor- Returns:
- true if field is not null and public, false otherwise
-
validate
default boolean validate(java.lang.reflect.Method method)
Checks that a method is valid for permission check.- Parameters:
method
- the method- Returns:
- true if method is not null and public, false otherwise
-
validate
default boolean validate(java.lang.Package pack)
Checks that a package is valid for permission check.- Parameters:
pack
- the package- Returns:
- true if the class is not null, false otherwise
-
-