Add support for TLS protocol tracing (#2096)

Summary: Add support for TLS protocol tracing

This is the final change to wire up the tls protocol parser and stitcher
into stirling. I've also filed #2095 to track supporting tracing TLS
handshakes and the application data.

Relevant Issues: N/A

Type of change: /kind feature

Test Plan: New tests verify functionality works end to end

Changelog Message: Added support for tracing TLS handshakes. This can be
enabled with `--stirling_enable_tls_tracing=1` or through the
`PX_STIRLING_ENABLE_TLS_TRACING` environment variable. Until #2095 is
addressed, this will disable tracing the plaintext within encrypted
connections.

---------

Signed-off-by: Dom Del Nano <ddelnano@gmail.com>

Author: ddelnano

src/shared/protocols/protocols.h

@@ -39,6 +39,7 @@ enum class Protocol {
   kKafka = 10,
   kMux = 11,
   kAMQP = 12,
+  kTLS = 13,
 };
 
 }  // namespace protocols

src/stirling/binaries/stirling_wrapper.cc

@@ -62,7 +62,7 @@ DEFINE_string(trace, "",
               "Dynamic trace to deploy. Either (1) the path to a file containing PxL or IR trace "
               "spec, or (2) <path to object file>:<symbol_name> for full-function tracing.");
 DEFINE_string(print_record_batches,
-              "http_events,mysql_events,pgsql_events,redis_events,cql_events,dns_events",
+              "http_events,mysql_events,pgsql_events,redis_events,cql_events,dns_events,tls_events",
               "Comma-separated list of tables to print.");
 DEFINE_bool(init_only, false, "If true, only runs the init phase and exits. For testing.");
 DEFINE_int32(timeout_secs, -1,

src/stirling/source_connectors/socket_tracer/BUILD.bazel

@@ -518,6 +518,27 @@ pl_cc_bpf_test(
     ],
 )
 
+pl_cc_bpf_test(
+    name = "tls_trace_bpf_test",
+    timeout = "long",
+    srcs = ["tls_trace_bpf_test.cc"],
+    flaky = True,
+    shard_count = 2,
+    tags = [
+        "cpu:16",
+        "no_asan",
+        "requires_bpf",
+    ],
+    deps = [
+        ":cc_library",
+        "//src/common/testing/test_utils:cc_library",
+        "//src/stirling/source_connectors/socket_tracer/testing:cc_library",
+        "//src/stirling/source_connectors/socket_tracer/testing/container_images:curl_container",
+        "//src/stirling/source_connectors/socket_tracer/testing/container_images:nginx_openssl_3_0_8_container",
+        "//src/stirling/testing:cc_library",
+    ],
+)
+
 pl_cc_bpf_test(
     name = "dyn_lib_trace_bpf_test",
     timeout = "moderate",

src/stirling/source_connectors/socket_tracer/bcc_bpf/BUILD.bazel

@@ -82,6 +82,7 @@ pl_cc_test(
         "ENABLE_NATS_TRACING=true",
         "ENABLE_MONGO_TRACING=true",
         "ENABLE_AMQP_TRACING=true",
+        "ENABLE_TLS_TRACING=true",
     ],
     deps = [
         "//src/stirling/bpf_tools/bcc_bpf:headers",

src/stirling/source_connectors/socket_tracer/bcc_bpf/protocol_inference.h

@@ -60,6 +60,46 @@ static __inline enum message_type_t infer_http_message(const char* buf, size_t c
   return kUnknown;
 }
 
+static __inline enum message_type_t infer_tls_message(const char* buf, size_t count) {
+  if (count < 6) {
+    return kUnknown;
+  }
+
+  uint8_t content_type = buf[0];
+  // TLS content types correspond to the following:
+  // 0x14: ChangeCipherSpec
+  // 0x15: Alert
+  // 0x16: Handshake
+  // 0x17: ApplicationData
+  // 0x18: Heartbeat
+  if (content_type != 0x16) {
+    return kUnknown;
+  }
+
+  uint16_t legacy_version = buf[1] << 8 | buf[2];
+  // TLS versions correspond to the following:
+  // 0x0300: SSL 3.0
+  // 0x0301: TLS 1.0
+  // 0x0302: TLS 1.1
+  // 0x0303: TLS 1.2
+  // 0x0304: TLS 1.3
+  if (legacy_version < 0x0300 || legacy_version > 0x0304) {
+    return kUnknown;
+  }
+
+  uint8_t handshake_type = buf[5];
+  // Check for ServerHello
+  if (handshake_type == 2) {
+    return kResponse;
+  }
+  // Check for ClientHello
+  if (handshake_type == 1) {
+    return kRequest;
+  }
+
+  return kUnknown;
+}
+
 // Cassandra frame:
 //      0         8        16        24        32         40
 //      +---------+---------+---------+---------+---------+
@@ -699,7 +739,16 @@ static __inline struct protocol_message_t infer_protocol(const char* buf, size_t
   //               role by considering which side called accept() vs connect(). Once the clean-up
   //               above is done, the code below can be turned into a chained ternary.
   // PROTOCOL_LIST: Requires update on new protocols.
-  if (ENABLE_HTTP_TRACING && (inferred_message.type = infer_http_message(buf, count)) != kUnknown) {
+  //
+  // TODO(ddelnano): TLS tracing should be handled differently in the future as we want to be able
+  // to trace the handshake and the application data separately (gh#2095). The current connection
+  // tracker model only works with one or the other, meaning if TLS tracing is enabled, tracing the
+  // plaintext within an encrypted conn will not work. ENABLE_TLS_TRACING will default to false
+  // until this is revisted.
+  if (ENABLE_TLS_TRACING && (inferred_message.type = infer_tls_message(buf, count)) != kUnknown) {
+    inferred_message.protocol = kProtocolTLS;
+  } else if (ENABLE_HTTP_TRACING &&
+             (inferred_message.type = infer_http_message(buf, count)) != kUnknown) {
     inferred_message.protocol = kProtocolHTTP;
   } else if (ENABLE_CQL_TRACING &&
              (inferred_message.type = infer_cql_message(buf, count)) != kUnknown) {

src/stirling/source_connectors/socket_tracer/bcc_bpf/protocol_inference_test.cc

@@ -482,3 +482,27 @@ TEST(ProtocolInferenceTest, AMQPResponse) {
   EXPECT_EQ(protocol_message.protocol, kProtocolAMQP);
   EXPECT_EQ(protocol_message.type, kResponse);
 }
+
+TEST(ProtocolInferenceTest, TLSRequest) {
+  struct conn_info_t conn_info = {};
+  // TLS Client Hello
+  constexpr uint8_t kReqFrame[] = {
+      0x16, 0x03, 0x01, 0x00, 0x01, 0x01, 0x00, 0x01, 0xfc, 0x03, 0x03, 0x7b, 0x7b, 0x7b,
+  };
+  auto protocol_message =
+      infer_protocol(reinterpret_cast<const char*>(kReqFrame), sizeof(kReqFrame), &conn_info);
+  EXPECT_EQ(protocol_message.protocol, kProtocolTLS);
+  EXPECT_EQ(protocol_message.type, kRequest);
+}
+
+TEST(ProtocolInferenceTest, TLSResponse) {
+  struct conn_info_t conn_info = {};
+  // TLS Server Hello
+  constexpr uint8_t kRespFrame[] = {
+      0x16, 0x03, 0x01, 0x00, 0x01, 0x02, 0x00, 0x00, 0xfc, 0x03, 0x03, 0x7b, 0x7b, 0x7b,
+  };
+  auto protocol_message =
+      infer_protocol(reinterpret_cast<const char*>(kRespFrame), sizeof(kRespFrame), &conn_info);
+  EXPECT_EQ(protocol_message.protocol, kProtocolTLS);
+  EXPECT_EQ(protocol_message.type, kResponse);
+}

src/stirling/source_connectors/socket_tracer/bcc_bpf_intf/common.h

@@ -51,6 +51,7 @@ enum traffic_protocol_t {
   kProtocolKafka = 10,
   kProtocolMux = 11,
   kProtocolAMQP = 12,
+  kProtocolTLS = 13,
 // We use magic enum to iterate through protocols in C++ land,
 // and don't want the C-enum-size trick to show up there.
 #ifndef __cplusplus

src/stirling/source_connectors/socket_tracer/conn_tracker.cc

@@ -674,6 +674,7 @@ auto CreateTraceRoles() {
   res.Set(kProtocolKafka, {kRoleServer});
   res.Set(kProtocolMux, {kRoleServer});
   res.Set(kProtocolAMQP, {kRoleServer});
+  res.Set(kProtocolTLS, {kRoleServer});
 
   DCHECK(res.AreAllKeysSet());
   return res;

src/stirling/source_connectors/socket_tracer/data_stream.cc

@@ -215,6 +215,10 @@ template void DataStream::ProcessBytesToFrames<protocols::amqp::channel_id, prot
 template void DataStream::ProcessBytesToFrames<
     protocols::mongodb::stream_id_t, protocols::mongodb::Frame, protocols::mongodb::StateWrapper>(
     message_type_t type, protocols::mongodb::StateWrapper* state);
+
+template void DataStream::ProcessBytesToFrames<protocols::tls::stream_id_t, protocols::tls::Frame,
+                                               protocols::NoState>(message_type_t type,
+                                                                   protocols::NoState* state);
 void DataStream::Reset() {
   data_buffer_.Reset();
   has_new_events_ = false;

src/stirling/source_connectors/socket_tracer/protocols/BUILD.bazel

@@ -46,5 +46,6 @@ pl_cc_library(
         "//src/stirling/source_connectors/socket_tracer/protocols/nats:cc_library",
         "//src/stirling/source_connectors/socket_tracer/protocols/pgsql:cc_library",
         "//src/stirling/source_connectors/socket_tracer/protocols/redis:cc_library",
+        "//src/stirling/source_connectors/socket_tracer/protocols/tls:cc_library",
     ],
 )