DOCS Auditing search queries (elastic#35301)

This documents how to include the search queries in the audit log. There is a catch, that even if enabling `emit_request_body`, which should output queries included in request bodies, search queries were not output because, implicitly, no REST layer audit event type was included. This folk knowledge is herein imprinted.

Author: albertzaharovits

x-pack/docs/en/security/auditing/auditing-search-queries.asciidoc

@@ -0,0 +1,53 @@
+[role="xpack"]
+[testenv="gold+"]
+[[auditing-search-queries]]
+=== Auditing search queries
+
+There is no <<audit-event-types, audit event type>> specifically
+dedicated to search queries. Search queries are analyzed and then processed; the 
+processing triggers authorization actions that are audited.
+However, the original raw query, as submitted by the client, is not accessible
+downstream when authorization auditing occurs.
+
+Search queries are contained inside HTTP request bodies, however, and some
+audit events that are generated by the REST layer can be toggled to output
+the request body to the audit log.
+
+To make certain audit events include the request body, edit the following 
+settings in the `elasticsearch.yml` file:
+
+* For the `logfile` audit output:
++ 
+--
+[source,yaml]
+----------------------------
+xpack.security.audit.logfile.events.emit_request_body: true
+----------------------------
+--
+
+* For the `index` output:
++
+--
+[source,yaml]
+----------------------------
+xpack.security.audit.index.events.emit_request_body: true
+----------------------------
+--
+
+IMPORTANT: No filtering is performed when auditing, so sensitive data might be
+audited in plain text when audit events include the request body. Also, the
+request body can contain malicious content that can break a parser consuming
+the audit logs.
+
+There are only a handful of <<audit-event-types, audit event types>> that are 
+generated in the REST layer and can access the request body. Most of them are not
+included by default.
+
+A good practical piece of advice is to add `authentication_success` to the event
+types that are audited. Add it to the list in the 
+`xpack.security.audit.logfile.events.include` or 
+`xpack.security.audit.index.events.include` settings. This type is not audited
+by default.
+
+NOTE: Typically, the include list contains other event types as well, such as
+`access_granted` or `access_denied`.

x-pack/docs/en/security/auditing/index.asciidoc

@@ -11,5 +11,8 @@ include::output-logfile.asciidoc[]
 :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/output-index.asciidoc
 include::output-index.asciidoc[]
 
+:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/auditing-search-queries.asciidoc
+include::auditing-search-queries.asciidoc[]
+
 :edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc
-include::forwarding-logs.asciidoc[]
+include::forwarding-logs.asciidoc[]