This is an automated email from the ASF dual-hosted git repository. cmcfarlen pushed a commit to branch 10.2.x in repository https://gitbox.apache.org/repos/asf/trafficserver.git
commit 5be30b83295e4a5c66c715f604a45a381a2160fa 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 (cherry picked from commit 108568b254d3f3030fc624e76e5eac32b36a5263) --- 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 b5bc34ad7b..48fd59d5a3 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:
