celv2: expose AUDIT return value, trigger event upload with flag set (#956)

Author: russellhancox

MODULE.bazel

@@ -18,7 +18,7 @@ bazel_dep(name = "boringssl", version = "0.20260211.0")
 bazel_dep(name = "protos", version = "1.0.1", repo_name = "northpolesec_protos")
 git_override(
     module_name = "protos",
-    commit = "ae9f6e1cfca5cdbac04240cac6be46b58c4b1161",
+    commit = "df6b5ea22bdfeb185b5a22d7090553ec80ce081f",
     remote = "https://github.com/northpolesec/protos",
 )
 

Source/common/SNTCachedDecision.h

@@ -75,4 +75,11 @@
 @property BOOL silentTouchID;
 @property NSNumber* touchIDCooldownMinutes;  // nil = no caching (prompt every time)
 
+/// YES if the matching CEL rule returned AUDIT. The execution itself is
+/// allowed (the decision is set to the underlying allow event state, e.g.
+/// SNTEventStateAllowBinary or SNTEventStateAllowCELFallback) but the event
+/// is logged and uploaded with this flag set so audit-only matches can be
+/// distinguished from regular allow decisions on the server.
+@property BOOL auditReturn;
+
 @end

Source/common/SNTCachedDecision.mm

@@ -87,6 +87,7 @@ - (id)copyWithZone:(NSZone*)zone {
   copy.holdAndAsk = _holdAndAsk;
   copy.silentTouchID = _silentTouchID;
   copy.touchIDCooldownMinutes = _touchIDCooldownMinutes;
+  copy.auditReturn = _auditReturn;
   return copy;
 }
 

Source/common/SNTStoredExecutionEvent.h

@@ -89,6 +89,11 @@
 /// The decision santad returned.
 @property SNTEventState decision;
 
+/// YES if the matching CEL rule returned AUDIT. The decision itself is an
+/// allow decision; this flag indicates the rule was audit-only and the event
+/// is uploaded so audit matches can be distinguished on the sync server.
+@property BOOL auditReturn;
+
 /// The decision depends on the user approving execution.
 @property BOOL holdAndAsk;
 

Source/common/SNTStoredExecutionEvent.mm

@@ -80,6 +80,7 @@ - (void)encodeWithCoder:(NSCoder*)coder {
 
   ENCODE(coder, executingUser);
   ENCODE_BOXABLE(coder, decision);
+  ENCODE_BOXABLE(coder, auditReturn);
   ENCODE_BOXABLE(coder, holdAndAsk);
   ENCODE_BOXABLE(coder, silentTouchID);
   ENCODE_BOXABLE(coder, seatbeltRequired);
@@ -128,6 +129,7 @@ - (instancetype)initWithCoder:(NSCoder*)decoder {
 
     DECODE(decoder, executingUser, NSString);
     DECODE_SELECTOR(decoder, decision, NSNumber, unsignedLongLongValue);
+    DECODE_SELECTOR(decoder, auditReturn, NSNumber, boolValue);
     DECODE_SELECTOR(decoder, holdAndAsk, NSNumber, boolValue);
     DECODE_SELECTOR(decoder, silentTouchID, NSNumber, boolValue);
     DECODE_SELECTOR(decoder, seatbeltRequired, NSNumber, boolValue);

Source/common/cel/CELProtoTraits.h

@@ -78,6 +78,7 @@ struct CELProtoTraits<true> {
   static constexpr ReturnValue REQUIRE_TOUCHID_ONLY =
       ::santa::cel::v2::REQUIRE_TOUCHID_ONLY;
   static constexpr ReturnValue SEATBELT = ::santa::cel::v2::SEATBELT;
+  static constexpr ReturnValue AUDIT = ::santa::cel::v2::AUDIT;
 
   // Descriptor accessors
   static const google::protobuf::EnumDescriptor* ReturnValue_descriptor() {

Source/common/cel/Test.mm

@@ -270,6 +270,66 @@ - (void)testBasic {
   }
 }
 
+- (void)testAuditReturnValue {
+  using ReturnValue = santa::cel::CELProtoTraits<true>::ReturnValue;
+  using ExecutableFileT = santa::cel::CELProtoTraits<true>::ExecutableFileT;
+  using AncestorT = santa::cel::CELProtoTraits<true>::AncestorT;
+  using FileDescriptorT = santa::cel::CELProtoTraits<true>::FileDescriptorT;
+
+  XCTAssertEqual(santa::cel::CELProtoTraits<true>::AUDIT, ::santa::cel::v2::AUDIT);
+
+  auto f = std::make_unique<ExecutableFileT>();
+  f->set_team_id("EQHXZ8M8AV");
+  santa::cel::Activation<true> activation(
+      std::move(f),
+      ^std::vector<std::string>() {
+        return {"hello", "world"};
+      },
+      ^std::map<std::string, std::string>() {
+        return {};
+      },
+      ^uid_t() {
+        return 0;
+      },
+      ^std::string() {
+        return "/";
+      },
+      ^std::string() {
+        return "/usr/bin/test";
+      },
+      ^std::vector<AncestorT>() {
+        return {};
+      },
+      ^std::vector<FileDescriptorT>() {
+        return {};
+      });
+
+  auto sut = santa::cel::Evaluator<true>::Create();
+  XCTAssertTrue(sut.ok());
+
+  {
+    // Static - AUDIT returned when team_id matches
+    auto result = sut.value()->CompileAndEvaluate(
+        "target.team_id == 'EQHXZ8M8AV' ? AUDIT : ALLOWLIST", activation);
+    if (!result.ok()) {
+      XCTFail("Failed to evaluate: %s", result.status().message().data());
+    } else {
+      XCTAssertEqual(result.value().value, ReturnValue::AUDIT);
+      XCTAssertEqual(result.value().cacheable, true);
+    }
+  }
+  {
+    // Dynamic - AUDIT returned when args non-empty
+    auto result = sut.value()->CompileAndEvaluate("size(args) > 0 ? AUDIT : ALLOWLIST", activation);
+    if (!result.ok()) {
+      XCTFail("Failed to evaluate: %s", result.status().message().data());
+    } else {
+      XCTAssertEqual(result.value().value, ReturnValue::AUDIT);
+      XCTAssertEqual(result.value().cacheable, false);
+    }
+  }
+}
+
 - (void)testV2Only {
   auto argsFn = ^std::vector<std::string>() {
     return {"hello", "world"};

Source/common/santa.proto

@@ -350,6 +350,13 @@ message Execution {
 
   // The server-assigned rule ID that was used to make the decision
   optional int64 rule_id = 18;
+
+  // True if the matching rule returned AUDIT from a CEL expression. The
+  // execution was allowed (as if the rule had returned ALLOWLIST), but the
+  // event is logged with this flag set so audit matches can be distinguished
+  // from regular allow decisions. The `decision` and `reason` fields still
+  // report the underlying allow decision (e.g. DECISION_ALLOW / REASON_BINARY).
+  optional bool audit_return = 19;
 }
 
 // Information about a fork event

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

@@ -337,6 +337,10 @@ static inline void AppendSocketAddress(std::string& str, es_address_type_t type,
   str.append("|reason=");
   str.append(GetReasonString(cd.decision));
 
+  if (cd.auditReturn) {
+    str.append("|audit=true");
+  }
+
   if (cd.decisionExtra) {
     str.append("|explain=");
     str.append([cd.decisionExtra UTF8String]);

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

@@ -604,6 +604,10 @@ void EncodeEntitlements(::pbv1::Execution* pb_exec, SNTCachedDecision* cd) {
     pb_exec->set_rule_id(cd.ruleId);
   }
 
+  if (cd.auditReturn) {
+    pb_exec->set_audit_return(true);
+  }
+
   return FinalizeProto(santa_msg);
 }