[CWS] Introduce CWS Network Flow Monitor

DataDog · Dec 18, 2024 · a5253a0 · a5253a0
1 parent 52f0517
commit a5253a0
Show file tree

Hide file tree

Showing 93 changed files with 5,956 additions and 1,957 deletions.
diff --git a/cmd/security-agent/subcommands/runtime/security_profile.go b/cmd/security-agent/subcommands/runtime/security_profile.go
@@ -158,6 +158,9 @@ func printActivityTreeStats(prefix string, msg *api.ActivityTreeStatsMessage) {
 	fmt.Printf("%s    file_nodes_count: %v\n", prefix, msg.GetFileNodesCount())
 	fmt.Printf("%s    dns_nodes_count: %v\n", prefix, msg.GetDNSNodesCount())
 	fmt.Printf("%s    socket_nodes_count: %v\n", prefix, msg.GetSocketNodesCount())
+	fmt.Printf("%s    imds_nodes_count: %v\n", prefix, msg.GetIMDSNodesCount())
+	fmt.Printf("%s    syscall_nodes_count: %v\n", prefix, msg.GetSyscallNodesCount())
+	fmt.Printf("%s    flow_nodes_count: %v\n", prefix, msg.GetFlowNodesCount())
 }
 
 func printSecurityProfileMessage(msg *api.SecurityProfileMessage) {

diff --git a/docs/cloud-workload-security/backend_linux.schema.json b/docs/cloud-workload-security/backend_linux.schema.json
@@ -605,6 +605,43 @@
       ],
       "description": "FileEventSerializer serializes a file event to JSON"
     },
+    "Flow": {
+      "properties": {
+        "l3_protocol": {
+          "type": "string",
+          "description": "l3_protocol is the layer 3 protocol name"
+        },
+        "l4_protocol": {
+          "type": "string",
+          "description": "l4_protocol is the layer 4 protocol name"
+        },
+        "source": {
+          "$ref": "#/$defs/IPPort",
+          "description": "source is the emitter of the network event"
+        },
+        "destination": {
+          "$ref": "#/$defs/IPPort",
+          "description": "destination is the receiver of the network event"
+        },
+        "ingress": {
+          "$ref": "#/$defs/NetworkStats",
+          "description": "ingress holds the network statistics for ingress traffic"
+        },
+        "egress": {
+          "$ref": "#/$defs/NetworkStats",
+          "description": "egress holds the network statistics for egress traffic"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object",
+      "required": [
+        "l3_protocol",
+        "l4_protocol",
+        "source",
+        "destination"
+      ],
+      "description": "FlowSerializer defines a new flow serializer"
+    },
     "IMDSEvent": {
       "properties": {
         "type": {
@@ -889,6 +926,10 @@
         "size": {
           "type": "integer",
           "description": "size is the size in bytes of the network event"
+        },
+        "network_direction": {
+          "type": "string",
+          "description": "network_direction indicates if the packet was captured on ingress or egress"
         }
       },
       "additionalProperties": false,
@@ -898,7 +939,8 @@
         "l4_protocol",
         "source",
         "destination",
-        "size"
+        "size",
+        "network_direction"
       ],
       "description": "NetworkContextSerializer serializes the network context to JSON"
     },
@@ -926,6 +968,43 @@
       ],
       "description": "NetworkDeviceSerializer serializes the network device context to JSON"
     },
+    "NetworkFlowMonitor": {
+      "properties": {
+        "device": {
+          "$ref": "#/$defs/NetworkDevice",
+          "description": "device is the network device on which the event was captured"
+        },
+        "flows_count": {
+          "type": "integer",
+          "description": "flows_count holds the count of flows for this event"
+        },
+        "flows": {
+          "items": {
+            "$ref": "#/$defs/Flow"
+          },
+          "type": "array",
+          "description": "flows is the list of flows with network statistics that were captured"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object",
+      "description": "NetworkFlowMonitorSerializer defines a network monitor event serializer"
+    },
+    "NetworkStats": {
+      "properties": {
+        "data_size": {
+          "type": "integer",
+          "description": "data_size is the total count of bytes sent or received"
+        },
+        "packet_count": {
+          "type": "integer",
+          "description": "packet_count is the total count of packets sent or received"
+        }
+      },
+      "additionalProperties": false,
+      "type": "object",
+      "description": "NetworkStatsSerializer defines a new network stats serializer"
+    },
     "PTraceEvent": {
       "properties": {
         "request": {
@@ -1359,6 +1438,10 @@
           "type": "integer",
           "description": "size is the size in bytes of the network event"
         },
+        "network_direction": {
+          "type": "string",
+          "description": "network_direction indicates if the packet was captured on ingress or egress"
+        },
         "tls": {
           "$ref": "#/$defs/TLSContext"
         }
@@ -1370,7 +1453,8 @@
         "l4_protocol",
         "source",
         "destination",
-        "size"
+        "size",
+        "network_direction"
       ],
       "description": "RawPacketSerializer defines a raw packet serializer"
     },
@@ -1769,6 +1853,9 @@
     },
     "packet": {
       "$ref": "#/$defs/RawPacket"
+    },
+    "network_flow_monitor": {
+      "$ref": "#/$defs/NetworkFlowMonitor"
     }
   },
   "additionalProperties": false,

diff --git a/docs/cloud-workload-security/linux_expressions.md b/docs/cloud-workload-security/linux_expressions.md
@@ -550,6 +550,7 @@ A DNS request was sent
 | [`network.device.ifname`](#common-networkdevicecontext-ifname-doc) | Interface ifname |
 | [`network.l3_protocol`](#common-networkcontext-l3_protocol-doc) | L3 protocol of the network packet |
 | [`network.l4_protocol`](#common-networkcontext-l4_protocol-doc) | L4 protocol of the network packet |
+| [`network.network_direction`](#common-networkcontext-network_direction-doc) | Network direction of the network packet |
 | [`network.size`](#common-networkcontext-size-doc) | Size in bytes of the network packet |
 | [`network.source.ip`](#common-ipportcontext-ip-doc) | IP address |
 | [`network.source.is_public`](#common-ipportcontext-is_public-doc) | Whether the IP address belongs to a public network |
@@ -756,6 +757,7 @@ An IMDS event was captured
 | [`network.device.ifname`](#common-networkdevicecontext-ifname-doc) | Interface ifname |
 | [`network.l3_protocol`](#common-networkcontext-l3_protocol-doc) | L3 protocol of the network packet |
 | [`network.l4_protocol`](#common-networkcontext-l4_protocol-doc) | L4 protocol of the network packet |
+| [`network.network_direction`](#common-networkcontext-network_direction-doc) | Network direction of the network packet |
 | [`network.size`](#common-networkcontext-size-doc) | Size in bytes of the network packet |
 | [`network.source.ip`](#common-ipportcontext-ip-doc) | IP address |
 | [`network.source.is_public`](#common-ipportcontext-is_public-doc) | Whether the IP address belongs to a public network |
@@ -977,6 +979,7 @@ A raw network packet captured
 | [`packet.filter`](#packet-filter-doc) | pcap filter expression |
 | [`packet.l3_protocol`](#common-networkcontext-l3_protocol-doc) | L3 protocol of the network packet |
 | [`packet.l4_protocol`](#common-networkcontext-l4_protocol-doc) | L4 protocol of the network packet |
+| [`packet.network_direction`](#common-networkcontext-network_direction-doc) | Network direction of the network packet |
 | [`packet.size`](#common-networkcontext-size-doc) | Size in bytes of the network packet |
 | [`packet.source.ip`](#common-ipportcontext-ip-doc) | IP address |
 | [`packet.source.is_public`](#common-ipportcontext-is_public-doc) | Whether the IP address belongs to a public network |
@@ -2311,6 +2314,18 @@ exec.file.name == "apt"
 
 Matches the execution of any file named apt.
 
+### `*.network_direction` {#common-networkcontext-network_direction-doc}
+Type: int
+
+Definition: Network direction of the network packet
+
+`*.network_direction` has 2 possible prefixes:
+`network` `packet`
+
+Constants: [Network directions](#network-directions)
+
+
+
 ### `*.package.name` {#common-fileevent-package-name-doc}
 Type: string
 
@@ -4236,6 +4251,14 @@ Network Address Family constants are the supported network address families.
 | `AF_XDP` | all |
 | `AF_MAX` | all |
 
+### `Network directions` {#network-directions}
+Network directions are the supported directions of network packets.
+
+| Name | Architectures |
+| ---- |---------------|
+| `INGRESS` | all |
+| `EGRESS` | all |
+
 ### `Open flags` {#open-flags}
 Open flags are the supported flags for the open syscall.