Categorization: Add new "iam" category and associated types "admin", …

…"group", "user" (#756)

CHANGELOG.next.md

@@ -18,6 +18,7 @@ Thanks, you're awesome :-) -->
 * Added `dll.*` fields (#679)
 * Fieldset for PE metadata. #731
 * Globally unique identifier `entity_id` for `process` and `process.parent`. (#747)
+* Added iam value for `event.category` and three related values for `event.type`. (#756)
 
 #### Improvements
 

docs/field-details.asciidoc

@@ -1491,7 +1491,7 @@ Note: this field should contain an array of values.
 
 *Important*: The field value must be one of the following:
 
-authentication, database, driver, file, host, intrusion_detection, malware, package, process, web
+authentication, database, driver, file, host, iam, intrusion_detection, malware, package, process, web
 
 To learn more about when to use which value, visit the page
 <<ecs-allowed-values-event-category,allowed values for event.category>>
@@ -1825,7 +1825,7 @@ Note: this field should contain an array of values.
 
 *Important*: The field value must be one of the following:
 
-access, change, creation, deletion, end, error, info, installation, start
+access, admin, change, creation, deletion, end, error, group, info, installation, start, user
 
 To learn more about when to use which value, visit the page
 <<ecs-allowed-values-event-type,allowed values for event.type>>

docs/field-values.asciidoc

@@ -143,6 +143,7 @@ that will require subsequent breaking changes.
 * <<ecs-event-category-driver,driver>>
 * <<ecs-event-category-file,file>>
 * <<ecs-event-category-host,host>>
+* <<ecs-event-category-iam,iam>>
 * <<ecs-event-category-intrusion_detection,intrusion_detection>>
 * <<ecs-event-category-malware,malware>>
 * <<ecs-event-category-package,package>>
@@ -225,6 +226,20 @@ Note that this category is for information about hosts themselves; it is not mea
 access, change, end, info, start
 
 
+[float]
+[[ecs-event-category-iam]]
+==== iam
+
+Identity and access management (IAM) events relating to users, groups, and administration. Use this category to visualize and analyze IAM-related logs and data from active directory, LDAP, Okta, Duo, and other IAM systems.
+
+
+
+
+*Expected event types for category iam:*
+
+admin, change, creation, deletion, group, info, user
+
+
 [float]
 [[ecs-event-category-intrusion_detection]]
 ==== intrusion_detection
@@ -312,14 +327,17 @@ that will require subsequent breaking changes.
 *Allowed Values*
 
 * <<ecs-event-type-access,access>>
+* <<ecs-event-type-admin,admin>>
 * <<ecs-event-type-change,change>>
 * <<ecs-event-type-creation,creation>>
 * <<ecs-event-type-deletion,deletion>>
 * <<ecs-event-type-end,end>>
 * <<ecs-event-type-error,error>>
+* <<ecs-event-type-group,group>>
 * <<ecs-event-type-info,info>>
 * <<ecs-event-type-installation,installation>>
 * <<ecs-event-type-start,start>>
+* <<ecs-event-type-user,user>>
 
 [float]
 [[ecs-event-type-access]]
@@ -331,6 +349,16 @@ The access event type is used for the subset of events within a category that in
 
 
 
+[float]
+[[ecs-event-type-admin]]
+==== admin
+
+The admin event type is used for the subset of events within a category that are related to admin objects. For example, administrative changes within an IAM framework that do not specifically affect a user or group (e.g., adding new applications to a federation solution or connecting discrete forests in Active Directory) would fall into this subcategory. Common example: `event.category:iam AND event.type:change AND event.type:admin`. You can further distinguish admin operations using the ECS `event.action` field.
+
+
+
+
+
 [float]
 [[ecs-event-type-change]]
 ==== change
@@ -381,6 +409,16 @@ The error event type is used for the subset of events within a category that ind
 
 
 
+[float]
+[[ecs-event-type-group]]
+==== group
+
+The group event type is used for the subset of events within a category that are related to group objects. Common example: `event.category:iam AND event.type:creation AND event.type:group`. You can further distinguish group operations using the ECS `event.action` field.
+
+
+
+
+
 [float]
 [[ecs-event-type-info]]
 ==== info
@@ -411,6 +449,16 @@ The start event type is used for the subset of events within a category that ind
 
 
 
+[float]
+[[ecs-event-type-user]]
+==== user
+
+The user event type is used for the subset of events within a category that are related to user objects. Common example: `event.category:iam AND event.type:deletion AND event.type:user`. You can further distinguish user operations using the ECS `event.action` field.
+
+
+
+
+
 [[ecs-allowed-values-event-outcome]]
 === ECS Categorization Field: event.outcome
 

generated/ecs/ecs_flat.yml

@@ -1839,6 +1839,20 @@ event.category:
     - info
     - start
     name: host
+  - description: 'Identity and access management (IAM) events relating to users, groups,
+      and administration. Use this category to visualize and analyze IAM-related logs
+      and data from active directory, LDAP, Okta, Duo, and other IAM systems.
+
+      '
+    expected_event_types:
+    - admin
+    - change
+    - creation
+    - deletion
+    - group
+    - info
+    - user
+    name: iam
   - description: 'Relating to intrusion detections from IDS/IPS systems and functions,
       both network and host-based. Use this category to visualize and analyze intrusion
       detection alerts from systems such as Snort, Suricata, and Palo Alto threat
@@ -2311,6 +2325,16 @@ event.type:
 
       '
     name: access
+  - description: 'The admin event type is used for the subset of events within a category
+      that are related to admin objects. For example, administrative changes within
+      an IAM framework that do not specifically affect a user or group (e.g., adding
+      new applications to a federation solution or connecting discrete forests in
+      Active Directory) would fall into this subcategory. Common example: `event.category:iam
+      AND event.type:change AND event.type:admin`. You can further distinguish admin
+      operations using the ECS `event.action` field.
+
+      '
+    name: admin
   - description: 'The change event type is used for the subset of events within a
       category that indicate that something has changed. If semantics best describe
       an event as modified, then include them in this subcategory. Common examples
@@ -2346,6 +2370,13 @@ event.type:
 
       '
     name: error
+  - description: 'The group event type is used for the subset of events within a category
+      that are related to group objects. Common example: `event.category:iam AND event.type:creation
+      AND event.type:group`. You can further distinguish group operations using the
+      ECS `event.action` field.
+
+      '
+    name: group
   - description: 'The info event type is used for the subset of events within a category
       that indicate that they are purely informational, and don''t report a state
       change, or any type of action. For example, an initial run of a file integrity
@@ -2369,6 +2400,13 @@ event.type:
 
       '
     name: start
+  - description: 'The user event type is used for the subset of events within a category
+      that are related to user objects. Common example: `event.category:iam AND event.type:deletion
+      AND event.type:user`. You can further distinguish user operations using the
+      ECS `event.action` field.
+
+      '
+    name: user
   dashed_name: event-type
   description: 'This is one of four ECS Categorization Fields, and indicates the third
     level in the ECS category hierarchy.

generated/ecs/ecs_nested.yml

@@ -2091,6 +2091,20 @@ event:
         - info
         - start
         name: host
+      - description: 'Identity and access management (IAM) events relating to users,
+          groups, and administration. Use this category to visualize and analyze IAM-related
+          logs and data from active directory, LDAP, Okta, Duo, and other IAM systems.
+
+          '
+        expected_event_types:
+        - admin
+        - change
+        - creation
+        - deletion
+        - group
+        - info
+        - user
+        name: iam
       - description: 'Relating to intrusion detections from IDS/IPS systems and functions,
           both network and host-based. Use this category to visualize and analyze
           intrusion detection alerts from systems such as Snort, Suricata, and Palo
@@ -2573,6 +2587,17 @@ event:
 
           '
         name: access
+      - description: 'The admin event type is used for the subset of events within
+          a category that are related to admin objects. For example, administrative
+          changes within an IAM framework that do not specifically affect a user or
+          group (e.g., adding new applications to a federation solution or connecting
+          discrete forests in Active Directory) would fall into this subcategory.
+          Common example: `event.category:iam AND event.type:change AND event.type:admin`.
+          You can further distinguish admin operations using the ECS `event.action`
+          field.
+
+          '
+        name: admin
       - description: 'The change event type is used for the subset of events within
           a category that indicate that something has changed. If semantics best describe
           an event as modified, then include them in this subcategory. Common examples
@@ -2609,6 +2634,13 @@ event:
 
           '
         name: error
+      - description: 'The group event type is used for the subset of events within
+          a category that are related to group objects. Common example: `event.category:iam
+          AND event.type:creation AND event.type:group`. You can further distinguish
+          group operations using the ECS `event.action` field.
+
+          '
+        name: group
       - description: 'The info event type is used for the subset of events within
           a category that indicate that they are purely informational, and don''t
           report a state change, or any type of action. For example, an initial run
@@ -2633,6 +2665,13 @@ event:
 
           '
         name: start
+      - description: 'The user event type is used for the subset of events within
+          a category that are related to user objects. Common example: `event.category:iam
+          AND event.type:deletion AND event.type:user`. You can further distinguish
+          user operations using the ECS `event.action` field.
+
+          '
+        name: user
       dashed_name: event-type
       description: 'This is one of four ECS Categorization Fields, and indicates the
         third level in the ECS category hierarchy.

schemas/event.yml

@@ -179,6 +179,19 @@
             - end
             - info
             - start
+        - name: iam
+          description: >
+            Identity and access management (IAM) events relating to users, groups, and administration.
+            Use this category to visualize and analyze IAM-related logs and data from active directory,
+            LDAP, Okta, Duo, and other IAM systems.
+          expected_event_types:
+            - admin
+            - change
+            - creation
+            - deletion
+            - group
+            - info
+            - user
         - name: intrusion_detection
           description: >
             Relating to intrusion detections from IDS/IPS systems and functions,
@@ -310,6 +323,16 @@
             Note for file access, both directory listings and file opens should be included
             in this subcategory. You can further distinguish access operations using the ECS
             `event.action` field.
+        - name: admin
+          description: >
+            The admin event type is used for the subset of events within a category
+            that are related to admin objects. For example, administrative changes within
+            an IAM framework that do not specifically affect a user or group (e.g., adding new
+            applications to a federation solution or connecting discrete forests in Active Directory)
+            would fall into this subcategory.
+            Common example: `event.category:iam AND event.type:change AND event.type:admin`.
+            You can further distinguish admin operations using the ECS
+            `event.action` field.
         - name: change
           description: >
             The change event type is used for the subset of events within a category
@@ -342,6 +365,13 @@
             Note that pipeline errors that occur during the event ingestion process
             should not use this `event.type` value. Instead, they should use
             `event.kind:pipeline_error`.
+        - name: group
+          description: >
+            The group event type is used for the subset of events within a category
+            that are related to group objects.
+            Common example: `event.category:iam AND event.type:creation AND event.type:group`.
+            You can further distinguish group operations using the ECS
+            `event.action` field.
         - name: info
           description: >
             The info event type is used for the subset of events within a category
@@ -362,6 +392,13 @@
             The start event type is used for the subset of events within a category
             that indicate something has started. A common example is
             `event.category:process AND event.type:start`.
+        - name: user
+          description: >
+            The user event type is used for the subset of events within a category
+            that are related to user objects.
+            Common example: `event.category:iam AND event.type:deletion AND event.type:user`.
+            You can further distinguish user operations using the ECS
+            `event.action` field.
 
     - name: module
       level: core