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 1f72ecece Updates stage by Jenkins
1f72ecece is described below
commit 1f72ecece95d89b40cc57b66f347cf08d06a577d
Author: jenkins <[email protected]>
AuthorDate: Sat Nov 5 16:53:27 2022 +0000
Updates stage by Jenkins
---
.../core-developers/parameters-interceptor.html | 78 ++++++++++++----------
1 file changed, 43 insertions(+), 35 deletions(-)
diff --git a/content/core-developers/parameters-interceptor.html
b/content/core-developers/parameters-interceptor.html
index 3a419816b..22f8d5a61 100644
--- a/content/core-developers/parameters-interceptor.html
+++ b/content/core-developers/parameters-interceptor.html
@@ -146,60 +146,66 @@
<p>This interceptor sets all parameters on the value stack.</p>
-<p>This interceptor gets all parameters from <code class="language-plaintext
highlighter-rouge">ActionContext#getParameters()</code> and sets them on the
value stack by calling
-<code class="language-plaintext highlighter-rouge">ValueStack#setValue(String,
Object)</code>, typically resulting in the values submitted in a form request
being applied
-to an action in the value stack. Note that the parameter map must contain a
<code class="language-plaintext highlighter-rouge">String</code> key and often
containers a <code class="language-plaintext highlighter-rouge">String[]</code>
+<p>This interceptor gets all parameters from <code class="language-plaintext
highlighter-rouge">ActionContext#getParameters()</code> and sets them on the
value stack by calling
+<code class="language-plaintext highlighter-rouge">ValueStack#setValue(String,
Object)</code>, typically resulting in the values submitted in a form request
being applied
+to an action in the value stack. Note that the parameter map must contain a
<code class="language-plaintext highlighter-rouge">String</code> key and often
containers a <code class="language-plaintext highlighter-rouge">String[]</code>
for the value.</p>
-<p>The interceptor takes one parameter named <code class="language-plaintext
highlighter-rouge">ordered</code>. When set to true action properties are
guaranteed to be set top-down
-which means that top action’s properties are set first. Then it’s
subcomponents properties are set. The reason for this
-order is to enable a “factory” pattern. For example, let’s assume that one has
an action that contains a property named
-<code class="language-plaintext highlighter-rouge">modelClass</code> that
allows to choose what is the underlying implementation of model. By assuring
that <code class="language-plaintext highlighter-rouge">modelClass</code>
-property is set before any model properties are set, it’s possible to choose
model implementation during
-<code class="language-plaintext
highlighter-rouge">action.setModelClass()</code> call. Similarly it’s possible
to use <code class="language-plaintext
highlighter-rouge">action.setPrimaryKey()</code> property set call to actually
-load the model class from persistent storage. Without any assumption on
parameter order you have to use patterns
+<p>The interceptor takes one parameter named <code class="language-plaintext
highlighter-rouge">ordered</code>. When set to true action properties are
guaranteed to be set top-down
+which means that top action’s properties are set first. Then it’s
subcomponents properties are set. The reason for this
+order is to enable a “factory” pattern. For example, let’s assume that one has
an action that contains a property named
+<code class="language-plaintext highlighter-rouge">modelClass</code> that
allows to choose what is the underlying implementation of model. By assuring
that <code class="language-plaintext highlighter-rouge">modelClass</code>
+property is set before any model properties are set, it’s possible to choose
model implementation during
+<code class="language-plaintext
highlighter-rouge">action.setModelClass()</code> call. Similarly it’s possible
to use <code class="language-plaintext
highlighter-rouge">action.setPrimaryKey()</code> property set call to actually
+load the model class from persistent storage. Without any assumption on
parameter order you have to use patterns
like <a href="prepare-interceptor">Preparable Interface</a>.</p>
-<p>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
+<p>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 <code class="language-plaintext
highlighter-rouge">#acceptableName(String)</code>
-method. In addition to this method, if the action being invoked implements the
<code class="language-plaintext highlighter-rouge">ParameterNameAware</code>
interface, the action
+method. In addition to this method, if the action being invoked implements the
<code class="language-plaintext highlighter-rouge">ParameterNameAware</code>
interface, the action
will be consulted to determine if the parameter should be set.</p>
-<p>In addition to these restrictions, a flag (<code class="language-plaintext
highlighter-rouge">ReflectionContextState#DENY_METHOD_EXECUTION</code>) is set
such that no methods
-are allowed to be invoked. That means that any expression such as <code
class="language-plaintext highlighter-rouge">person.doSomething()</code> or
<code class="language-plaintext highlighter-rouge">person.getName()</code> will
be
-explicitly forbidden. This is needed to make sure that your application is not
exposed to attacks by malicious users.</p>
+<p>In addition to these restrictions, a flag (<code class="language-plaintext
highlighter-rouge">ReflectionContextState#DENY_METHOD_EXECUTION</code>) is set
such that no methods
+are allowed to be invoked. That means that any expression such as <code
class="language-plaintext highlighter-rouge">person.doSomething()</code> or
<code class="language-plaintext highlighter-rouge">person.getName()</code> will
be
+explicitly forbidden. This is needed to make sure that your application is not
exposed to attacks by malicious users.</p>
-<p>While this interceptor is being invoked, a flag (<code
class="language-plaintext
highlighter-rouge">ReflectionContextState#CREATE_NULL_OBJECTS</code>) is turned
on to ensure
-that any null reference is automatically created - if possible. See the type
conversion documentation
-and the <code class="language-plaintext
highlighter-rouge">InstantiatingNullHandler</code> javadocs for more
information.</p>
+<p>While this interceptor is being invoked, a flag (<code
class="language-plaintext
highlighter-rouge">ReflectionContextState#CREATE_NULL_OBJECTS</code>) is turned
on to ensure
+that any null reference is automatically created - if possible. See the type
conversion documentation
+and the <code class="language-plaintext
highlighter-rouge">InstantiatingNullHandler</code> javadocs for more
information.</p>
-<p>Finally, a third flag (<code class="language-plaintext
highlighter-rouge">XWorkConverter#REPORT_CONVERSION_ERRORS</code>) is set that
indicates any errors when converting
-the values to their final data type (<code class="language-plaintext
highlighter-rouge">String[] -> int</code>) an unrecoverable error occurred.
With this flag set, the type
-conversion errors will be reported in the action context. See the type
conversion documentation and the <code class="language-plaintext
highlighter-rouge">XWorkConverter</code>
+<p>Finally, a third flag (<code class="language-plaintext
highlighter-rouge">XWorkConverter#REPORT_CONVERSION_ERRORS</code>) is set that
indicates any errors when converting
+the values to their final data type (<code class="language-plaintext
highlighter-rouge">String[] -> int</code>) an unrecoverable error occurred.
With this flag set, the type
+conversion errors will be reported in the action context. See the type
conversion documentation and the <code class="language-plaintext
highlighter-rouge">XWorkConverter</code>
javadocs for more information.</p>
-<p>Since Struts 6.1.0 this interceptor also implements a <code
class="language-plaintext highlighter-rouge">ParameterValueAware</code>
interface. This interface, in conjunction with the optional <code
class="language-plaintext 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 OGN [...]
+<p>Since Struts 6.1.0 this interceptor also implements a <code
class="language-plaintext highlighter-rouge">ParameterValueAware</code>
interface. This interface, in conjunction
+with the optional <code class="language-plaintext
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 input being
echoed back as part of the action result.
+This is not intended to replace good coding habits as described on
+<a
href="../../security/#proactively-protect-from-ognl-expression-injections-attacks-if-easily-applicable">Proactively
protect from OGNL Expression Injections attacks if easily applicable</a>
+and is available as part of a defense in depth methodology. By default
excludeValuePatterns is not defined.</p>
-<p>If you are looking for detailed logging information about your parameters,
turn on <code class="language-plaintext highlighter-rouge">DEBUG</code> level
logging for this
+<p>If you are looking for detailed logging information about your parameters,
turn on <code class="language-plaintext highlighter-rouge">DEBUG</code> level
logging for this
interceptor. A detailed log of all the parameter keys and values will be
reported.</p>
<p>Since XWork 2.0.2, this interceptor extends <code class="language-plaintext
highlighter-rouge">MethodFilterInterceptor</code>, therefore being able to deal
with
excludeMethods/includeMethods parameters. See <a
href="default-workflow-interceptor">Default Workflow Interceptor</a>
for documentation and examples on how to use this feature.</p>
-<p>For more information on ways to restrict the parameter names allowed, see
the <code class="language-plaintext
highlighter-rouge">ParameterNameAware</code> javadocs.</p>
+<p>For more information on ways to restrict the parameter names allowed, see
the <code class="language-plaintext
highlighter-rouge">ParameterNameAware</code> javadocs.</p>
<h2 id="parameters">Parameters</h2>
<ul>
- <li><code class="language-plaintext highlighter-rouge">ordered</code> - set
to true if you want the top-down property setter behaviour</li>
- <li><code class="language-plaintext
highlighter-rouge">acceptParamNames</code> - a comma delimited list of regular
expressions to describe a allowlist of accepted parameter names.
+ <li><code class="language-plaintext highlighter-rouge">ordered</code> - set
to true if you want the top-down property setter behaviour</li>
+ <li><code class="language-plaintext
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="language-plaintext highlighter-rouge">excludeParams</code>
- a comma delimited list of regular expressions to describe a denylist of not
allowed parameter names</li>
- <li><code class="language-plaintext
highlighter-rouge">acceptedValuePatterns</code> - a comma delimited list of
regular expressions to describe a allowlist of accepted parameter values </li>
- <li><code class="language-plaintext
highlighter-rouge">excludeValuePatterns</code> - a comma delimited list of
regular expressions to describe a denylist of not allowed parameter values</li>
- <li><code class="language-plaintext
highlighter-rouge">paramNameMaxLength</code> - the maximum length of parameter
names; parameters with longer names will be ignored;
+ <li><code class="language-plaintext highlighter-rouge">excludeParams</code>
- a comma delimited list of regular expressions to describe a denylist of not
allowed parameter names</li>
+ <li><code class="language-plaintext
highlighter-rouge">acceptedValuePatterns</code> - a comma delimited list of
regular expressions to describe a allowlist of accepted parameter values</li>
+ <li><code class="language-plaintext
highlighter-rouge">excludeValuePatterns</code> - a comma delimited list of
regular expressions to describe a denylist of not allowed parameter values</li>
+ <li><code class="language-plaintext
highlighter-rouge">paramNameMaxLength</code> - the maximum length of parameter
names; parameters with longer names will be ignored;
the default is 100 characters</li>
</ul>
@@ -239,7 +245,8 @@ by the interceptor.</p>
<p>It’s also possible to define <code class="language-plaintext
highlighter-rouge">acceptedValuePatterns</code> to accept only values that
match the defined set of patterns.</p>
-<p>Below is an example of adding parameter values ${} and %{} to the list of
parameter values that should be excluded and only accept <strong>a-z</strong>
or <strong>0-9</strong>.</p>
+<p>Below is an example of adding parameter values ${} and %{} to the list of
parameter values that should be excluded
+and only accept <strong>a-z</strong> or <strong>0-9</strong>.</p>
<p><strong>Setup Interceptor Stack To Exclude ${ and %{ Parameter
Values</strong></p>
@@ -259,9 +266,10 @@ by the interceptor.</p>
<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="language-plaintext highlighter-rouge">ParameterNameAware</code> and
<code class="language-plaintext 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="language-plaintext
highlighter-rouge">#acceptableName(String)</code> and/or <code
class="language-plaintext
highlighter-rouge">#acceptableParameterValue(String)</code> method.</p>
+<p>The best way to add behavior to this interceptor is to utilize the <code
class="language-plaintext highlighter-rouge">ParameterNameAware</code> and
<code class="language-plaintext 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="language-plaintext highlighter-rouge">#acceptableName(String)</code>
and/or <code class="language-plaintext
highlighter-rouge">#acceptableParameterValue(String)</code>
+method.</p>
<blockquote>
<p>Using <code class="language-plaintext
highlighter-rouge">ParameterNameAware</code> could be dangerous as <code
class="language-plaintext
highlighter-rouge">ParameterNameAware#acceptableParameterName(String)</code>
takes precedence
