Add logging support for ES_EVENT_TYPE_NOTIFY_PROC_SUSPEND_RESUME (#883)

Add full support for logging process suspend/resume events:
- updated the proto to add a `ProcSuspendResume` message with
instigator, target, and Type enum
- updated enriched types and serializers
- updated the Telemetry map with a new key `kProcSuspendResume` 
- updated notifier subscriptions to include the
`NOTIFY_PROC_SUSPEND_RESUME` event
- updated metrics
- updated tests

Author: pmarkowsky

Source/common/TelemetryEventMap.h

@@ -49,6 +49,7 @@ enum class TelemetryEvent : uint64_t {
   kLaunchItem              = 1 << 21,
   kTCCModification         = 1 << 22,
   kXProtect                = 1 << 23,
+  kProcSuspendResume       = 1 << 24,
   kEverything              = ~0ULL,
 };
 // clang-format on

Source/common/TelemetryEventMap.mm

@@ -50,6 +50,7 @@ static inline TelemetryEvent EventNameToMask(std::string_view event) {
       {"launchitem", TelemetryEvent::kLaunchItem},
       {"tccmodification", TelemetryEvent::kTCCModification},
       {"xprotect", TelemetryEvent::kXProtect},
+      {"procsuspendresume", TelemetryEvent::kProcSuspendResume},
       // IMPORTANT: When adding new keys to the map, keep the set of keys in
       // `docs/src/lib/santaconfig.ts` in sync.
 
@@ -114,6 +115,7 @@ TelemetryEvent ESEventToTelemetryEvent(es_event_type_t event) {
 #if HAVE_MACOS_15_4
     case ES_EVENT_TYPE_NOTIFY_TCC_MODIFY: return TelemetryEvent::kTCCModification;
 #endif  // HAVE_MACOS_15_4
+    case ES_EVENT_TYPE_NOTIFY_PROC_SUSPEND_RESUME: return TelemetryEvent::kProcSuspendResume;
     default: return TelemetryEvent::kNone;
   }
 }

Source/common/TelemetryEventMapTest.mm

@@ -60,6 +60,7 @@ - (void)testTelemetryConfigToBitmask {
       {"LaunchItem", TelemetryEvent::kLaunchItem},
       {"TCCModification", TelemetryEvent::kTCCModification},
       {"XProtect", TelemetryEvent::kXProtect},
+      {"ProcSuspendResume", TelemetryEvent::kProcSuspendResume},
 
       // special cases
       {"none", TelemetryEvent::kNone},
@@ -112,6 +113,7 @@ - (void)testESEventToTelemetryEvent {
       {ES_EVENT_TYPE_NOTIFY_BTM_LAUNCH_ITEM_REMOVE, TelemetryEvent::kLaunchItem},
       {ES_EVENT_TYPE_NOTIFY_XP_MALWARE_DETECTED, TelemetryEvent::kXProtect},
       {ES_EVENT_TYPE_NOTIFY_XP_MALWARE_REMEDIATED, TelemetryEvent::kXProtect},
+      {ES_EVENT_TYPE_NOTIFY_PROC_SUSPEND_RESUME, TelemetryEvent::kProcSuspendResume},
 #if HAVE_MACOS_15
       {ES_EVENT_TYPE_NOTIFY_GATEKEEPER_USER_OVERRIDE, TelemetryEvent::kGatekeeperOverride},
 #endif  // HAVE_MACOS_15

Source/common/es/EnrichedTypes.h

@@ -344,6 +344,23 @@ class EnrichedCSInvalidated : public EnrichedEventType {
   EnrichedCSInvalidated(const EnrichedCSInvalidated& other) = delete;
 };
 
+class EnrichedProcSuspendResume : public EnrichedEventType {
+ public:
+  EnrichedProcSuspendResume(Message&& es_msg, EnrichedProcess&& instigator,
+                            std::optional<EnrichedProcess>&& target)
+      : EnrichedEventType(std::move(es_msg), std::move(instigator)),
+        target_(std::move(target)) {}
+
+  EnrichedProcSuspendResume(EnrichedProcSuspendResume&&) = default;
+
+  EnrichedProcSuspendResume(const EnrichedProcSuspendResume& other) = delete;
+
+  const std::optional<EnrichedProcess>& target() const { return target_; }
+
+ private:
+  std::optional<EnrichedProcess> target_;
+};
+
 // Note: All EnrichedLoginWindowSession* classes currently have the same
 // data and implementation. To improve maintainability but still provide
 // individual types, an internal EnrichedLoginWindowSession base class is
@@ -780,7 +797,8 @@ using EnrichedType = std::variant<
     EnrichedLoginLogout, EnrichedAuthenticationOD,
     EnrichedAuthenticationTouchID, EnrichedAuthenticationToken,
     EnrichedAuthenticationAutoUnlock, EnrichedClone, EnrichedCopyfile,
-    EnrichedLaunchItem, EnrichedXProtectDetected, EnrichedXProtectRemediated
+    EnrichedProcSuspendResume, EnrichedLaunchItem, EnrichedXProtectDetected,
+    EnrichedXProtectRemediated
 #if HAVE_MACOS_15
     ,
     EnrichedGatekeeperOverride

Source/common/es/Enricher.mm

@@ -188,6 +188,14 @@
           std::move(es_msg), Enrich(*es_msg->process), Enrich(es_msg->event.tcc_modify->instigator),
           Enrich(es_msg->event.tcc_modify->responsible)));
 #endif  // HAVE_MACOS_15_4
+    case ES_EVENT_TYPE_NOTIFY_PROC_SUSPEND_RESUME: {
+      std::optional<EnrichedProcess> target;
+      if (es_msg->event.proc_suspend_resume.target) {
+        target.emplace(Enrich(*es_msg->event.proc_suspend_resume.target));
+      }
+      return std::make_unique<EnrichedMessage>(EnrichedProcSuspendResume(
+          std::move(es_msg), Enrich(*es_msg->process), std::move(target)));
+    }
     default:
       // This is a programming error
       LOGE(@"Attempting to enrich an unhandled event type: %d", es_msg->event_type);

Source/common/santa.proto

@@ -1230,6 +1230,24 @@ message NetworkActivity {
   repeated Process processes = 1;
 }
 
+// Information about a process suspend/resume event
+message ProcSuspendResume {
+  // The process initiating the suspend/resume
+  optional ProcessInfoLight instigator = 1;
+
+  // The target process being suspended/resumed
+  optional ProcessInfo target = 2;
+
+  // The type of suspend/resume action
+  enum Type {
+    TYPE_UNKNOWN = 0;
+    TYPE_SUSPEND = 1;
+    TYPE_RESUME = 2;
+    TYPE_SHUTDOWN_SOCKETS = 3;
+  }
+  optional Type type = 3;
+}
+
 // A message encapsulating a single event
 message SantaMessage {
   // Machine ID of the host emitting this log
@@ -1273,6 +1291,7 @@ message SantaMessage {
     TCCModification tcc_modification = 32;
     XProtect xprotect = 33;
     NetworkActivity network_activity = 34;
+    ProcSuspendResume proc_suspend_resume = 35;
   }
 }
 

Source/santad/EventProviders/SNTEndpointSecurityRecorder.mm

@@ -223,6 +223,7 @@ - (void)enable {
     ES_EVENT_TYPE_NOTIFY_BTM_LAUNCH_ITEM_REMOVE,
     ES_EVENT_TYPE_NOTIFY_XP_MALWARE_DETECTED,
     ES_EVENT_TYPE_NOTIFY_XP_MALWARE_REMEDIATED,
+    ES_EVENT_TYPE_NOTIFY_PROC_SUSPEND_RESUME,
   };
 
 #if HAVE_MACOS_15

Source/santad/EventProviders/SNTEndpointSecurityRecorderTest.mm

@@ -101,7 +101,8 @@ - (void)setUp {
                                               ES_EVENT_TYPE_NOTIFY_BTM_LAUNCH_ITEM_ADD,
                                               ES_EVENT_TYPE_NOTIFY_BTM_LAUNCH_ITEM_REMOVE,
                                               ES_EVENT_TYPE_NOTIFY_XP_MALWARE_DETECTED,
-                                              ES_EVENT_TYPE_NOTIFY_XP_MALWARE_REMEDIATED};
+                                              ES_EVENT_TYPE_NOTIFY_XP_MALWARE_REMEDIATED,
+                                              ES_EVENT_TYPE_NOTIFY_PROC_SUSPEND_RESUME};
 
 #if HAVE_MACOS_15
   if (@available(macOS 15.0, *)) {

Source/santad/Logs/EndpointSecurity/Serializers/BasicString.h

@@ -51,6 +51,7 @@ class BasicString : public Serializer {
   std::vector<uint8_t> SerializeMessage(const santa::EnrichedCSInvalidated&) override;
   std::vector<uint8_t> SerializeMessage(const santa::EnrichedClone&) override;
   std::vector<uint8_t> SerializeMessage(const santa::EnrichedCopyfile&) override;
+  std::vector<uint8_t> SerializeMessage(const santa::EnrichedProcSuspendResume&) override;
   std::vector<uint8_t> SerializeMessage(const santa::EnrichedLoginWindowSessionLogin&) override;
   std::vector<uint8_t> SerializeMessage(const santa::EnrichedLoginWindowSessionLogout&) override;
   std::vector<uint8_t> SerializeMessage(const santa::EnrichedLoginWindowSessionLock&) override;

Source/santad/Logs/EndpointSecurity/Serializers/BasicString.mm

@@ -520,6 +520,30 @@ static inline void AppendSocketAddress(std::string& str, es_address_type_t type,
   return FinalizeString(str);
 }
 
+std::vector<uint8_t> BasicString::SerializeMessage(const EnrichedProcSuspendResume& msg) {
+  std::string str = CreateDefaultString();
+
+  str.append("action=PROC_SUSPEND_RESUME");
+
+  switch (msg->event.proc_suspend_resume.type) {
+    case ES_PROC_SUSPEND_RESUME_TYPE_SUSPEND: str.append("|type=SUSPEND"); break;
+    case ES_PROC_SUSPEND_RESUME_TYPE_RESUME: str.append("|type=RESUME"); break;
+    case ES_PROC_SUSPEND_RESUME_TYPE_SHUTDOWN_SOCKETS: str.append("|type=SHUTDOWN_SOCKETS"); break;
+    default: str.append("|type=UNKNOWN"); break;
+  }
+
+  if (msg->event.proc_suspend_resume.target) {
+    str.append("|targetpid=");
+    str.append(std::to_string(Pid(msg->event.proc_suspend_resume.target->audit_token)));
+    str.append("|targetpath=");
+    str.append(FilePath(msg->event.proc_suspend_resume.target->executable).Sanitized());
+  }
+
+  AppendInstigator(str, msg);
+
+  return FinalizeString(str);
+}
+
 std::vector<uint8_t> BasicString::SerializeMessage(const EnrichedLoginWindowSessionLogin& msg) {
   std::string str = CreateDefaultString();