Fix ECS HTTP scheme and improve docs (#86612) (#86632)

docs/user/security/audit-logging.asciidoc

@@ -47,9 +47,11 @@ For information on how to configure `xpack.security.audit.appender`, refer to
 
 Refer to the table of events that can be logged for auditing purposes. 
 
-Each event is broken down into `category`, `type`, `action` and `outcome` fields
+Each event is broken down into <<field-event-category, category>>, <<field-event-type, type>>, <<field-event-action, action>> and <<field-event-outcome, outcome>> fields
 to make it easy to filter, query and aggregate the resulting logs. 
 
+Refer to <<xpack-security-ecs-audit-schema>> for a table of fields that get logged with audit event. 
+
 [NOTE]
 ============================================================================
 To ensure that a record of every operation is persisted even in case of an
@@ -230,3 +232,188 @@ Refer to the corresponding {es} logs for potential write errors.
 | `http_request`
 | `unknown` | User is making an HTTP request.
 |======
+
+
+[[xpack-security-ecs-audit-schema]]
+==== ECS audit schema
+
+Audit logs are written in JSON using https://www.elastic.co/guide/en/ecs/1.6/index.html[Elastic Common Schema (ECS)] specification.
+
+[cols="2*<"]
+|======
+
+2+a| ===== Base Fields
+
+| *Field*
+| *Description*
+
+| `@timestamp`
+| Time when the event was generated. 
+
+Example: `2016-05-23T08:05:34.853Z`
+
+| `message`
+| Human readable description of the event. 
+
+2+a| ===== Event Fields
+
+| *Field*
+| *Description*
+
+| [[field-event-action]] `event.action`
+| The action captured by the event.
+
+Refer to <<xpack-security-ecs-audit-logging>> for a table of possible actions. 
+
+| [[field-event-category]] `event.category`
+| High level category associated with the event.
+
+This field is closely related to `event.type`, which is used as a subcategory.
+
+Possible values:
+`database`,
+`web`,
+`authentication`
+
+| [[field-event-type]] `event.type`
+| Subcategory associated with the event.
+
+This field can be used along with the `event.category` field to enable filtering events down to a level appropriate for single visualization.
+
+Possible values:
+`creation`,
+`access`,
+`change`,
+`deletion`
+
+| [[field-event-outcome]] `event.outcome`
+| Denotes whether the event represents a success or failure. 
+
+Possible values:
+`success`,
+`failure`,
+`unknown`
+
+2+a| ===== User Fields
+
+| *Field*
+| *Description*
+
+| `user.name`
+| Login name of the user.
+
+Example: `jdoe`
+
+| `user.roles[]`
+| Set of user roles at the time of the event.
+
+Example: `[kibana_admin, reporting_user]`
+
+2+a| ===== Kibana Fields
+
+| *Field*
+| *Description*
+
+| `kibana.space_id`
+| ID of the space associated with the event.
+
+Example: `default`
+
+| `kibana.session_id`
+| ID of the user session associated with the event. 
+
+Each login attempt results in a unique session id.
+
+| `kibana.saved_object.type`
+| Type of saved object associated with the event.
+
+Example: `dashboard`
+
+| `kibana.saved_object.id`
+| ID of the saved object associated with the event.
+
+| `kibana.authentication_provider`
+| Name of the authentication provider associated with the event.
+
+Example: `my-saml-provider`
+
+| `kibana.authentication_type`
+| Type of the authentication provider associated with the event.
+
+Example: `saml`
+
+| `kibana.authentication_realm`
+| Name of the Elasticsearch realm that has authenticated the user.
+
+Example: `native`
+
+| `kibana.lookup_realm`
+| Name of the Elasticsearch realm where the user details were retrieved from.
+
+Example: `native`
+
+| `kibana.add_to_spaces[]`
+| Set of space IDs that a saved object is being shared to as part of the event.
+
+Example: `[default, marketing]`
+
+| `kibana.delete_from_spaces[]`
+| Set of space IDs that a saved object is being removed from as part of the event.
+
+Example: `[marketing]`
+
+2+a| ===== Error Fields
+
+| *Field*
+| *Description*
+
+| `error.code`
+| Error code describing the error.
+
+| `error.message`
+| Error message. 
+
+2+a| ===== HTTP and URL Fields
+
+| *Field*
+| *Description*
+
+| `http.request.method`
+| HTTP request method.
+
+Example: `get`, `post`, `put`, `delete`
+
+| `url.domain`
+| Domain of the url.
+
+Example: `www.elastic.co`
+
+| `url.path`
+| Path of the request.
+
+Example: `/search`
+
+| `url.port`
+| Port of the request.
+
+Example: `443`
+
+| `url.query`
+| The query field describes the query string of the request.
+
+Example: `q=elasticsearch`
+
+| `url.scheme`
+| Scheme of the request.
+
+Example: `https`
+
+2+a| ===== Tracing Fields
+
+| *Field*
+| *Description*
+
+| `trace.id`
+| Unique identifier allowing events of the same transaction from {kib} and {es} to be be correlated.
+
+|======

x-pack/plugins/security/server/audit/audit_events.test.ts

@@ -284,7 +284,7 @@ describe('#httpRequestEvent', () => {
           "path": "/path",
           "port": undefined,
           "query": undefined,
-          "scheme": "http:",
+          "scheme": "http",
         },
       }
     `);
@@ -321,7 +321,7 @@ describe('#httpRequestEvent', () => {
           "path": "/original/path",
           "port": undefined,
           "query": "query=param",
-          "scheme": "http:",
+          "scheme": "http",
         },
       }
     `);

x-pack/plugins/security/server/audit/audit_events.ts

@@ -28,14 +28,9 @@ export interface AuditEvent {
     category?: EventCategory;
     type?: EventType;
     outcome?: EventOutcome;
-    module?: string;
-    dataset?: string;
   };
   user?: {
     name: string;
-    email?: string;
-    full_name?: string;
-    hash?: string;
     roles?: readonly string[];
   };
   kibana?: {
@@ -87,17 +82,10 @@ export interface AuditEvent {
   http?: {
     request?: {
       method?: string;
-      body?: {
-        content: string;
-      };
-    };
-    response?: {
-      status_code?: number;
     };
   };
   url?: {
     domain?: string;
-    full?: string;
     path?: string;
     port?: number;
     query?: string;
@@ -108,14 +96,10 @@ export interface AuditEvent {
 export enum EventCategory {
   DATABASE = 'database',
   WEB = 'web',
-  IAM = 'iam',
   AUTHENTICATION = 'authentication',
-  PROCESS = 'process',
 }
 
 export enum EventType {
-  USER = 'user',
-  GROUP = 'group',
   CREATION = 'creation',
   ACCESS = 'access',
   CHANGE = 'change',
@@ -152,7 +136,7 @@ export function httpRequestEvent({ request }: HttpRequestParams): AuditEvent {
       path: url.pathname,
       port: url.port ? parseInt(url.port, 10) : undefined,
       query: url.search ? url.search.slice(1) : undefined,
-      scheme: url.protocol,
+      scheme: url.protocol ? url.protocol.substr(0, url.protocol.length - 1) : undefined,
     },
   };
 }