diff --git a/x-pack/docs/en/security/auditing/auditing-search-queries.asciidoc b/x-pack/docs/en/security/auditing/auditing-search-queries.asciidoc new file mode 100644 index 00000000000..fa00f8eeeef --- /dev/null +++ b/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 <> 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 <> 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`. diff --git a/x-pack/docs/en/security/auditing/index.asciidoc b/x-pack/docs/en/security/auditing/index.asciidoc index e82fd4397fb..027482df75f 100644 --- a/x-pack/docs/en/security/auditing/index.asciidoc +++ b/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[] \ No newline at end of file +include::forwarding-logs.asciidoc[]