Parameter Injection and @StrutsParameter

All examples belong to one scratch WAR built from the bookshelf-struts base: struts2-core 7.4.0 from the org.apache.struts:struts2-bom:7.4.0, log4j-slf4j2-impl, the Servlet and Pages APIs with scope provided, the filter StrutsPrepareAndExecuteFilter mapped to /* in web.xml, and a log4j2.xml that writes the logger org.apache.struts2.interceptor.parameter at DEBUG to a file, so that the decision about every parameter can be read. The WAR is deployed on Tomcat 11.0.26 under the context /g9params. Three more deployments of the same classes differ only in one file, WEB-INF/classes/struts.properties, which changes the binding constants (the table below). Imports and package lines are left out of the listings; the package is org.example.bookshelf. The view of every action is a JSP that prints a dump property as plain text, so that one request shows everything that the binding did.

Source: Apache Struts — default.properties

The request examples use curl against http://localhost:18080. The brackets of books[0].title are not legal in a raw URL query (Tomcat answers HTTP 400, Invalid character found in the request target), so the examples that contain brackets send them in a form body with POST, which is also how a browser sends a form.

Struts has no form-bean layer between the request and the action. The params interceptor reads the request parameters from the ActionContext and, for each name and value, calls ValueStack.setValue(name, value). The name is an OGNL expression evaluated against the value stack, so filter calls setFilter, book.title calls getBook().setTitle(...), tags with two values fills a List, and books[0].title reaches the first element of a list. The conversion of the String values to int, Date, List<String> and so on happens during that call; the type conversion page of this part covers it and conversionError (the next interceptor in the stack) reports failures. While the call runs, the interceptor sets three flags on the OGNL context: no method execution (a name such as person.doSomething() is refused), automatic creation of null objects on the path (so book.publisher.name can create the Publisher), and reporting of conversion errors.

The same mechanism is what made old Struts applications vulnerable: any public setter, and any property reachable through a getter, was a way to write into the server. Two verified examples from the project’s own history sit at the two ends of the spectrum. CVE-2014-0114 is the class loader manipulation through Commons BeanUtils in Struts 1.x, where a request parameter named class reached the class loader through the bean that BeanUtils populated. CVE-2024-53677 (bulletin S2-067, see Security Bulletins) is a flaw of the file upload logic in which an attacker mixes the setters of uploaded files with normal fields to manipulate upload paths, which is one reason the old upload interceptor was removed in 7.0. Struts 7 answers with defence in depth, and @StrutsParameter is the part that the action author writes.

Source: CVE-2014-0114

Source: Apache Struts — Security Bulletin S2-067

Source: Apache Struts — Parameters Interceptor

params is interceptor 17 of the 24 in defaultStack (see Interceptors) and it appears twice in paramsPrepareParamsStack, before and after prepare. Four neighbours matter for binding:

In defaultStack the interceptor prepare (7) runs before params, so prepare() sees an action that has no request data yet; the stack paramsPrepareParamsStack exists for the case where it must see it. Both stacks are described in the interceptors page, and the action class that receives the values is described in Actions.

Source: Apache Struts — Interceptors, The Default Configuration

A parameter is applied only if it passes every check below, in this order. The order comes from the 7.4.0 bytecode of ParametersInterceptor (toAcceptableParameters calls the name checks, then the annotation check, then the value checks) and was confirmed by the DEBUG log of the scratch WAR.

The diagram has two outcomes that look the same from the outside and differ in the log. A parameter dropped by the interceptor is logged at DEBUG (a name pattern, an annotation, a value pattern) or, for an over-long name, at WARN. A parameter that passes the interceptor but reaches a class that the OGNL allowlist does not know is blocked inside OGNL and logged at WARN by SecurityMemberAccess. The two layers are independent: @StrutsParameter decides which properties may be written, the allowlist decides which classes OGNL may touch at all, and a nested example below needs both.

Source: Apache Struts — Parameters Interceptor, Parameters

Source: Apache Struts — Security, Defining and annotating your Action parameters

Source: Apache Struts — Security, Allowlist Capability

Source: Apache Struts 7.4.0 Javadoc — ParametersInterceptor

org.apache.struts2.interceptor.parameter.StrutsParameter is a runtime annotation with two members:

The annotation goes on one of three places, and the place says what is being authorised:

Since 7.4.0 a setter that returns a value instead of void (a fluent setter) is honoured too; before, an annotation on it was ignored (WW-5709). Annotated members must be safe for any user who can reach the action: the security guide says never to annotate a getter that returns a live Hibernate entity, a Spring bean or any service, and to keep database entities apart from request DTOs.

Source: Apache Struts — StrutsParameter Annotation, Usage

Source: Apache Struts 7.4.0 Javadoc — StrutsParameter

The official page states the rule in one sentence: depth is the number of periods or brackets that may appear in the parameter name, and indexing into a collection or a map is itself a level, so reaching a property of a list element costs one more than reaching the same property of a plain object. A first request on the default deployment sets only annotated members:

limit and sort kept their defaults (10 and -) and hidden.title was ignored: no annotation, no binding, and no error in the response; the request is answered normally. The table lists the individual requests, each sent alone to /g9params/shelf and compared with the unchanged page.

Source: Apache Struts — StrutsParameter Annotation, Understanding the depth parameter

Three rules summarise the table. First, the setter annotation and the getter annotation do different jobs: tags=sf&tags=classic needs the setter, genres[0]=space needs the getter with a depth, and an indexed list that is posted by a JSON body needs the getter as well. Second, count the segments after the annotated property, and add one for every index, so books[0].title is 2 and book.title is 1. Third, the depth is a ceiling that the security guide asks you to keep at the smallest value the use case needs (its DTO example uses depth = 1 for formData.fullName).

In the DEBUG log the same decisions read as follows, with the logger StrutsParameterAuthorizer:

Source: Apache Struts — Security, Defining and annotating your Action parameters

The annotation passes featured.publisher.name (depth 2 on getFeatured), and still the value does not arrive on the default deployment. The log shows why, one layer further down:

With struts.allowlist.enable=true (the 7.x default), OGNL may only touch allowlisted classes: the Struts classes, the classes named in struts.xml packages, and the types that the annotated members return (here Book, which is why book.title works). A class that sits deeper in the graph, Publisher at the second level, is not added by itself. The deployment /g9paramsal adds it with struts.allowlist.classes=org.example.bookshelf.Publisher:

Only featured.publisher.name arrived: book.publisher.name and books[0].publisher.name still fail the depth check, which the allowlist cannot change. The two constants are independent and a nested form needs both: the right depth and a class that OGNL may touch. The apache/struts-examples project struts-parameter shows the same combination, a struts.xml constant struts.allowlist.packageNames for the example package and @StrutsParameter(depth = 2) on a getter that returns a list of users and on an adminUser property.

Source: Apache Struts — Security, Allowlist Capability

Source: apache/struts-examples — struts-parameter

Two constants in default.properties control the annotation requirement:

Source: Apache Struts — default.properties

requireAnnotations was opt-in in Struts 6.4 and is the default since 7.0. transitionMode is a migration aid for an application whose actions have many unannotated setters: with it on, only nested parameters (DTOs and collections that are reached through getters) require annotations, and plain public setters stay exposed. The auto-allowlisting that the annotations provide is not degraded, so an application can turn the allowlist on first and add the annotations later. The scratch WAR was deployed three times and sent the same request. The request was filter=dune&limit=5&sort=title&hidden.title=X&genres[0]=s&book.title=D&books[0].title=U.

The requireAnnotations=false row holds a lesson: without annotations the allowlist is the only brake on nested properties. Nothing allowlisted Book (no annotated getter returns it), so book.title, hidden.title and books[0].title all failed with SecurityMemberAccess warnings, while the plain setters limit and sort were applied. That configuration is not a safe mode: it is the pre-7 behaviour for every top-level setter, and a class that gets allowlisted for another reason becomes writable from the request. In transition mode limit and sort are written (non-nested) but hidden.title is still refused, and the log says so:

Source: Apache Struts — Security, Defining and annotating your Action parameters

When an action implements ModelDriven<T> and the modelDriven interceptor has pushed the model on the value stack, the model, not the action, is the authorisation target and the model’s members are exempt from the annotation requirement: the whole model is bindable, nested properties included. The reasoning in the guide is that returning an object from getModel() declares that object to be the request surface. The consequences are why the guide says a model must be a request DTO and never a domain or persistence entity.

title and author reached the model without any annotation on Book. filter reached the action because it is annotated. limit did not: since 7.4.0 the exemption covers the model and only the model, and the log names the reason:

The decision order of the guide is: the model declares the property, so it is bound; the action declares it, so it is bound only if annotated; neither declares it, so it is bound (to keep models that resolve properties through a custom OGNL accessor, such as a map-backed model, working). Because the model is checked first, a model property that shadows an action property, as getTitle does above, binds without an annotation, which matches how OGNL resolves the name against the top of the stack. Before 7.4.0 every parameter sent to a ModelDriven action was exempt, so an application that relied on that either annotates those setters now or turns on transition mode, which exempts non-nested parameters on ModelDriven actions as well (the deployment /g9paramstm set limit=5 on this action, verified).

The exemption lifts the annotation requirement and nothing else: name patterns, ParameterNameAware and the OGNL allowlist still apply. publisher.name=Tor on the default deployment changes nothing because Publisher is not allowlisted; on /g9paramsal the same request yields model=Book[null,null,null,Publisher[Tor,null]]. A ModelDriven action outside the model is not exempt, so a JSON interceptor root expression on an action that does not implement the interface still needs annotations. The model-driven and Preparable page of this part covers the pattern; this page owns the binding rule.

Source: Apache Struts — StrutsParameter Annotation, ModelDriven actions

Source: Apache Struts — StrutsParameter Annotation, The action’s own members are not exempt

Before the annotation is consulted, the interceptor checks the name. The 7.4.0 class DefaultAcceptedPatternsChecker holds the default accepted name pattern, and DefaultExcludedPatternsChecker the excluded ones. The accepted pattern, copied from the constant pool of the jar, is a word followed by any number of .word, [digits], (digits), ['key'] and ('key') segments:

Source: Apache Struts — Security, Accepted / Excluded Patterns

That is why labels[en] is refused (a bracket needs digits or a quoted key) and labels['en'] is accepted. The log names the pattern that rejected a name:

Source: Apache Struts — Parameters Interceptor, Excluding parameters

The excluded patterns cover the objects that an attacker would want to reach: the context maps (session, request, application, parameters, context), the struts and dojo helpers, the member access object, top and any class reference, and the names actionErrors, actionMessages and fieldErrors. When dynamic method invocation is disabled (the default), the prefixes action: and method: are excluded as well. The official page lists a shorter, older regular expression list under Default List of Parameters Excluded; trust the jar, as the next paragraph explains. On the Bookshelf, request.value=1, struts.x=1, book.class.name=x and %23session.x=1 (the encoded form of #session.x) all left the dump unchanged.

Since Struts 6.1.0 the interceptor also checks values, with acceptedValuePatterns (an allowlist of regular expressions that every value must match) and excludedValuePatterns (a denylist), both comma-separated. A value that fails drops the whole parameter. The guide presents it as defence in depth against forced OGNL evaluation when user input is echoed back into an expression, not as a replacement for good code. The bookshelfParams stack above accepts only word characters, white space, apostrophes and hyphens, and refuses any value that contains ${ or %{:

The last two values, a<b and ${1}, matched neither the accepted pattern nor the excluded one’s negation and were dropped, leaving the default -. The log line is DEBUG ParametersInterceptor Value [a{1}] of parameter [filter] was not accepted and will be dropped!. Keep two cautions in mind. A pattern such as [a-zA-Z0-9]* (the guide’s example) refuses names with accents and punctuation in a book title, so on the Bookshelf the accepted pattern would be too tight for a title field; apply value patterns on the actions that take identifiers and codes, not on free text. And the attribute is spelled excludedValuePatterns in the XML snippet of the guide and excludeValuePatterns in its prose; the setter in the 7.4.0 jar is setExcludedValuePatterns.

Source: Apache Struts — Parameters Interceptor, Excluding parameter values

An action can veto parameters itself by implementing org.apache.struts2.action.ParameterNameAware (the method acceptableParameterName(String)) and org.apache.struts2.action.ParameterValueAware (acceptableParameterValue(String), since 6.1.0). The GuardedAction accepts every name except secret and rejects every value that contains the text DROP, and secret is annotated, so the veto is the only thing that stops it:

The Parameters Interceptor page says that ParameterNameAware takes precedence over the interceptor, so that an action can accept a name that the interceptor excluded. On 7.4.0 that is not what happens: isAcceptableName runs first and isAcceptableParameterNameAware only afterwards (the code shows isAcceptableName(...) && isAcceptableParameterNameAware(...)), and the scratch action answers true to request.value, yet /guarded?request.value=X leaves request.value=untouched (the default excluded pattern wins). Use the interfaces to be stricter, not looser. The Javadoc of ParameterNameAware recommends the same pattern, a white list of accepted parameters or a black list of rejected ones.

Source: Apache Struts 7.4.0 Javadoc — ParameterNameAware

Source: Apache Struts 7.4.0 Javadoc — ParameterValueAware

Source: Apache Struts — Parameters Interceptor, Extending the Interceptor

Two more interfaces of org.apache.struts2.action change what the interceptor does for an action. NoParameters is a marker: the interceptor is skipped for the whole action, whatever the request carries. ParametersAware has the single method withParameters(HttpParameters) and receives the whole parameter map of the request without any binding, which is the clean way to read parameters that are not properties.

filter and edition are annotated on the parent class and would be set on /shelf; on /frozen nothing is. Use the marker for a read-only action (a dashboard, a download) where a parameter should never change state.

Source: Apache Struts 7.4.0 Javadoc — NoParameters

Source: Apache Struts 7.4.0 Javadoc — ParametersAware

Two interceptors in defaultStack set properties without the request. They run before params, they are not subject to @StrutsParameter (the values are written by the configuration, which the author controls), and the later params interceptor cannot override them if its own parameter is refused:

staticParams applied <param name="sort"> and <param name="limit"> to the unannotated setters setSort and setLimit, and the request’s sort=hacked&limit=3 changed nothing. actionMappingParams applied the wildcard value {1} of page-* to sort in the same way. That is a good place for constants that must not be user-controlled, and a reminder that these two channels bypass the annotation. The wildcard page of this part covers the {1} syntax.

Source: Apache Struts — Static Parameters Interceptor

Source: Apache Struts — Action Configuration

By default the order in which parameters are applied is the order of the parameter map, which is not something to build logic on. The params interceptor has the parameter ordered: when true, properties are applied top-down, the action’s own properties first and then the properties of its sub-objects, so that a modelClass property can choose the model implementation before the model’s fields are set (the guide’s factory example), or setPrimaryKey can load an entity before its fields are filled. Without a guaranteed order the alternative is the Preparable interface and the stack paramsPrepareParamsStack, covered with the model-driven page. The orderedParams stack of the scratch WAR enables it:

On /tuned/ordered?filter=a&book.title=D the request is bound as on /shelf (filter=a, book=Book[D,...]); the guarantee is about order, which a one-property check cannot show, so the example proves only that the stack deploys and binds. The annotation checks apply unchanged.

Source: Apache Struts — Parameters Interceptor

A form is where the names come from. The Struts tags generate the names the interceptor must accept; the tag form and the action must agree on both name and depth. The edit action shows a form for the list of books, a single book and the filter:

The form is rendered with empty values because the edit action has not been given any. Submitting it posts three annotated paths and one annotated setter, and the action accepts them all:

Posting books[0].title=Dune&book.title=Emma&filter=sf to /g9params/edit instead redraws the form with the values in place (books[0].title is Dune, book.title is Emma, filter is sf, books[1].title stays empty), because the tags read the property back through the value stack (verified). The effect is the same as the ActionForm redisplay of Struts 1, without a form class. Two habits keep a real form safe: name the inputs only with paths that the annotations allow (a form field that the action rejects is a silent bug, not an error), and do not use the submit button’s name as a property (the guide’s Exclude Parameters tutorial exists because s:submit creates a submit parameter that has no setter).

Source: Apache Struts — textfield tag

Source: Apache Struts — Getting Started, Exclude Parameters

Since 7.2.0 the @StrutsParameter authorisation is enforced on every channel that can populate an action from request data, not only on params:

For the JSON and REST plugins three details matter. Properties are matched by their Java member, not by their wire name (@JsonProperty, @JsonAlias or a naming strategy do not change which member is authorised; the wire name was used up to 7.3.0, WW-5715). Properties bound by a constructor (Java record components, @JsonCreator constructors and @ConstructorProperties) bypassed the check up to Struts 7.2.1 and are authorised like any other property since 7.3.0 (WW-5642): an unauthorised component is left unset, and if the record’s own constructor refuses the null the whole object under construction is dropped. A REST action that relied on record bodies without annotations therefore needs @StrutsParameter(depth = ...) on the getter that reaches them, or a ModelDriven model, otherwise the values silently stop arriving. And a class with a Jackson any-setter (@JsonAnySetter) is not wrapped by default: since 7.4.0 the constant struts.rest.anySetter.requireAnnotations=true (default false, effective only when requireAnnotations is on) makes an any-setter receive keys only when it carries @StrutsParameter(allowDynamicKeys = true), with depth limiting the nesting of each key’s value:

The REST plugin page of this part covers these in context. The snippets above are copied from the guide and were not run: the REST plugin was not part of the scratch WAR.

Source: Apache Struts — StrutsParameter Annotation, Where authorization applies

Source: Apache Struts — StrutsParameter Annotation, Creator-bound properties

Source: Apache Struts — StrutsParameter Annotation, Jackson any-setters

A reader who knows Struts 1 asks where the ActionForm went. The concepts map one to one, and the old safety argument, that the form is a firewall between the request and the business objects, is now made by the annotations.

Struts 1 reached end of life in 2013 and CVE-2014-0114 was never fixed there; this table serves reading and migrating legacy code, not new design.

Source: Apache Struts — StrutsParameter Annotation

Source: Apache Struts — Struts 1 end of life announcement

Turn the DEBUG level on for the package org.apache.struts2.interceptor.parameter and every parameter prints the sequence of checks above. The scratch WAR used this log4j2.xml:

Three things to look for: StrutsParameterAuthorizer lines say why an annotation was or was not found, the line Setting params ... lists what the interceptor tries to apply, and SecurityMemberAccess warnings (from the OGNL package) say that a class is not allowlisted. In devMode, a parameter that has no setter additionally produces the Developer Notification that the official page quotes; keep devMode off in production, as the security guide requires.

Source: Apache Struts — Parameters Interceptor, Warning on missing parameters

Source: Apache Struts — Security

Source: Apache Struts — StrutsParameter Annotation

Source: Apache Struts — Parameters Interceptor

Source: Apache Struts — Struts 6.x.x to 7.x.x migration

Source: Apache Struts — StrutsParameter Annotation

Source: Apache Struts — Security, Accepted / Excluded Patterns

Two of the section’s books deal with binding. Struts 2 in Action (Manning, 2008, chapters 3 and 5) is written for Struts 2.0, where any public setter filled from the request, and Struts in Action (Manning, 2002, chapter 5, ActionForms) is about Struts 1 forms. The concepts carry over, with the exceptions below.

Source: Apache Struts — Struts 6.x.x to 7.x.x migration

Source: Apache Struts — Struts 2.5 to 6.0.0 migration

Reading the official pages against the 7.4.0 jar and the scratch WAR showed inconsistencies that a reader will meet.