Add ancestry array to process object (#1317)

#### Related Issue: #1275 #### Description of changes: Adds an array for the expression of process ancestry through process entity objects. The process entity is a new object that the process object is modified to extend. This enables the inclusion of extended parentage information without deep nesting which is discouraged in the `parent_process` attribute description. Full details for processes in the ancestry would still need to be looked up based on the fields in the process entity object. This PR also deprecates the `lineage` attribute within the process object in favour of the `ancestry` attribute which has much more explicit guidance on how to construct the array. Signed-off-by: Mitchell Wasson <[email protected]>
ocsf · Jan 16, 2025 · f5399f2 · f5399f2
1 parent 56ab3cc
commit f5399f2
Show file tree

Hide file tree

Showing 4 changed files with 51 additions and 18 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -82,6 +82,7 @@ Thankyou! -->
     1. Added `related_events_count` as an `int_t`. #1271
     1. Added `event_uid` as a `string_t`. #1312
     1. Added `debug` attribute as a `string_t` array, used in the `metadata` object. #1308
+    1. Added `ancestry` as a list of `process_entity`. #1317
 
 * #### Objects
     1. Added `environment_variable` object. #1172, #1288
@@ -97,6 +98,7 @@ Thankyou! -->
     1. Added `software_component` and `sbom` objects. #1262
     1. Added `drive_type` and `drive_type_id` objects. #1287
     1. Added `cpu_architecture` and `cpu_architecture_id` objects. #1278
+    1. Added `process_entity` object. #1317
 
 * ### Profiles
     1. Added `incident` profile. #1293
@@ -178,6 +180,8 @@ Thankyou! -->
     1. Added `event_uid` to the `logger` object. #1312
     1. Added `debug` attribute to `metadata` object. #1308
     1. Added optional `url` attribute to the `file` object. This was allows capturing a file's URL in the File Hosting Activity (6006) event class. #1289
+    1. Changed the `process` object to extend the `process_entity` object. #1317
+    1. Added `ancestry` to the `process` object. #1317
 
 ### Bugfixes
 1. Added sibling definition to `confidence_id` in dictionary, accurately associating `confidence` as its sibling. #1180
@@ -198,6 +202,7 @@ Thankyou! -->
 1. Deprecated `package` in `Software Inventory Info` in favour of `sbom`. #1262
 1. Deprecated `product_uid` in favor of the `product` object. #1271
 1. Deprecated `policy` in favor of `policies` in `Account Change` class. #1282
+1. Deprecated `lineage` in the `process` object. #1317
 
 ### Misc
 1. Added `user.uid` as an Observable type - `type_id: 31`. #1155

diff --git a/dictionary.json b/dictionary.json
@@ -186,6 +186,12 @@
       "description": "The analytic technique used to analyze and derive insights from the data or information that led to the finding or conclusion.",
       "type": "analytic"
     },
+    "ancestry": {
+      "caption": "Ancestry",
+      "description": "An array of Process Entities describing the extended parentage of this process object. Direct parent information sould be expressed through the <code>parent_process</code> attribute. The first array element is the direct parent of this process object. Subsequent list elements go up the process parentage hierarchy. That is, the array is sorted from newest to oldest process. It is recommended to only populate this field for the top-level process object.",
+      "type": "process_entity",
+      "is_array": true
+    },
     "answers": {
       "caption": "DNS Answer",
       "description": "The Domain Name System (DNS) answers.",
@@ -3570,7 +3576,7 @@
     },
     "parent_process": {
       "caption": "Parent Process",
-      "description": "The parent process of this process object. It is recommended to only populate this field for the first process object, to prevent deep nesting.",
+      "description": "The parent process of this process object. It is recommended to only populate this field for the top-level process object, to prevent deep nesting. Additional ancestry information can be supplied in the <code>ancestry</code> attribute.",
       "type": "process"
     },
     "parent_uid": {

diff --git a/objects/process.json b/objects/process.json
@@ -3,7 +3,7 @@
   "name": "process",
   "description": "The Process object describes a running instance of a launched program.",
   "references": [{"url": "https://d3fend.mitre.org/dao/artifact/d3f:Process/", "description": "D3FEND™ Ontology d3f:Process"}],
-  "extends": "_entity",
+  "extends": "process_entity",
   "observable": 25,
   "profiles": [
     "container"
@@ -12,12 +12,8 @@
     "$include": [
       "profiles/container.json"
     ],
-    "cmd_line": {
-      "requirement": "recommended"
-    },
-    "created_time": {
-      "description": "The time when the process was created/started.",
-      "requirement": "recommended"
+    "ancestry": {
+      "requirement": "optional"
     },
     "environment_variables": {
       "description": "Environment variables associated with the process.",
@@ -34,21 +30,18 @@
       "requirement": "optional"
     },
     "lineage": {
+      "@deprecated": {
+        "since": "1.4.0",
+        "message": "Use the <code>ancestry</code> attribute."
+      },
       "requirement": "optional"
     },
     "loaded_modules": {
       "requirement": "optional"
     },
-    "name": {
-      "description": "The friendly name of the process, for example: <code>Notepad++</code>.",
-      "type": "process_name_t"
-    },
     "parent_process": {
       "requirement": "recommended"
     },
-    "pid": {
-      "requirement": "recommended"
-    },
     "sandbox": {
       "requirement": "optional"
     },
@@ -63,9 +56,6 @@
     "tid": {
       "requirement": "optional"
     },
-    "uid": {
-      "description": "A unique identifier for this process assigned by the producer (tool).  Facilitates correlation of a process event with other events for that process."
-    },
     "user": {
       "description": "The user under which this process is running.",
       "requirement": "recommended"

diff --git a/objects/process_entity.json b/objects/process_entity.json
@@ -0,0 +1,32 @@
+{
+    "caption": "Process Entity",
+    "description": "The Process Entity object provides critical fields for referencing a process.",
+    "name": "process_entity",
+    "extends": "_entity",
+    "attributes": {
+        "cmd_line": {
+            "requirement": "recommended"
+        },
+        "created_time": {
+            "description": "The time when the process was created/started.",
+            "requirement": "recommended"
+        },
+        "name": {
+            "description": "The friendly name of the process, for example: <code>Notepad++</code>.",
+            "type": "process_name_t"
+        },
+        "path":{
+            "description": "The process file path.",
+            "requirement": "optional"
+        },
+        "pid": {
+            "requirement": "recommended"
+        },
+        "uid": {
+            "description": "A unique identifier for this process assigned by the producer (tool).  Facilitates correlation of a process event with other events for that process."
+        }
+    },
+    "constraints": {
+        "at_least_one": ["cmd_line", "name", "path", "pid", "uid"]
+    }
+}