This is an automated email from the ASF dual-hosted git repository.
maskit pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new 108568b254 docs: document the wipe_field_value logging filter (#13374)
108568b254 is described below
commit 108568b254d3f3030fc624e76e5eac32b36a5263
Author: Masakazu Kitajo <[email protected]>
AuthorDate: Mon Jul 13 10:15:17 2026 -0600
docs: document the wipe_field_value logging filter (#13374)
* docs: document the wipe_field_value logging filter
Add a dedicated section describing how the wipe_field_value log
filter masks query parameter values, including that it matches
parameter names rather than values. The worked example is taken
from the existing log-filter autest so the shown output matches
what Traffic Server actually produces.
* Address copilot comments
---
doc/admin-guide/files/logging.yaml.en.rst | 64 +++++++++++++++++++++++++++++++
1 file changed, 64 insertions(+)
diff --git a/doc/admin-guide/files/logging.yaml.en.rst
b/doc/admin-guide/files/logging.yaml.en.rst
index 095f4649e4..9801a8b921 100644
--- a/doc/admin-guide/files/logging.yaml.en.rst
+++ b/doc/admin-guide/files/logging.yaml.en.rst
@@ -258,6 +258,70 @@ supported at this time.
expect. If, for example, we had 2 accept log filters, each disjoint from
the other,
nothing will ever get logged on the given log object.
+Wiping Query Parameter Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``wipe_field_value`` action masks the values of matching query string
+parameters before the event is written to the log. Unlike ``accept`` and
+``reject``, a ``wipe_field_value`` filter never drops an event; it only
rewrites
+the logged field. This is useful for keeping secrets such as passwords, session
+tokens, or email addresses out of the access log while still logging the
request.
+
+The filter examines the query string of the field named in the ``condition``
+(typically ``cquuc``, the client request URL) and, for every query parameter
+whose **name** matches one of the filter values, replaces that parameter's
value
+with a run of ``X`` characters of the same length. The ``condition`` operator
and
+values behave exactly as described above; use ``CASE_INSENSITIVE_CONTAIN`` (or
+``CONTAIN``) so that any parameter name containing one of the listed tokens is
+wiped.
+
+.. important::
+
+ Only the query parameter **names** are matched, never their values. A
+ parameter is wiped only when the pattern appears in the part of the
parameter
+ before its ``=``. A value that happens to equal one of the filter tokens is
+ left untouched.
+
+The following filter wipes the values of a set of sensitive parameters:
+
+.. code:: yaml
+
+ filters:
+ - name: queryparamescaper_cquuc
+ action: WIPE_FIELD_VALUE
+ condition: cquuc CASE_INSENSITIVE_CONTAIN
password,secret,access_token,session_redirect,cardNumber,code,query,search-query,prefix,keywords,email,handle
+
+Given that filter attached to a log using the ``%<cquuc>`` format, the
following
+request URLs are logged as shown. Note that ``cquuc`` is the client request's
+*canonical* URL, so the logged value includes the scheme and host:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Requested URL
+ - Logged value
+ * - ``http://example.com/test-1?name=value&[email protected]``
+ - ``http://example.com/test-1?name=value&email=XXXXXXXXXXXXX``
+ * - ``http://example.com/[email protected]&name=password``
+ - ``http://example.com/test-2?email=XXXXXXXXXXXXX&name=password``
+ * -
``http://example.com/test-3?trivial=password&name1=val1&[email protected]``
+ -
``http://example.com/test-3?trivial=password&name1=val1&email=XXXXXXXXXXXXX``
+ * -
``http://example.com/test-4?trivial=password&email=&name=handle&session_redirect=wiped_string``
+ -
``http://example.com/test-4?trivial=password&email=&name=handle&session_redirect=XXXXXXXXXXXX``
+ * -
``http://example.com/test-5?trivial=password&[email protected]&[email protected]&session_redirect=wiped_string&[email protected]&name=value``
+ -
``http://example.com/test-5?trivial=password&email=XXXXXXXXXXXXX&email=XXXXXXXXXXXXX&session_redirect=XXXXXXXXXXXX&email=XXXXXXXXXXXXX&name=value``
+
+Note the behavior demonstrated above:
+
+- In ``test-2`` the ``name=password`` parameter is **not** wiped: the token
+ ``password`` appears in the value, not in the parameter name.
+- In ``test-3`` the ``trivial=password`` parameter is likewise left alone for
the
+ same reason, while ``email`` is wiped.
+- An empty value (``email=`` in ``test-4``) matches but produces an empty wipe,
+ since there is nothing to mask.
+- In ``test-5`` every occurrence of the repeated ``email`` parameter is wiped,
not
+ just the first.
+
.. _admin-custom-logs-logs:
