This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-staging
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/asf-staging by this push:
new d7b35c224 Updates stage by Jenkins
d7b35c224 is described below
commit d7b35c22453868cce803d0d0ccffaf0283018d23
Author: jenkins <bui...@apache.org>
AuthorDate: Mon Sep 19 13:41:47 2022 +0000
Updates stage by Jenkins
---
.../core-developers/parameters-interceptor.html | 38 +++++++++++++++++++---
1 file changed, 33 insertions(+), 5 deletions(-)
diff --git a/content/core-developers/parameters-interceptor.html
b/content/core-developers/parameters-interceptor.html
index 96dd7dcb9..7b627b824 100644
--- a/content/core-developers/parameters-interceptor.html
+++ b/content/core-developers/parameters-interceptor.html
@@ -136,6 +136,7 @@
<ul id="markdown-toc">
<li><a href="#parameters" id="markdown-toc-parameters">Parameters</a></li>
<li><a href="#excluding-parameters"
id="markdown-toc-excluding-parameters">Excluding parameters</a></li>
+ <li><a href="#excluding-parameter-values"
id="markdown-toc-excluding-parameter-values">Excluding parameter values</a></li>
<li><a href="#extending-the-interceptor"
id="markdown-toc-extending-the-interceptor">Extending the Interceptor</a></li>
<li><a href="#warning-on-missing-parameters"
id="markdown-toc-warning-on-missing-parameters">Warning on missing
parameters</a> <ul>
<li><a href="#examples" id="markdown-toc-examples">Examples</a></li>
@@ -178,6 +179,8 @@ the values to their final data type (<code
class="highlighter-rouge">String[] -&
conversion errors will be reported in the action context. See the type
conversion documentation and the <code
class="highlighter-rouge">XWorkConverter</code>
javadocs for more information.</p>
+<p>Since Struts 6.1.0 this interceptor also implements a <code
class="highlighter-rouge">ParameterValueAware</code> interface. This interface,
in conjunction with the optional <code
class="highlighter-rouge">excludeValuePatterns</code>, 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 i
[...]
+
<p>If you are looking for detailed logging information about your parameters,
turn on <code class="highlighter-rouge">DEBUG</code> level logging for this
interceptor. A detailed log of all the parameter keys and values will be
reported.</p>
@@ -191,9 +194,11 @@ for documentation and examples on how to use this
feature.</p>
<ul>
<li><code class="highlighter-rouge">ordered</code> - set to true if you want
the top-down property setter behaviour</li>
- <li><code class="highlighter-rouge">acceptParamNames</code> - a comma
delimited list of regular expressions to describe a whitelist of accepted
parameter names.
+ <li><code class="highlighter-rouge">acceptParamNames</code> - 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</li>
- <li><code class="highlighter-rouge">excludeParams</code> - a comma delimited
list of regular expressions to describe a blacklist of not allowed parameter
names</li>
+ <li><code class="highlighter-rouge">excludeParams</code> - a comma delimited
list of regular expressions to describe a denylist of not allowed parameter
names</li>
+ <li><code class="highlighter-rouge">acceptedValuePatterns</code> - a comma
delimited list of regular expressions to describe a allowlist of accepted
parameter values </li>
+ <li><code class="highlighter-rouge">excludeValuePatterns</code> - a comma
delimited list of regular expressions to describe a denylist of not allowed
parameter values</li>
<li><code class="highlighter-rouge">paramNameMaxLength</code> - the maximum
length of parameter names; parameters with longer names will be ignored;
the default is 100 characters</li>
</ul>
@@ -226,11 +231,34 @@ will be ignored by the interceptor. Interceptor stacks
defined by Struts already
<span class="nt"><default-interceptor-ref</span> <span
class="na">name=</span><span class="s">"appDefault"</span> <span
class="nt">/></span>
</code></pre></div></div>
+<h2 id="excluding-parameter-values">Excluding parameter values</h2>
+
+<p>This interceptor can be forced to ignore parameters based on the value, by
setting its <code class="highlighter-rouge">excludeValuePatterns</code>
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.</p>
+
+<p>Below is an example of adding parameter values ${} and %{} to the list of
parameter values that should be excluded.</p>
+
+<p><strong>Setup Interceptor Stack To Exclude ${ and %{ Parameter
Values</strong></p>
+
+<div class="language-xml highlighter-rouge"><div class="highlight"><pre
class="highlight"><code><span class="nt"><interceptors></span>
+ <span class="nt"><interceptor-stack</span> <span
class="na">name=</span><span class="s">"appDefault"</span><span
class="nt">></span>
+ <span class="nt"><interceptor-ref</span> <span
class="na">name=</span><span class="s">"defaultStack"</span><span
class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"exception.logEnabled"</span><span class="nt">></span>true<span
class="nt"></param></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"exception.logLevel"</span><span class="nt">></span>ERROR<span
class="nt"></param></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"params.excludeValuePatterns"</span><span
class="nt">></span>.*\$\{.*?\}.*,.*%\{.*?\}.*<span
class="nt"></param></span>
+ <span class="nt"></interceptor-ref></span>
+ <span class="nt"></interceptor-stack></span>
+<span class="nt"></interceptors></span>
+
+<span class="nt"><default-interceptor-ref</span> <span
class="na">name=</span><span class="s">"appDefault"</span> <span
class="nt">/></span>
+</code></pre></div></div>
+
<h2 id="extending-the-interceptor">Extending the Interceptor</h2>
-<p>The best way to add behavior to this interceptor is to utilize the <code
class="highlighter-rouge">ParameterNameAware</code> interface in your actions.
+<p>The best way to add behavior to this interceptor is to utilize the <code
class="highlighter-rouge">ParameterNameAware</code> and <code
class="highlighter-rouge">ParameterValueAware</code> 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 <code
class="highlighter-rouge">#acceptableName(String)</code> method.</p>
+and override the <code
class="highlighter-rouge">#acceptableName(String)</code> and/or <code
class="highlighter-rouge">#acceptableParameterValue(String)</code> method.</p>
<blockquote>
<p>Using <code class="highlighter-rouge">ParameterNameAware</code> could be
dangerous as <code
class="highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code>
takes precedence
@@ -240,7 +268,7 @@ it with <code
class="highlighter-rouge">ParameterNameAware#acceptableParameterNa
<blockquote>
<p>The best idea is to define very tight restrictions with <code
class="highlighter-rouge">ParametersInterceptor</code> and relax them per
action
-with <code
class="highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code></p>
+with <code
class="highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code>
and/or <code
class="highlighter-rouge">ParameterValueAware#acceptableParameterValue(String)</code></p>
</blockquote>
<h2 id="warning-on-missing-parameters">Warning on missing parameters</h2>
