[client,management] add netflow support to client and update management (#3414)

adds NetFlow functionality to track and log network traffic information between peers, with features including: - Flow logging for TCP, UDP, and ICMP traffic - Integration with connection tracking system - Resource ID tracking in NetFlow events - DNS and exit node collection configuration - Flow API and Redis cache in management - Memory-based flow storage implementation - Kernel conntrack counters and userspace counters - TCP state machine improvements for more accurate tracking - Migration from net.IP to netip.Addr in the userspace firewall
2026-04-20 17:26:40 +00:00 · 2025-03-20 17:05:48 +01:00
parent f51e0b59bd
commit c02e236196
151 changed files with 7118 additions and 2234 deletions
--- a/management/server/http/api/openapi.yml
+++ b/management/server/http/api/openapi.yml
@@ -106,6 +106,18 @@ components:
          description: (Cloud only) Enables or disables peer approval globally. If enabled, all peers added will be in pending state until approved by an admin.
          type: boolean
          example: true
+        network_traffic_logs_enabled:
+          description: Enables or disables network traffic logs. If enabled, all network traffic logs from peers will be stored.
+          type: boolean
+          example: true
+        network_traffic_packet_counter_enabled:
+          description: Enables or disables network traffic packet counter. If enabled, network packets and their size will be counted and reported. (This can have an slight impact on performance)
+          type: boolean
+          example: true
+      required:
+        - peer_approval_enabled
+        - network_traffic_logs_enabled
+        - network_traffic_packet_counter_enabled
    AccountRequest:
      type: object
      properties:
@@ -1817,6 +1829,137 @@ components:
        - ingress_start
        - ingress_end
        - protocol
+    NetworkTrafficLocation:
+      type: object
+      properties:
+        city_name:
+          type: string
+          description: "Name of the city (if known)."
+        country_code:
+          type: string
+          description: "ISO country code (if known)."
+      required:
+        - city_name
+        - country_code
+    NetworkTrafficEndpoint:
+      type: object
+      properties:
+        id:
+          type: string
+          description: "ID of this endpoint (e.g., peer ID or resource ID)."
+        type:
+          type: string
+          description: "Type of the endpoint object (e.g., UNKNOWN, PEER, HOST_RESOURCE)."
+        name:
+          type: string
+          description: "Name is the name of the endpoint object (e.g., a peer name)."
+        geo_location:
+          $ref: '#/components/schemas/NetworkTrafficLocation'
+        os:
+          type: string
+          nullable: true
+          description: "Operating system of the peer, if applicable."
+        address:
+          type: string
+          description: "IP address (and possibly port) in string form."
+          example: "100.64.0.10:51820"
+        dns_label:
+          type: string
+          nullable: true
+          description: "DNS label/name if available."
+      required:
+        - id
+        - type
+        - name
+        - geo_location
+        - os
+        - address
+        - dns_label
+    NetworkTrafficEvent:
+      type: object
+      properties:
+        id:
+          type: string
+          description: "ID of the event. Unique."
+        flow_id:
+          type: string
+          description: "FlowID is the ID of the connection flow. Not unique because it can be the same for multiple events (e.g., start and end of the connection)."
+        reporter_id:
+          type: string
+          description: "ID of the reporter of the event (e.g., the peer that reported the event)."
+        timestamp:
+          type: string
+          format: date-time
+          description: "Timestamp of the event."
+        source:
+          $ref: '#/components/schemas/NetworkTrafficEndpoint'
+        user_id:
+          type: string
+          nullable: true
+          description: "UserID is the ID of the user that initiated the event (can be empty as not every event is user-initiated)."
+        user_email:
+          type: string
+          nullable: true
+          description: "Email of the user who initiated the event (if any)."
+        user_name:
+          type: string
+          nullable: true
+          description: "Name of the user who initiated the event (if any)."
+        destination:
+          $ref: '#/components/schemas/NetworkTrafficEndpoint'
+        protocol:
+          type: integer
+          description: "Protocol is the protocol of the traffic (e.g. 1 = ICMP, 6 = TCP, 17 = UDP, etc.)."
+        type:
+          type: string
+          description: "Type of the event (e.g. TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP)."
+        direction:
+          type: string
+          description: "Direction of the traffic (e.g. DIRECTION_UNKNOWN, INGRESS, EGRESS)."
+        rx_bytes:
+          type: integer
+          description: "Number of bytes received."
+        rx_packets:
+          type: integer
+          description: "Number of packets received."
+        tx_bytes:
+          type: integer
+          description: "Number of bytes transmitted."
+        tx_packets:
+          type: integer
+          description: "Number of packets transmitted."
+        policy_id:
+          type: string
+          description: "ID of the policy that allowed this event."
+        policy_name:
+          type: string
+          description: "Name of the policy that allowed this event."
+        icmp_type:
+          type: integer
+          description: "ICMP type (if applicable)."
+        icmp_code:
+          type: integer
+          description: "ICMP code (if applicable)."
+      required:
+        - id
+        - flow_id
+        - reporter_id
+        - timestamp
+        - source
+        - user_id
+        - user_email
+        - destination
+        - protocol
+        - type
+        - direction
+        - rx_bytes
+        - rx_packets
+        - tx_bytes
+        - tx_packets
+        - policy_id
+        - policy_name
+        - icmp_type
+        - icmp_code
  responses:
    not_found:
      description: Resource not found
@@ -3972,10 +4115,10 @@ paths:
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
-  /api/events:
+  /api/events/audit:
    get:
-      summary: List all Events
-      description: Returns a list of all events
+      summary: List all Audit Events
+      description: Returns a list of all audit events
      tags: [ Events ]
      security:
        - BearerAuth: [ ]
@@ -3997,6 +4140,26 @@ paths:
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
+  /api/events/network-traffic:
+    get:
+      summary: List all Network Traffic Events
+      description: Returns a list of all network traffic events
+      tags: [ Events ]
+      x-cloud-only: true
+      x-experimental: true
+      responses:
+        "200":
+          description: List of network traffic events
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/NetworkTrafficEvent"
+        "401":
+          $ref: "#/components/responses/requires_authentication"
+        "500":
+          $ref: "#/components/responses/internal_error"
  /api/posture-checks:
    get:
      summary: List all Posture Checks
--- a/management/server/http/api/types.gen.go
+++ b/management/server/http/api/types.gen.go
@@ -230,8 +230,14 @@ type Account struct {

 // AccountExtraSettings defines model for AccountExtraSettings.
 type AccountExtraSettings struct {
+	// NetworkTrafficLogsEnabled Enables or disables network traffic logs. If enabled, all network traffic logs from peers will be stored.
+	NetworkTrafficLogsEnabled bool `json:"network_traffic_logs_enabled"`
+
+	// NetworkTrafficPacketCounterEnabled Enables or disables network traffic packet counter. If enabled, network packets and their size will be counted and reported. (This can have an slight impact on performance)
+	NetworkTrafficPacketCounterEnabled bool `json:"network_traffic_packet_counter_enabled"`
+
 	// PeerApprovalEnabled (Cloud only) Enables or disables peer approval globally. If enabled, all peers added will be in pending state until approved by an admin.
-	PeerApprovalEnabled *bool `json:"peer_approval_enabled,omitempty"`
+	PeerApprovalEnabled bool `json:"peer_approval_enabled"`
 }

 // AccountRequest defines model for AccountRequest.
@@ -817,6 +823,97 @@ type NetworkRouterRequest struct {
 	PeerGroups *[]string `json:"peer_groups,omitempty"`
 }

+// NetworkTrafficEndpoint defines model for NetworkTrafficEndpoint.
+type NetworkTrafficEndpoint struct {
+	// Address IP address (and possibly port) in string form.
+	Address string `json:"address"`
+
+	// DnsLabel DNS label/name if available.
+	DnsLabel    *string                `json:"dns_label"`
+	GeoLocation NetworkTrafficLocation `json:"geo_location"`
+
+	// Id ID of this endpoint (e.g., peer ID or resource ID).
+	Id string `json:"id"`
+
+	// Name Name is the name of the endpoint object (e.g., a peer name).
+	Name string `json:"name"`
+
+	// Os Operating system of the peer, if applicable.
+	Os *string `json:"os"`
+
+	// Type Type of the endpoint object (e.g., UNKNOWN, PEER, HOST_RESOURCE).
+	Type string `json:"type"`
+}
+
+// NetworkTrafficEvent defines model for NetworkTrafficEvent.
+type NetworkTrafficEvent struct {
+	Destination NetworkTrafficEndpoint `json:"destination"`
+
+	// Direction Direction of the traffic (e.g. DIRECTION_UNKNOWN, INGRESS, EGRESS).
+	Direction string `json:"direction"`
+
+	// FlowId FlowID is the ID of the connection flow. Not unique because it can be the same for multiple events (e.g., start and end of the connection).
+	FlowId string `json:"flow_id"`
+
+	// IcmpCode ICMP code (if applicable).
+	IcmpCode int `json:"icmp_code"`
+
+	// IcmpType ICMP type (if applicable).
+	IcmpType int `json:"icmp_type"`
+
+	// Id ID of the event. Unique.
+	Id string `json:"id"`
+
+	// PolicyId ID of the policy that allowed this event.
+	PolicyId string `json:"policy_id"`
+
+	// PolicyName Name of the policy that allowed this event.
+	PolicyName string `json:"policy_name"`
+
+	// Protocol Protocol is the protocol of the traffic (e.g. 1 = ICMP, 6 = TCP, 17 = UDP, etc.).
+	Protocol int `json:"protocol"`
+
+	// ReporterId ID of the reporter of the event (e.g., the peer that reported the event).
+	ReporterId string `json:"reporter_id"`
+
+	// RxBytes Number of bytes received.
+	RxBytes int `json:"rx_bytes"`
+
+	// RxPackets Number of packets received.
+	RxPackets int                    `json:"rx_packets"`
+	Source    NetworkTrafficEndpoint `json:"source"`
+
+	// Timestamp Timestamp of the event.
+	Timestamp time.Time `json:"timestamp"`
+
+	// TxBytes Number of bytes transmitted.
+	TxBytes int `json:"tx_bytes"`
+
+	// TxPackets Number of packets transmitted.
+	TxPackets int `json:"tx_packets"`
+
+	// Type Type of the event (e.g. TYPE_UNKNOWN, TYPE_START, TYPE_END, TYPE_DROP).
+	Type string `json:"type"`
+
+	// UserEmail Email of the user who initiated the event (if any).
+	UserEmail *string `json:"user_email"`
+
+	// UserId UserID is the ID of the user that initiated the event (can be empty as not every event is user-initiated).
+	UserId *string `json:"user_id"`
+
+	// UserName Name of the user who initiated the event (if any).
+	UserName *string `json:"user_name"`
+}
+
+// NetworkTrafficLocation defines model for NetworkTrafficLocation.
+type NetworkTrafficLocation struct {
+	// CityName Name of the city (if known).
+	CityName string `json:"city_name"`
+
+	// CountryCode ISO country code (if known).
+	CountryCode string `json:"country_code"`
+}
+
 // OSVersionCheck Posture check for the version of operating system
 type OSVersionCheck struct {
 	// Android Posture check for the version of operating system