santasyncservice: parse, dispatch, and report network flow rules (#976)

Adds the validator scaffolding, sync-response parsing, and
pre/postflight reporting:

- SNDNetworkFlowRuleValidator interface + always-YES stub in the
santanetd module (real impl lands later), following the
SNDFilterConfigurationHelper pattern.
- Parse network_flow_rules from RuleDownloadResponse into
SNTNetworkFlowRule (validating + dropping invalid), and dispatch them
via the existing combined
databaseRuleAddExecutionRules:fileAccessRules:networkFlowRules:... XPC.
- Populate network_flow_rule_count / network_flow_rules_hash in
preflight and network_flow_rules_received/_processed/_hash in
postflight, gated on syncv2.

Author: mlw

Source/common/SNTSyncConstants.h

@@ -45,6 +45,7 @@ extern NSString* const kTeamIDRuleCount;
 extern NSString* const kSigningIDRuleCount;
 extern NSString* const kCDHashRuleCount;
 extern NSString* const kFileAccessRuleCount;
+extern NSString* const kNetworkFlowRuleCount;
 extern NSString* const kFullSyncInterval;
 extern NSString* const kFCMToken;
 extern NSString* const kFCMFullSyncInterval;

Source/common/SNTSyncConstants.mm

@@ -45,6 +45,7 @@
 NSString* const kSigningIDRuleCount = @"signingid_rule_count";
 NSString* const kCDHashRuleCount = @"cdhash_rule_count";
 NSString* const kFileAccessRuleCount = @"file_access_rule_count";
+NSString* const kNetworkFlowRuleCount = @"network_flow_rule_count";
 NSString* const kFullSyncInterval = @"full_sync_interval";
 NSString* const kFCMToken = @"fcm_token";
 NSString* const kFCMFullSyncInterval = @"fcm_full_sync_interval";

Source/santasyncservice/BUILD

@@ -169,13 +169,15 @@ objc_library(
         ":SNTSyncState",
         "//Source/common:SNTCommonEnums",
         "//Source/common:SNTFileAccessRule",
+        "//Source/common:SNTNetworkFlowRule",
         "//Source/common:SNTRule",
         "//Source/common:SNTSyncConstants",
         "//Source/common:SNTXPCControlInterface",
         "//Source/common:String",
         "//Source/common/faa:WatchItemPolicy",
         "//Source/common/faa:WatchItems",
         "@northpolesec_protos//syncv2:v2_cc_proto",
+        "@santanetd//src/santanetd:SNDNetworkFlowRuleValidator",
     ],
 )
 
@@ -187,6 +189,7 @@ santa_unit_test(
     deps = [
         ":SNTSyncRuleDownload",
         "//Source/common:SNTFileAccessRule",
+        "//Source/common:SNTNetworkFlowRule",
         "//Source/common:TestUtils",
         "//Source/common/faa:WatchItemPolicy",
         "//Source/common/faa:WatchItems",
@@ -380,6 +383,7 @@ santa_unit_test(
         "//Source/common:SNTFileInfo",
         "//Source/common:SNTLogging",
         "//Source/common:SNTMetricSet",
+        "//Source/common:SNTNetworkFlowRule",
         "//Source/common:SNTRule",
         "//Source/common:SNTSIPStatus",
         "//Source/common:SNTStoredEvent",
@@ -400,6 +404,7 @@ santa_unit_test(
         "@northpolesec_protos//sync:v1_cc_proto",
         "@northpolesec_protos//syncv2:v2_cc_proto",
         "@protobuf//src/google/protobuf/json",
+        "@santanetd//src/santanetd:SNDNetworkFlowRuleValidator",
     ],
 )
 

Source/santasyncservice/SNTSyncPostflight.mm

@@ -40,6 +40,10 @@ BOOL Postflight(SNTSyncPostflight* self) {
         static_cast<uint32_t>(self.syncState.fileAccessRulesReceived));
     req->set_file_access_rules_processed(
         static_cast<uint32_t>(self.syncState.fileAccessRulesProcessed));
+    req->set_network_flow_rules_received(
+        static_cast<uint32_t>(self.syncState.networkFlowRulesReceived));
+    req->set_network_flow_rules_processed(
+        static_cast<uint32_t>(self.syncState.networkFlowRulesProcessed));
   }
 
   switch (self.syncState.syncType) {
@@ -53,6 +57,7 @@ BOOL Postflight(SNTSyncPostflight* self) {
     req->set_rules_hash(santa::NSStringToUTF8String(execRulesHash));
     if constexpr (IsV2) {
       req->set_file_access_rules_hash(santa::NSStringToUTF8String(faaRulesHash));
+      req->set_network_flow_rules_hash(santa::NSStringToUTF8String(nfRulesHash));
     }
   }];
 

Source/santasyncservice/SNTSyncPreflight.mm

@@ -125,13 +125,15 @@ BOOL Preflight(SNTSyncPreflight* self, google::protobuf::Arena* arena,
     req->set_cdhash_rule_count(static_cast<uint32_t>(counts.cdhash));
     if constexpr (IsV2) {
       req->set_file_access_rule_count(static_cast<uint32_t>(counts.fileAccess));
+      req->set_network_flow_rule_count(static_cast<uint32_t>(counts.networkFlow));
     }
   }];
 
   [rop databaseRulesHash:^(NSString* execRulesHash, NSString* faaRulesHash, NSString* nfRulesHash) {
     req->set_rules_hash(NSStringToUTF8String(execRulesHash));
     if constexpr (IsV2) {
       req->set_file_access_rules_hash(NSStringToUTF8String(faaRulesHash));
+      req->set_network_flow_rules_hash(NSStringToUTF8String(nfRulesHash));
     }
   }];
 

Source/santasyncservice/SNTSyncRuleDownload.mm

@@ -20,6 +20,7 @@
 
 #import "Source/common/MOLXPCConnection.h"
 #import "Source/common/SNTFileAccessRule.h"
+#import "Source/common/SNTNetworkFlowRule.h"
 #import "Source/common/SNTRule.h"
 #import "Source/common/SNTSyncConstants.h"
 #import "Source/common/SNTXPCControlInterface.h"
@@ -32,6 +33,7 @@
 #import "Source/santasyncservice/SNTSyncLogging.h"
 #import "Source/santasyncservice/SNTSyncState.h"
 #include "google/protobuf/arena.h"
+#import "src/santanetd/SNDNetworkFlowRuleValidator.h"
 #include "syncv2/v2.pb.h"
 
 namespace pbv2 = ::santa::sync::v2;
@@ -56,20 +58,24 @@ void ProcessDeprecatedBundleNotificationsForRule(
 NSDictionary* OptionsFromProtoFAARuleAdd(const ::pbv2::FileAccessRule::Add& pbAddRule);
 NSArray* ProcessesFromProtoFAARuleProcesses(
     const google::protobuf::RepeatedPtrField<::pbv2::FileAccessRule::Process>& pbProcesses);
+SNTNetworkFlowRule* NetworkFlowRuleFromProto(const ::pbv2::NetworkFlowRule& nr);
 
 // Small local object to more easily return the different sets of downloaded rules.
 @interface SNTDownloadedRuleSets : NSObject
 @property(readonly) NSArray<SNTRule*>* executionRules;
 @property(readonly) NSArray<SNTFileAccessRule*>* fileAccessRules;
+@property(readonly) NSArray<SNTNetworkFlowRule*>* networkRules;
 @end
 
 @implementation SNTDownloadedRuleSets
 - (instancetype)initWithExecutionRules:(NSArray<SNTRule*>*)executionRules
-                       fileAccessRules:(NSArray<SNTFileAccessRule*>*)fileAccessRules {
+                       fileAccessRules:(NSArray<SNTFileAccessRule*>*)fileAccessRules
+                          networkRules:(NSArray<SNTNetworkFlowRule*>*)networkRules {
   self = [super init];
   if (self) {
     _executionRules = executionRules;
     _fileAccessRules = fileAccessRules;
+    _networkRules = networkRules;
   }
   return self;
 }
@@ -94,8 +100,10 @@ SNTRuleCleanup SyncTypeToRuleCleanup(SNTSyncType syncType) {
 
   self.syncState.rulesReceived = 0;
   self.syncState.fileAccessRulesReceived = 0;
+  self.syncState.networkFlowRulesReceived = 0;
   NSMutableArray<SNTRule*>* newRules = [NSMutableArray array];
   NSMutableArray<SNTFileAccessRule*>* newFileAccessRules = [NSMutableArray array];
+  NSMutableArray<SNTNetworkFlowRule*>* newNetworkRules = [NSMutableArray array];
   std::string cursor;
 
   do {
@@ -135,22 +143,34 @@ SNTRuleCleanup SyncTypeToRuleCleanup(SNTSyncType syncType) {
           }
           [newFileAccessRules addObject:rule];
         }
+
+        for (const ::pbv2::NetworkFlowRule& networkRule : response.network_flow_rules()) {
+          SNTNetworkFlowRule* rule = NetworkFlowRuleFromProto(networkRule);
+          if (!rule) {
+            SLOGD(@"Ignoring bad network flow rule: %s", networkRule.Utf8DebugString().c_str());
+            continue;
+          }
+          [newNetworkRules addObject:rule];
+        }
       }
 
       cursor = response.cursor();
       SLOGI(@"Received %lu rules", (unsigned long)response.rules_size());
       self.syncState.rulesReceived += response.rules_size();
       if constexpr (IsV2) {
         self.syncState.fileAccessRulesReceived += response.file_access_rules_size();
+        self.syncState.networkFlowRulesReceived += response.network_flow_rules_size();
       }
     }
   } while (!cursor.empty());
 
   self.syncState.rulesProcessed = newRules.count;
   self.syncState.fileAccessRulesProcessed = newFileAccessRules.count;
+  self.syncState.networkFlowRulesProcessed = newNetworkRules.count;
 
   return [[SNTDownloadedRuleSets alloc] initWithExecutionRules:newRules
-                                               fileAccessRules:newFileAccessRules];
+                                               fileAccessRules:newFileAccessRules
+                                                  networkRules:newNetworkRules];
 }
 
 NSArray* PathsFromProtoFAARulePaths(
@@ -299,6 +319,27 @@ SNTRuleCleanup SyncTypeToRuleCleanup(SNTSyncType syncType) {
   }
 }
 
+SNTNetworkFlowRule* NetworkFlowRuleFromProto(const ::pbv2::NetworkFlowRule& nr) {
+  switch (nr.action_case()) {
+    case ::pbv2::NetworkFlowRule::kAdd: {
+      std::string serialized;
+      nr.add().SerializeToString(&serialized);
+      NSData* blob = [NSData dataWithBytes:serialized.data() length:serialized.size()];
+
+      NSError* err;
+      if (!SNDValidateNetworkFlowRule(blob, &err)) {
+        SLOGW(@"Dropping invalid network flow rule %lld: %@", (long long)nr.add().rule_id(),
+              err.localizedDescription ?: @"validation failed");
+        return nil;
+      }
+      return [[SNTNetworkFlowRule alloc] initAddRuleWithId:nr.add().rule_id() protoBlob:blob];
+    }
+    case ::pbv2::NetworkFlowRule::kRemove:
+      return [[SNTNetworkFlowRule alloc] initRemoveRuleWithId:nr.remove().rule_id()];
+    default: return nil;
+  }
+}
+
 template <bool IsV2>
 SNTRule* RuleFromProtoRule(const typename santa::ProtoTraits<IsV2>::RuleT& rule) {
   using Traits = santa::ProtoTraits<IsV2>;
@@ -435,7 +476,8 @@ - (BOOL)sync {
     return NO;
   }
   // If the request was successfully completed, but no new rules received, just return
-  if (!newRules.executionRules.count && !newRules.fileAccessRules.count) {
+  if (!newRules.executionRules.count && !newRules.fileAccessRules.count &&
+      !newRules.networkRules.count) {
     return YES;
   }
 
@@ -447,7 +489,7 @@ - (BOOL)sync {
   [[self.daemonConn remoteObjectProxy]
       databaseRuleAddExecutionRules:newRules.executionRules
                     fileAccessRules:newRules.fileAccessRules
-                   networkFlowRules:nil
+                   networkFlowRules:newRules.networkRules
                         ruleCleanup:SyncTypeToRuleCleanup(self.syncState.syncType)
                              source:SNTRuleAddSourceSyncService
                               reply:^(BOOL didSucceed, NSArray<NSError*>* e) {
@@ -489,6 +531,10 @@ - (BOOL)sync {
     SLOGI(@"Processed %lu file access rules", newRules.fileAccessRules.count);
   }
 
+  if (newRules.networkRules.count) {
+    SLOGI(@"Processed %lu network flow rules", newRules.networkRules.count);
+  }
+
   // Send out push notifications about any newly allowed binaries
   // that had been previously blocked by santad.
   [self announceUnblockingRules:newRules.executionRules];

Source/santasyncservice/SNTSyncRuleDownloadTest.mm

@@ -18,6 +18,7 @@
 #import <XCTest/XCTest.h>
 
 #import "Source/common/SNTFileAccessRule.h"
+#import "Source/common/SNTNetworkFlowRule.h"
 #include "Source/common/TestUtils.h"
 #include "Source/common/faa/WatchItemPolicy.h"
 #include "Source/common/faa/WatchItems.h"
@@ -32,6 +33,7 @@
 extern NSArray* ProcessesFromProtoFAARuleProcesses(
     const google::protobuf::RepeatedPtrField<::pbv2::FileAccessRule::Process>& pbProcesses);
 extern SNTFileAccessRule* FAARuleFromProtoFileAccessRule(const ::pbv2::FileAccessRule& wi);
+extern SNTNetworkFlowRule* NetworkFlowRuleFromProto(const ::pbv2::NetworkFlowRule& nr);
 
 @interface SNTSyncRuleDownloadTest : XCTestCase
 @end
@@ -330,6 +332,42 @@ - (void)testInvalidFAARuleFromProtoFileAccessRuleAdd {
   }
 }
 
+- (void)testNetworkFlowRuleFromProtoAdd {
+  ::pbv2::NetworkFlowRule nr;
+  ::pbv2::NetworkFlowRule::Add* add = nr.mutable_add();
+  add->set_rule_id(42);
+  add->set_action(::pbv2::NetworkFlowRule::ACTION_DENY);
+  add->set_direction(::pbv2::NETWORK_FLOW_DIRECTION_OUTGOING);
+
+  SNTNetworkFlowRule* rule = NetworkFlowRuleFromProto(nr);
+  XCTAssertNotNil(rule);
+  XCTAssertEqual(rule.ruleId, 42);
+  XCTAssertEqual(rule.state, SNTNetworkFlowRuleStateAdd);
+  XCTAssertNotNil(rule.protoBlob);
+
+  // The blob round-trips back to the originating Add.
+  ::pbv2::NetworkFlowRule::Add parsed;
+  XCTAssertTrue(parsed.ParseFromArray(rule.protoBlob.bytes, (int)rule.protoBlob.length));
+  XCTAssertEqual(parsed.rule_id(), 42);
+  XCTAssertEqual(parsed.action(), ::pbv2::NetworkFlowRule::ACTION_DENY);
+}
+
+- (void)testNetworkFlowRuleFromProtoRemove {
+  ::pbv2::NetworkFlowRule nr;
+  nr.mutable_remove()->set_rule_id(99);
+
+  SNTNetworkFlowRule* rule = NetworkFlowRuleFromProto(nr);
+  XCTAssertNotNil(rule);
+  XCTAssertEqual(rule.ruleId, 99);
+  XCTAssertEqual(rule.state, SNTNetworkFlowRuleStateRemove);
+  XCTAssertNil(rule.protoBlob);
+}
+
+- (void)testNetworkFlowRuleFromProtoEmptyIsNil {
+  ::pbv2::NetworkFlowRule nr;
+  XCTAssertNil(NetworkFlowRuleFromProto(nr));
+}
+
 - (void)testFAARuleFromProtoFileAccessRuleRemove {
   ::pbv2::FileAccessRule wi;
   ::pbv2::FileAccessRule::Remove* pbRemove = wi.mutable_remove();

Source/santasyncservice/SNTSyncState.h

@@ -115,6 +115,8 @@
 @property NSUInteger rulesProcessed;
 @property NSUInteger fileAccessRulesReceived;
 @property NSUInteger fileAccessRulesProcessed;
+@property NSUInteger networkFlowRulesReceived;
+@property NSUInteger networkFlowRulesProcessed;
 
 @property BOOL preflightOnly;
 @property BOOL pushNotificationSync;

Source/santasyncservice/SNTSyncTest.mm

@@ -530,6 +530,7 @@ - (void)testPreflightDatabaseCounts {
       .signingID = 123,
       .cdhash = 11,
       .fileAccess = 513,
+      .networkFlow = 77,
   };
 
   OCMStub([self.daemonConnRop
@@ -549,8 +550,33 @@ - (void)testPreflightDatabaseCounts {
             XCTAssertEqualObjects(requestDict[kSigningIDRuleCount], @(ruleCounts.signingID));
             if (self.syncState.isSyncV2) {
               XCTAssertEqualObjects(requestDict[kFileAccessRuleCount], @(ruleCounts.fileAccess));
+              XCTAssertEqualObjects(requestDict[kNetworkFlowRuleCount], @(ruleCounts.networkFlow));
             } else {
               XCTAssertNil(requestDict[kFileAccessRuleCount]);
+              XCTAssertNil(requestDict[kNetworkFlowRuleCount]);
+            }
+            return YES;
+          }];
+
+  [sut sync];
+}
+
+- (void)testPreflightRulesHash {
+  [self setupDefaultDaemonConnResponses];
+  SNTSyncPreflight* sut = [[SNTSyncPreflight alloc] initWithState:self.syncState];
+
+  [self stubRequestBody:nil
+               response:nil
+                  error:nil
+          validateBlock:^BOOL(NSURLRequest* req) {
+            NSDictionary* requestDict = [self dictFromRequest:req];
+            XCTAssertEqualObjects(requestDict[@"rulesHash"], @"the-hash");
+            if (self.syncState.isSyncV2) {
+              XCTAssertEqualObjects(requestDict[@"fileAccessRulesHash"], @"the-faa-hash");
+              XCTAssertEqualObjects(requestDict[@"network_flow_rules_hash"], @"the-nf-hash");
+            } else {
+              XCTAssertNil(requestDict[@"fileAccessRulesHash"]);
+              XCTAssertNil(requestDict[@"network_flow_rules_hash"]);
             }
             return YES;
           }];
@@ -1207,6 +1233,7 @@ - (void)testPostflightBasicResponse {
             XCTAssertEqualObjects(requestDict[@"rulesHash"], @"the-hash");
             if (self.syncState.isSyncV2) {
               XCTAssertEqualObjects(requestDict[@"fileAccessRulesHash"], @"the-faa-hash");
+              XCTAssertEqualObjects(requestDict[@"network_flow_rules_hash"], @"the-nf-hash");
             }
             return YES;
           }];
@@ -1215,6 +1242,38 @@ - (void)testPostflightBasicResponse {
   OCMVerify([self.daemonConnRop updateSyncSettings:OCMOCK_ANY reply:OCMOCK_ANY]);
 }
 
+- (void)testPostflightReportsRuleCounts {
+  [self setupDefaultDaemonConnResponses];
+  self.syncState.rulesReceived = 10;
+  self.syncState.rulesProcessed = 9;
+  self.syncState.fileAccessRulesReceived = 4;
+  self.syncState.fileAccessRulesProcessed = 3;
+  self.syncState.networkFlowRulesReceived = 6;
+  self.syncState.networkFlowRulesProcessed = 5;
+  SNTSyncPostflight* sut = [[SNTSyncPostflight alloc] initWithState:self.syncState];
+
+  [self stubRequestBody:nil
+               response:nil
+                  error:nil
+          validateBlock:^BOOL(NSURLRequest* req) {
+            NSDictionary* requestDict = [self dictFromRequest:req];
+            XCTAssertEqualObjects(requestDict[@"rules_received"], @10);
+            XCTAssertEqualObjects(requestDict[@"rules_processed"], @9);
+            if (self.syncState.isSyncV2) {
+              XCTAssertEqualObjects(requestDict[@"file_access_rules_received"], @4);
+              XCTAssertEqualObjects(requestDict[@"file_access_rules_processed"], @3);
+              XCTAssertEqualObjects(requestDict[@"network_flow_rules_received"], @6);
+              XCTAssertEqualObjects(requestDict[@"network_flow_rules_processed"], @5);
+            } else {
+              XCTAssertNil(requestDict[@"network_flow_rules_received"]);
+              XCTAssertNil(requestDict[@"network_flow_rules_processed"]);
+            }
+            return YES;
+          }];
+
+  XCTAssertTrue([sut sync]);
+}
+
 - (SNTConfigBundle*)runPostflightAndCaptureBundleWithInflightSyncType:(SNTSyncType)inflight {
   [self setupDefaultDaemonConnResponses];
   self.syncState.syncType = inflight;

Source/santasyncservice/testdata/sync_preflight_request_v2.json

@@ -1 +1 @@
-{"serial_num":"QYGF4QM373","hostname":"full-hostname.example.com","os_version":"14.5","os_build":"23F79","model_identifier":"MacBookPro18,3","santa_version":"2024.6.655965194","primary_user":"username1","client_mode":"MONITOR","machine_id":"50C7E1EB-2EF5-42D4-A084-A7966FC45A95","sipStatus":111,"rulesHash":"the-hash","fileAccessRulesHash":"the-faa-hash"}
+{"serial_num":"QYGF4QM373","hostname":"full-hostname.example.com","os_version":"14.5","os_build":"23F79","model_identifier":"MacBookPro18,3","santa_version":"2024.6.655965194","primary_user":"username1","client_mode":"MONITOR","machine_id":"50C7E1EB-2EF5-42D4-A084-A7966FC45A95","sipStatus":111,"rulesHash":"the-hash","fileAccessRulesHash":"the-faa-hash","network_flow_rules_hash":"the-nf-hash"}