Add ancestry array to process object

Create new process_entity object and have process extend it The ancestry attribute is an array of process_entity. This array supersedes the lineage array in the process object. Additionally, it gives a way to compactly communicate key identifiers to look up full information for extended process parentage. Signed-off-by: Mitchell Wasson <[email protected]>
ocsf · Jan 15, 2025 · 90fb01d · 90fb01d
1 parent 56ab3cc
commit 90fb01d
Show file tree

Hide file tree

Showing 4 changed files with 48 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,29 @@
+{
+    "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."
+        }
+    }
+}