Edit on GitHub

# Security

## Security tips

The Apache Struts 2 doesn’t provide any security mechanism - it is just a pure web framework. Below are few tips you should consider during application development with the Apache Struts 2.

### Restrict access to the Config Browser Plugin

Config Browser Plugin exposes internal configuration and should be used only during development phase. If you must use it on production site, we strictly recommend restricting access to it - you can use
Basic Authentication or any other security mechanism (e.g. Apache Shiro)

### Don’t mix different access levels in the same namespace

Very often access to different resources is controlled based on URL patterns, see snippet below. Because of that you cannot mix actions with different security levels in the same namespace. Always group actions in one namespace by security level.

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>admin</web-resource-name>
            <url-pattern>/secure/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>admin</role-name>
        </auth-constraint>
    </security-constraint>

### Never expose JSP files directly

You must always hide JSP file behind an action, you cannot allow for direct access to the JSP files as this can leads to unpredictable security vulnerabilities. You can achieve this by putting all your JSP files under the `WEB-INF` folder

- most of the JEE containers restrict access to files placed under the `WEB-INF` folder. Second option is to add security constraint to the `web.xml` file:

    <!-- Restricts access to pure JSP files - access available only via Struts action -->
    <security-constraint>
        <display-name>No direct JSP access</display-name>
        <web-resource-collection>
            <web-resource-name>No-JSP</web-resource-name>
            <url-pattern>*.jsp</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>no-users</role-name>
        </auth-constraint>
    </security-constraint>

    <security-role>
        <description>Don't assign users to this role</description>
        <role-name>no-users</role-name>
    </security-role>

The best approach is to used the both solutions.

### Disable devMode

The `devMode` is a very useful option during development time, allowing for deep introspection and debugging into you app.

However, in production it exposes your application to be presenting too many informations on application’s internals or to evaluating risky parameter expressions. Please always disable `devMode` before deploying your application to a production environment. While it is disabled by default, your `struts.xml` might include a line setting it to `true`. The best way is to ensure the following setting is applied to our `struts.xml` for production deployment:

    <constant name ="struts.devMode" value="false" />

### Reduce logging level

It’s a good practice to reduce logging level from DEBUG to INFO or less. Framework’s classes can produce a lot of logging entries which will pollute the log file. You can even set logging level to WARN for classes that belongs to the framework, see example Log4j2 configuration:

    <?xml version="1.0" encoding="UTF-8"?>
    <Configuration>
        <Appenders>
            <Console name="STDOUT" target="SYSTEM_OUT">
                <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
            </Console>
        </Appenders>
        <Loggers>
            <Logger name="com.opensymphony.xwork2" level="warn"/>
            <Logger name="org.apache.struts2" level="warn"/>
            <Root level="info">
                <AppenderRef ref="STDOUT"/>
            </Root>
        </Loggers>
    </Configuration>

### Use UTF-8 encoding

Always use `UTF-8` encoding when building an application with the Apache Struts 2, when using JSPs please add the following header to each JSP file

    <%@ page contentType="text/html; charset=UTF-8" %>

### Defining and annotating your Action parameters

> Note: Since 6.4 using `struts.parameters.requireAnnotations=true`. Or by default from 7.0.

Request parameters, such as those submitted by a form, can be stored on your Struts Action class by defining getters and setters for them. For example, if you have a form with a field called `name`, you can store the value of that field by defining a `public void setName(String name)` method on your Action class, and then importantly, annotating this method with `@StrutsParameter`. The presence of this annotation indicates that the method is intended for parameter injection and is safe to be invoked by any user who can view the Action.

    private String name;

    @StrutsParameter
    public void setName(String name) {
        this.name = name;
    }

If you wish to populate a DTO (Data Transfer Object) instead of setting the parameters directly on the Action class, you can define a getter for the DTO on your Action class instead. For example, define a method `public MyDto getFormData()` which is also annotated by `@StrutsParameter(depth = 1)`. Then, a parameter with name `formData.fullName` will be mapped to the setter `setFullName` on that DTO. Note that the `@StrutsParameter` annotation has a `depth` field which dictates the depth to which parameter injection is permitted. The default value is 0, which only allows setting parameters directly on the Action class as in the first example. A `depth` of 1 indicates that the immediate public properties of an object returned by the getter are permitted to be set. If you have further nested objects, you can increase the `depth` accordingly. Do not set this `depth` field to a value greater than the minimum required for your use case.

    private MyDto formData = new MyDto();

    @StrutsParameter(depth = 1)
    public MyDto getFormData() {
        return formData;
    }

    public static class MyDto {
        private String fullName;

        public void setFullName(String fullName) {
            this.fullName = fullName;
        }
    }

It is critical that any method you annotate with `@StrutsParameter` is safe for any user who can view that corresponding action to invoke (including any public methods on objects returned by that method and so forth). Any getters you annotate should only ever return a DTO or a collection/hierarchy of DTOs. Do NOT mix business logic or service references with your parameter injection methods and DTOs. Additionally, any database DTOs should be entirely separate from request parameter/form DTOs.

Do NOT, under any circumstance, annotate a method that returns one of the following unsafe objects:

- live Hibernate persistent objects
- container or Spring-managed beans, or any other live components/services
- objects (or objects that contain references to objects) that contain setter methods that are used for anything other than setting form parameter values

If you are finding updating your application with this new annotation time-consuming, you can temporarily combine the above option with `struts.parameters.requireAnnotations.transitionMode=true`. When this mode is enabled, only ‘nested’ parameters, i.e. DTOs or Collections represented by public getters on Action classes, will require annotations. This means public setters will still be exposed for parameter injection. Notably, the auto-allowlisting capability, which is also supported by these annotations, is not degraded in any way, so it proves a useful transitioning option for applications that wish to enable the OGNL allowlist as soon as possible.

### Do not define setters when not needed

> Note: Only relevant if you are not using `struts.parameters.requireAnnotations=true` as per the previous section.

You should carefully design your actions without exposing anything via setters and getters, this can lead to potential security vulnerabilities. Any action’s setter can be used to set incoming untrusted user’s value which can contain suspicious expression. Some Struts `Result`s automatically populate params based on values in `ValueStack` (action in most cases is the root) which means incoming value will be evaluated as an expression during this process.

### Do not use incoming values as an input for localisation logic

All `TextProvider`’s `getText(...)` methods (e.g. in`ActionSupport`) perform evaluation of parameters included in a message to properly localize the text. This means using incoming request parameters with `getText(...)` methods is potentially dangerous and should be avoided. See example below, assuming that an action implements getter and setter for property `message`, the below code allows inject an OGNL expression:

    public String execute() throws Exception {
        message = getText(getMessage());
        return SUCCESS;
    }

Never use value of incoming request parameter as part of your localization logic.

### Do not use incoming, untrusted user input in forced expression evaluation

You can use a forced expression evalaution in many tags’ attributes by using `%{...}` syntax. This is a very powerful option but used with wrong data can lead to the Remote Code Execution. Never use forced expression evalaution if you didn’t verify the input or it can be passed in by a user.

Never use value of incoming request parameter as input for forced expression evalaution.

### Use Struts tags instead of raw EL expressions

JSP EL doesn’t perform any kind of escaping, you must perform this using a dedicated function, see this example. Never use a raw `${}` EL expression on incoming values as this can lead to injecting a malicious code into the page.

The safest option is to use Struts Tags instead.

### Define custom error pages

As mentioned in S2-006 it’s a good practicse to define your own error pages. This avoids exposing users to XSS attacks as Struts does not escape action’s names in automatically generated error pages.

You can either disable DMI

    <constant name="struts.enable.DynamicMethodInvocation" value="false" />

or define an error page

    <global-results>
      <result name="error">/error_page.jsp</result>
    </global-results>

    <global-exception-mappings>
      <exception-mapping exception="java.lang.Exception" result="error"/>
    </global-exception-mappings>

### Ambiguous Action Methods

This can impact actions which have large inheritance hierarchy and use the same method’s name throughout the hierarchy, this was reported as an issue WW-4405. See the example below:

    public class RealAction extends BaseAction {
        @Action("save")
        public String save() throws Exception {
            super.save();
            return SUCCESS;
        }
    }

    public class BaseAction extends AbstractAction {
        public String save() throws Exception {
            save(Double.MAX_VALUE);
            return SUCCESS;
        }
    }

    public abstract class AbstractAction extends ActionSupport {
        protected void save(Double val) {
            // some logic
        }
    }

In such case OGNL cannot properly map which method to call when request is coming. This is do the OGNL limitation. To solve the problem don’t use the same method’s names through the hierarchy, you can simply change the action’s method from `save()` to `saveAction()` and leaving annotation as is to allow call this action via `/save.action` request.

### Accepted / Excluded Patterns

As from version 2.3.20 the framework provides two new interfaces which are used to accept / exclude param names and values - AcceptedPatternsChecker and ExcludedPatternsChecker with default implementations. These two interfaces are used by the Parameters Interceptor and Cookie Interceptor to check if param can be accepted or must be excluded. If you were using `excludeParams` previously please compare patterns used by you with these provided by the framework in default implementation.

### Strict Method Invocation

This mechanism was introduced in version 2.5. It allows control what methods can be accessed with the bang “!” operator via Dynamic Method Invocation. Please read more in the Strict Method Invocation section of Action Configuration.

### Resource Isolation Using Fetch Metadata

> Note: since Struts 6.0.0

Fetch Metadata is a mitigation against common cross-origin attacks such as Cross-Site Request Forgery (CSRF). It is a web platform security feature designed to help servers defend themselves against cross-origin attacks based on the preferred resource isolation policy. The browser provides information about the context of an HTTP request in a set of `Sec-Fetch-*` headers. This allows the server processing the request to make decisions on whether the request should be accepted or rejected based on the available resource isolation policies.

A Resource Isolation Policy prevents the resources on a server from being requested by external websites. This policy can be enabled for all endpoints of the application or the endpoints that are meant to be loaded in a cross-site context can be exempted from applying the policy. Read more about Fetch Metadata and resource isolation here.

This mechanism is implemented in Struts using the FetchMetadata Interceptor. Refer to the documentation for FetchMetadata Interceptor instructions on how to enable Fetch Metadata.

### Cross Origin Isolation with COOP and COEP

> Note: since Struts 6.0.0

Cross-Origin Opener Policy is a security mitigation that lets developers isolate their resources against side-channel attacks and information leaks. The COOP response header allows a document to request a new browsing context group to better isolate itself from other untrustworthy origins.

Cross-Origin Embedder Policy prevents a document from loading any cross-origin resources which don’t explicitly grant the document permission to be loaded.

COOP and COEP are independent mechanisms that can be enabled, tested and deployed separately. While enabling one doesn’t require developers to enable the other, when set together COOP and COEP allows developers to use powerful features (such as `SharedArrayBuffer`, `performance.measureMemory()` and the JS Self-Profiling API) securely, without worrying about side channel attacks like Spectre. Further reading on COOP/COEP and why you need cross-origin isolation.

The recommended configuration for the policies are:

    Cross-Origin-Embedder-Policy: require-corp;
    Cross-Origin-Opener-Policy: same-origin;

COOP and COEP are implemented in Struts using CoopInterceptor and CoepInterceptor.

## Proactively protecting against OGNL Expression Injections attacks

The framework has a history of critical security bugs, many tied to its use of OGNL technology; Due to its ability to create or change executable code, OGNL is capable of introducing critical security flaws to any framework that uses it. Multiple Struts 2 versions have been vulnerable to OGNL security flaws. Consequently, we’ve equipped OGNL and the framework with a number of additional security capabilities, some of which need to be manually enabled.

> NOTE: These might break your current app functionality. Before using in production environment, you’re recommended to comprehensively test your app UI and functionalities with these enabled.

### Run OGNL expressions inside sandbox

You can do this simply via adding `-Dognl.security.manager` to JVM arguments. OGNL thereupon utilizes Java Security Manager to run OGNL expressions (which includes your actions either!) inside a sandbox with no permission. It is worth noting that it affects only OGNL expression execution and thereafter OGNL reverts Java Security Manager to its previous state.

Note: This feature does not work with JDK 21 and above.

### Restricting access to the Struts Context (ActionContext)

The Struts ActionContext is a core construct of the Struts framework. It is shared and manipulated throughout the codebase. From the ActionContext, it is possible to access application parameters, the OgnlValueStack, the current request/response/session, the servlet context, the Guice container, and a number of other objects either directly or indirectly via the directly exposed objects. The Struts ActionContext enables powerful features and functionality, but it also presents a major security risk if not properly secured.

The Struts ActionContext is accessible to OGNL expressions. In the case of an OGNL expression exploit, usually achieved through some form of server-side template injection or parameter injection, the ActionContext is a prime gadget for escalation of the vulnerability, often to remote code execution (RCE). Whilst known harmful capabilities of the ActionContext items are blocked by the OGNL Member Access policy exclusion list (see below), this is not always effective due to the myriad of changing objects available on the ActionContext. The new allowlist capability (also see below) offers much stronger protection. However, for the strongest level of protection, we recommend disabling access to the ActionContext from OGNL expressions entirely.

Note that before disabling access to the ActionContext from OGNL expressions, you should ensure that your application does not rely on this capability. OGNL expressions may access the context directly using the `#` operator, or indirectly using the OgnlValueStack’s fallback to context lookup capability. As of Struts 6.4.0, the Set, Iterator and Action Struts components require ActionContext access from OGNL expressions.

To disable access to the ActionContext from OGNL expressions, set the following constants in your `struts.xml` or `struts.properties` file. The option `struts.ognl.excludedNodeTypes` is an OGNL Guard setting which completely forbids the context accessing syntax node. The `struts.ognl.valueStackFallbackToContext` option disables ValueStack behaviour which allows the context to be accessed indirectly via a fallback behaviour triggered when an OGNL expression does not evaluate to a valid value.

    <constant name="struts.ognl.valueStackFallbackToContext" value="false"/>
    <constant name="struts.ognl.excludedNodeTypes" value="
                ognl.ASTThisVarRef,
                ognl.ASTVarRef
    "/>

### Apply a maximum allowed length on OGNL expressions

You can enable this via Struts configuration key `struts.ognl.expressionMaxLength` (defaults to 256). OGNL thereupon doesn’t evaluate any expression longer than specified value. You would choose a value large enough to permit ALL valid OGNL expressions used within the application. Values larger than the 200-400 range have diminishing security value (at which point it is really only a “style guard” for long OGNL expressions in an application).

### OGNL Member Access

Struts 2 implements an OGNL internal security mechanism which blocks access to particular classes and Java packages - it’s an OGNL-wide mechanism which means it affects any aspect of the framework i.e. incoming parameters, expressions used in JSPs, etc. Matching is done based on both the target and member class of all components of an OGNL expression.

There are 4 options that can be used to configure excluded packages and classes:

- `struts.excludedClasses`: comma-separated list of excluded classes.
- `struts.excludedPackageNames`: comma-separated list of excluded packages, matched using string comparison via `startWith`. Note that classes in subpackages are also excluded.
- `struts.excludedPackageNamePatterns` - comma-separated list of RegEx patterns used to exclude packages. Note that this option is more flexible than `struts.excludedPackageNames` but will have a greater impact on performance and page latency.
- `struts.excludedPackageExemptClasses` - comma-separated list of classes to exempt from any of the excluded packages or package name patterns. An exact exemption must exist for each exclusion match (target or member or both).

The defaults are defined here.

Any expression or target which does not pass this criteria will be blocked, and you will see a warning in the logs:

    [WARNING] Target class [class example.MyBean] or declaring class of member type [public example.MyBean()] are excluded!

In that case `new MyBean()` was used to create a new instance of class (inside JSP) - it’s blocked because the `target` of such expression is `java.lang.Class` which is excluded.

It is possible to redefine the above constants in `struts.xml`, but avoid reducing the list, instead extending the list with other known dangerous classes or packages in your application.

#### Additional Options

We additionally recommend enabling the following options (enabled by default in 7.0).

- `struts.ognl.allowStaticFieldAccess=false` - static field values which aren’t a primitive type can be used to access classes that wouldn’t otherwise be accessible
- `struts.disallowProxyObjectAccess=true` - disallow proxied objects from being used in OGNL expressions as these often represent application beans or database entities which are sensitive
- `struts.disallowDefaultPackageAccess=true` - disallow access to classes in the default package which should not be used in production
- `struts.ognl.disallowCustomOgnlMap=true` - disallow construction of custom OGNL maps which can be used to bypass the SecurityMemberAccess policy
- `struts.actionConfig.fallbackToEmptyNamespace=false` - prevent Actions in the empty namespace from being accessed from alternative endpoints

#### Allowlist Capability

> Note: Since Struts 6.4. Or by default from 7.0.

For the most stringent OGNL protection, we recommend enabling the allowlist capability with `struts.allowlist.enable`.

Now, in addition to enforcing the exclusion list, classes involved in OGNL expression must also belong to a list of allowlisted classes and packages. By default, all required Struts classes are allowlisted as well as any classes that are defined in your `struts.xml` package configurations.

We highly recommend enabling the parameter annotation capability to ensure any necessary parameter injection types are allowlisted, in addition to its other benefits.

You can add additional classes and packages to the allowlist with:

- `struts.allowlist.classes`: comma-separated list of allowlisted classes.
- `struts.allowlist.packageNames`: comma-separated list of allowlisted packages, matched using string comparison via `startsWith`. Note that classes in subpackages are also allowlisted.

Depending on the functionality of your application, you may not need to manually allowlist any classes. Please monitor your application logs for any warnings about blocked classes and add them to the allowlist as necessary.

#### Extensibility

> Note: since Struts 6.4.

The OGNL Member Access mechanism is extensible, allowing you to define your own rules for blocking access to OGNL expression evaluations. To do so, you may use the `struts.securityMemberAccess` extension point. Please be vigilant when overriding methods as not to reduce protections offered by the default implementation.

### Struts OGNL Guard

> Note: since Struts 6.4.

The Struts OGNL Guard allows applications to completely disable certain OGNL expression features/capabilities. This feature is disabled by default but can be enabled and configured with `struts.ognl.excludedNodeTypes`.

It is recommended to disable any OGNL feature you are not leveraging in your application.

For example, if you do not need to use the addition operation in any OGNL expressions, you can add `ognl.ASTAdd` to your excluded node types. This will mitigate against a host of String concatenation attacks.

For applications using a minimal number of Struts features, you may find the following list a good starting point. Please be aware that this list WILL break certain Struts features.

    <constant name="struts.ognl.excludedNodeTypes"
              value="
                ognl.ASTAdd,
                ognl.ASTAssign,
                ognl.ASTBitAnd,
                ognl.ASTBitNegate,
                ognl.ASTBitOr,
                ognl.ASTCtor,
                ognl.ASTDivide,
                ognl.ASTEval,
                ognl.ASTIn,
                ognl.ASTInstanceof,
                ognl.ASTKeyValue,
                ognl.ASTList,
                ognl.ASTMap,
                ognl.ASTMultiply,
                ognl.ASTNegate,
                ognl.ASTNotIn,
                ognl.ASTProject,
                ognl.ASTRootVarRef,
                ognl.ASTSelect,
                ognl.ASTSelectFirst,
                ognl.ASTSelectLast,
                ognl.ASTSequence,
                ognl.ASTShiftLeft,
                ognl.ASTShiftRight,
                ognl.ASTStaticField,
                ognl.ASTStaticMethod,
                ognl.ASTThisVarRef,
                ognl.ASTUnsignedShiftRight,
                ognl.ASTVarRef,
                ognl.ASTXor
    "/>

#### Extensibility

The Struts OGNL Guard mechanism is extensible, allowing you to define your own rules for blocking access to both raw OGNL expressions and compiled syntax trees. To do so, you may use the `struts.ognlGuard` extension point. You may choose to override the default implementation or implement the `OgnlGuard` interface directly.