This is an automated email from the ASF dual-hosted git repository.
lukaszlenart pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/master by this push:
new 3c8e0710f Update docs for WW-5184 (#170)
3c8e0710f is described below
commit 3c8e0710fe47b92ba8bd15d667660f2a67eb6d4b
Author: brianandle <106392082+brianan...@users.noreply.github.com>
AuthorDate: Mon Sep 19 06:39:48 2022 -0700
Update docs for WW-5184 (#170)
* Update parameters-interceptor.md
Updating for excludeValuePatterns/WW-5184
NOTE: The existing Using `ParameterNameAware` could be dangerous as
`ParameterNameAware#acceptableParameterName(String)` text is wrong because of
WW-4323 but I see thats slated to be fixed in 6.1.0.
* Update parameters-interceptor.md
* Update parameters-interceptor.md
* Update parameters-interceptor.md
---
source/core-developers/parameters-interceptor.md | 38 ++++++++++++++++++++----
1 file changed, 33 insertions(+), 5 deletions(-)
diff --git a/source/core-developers/parameters-interceptor.md
b/source/core-developers/parameters-interceptor.md
index 0aa7cee85..c1af6ff41 100644
--- a/source/core-developers/parameters-interceptor.md
+++ b/source/core-developers/parameters-interceptor.md
@@ -47,6 +47,8 @@ the values to their final data type (`String[] -> int`) an
unrecoverable error o
conversion errors will be reported in the action context. See the type
conversion documentation and the `XWorkConverter`
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. 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 [...]
+
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.
@@ -59,9 +61,11 @@ For more information on ways to restrict the parameter names
allowed, see the `P
## Parameters
- `ordered` - set to true if you want the top-down property setter behaviour
-- `acceptParamNames` - a comma delimited list of regular expressions to
describe a whitelist of accepted parameter names.
+- `acceptParamNames` - a comma delimited list of regular expressions to
describe a allowlist of accepted parameter names.
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 blacklist of not allowed parameter names
+- `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
- `paramNameMaxLength` - the maximum length of parameter names; parameters
with longer names will be ignored;
the default is 100 characters
@@ -95,18 +99,42 @@ Below is an example of adding a parameter named submit to
the list of parameters
<default-interceptor-ref name="appDefault" />
```
+## Excluding parameter values
+
+This interceptor can be forced to ignore parameters based on the value, by
setting its `excludeValuePatterns` attribute. This attribute accepts
+a comma separated list of regular expressions. When any of these expressions
match the value of a parameter, such parameter
+will be ignored by the interceptor.
+
+Below is an example of adding parameter values ${} and %{} to the list of
parameter values that should be excluded.
+
+**Setup Interceptor Stack To Exclude ${ and %{ Parameter Values**
+
+```xml
+<interceptors>
+ <interceptor-stack name="appDefault">
+ <interceptor-ref name="defaultStack">
+ <param name="exception.logEnabled">true</param>
+ <param name="exception.logLevel">ERROR</param>
+ <param
name="params.excludeValuePatterns">.*\$\{.*?\}.*,.*%\{.*?\}.*</param>
+ </interceptor-ref>
+ </interceptor-stack>
+</interceptors>
+
+<default-interceptor-ref name="appDefault" />
+```
+
## Extending the Interceptor
-The best way to add behavior to this interceptor is to utilize the
`ParameterNameAware` interface in your actions.
+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)` method.
+and override the `#acceptableName(String)` and/or
`#acceptableParameterValue(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)`.
> The best idea is to define very tight restrictions with
> `ParametersInterceptor` and relax them per action
-> with `ParameterNameAware#acceptableParameterName(String)`
+> with `ParameterNameAware#acceptableParameterName(String)` and/or
`ParameterValueAware#acceptableParameterValue(String)`
## Warning on missing parameters
