Add the api value to event.category (#2147) (#2155)

* Adding `api` to `event.category`

* better phrasing for description, added a few extra expected types

(cherry picked from commit 08237fe)

Co-authored-by: Christophe Alladoum <85187342+calladoum-elastic@users.noreply.github.com>

CHANGELOG.next.md

@@ -16,6 +16,8 @@ Thanks, you're awesome :-) -->
 
 #### Added
 
+* adding `api` option to `event.category` #2147
+
 #### Improvements
 
 #### Deprecated

docs/fields/field-details.asciidoc

@@ -3389,7 +3389,7 @@ Note: this field should contain an array of values.
 
 *Important*: The field value must be one of the following:
 
-authentication, configuration, database, driver, email, file, host, iam, intrusion_detection, malware, network, package, process, registry, session, threat, vulnerability, web
+api, authentication, configuration, database, driver, email, file, host, iam, intrusion_detection, malware, network, package, process, registry, session, threat, vulnerability, web
 
 To learn more about when to use which value, visit the page
 <<ecs-allowed-values-event-category,allowed values for event.category>>

docs/fields/field-values.asciidoc

@@ -132,6 +132,7 @@ This field is an array. This will allow proper categorization of some events tha
 
 *Allowed Values*
 
+* <<ecs-event-category-api,api>>
 * <<ecs-event-category-authentication,authentication>>
 * <<ecs-event-category-configuration,configuration>>
 * <<ecs-event-category-database,database>>
@@ -151,6 +152,18 @@ This field is an array. This will allow proper categorization of some events tha
 * <<ecs-event-category-vulnerability,vulnerability>>
 * <<ecs-event-category-web,web>>
 
+[float]
+[[ecs-event-category-api]]
+==== api
+
+Events in this category annotate API calls that occured on a system. Typical sources for those events could be from the Operating System level through the native libraries (for example Windows Win32, Linux libc, etc.), or managed sources of events (such as ETW, syslog), but can also include network protocols (such as SOAP, RPC, Websocket, REST, etc.)
+
+
+*Expected event types for category api:*
+
+access, admin, allowed, change, creation, deletion, denied, end, info, start, user
+
+
 [float]
 [[ecs-event-category-authentication]]
 ==== authentication

experimental/generated/ecs/ecs_flat.yml

@@ -2944,6 +2944,24 @@ event.agent_id_status:
   type: keyword
 event.category:
   allowed_values:
+  - description: Events in this category annotate API calls that occured on a system.
+      Typical sources for those events could be from the Operating System level through
+      the native libraries (for example Windows Win32, Linux libc, etc.), or managed
+      sources of events (such as ETW, syslog), but can also include network protocols
+      (such as SOAP, RPC, Websocket, REST, etc.)
+    expected_event_types:
+    - access
+    - admin
+    - allowed
+    - change
+    - creation
+    - deletion
+    - denied
+    - end
+    - info
+    - start
+    - user
+    name: api
   - description: Events in this category are related to the challenge and response
       process in which credentials are supplied and verified to allow the creation
       of a session. Common sources for these logs are Windows event logs and ssh logs.

experimental/generated/ecs/ecs_nested.yml

@@ -3936,6 +3936,24 @@ event:
       type: keyword
     event.category:
       allowed_values:
+      - description: Events in this category annotate API calls that occured on a
+          system. Typical sources for those events could be from the Operating System
+          level through the native libraries (for example Windows Win32, Linux libc,
+          etc.), or managed sources of events (such as ETW, syslog), but can also
+          include network protocols (such as SOAP, RPC, Websocket, REST, etc.)
+        expected_event_types:
+        - access
+        - admin
+        - allowed
+        - change
+        - creation
+        - deletion
+        - denied
+        - end
+        - info
+        - start
+        - user
+        name: api
       - description: Events in this category are related to the challenge and response
           process in which credentials are supplied and verified to allow the creation
           of a session. Common sources for these logs are Windows event logs and ssh

generated/ecs/ecs_flat.yml

@@ -2875,6 +2875,24 @@ event.agent_id_status:
   type: keyword
 event.category:
   allowed_values:
+  - description: Events in this category annotate API calls that occured on a system.
+      Typical sources for those events could be from the Operating System level through
+      the native libraries (for example Windows Win32, Linux libc, etc.), or managed
+      sources of events (such as ETW, syslog), but can also include network protocols
+      (such as SOAP, RPC, Websocket, REST, etc.)
+    expected_event_types:
+    - access
+    - admin
+    - allowed
+    - change
+    - creation
+    - deletion
+    - denied
+    - end
+    - info
+    - start
+    - user
+    name: api
   - description: Events in this category are related to the challenge and response
       process in which credentials are supplied and verified to allow the creation
       of a session. Common sources for these logs are Windows event logs and ssh logs.

generated/ecs/ecs_nested.yml

@@ -3856,6 +3856,24 @@ event:
       type: keyword
     event.category:
       allowed_values:
+      - description: Events in this category annotate API calls that occured on a
+          system. Typical sources for those events could be from the Operating System
+          level through the native libraries (for example Windows Win32, Linux libc,
+          etc.), or managed sources of events (such as ETW, syslog), but can also
+          include network protocols (such as SOAP, RPC, Websocket, REST, etc.)
+        expected_event_types:
+        - access
+        - admin
+        - allowed
+        - change
+        - creation
+        - deletion
+        - denied
+        - end
+        - info
+        - start
+        - user
+        name: api
       - description: Events in this category are related to the challenge and response
           process in which credentials are supplied and verified to allow the creation
           of a session. Common sources for these logs are Windows event logs and ssh

schemas/event.yml

@@ -156,6 +156,24 @@
       normalize:
         - array
       allowed_values:
+        - name: api
+          description: >
+            Events in this category annotate API calls that occured on a system. Typical sources
+            for those events could be from the Operating System level through the native libraries
+            (for example Windows Win32, Linux libc, etc.), or managed sources of events (such as ETW,
+            syslog), but can also include network protocols (such as SOAP, RPC, Websocket, REST, etc.)
+          expected_event_types:
+            - access
+            - admin
+            - allowed
+            - change
+            - creation
+            - deletion
+            - denied
+            - end
+            - info
+            - start
+            - user
         - name: authentication
           description: >
             Events in this category are related to the challenge and response process