Email object and Email Activity updates. Deprecate Email URL Activity and Email File Activity.

CHANGELOG.md

@@ -74,6 +74,7 @@ Thankyou! -->
     1. Added new `11: Basic Authentication` enum value to `auth_protocol_id`. #1239
     1. Added `values` as an array of `string_t`. #1251
     1. Added `kernel_release` as a `string_t`.
+    1. Added `domains` `files` `urls` and `message_trace_uid`. #1259
 * #### Objects
     1. Added `environment_variable` object. #1172
     1. Added `advisory` object. #1176
@@ -92,6 +93,7 @@ Thankyou! -->
     1. Removed constraint from `group_management` class. #1193
     1. Added `Archived|5` as an enum item to `status_id` attribute in Findings classes. #1219
     1. Added a `Trace` `activity_id` to the `Email Activity` class. #1252
+    1. Added a `message_trace_uid` to the `Email Activity` class. #1259
 * #### Profiles
     1. Added `is_alert`, `confidence_id`, `confidence`,  `confidence_score` attributes to the `security_control` profile. #1178
     1. Added `risk_level_id`, `risk_level`, `risk_score`, `risk_details` attributes to the `security_control` profile.  #1178
@@ -127,6 +129,7 @@ Thankyou! -->
     1. Added `hostname`, `ip`, and `name` to `resource_details` for purposes of assigning an Observable number. #1250
     1. Added `values` to `key_value_object`. #1251
     1. Added `kernel_release` to `os` object.
+    1. Added `domains` `files` `urls` to the `Email` object. Relaxed requirements on the `from` and `to` attributes and added the `at_least_one` constraint. #1259
 
 ### Bugfixes
 1. Added sibling definition to `confidence_id` in dictionary, accurately associating `confidence` as its sibling. #1180
@@ -143,6 +146,7 @@ Thankyou! -->
 1. Deprecated `imei` in favor of `imei_list` in `device` object. #1225
 1. Deprecated `data_classification` in favor of `data_classifications` in the `data_classification` profile. #1245
 1. Deprecated activity_id `4|Suppressed` in the Data Security Finding event class. This shouldn't have been added when we first created it, as the right place for this info is `status_id`. #1245
+1. Deprecated `email_file_activity` and `email_url_activity` in favor of updated `email_activity`. #1259
 
 ### Misc
 1. Added `user.uid` as an Observable type - `type_id: 31`. #1155

dictionary.json

@@ -1781,6 +1781,12 @@
       "type": "domain_contact",
       "is_array": true
     },
+    "domains": {
+      "caption": "Domains",
+      "description": "The domains that pertain to the event or object",
+      "type": "string_t",
+      "is_array": true
+    },
     "driver": {
       "caption": "Kernel Driver",
       "description": "The driver that was loaded/unloaded into the kernel",
@@ -2083,6 +2089,12 @@
       "description": "The result of the file change. It should contain the new values of the changed attributes.",
       "type": "file"
     },
+    "files": {
+      "caption": "Files",
+      "description": "The files that are part of the event or object",
+      "type": "file",
+      "is_array": true
+    },
     "finding": {
       "caption": "Finding",
       "description": "The Finding object provides details about a finding/detection generated by a security tool.",
@@ -3083,6 +3095,11 @@
       "description": "The description of the event/finding, as defined by the source.",
       "type": "string_t"
     },
+    "message_trace_uid": {
+      "caption": "Message Trace UID",
+      "description": "The identifier that tracks a message that travels through multiple points of a messaging service.",
+      "type": "string_t"
+    },
     "message_uid": {
       "caption": "Message UID",
       "description": "The email header Message-ID value, as defined by RFC 5322.",
@@ -5014,6 +5031,12 @@
       "description": "The URL string. See RFC 1738. For example: <code>http://www.example.com/download/trouble.exe</code>.",
       "type": "url_t"
     },
+    "urls": {
+      "caption": "URLs",
+      "description": "The URLs that pertain to the event or object.",
+      "type": "url",
+      "is_array": true
+    },
     "user": {
       "caption": "User",
       "description": "The user that pertains to the event or object.",

events/network/email_activity.json

@@ -2,7 +2,7 @@
   "uid": 9,
   "caption": "Email Activity",
   "category": "network",
-  "description": "Email events report activities of emails.",
+  "description": "Email Activity events report SMTP protocol and email activities including those with embedded URLs and files. See the <code>Email</code> object for details.",
   "extends": "base_event",
   "name": "email_activity",
   "attributes": {
@@ -25,7 +25,8 @@
         },
         "4": {
           "caption": "Trace",
-          "description": "Follow an email message as it travels through an organization. For example: <a target='_blank' href='https://learn.microsoft.com/en-us/Exchange/monitoring/trace-an-email-message/message-trace-modern-eac'>O365 Email Message Trace</a>."
+          "description": "Follow an email message as it travels through an organization. The <code>message_trace_uid</code> should be populated when selected.",
+          "references": [{"url": "href='https://learn.microsoft.com/en-us/Exchange/monitoring/trace-an-email-message/message-trace-modern-eac", "description": "For example O365 Email Message Trace"}]
         }
       }
     },
@@ -82,6 +83,13 @@
       "group": "primary",
       "requirement": "recommended"
     },
+    "email_uid": {
+      "group": "primary"
+    },
+    "message_trace_uid": {
+      "group": "primary",
+      "requirement": "recommended"
+    },
     "smtp_hello": {
       "description": "The value of the SMTP HELO or EHLO command sent by the initiator (client).",
       "group": "primary",

events/network/email_file_activity.json

@@ -5,6 +5,10 @@
   "description": "Email File Activity events report files within emails.",
   "extends": "base_event",
   "name": "email_file_activity",
+  "@deprecated": {
+    "message": "Use the <code>Email Activity</code> class with the <code>email.files[]</code> array instead.",
+    "since": "1.3.0"
+  },
   "attributes": {
     "$include": [
       "profiles/host.json",

events/network/email_url_activity.json

@@ -5,6 +5,10 @@
   "description": "Email URL Activity events report URLs within an email.",
   "extends": "base_event",
   "name": "email_url_activity",
+  "@deprecated": {
+    "message": "Use the <code>Email Activity</code> class with the <code>email.urls[]</code> array instead.",
+    "since": "1.3.0"
+  },
   "attributes": {
     "$include": [
       "profiles/host.json",

objects/email.json

@@ -1,7 +1,7 @@
 {
   "caption": "Email",
   "name": "email",
-  "description": "The Email object describes the email metadata such as sender, recipients, and direction.",
+  "description": "The Email object describes the email metadata such as sender, recipients, and direction, and can include embedded URLs and files.",
   "references": [{"url": "https://d3fend.mitre.org/dao/artifact/d3f:Email/", "description": "D3FEND™ Ontology d3f:Email."}],
   "extends": "object",
   "observable": 22,
@@ -18,8 +18,16 @@
     "delivered_to": {
       "requirement": "optional"
     },
+    "domains": {
+      "requirement": "optional",
+      "description": "The domain names that pertain to the email sender or recipients."
+    },
+    "files": {
+      "requirement": "optional",
+      "description": "The files embedded or attached to the email."
+    },
     "from": {
-      "requirement": "required"
+      "requirement": "recommended"
     },
     "http_headers": {
       "requirement": "optional"
@@ -49,7 +57,11 @@
       "requirement": "recommended"
     },
     "to": {
-      "requirement": "required"
+      "requirement": "recommended"
+    },
+    "urls": {
+      "requirement": "optional",
+      "description": "The URLs embedded in the email."
     },
     "x_originating_ip": {
       "requirement": "optional"
@@ -59,5 +71,13 @@
       "description": "The email unique identifier.",
       "requirement": "recommended"
     }
+  },
+  "constraints": {
+    "at_least_one": [
+      "from",
+      "to",
+      "smtp_from",
+      "smtp_to"
+    ]
   }
 }