diff --git a/doc/admin-guide/files/logging.yaml.en.rst b/doc/admin-guide/files/logging.yaml.en.rst index 095f4649e4b..9801a8b9218 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 ``%`` 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=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: + +- 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: