From 15cdf67390f7a34ddf7003f1dd2e8e48c71d51b7 Mon Sep 17 00:00:00 2001 From: Masakazu Kitajo Date: Thu, 9 Jul 2026 09:46:30 -0600 Subject: [PATCH 1/2] 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. --- doc/admin-guide/files/logging.yaml.en.rst | 54 +++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/doc/admin-guide/files/logging.yaml.en.rst b/doc/admin-guide/files/logging.yaml.en.rst index 095f4649e4b..989ff811434 100644 --- a/doc/admin-guide/files/logging.yaml.en.rst +++ b/doc/admin-guide/files/logging.yaml.en.rst @@ -258,6 +258,60 @@ 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,email + +Given that filter attached to a log using the ``%`` format, the following +request URLs are logged as shown: + +======================================================================================= ======================================================================================= +Requested URL Logged value +======================================================================================= ======================================================================================= +``/test-1?name=value&email=123@gmail.com`` ``/test-1?name=value&email=XXXXXXXXXXXXX`` +``/test-2?email=123@gmail.com&name=password`` ``/test-2?email=XXXXXXXXXXXXX&name=password`` +``/test-3?trivial=password&name1=val1&email=123@gmail.com`` ``/test-3?trivial=password&name1=val1&email=XXXXXXXXXXXXX`` +``/test-4?trivial=password&email=&name=handle&session_redirect=wiped_string`` ``/test-4?trivial=password&email=&name=handle&session_redirect=XXXXXXXXXXXX`` +======================================================================================= ======================================================================================= + +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. + .. _admin-custom-logs-logs: From 67186a32b5e272f3d64be6196df14a4edc4da5e3 Mon Sep 17 00:00:00 2001 From: Masakazu Kitajo Date: Thu, 9 Jul 2026 15:45:58 -0600 Subject: [PATCH 2/2] Address copilot comments --- doc/admin-guide/files/logging.yaml.en.rst | 32 +++++++++++++++-------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/doc/admin-guide/files/logging.yaml.en.rst b/doc/admin-guide/files/logging.yaml.en.rst index 989ff811434..9801a8b9218 100644 --- a/doc/admin-guide/files/logging.yaml.en.rst +++ b/doc/admin-guide/files/logging.yaml.en.rst @@ -289,19 +289,27 @@ The following filter wipes the values of a set of sensitive parameters: filters: - name: queryparamescaper_cquuc action: WIPE_FIELD_VALUE - condition: cquuc CASE_INSENSITIVE_CONTAIN password,secret,access_token,session_redirect,email + 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 ``%`` format, the following -request URLs are logged as shown: - -======================================================================================= ======================================================================================= -Requested URL Logged value -======================================================================================= ======================================================================================= -``/test-1?name=value&email=123@gmail.com`` ``/test-1?name=value&email=XXXXXXXXXXXXX`` -``/test-2?email=123@gmail.com&name=password`` ``/test-2?email=XXXXXXXXXXXXX&name=password`` -``/test-3?trivial=password&name1=val1&email=123@gmail.com`` ``/test-3?trivial=password&name1=val1&email=XXXXXXXXXXXXX`` -``/test-4?trivial=password&email=&name=handle&session_redirect=wiped_string`` ``/test-4?trivial=password&email=&name=handle&session_redirect=XXXXXXXXXXXX`` -======================================================================================= ======================================================================================= +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=123@gmail.com`` + - ``http://example.com/test-1?name=value&email=XXXXXXXXXXXXX`` + * - ``http://example.com/test-2?email=123@gmail.com&name=password`` + - ``http://example.com/test-2?email=XXXXXXXXXXXXX&name=password`` + * - ``http://example.com/test-3?trivial=password&name1=val1&email=123@gmail.com`` + - ``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=123@gmail.com&email=456@gmail.com&session_redirect=wiped_string&email=789@gmail.com&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: @@ -311,6 +319,8 @@ Note the behavior demonstrated above: 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: