This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch WW-4323-parameternameaware-docs in repository https://gitbox.apache.org/repos/asf/struts-site.git
commit 47f5012e38b9b18de4e99b482114a2a0a90819a9 Author: Lukasz Lenart <[email protected]> AuthorDate: Thu Oct 22 21:16:02 2026 +0200 WW-4323 docs: ParameterNameAware narrows, never widens, the params checks The Parameters Interceptor page claimed ParameterNameAware takes precedence over the interceptor, which has not been true since 2.3.16.1. Point per-action relaxation at the interceptor parameters, and correct the stale method names and the excludedValuePatterns parameter name. Co-Authored-By: Claude Opus 5.5 <[email protected]> --- source/core-developers/parameters-interceptor.md | 31 +++++++++++++++--------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/source/core-developers/parameters-interceptor.md b/source/core-developers/parameters-interceptor.md index 5fabfdbcf0..7f0c334505 100644 --- a/source/core-developers/parameters-interceptor.md +++ b/source/core-developers/parameters-interceptor.md @@ -30,9 +30,9 @@ like [Preparable Interface](prepare-interceptor). Because parameter names are effectively OGNL statements, it is important that security be taken in to account. This interceptor will not apply any values in the parameters map if the expression contains an assignment (=), multiple -expressions (,), or references any objects in the context (#). This is all done in the `#acceptableName(String)` +expressions (,), or references any objects in the context (#). This is all done in the `#isAcceptableName(String)` method. In addition to this method, if the action being invoked implements the `ParameterNameAware` interface, the action -will be consulted to determine if the parameter should be set. +will be consulted to determine if the parameter should be set. A parameter is set only when both checks accept it. In addition to these restrictions, a flag (`ReflectionContextState#DENY_METHOD_EXECUTION`) is set such that no methods are allowed to be invoked. That means that any expression such as `person.doSomething()` or `person.getName()` will be @@ -48,12 +48,12 @@ conversion errors will be reported in the action context. See the type conversio javadocs for more information. Since Struts 6.1.0 this interceptor also implements a `ParameterValueAware` interface. This interface, in conjunction -with the optional `excludeValuePatterns`, can be used to validate the parameter value(s) being set by the interceptor. +with the optional `excludedValuePatterns`, can be used to validate the parameter value(s) being set by the interceptor. If the value being set is excluded / not accepted the entire parameter will be dropped. This can be leveraged to mitigate against forced OGNL evaluation due to unsanitized user input being echoed back as part of the action result. This is not intended to replace good coding habits as described on [Proactively protect from OGNL Expression Injections attacks if easily applicable](../../security/#proactively-protect-from-ognl-expression-injections-attacks-if-easily-applicable) -and is available as part of a defense in depth methodology. By default excludeValuePatterns is not defined. +and is available as part of a defense in depth methodology. By default excludedValuePatterns is not defined. If you are looking for detailed logging information about your parameters, turn on `DEBUG` level logging for this interceptor. A detailed log of all the parameter keys and values will be reported. @@ -71,7 +71,7 @@ For more information on ways to restrict the parameter names allowed, see the `P Don't change the default unless you know what you are doing in terms of security implications - `excludeParams` - a comma delimited list of regular expressions to describe a denylist of not allowed parameter names - `acceptedValuePatterns` - a comma delimited list of regular expressions to describe a allowlist of accepted parameter values -- `excludeValuePatterns` - a comma delimited list of regular expressions to describe a denylist of not allowed parameter values +- `excludedValuePatterns` - a comma delimited list of regular expressions to describe a denylist of not allowed parameter values - `paramNameMaxLength` - the maximum length of parameter names; parameters with longer names will be ignored; the default is 100 characters @@ -137,15 +137,24 @@ and only accept **a-z** or **0-9**. The best way to add behavior to this interceptor is to utilize the `ParameterNameAware` and `ParameterValueAware` interfaces in your actions. However, if you wish to apply a global rule that isn't implemented in your action, then -you could extend this interceptor and override the `#acceptableName(String)` and/or `#acceptableParameterValue(String)` +you could extend this interceptor and override the `#isAcceptableName(String)` and/or `#isAcceptableValue(String, String)` method. -> Using `ParameterNameAware` could be dangerous as `ParameterNameAware#acceptableParameterName(String)` takes precedence -> over `ParametersInterceptor` which means if `ParametersInterceptor` excluded given parameter name you can accept -> it with `ParameterNameAware#acceptableParameterName(String)`. +> `ParameterNameAware#acceptableParameterName(String)` and `ParameterValueAware#acceptableParameterValue(String)` can +> only narrow what the interceptor accepts. A parameter rejected by the interceptor's own checks (accepted/excluded +> patterns, name length) is never set, even if the action accepts it. -> The best idea is to define very tight restrictions with `ParametersInterceptor` and relax them per action -> with `ParameterNameAware#acceptableParameterName(String)` and/or `ParameterValueAware#acceptableParameterValue(String)` +> To relax the rules for a single action, set the interceptor parameters (`acceptParamNames`, `excludeParams`, +> `acceptedValuePatterns`, `excludedValuePatterns`) in that action's configuration instead: + +```xml +<action name="myAction" class="com.example.MyAction"> + <interceptor-ref name="defaultStack"> + <param name="params.acceptParamNames">...</param> + </interceptor-ref> + <result>/success.jsp</result> +</action> +``` ## Warning on missing parameters
