feat: add IP trace ID filter to Hubble CLI

This change introduces the ability to filter Hubble flows by IP trace ID directly
from the Hubble CLI.

The following changes are included:
- A new `--ip-trace-id` flag is added to the `hubble observe` command,
which can be specified multiple times to filter for multiple trace IDs.
- A new `IPTraceIDFilter` is implemented to perform the filtering logic based
onthe provided trace IDs.
- The `IPTraceIDFilter` is added to the list of default filters.
- The help text for the `hubble observe` command is updated to include the new flag.

Signed-off-by: Ben Bigdelle <bigdelle@google.com>

Author: Bigdelle

hubble/cmd/cli_test.go

@@ -8,6 +8,7 @@ import (
 	"context"
 	_ "embed"
 	"fmt"
+	"strings"
 	"testing"
 
 	"github.com/spf13/viper"
@@ -41,6 +42,12 @@ denylist:
     - '{"source_ip":["1.1.1.1"]}'
 `
 
+func normalizeNewlines(content string) string {
+	content = strings.ReplaceAll(content, "\r\n", "\n")
+	content = strings.ReplaceAll(content, "\r", "\n")
+	return content
+}
+
 func TestTestHubbleObserve(t *testing.T) {
 	tests := []struct {
 		name           string
@@ -116,7 +123,7 @@ Use "hubble [command] --help" for more information about a command.
 			cli.SetArgs(tt.args)
 			err := cli.Execute()
 			require.Equal(t, tt.expectErr, err)
-			output := b.String()
+			output := normalizeNewlines(b.String())
 			if tt.expectedOutput != "" {
 				assert.Equal(t, tt.expectedOutput, output, "expected output does not match")
 			}

hubble/cmd/observe/flows.go

@@ -420,6 +420,10 @@ func newFlowsCmdHelper(usage cmdUsage, vp *viper.Viper, ofilter *flowFilter) *co
 		"trace-id", ofilter,
 		"Show only flows which match this trace ID"))
 
+	filterFlags.Var(filterVar(
+		"ip-trace-id", ofilter,
+		"Show only flows which match this IP trace ID"))
+
 	filterFlags.Var(filterVar(
 		"from-fqdn", ofilter,
 		`Show all flows originating at the given fully qualified domain name (e.g. "*.cilium.io").`))

hubble/cmd/observe/flows_filter.go

@@ -514,6 +514,18 @@ func (of *flowFilter) set(f *filterTracker, name, val string, track bool) error
 			f.TraceId = append(f.GetTraceId(), val)
 		})
 
+	case "ip-trace-id":
+		if val == "0" {
+			return fmt.Errorf("invalid --ip-trace-id value; must be greater than 0")
+		}
+		traceID, err := strconv.ParseUint(val, 10, 64)
+		if err != nil {
+			return fmt.Errorf("invalid --ip-trace-id value: %w", err)
+		}
+		f.apply(func(f *flowpb.FlowFilter) {
+			f.IpTraceId = append(f.GetIpTraceId(), traceID)
+		})
+
 	case "verdict":
 		if wipe {
 			f.apply(func(f *flowpb.FlowFilter) {

hubble/cmd/observe/flows_filter_test.go

@@ -1129,6 +1129,55 @@ func TestCluster(t *testing.T) {
 	}
 }
 
+func TestIpTraceId(t *testing.T) {
+	tt := []struct {
+		name    string
+		flags   []string
+		filters []*flowpb.FlowFilter
+		err     string
+	}{
+		{
+			name:    "error",
+			flags:   []string{"--ip-trace-id", "0"},
+			filters: []*flowpb.FlowFilter{},
+			err:     "invalid --ip-trace-id value; must be greater than 0",
+		},
+		{
+			name:  "single",
+			flags: []string{"--ip-trace-id", "1"},
+			filters: []*flowpb.FlowFilter{
+				{IpTraceId: []uint64{1}},
+			},
+		},
+		{
+			name:  "multiple",
+			flags: []string{"--ip-trace-id", "1", "--ip-trace-id", "2"},
+			filters: []*flowpb.FlowFilter{
+				{IpTraceId: []uint64{1, 2}},
+			},
+		},
+	}
+	for _, tc := range tt {
+		t.Run(tc.name, func(t *testing.T) {
+			f := newFlowFilter()
+			cmd := newFlowsCmdWithFilter(viper.New(), f)
+			err := cmd.Flags().Parse(tc.flags)
+			if tc.err != "" {
+				require.Errorf(t, err, tc.err)
+				return
+			} else {
+				require.NoError(t, err)
+			}
+			assert.Nil(t, f.blacklist)
+			got := f.whitelist.flowFilters()
+			diff := cmp.Diff(tc.filters, got, cmpopts.IgnoreUnexported(flowpb.FlowFilter{}))
+			if diff != "" {
+				t.Errorf("mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}
+
 func TestCELExpression(t *testing.T) {
 	tt := []struct {
 		name    string

hubble/cmd/observe_help.txt

@@ -62,6 +62,7 @@ Filters Flags:
       --identity filter                     Show all flows related to an endpoint with the given security identity
       --interface filter                    Show all flows observed at the given interface name (e.g. eth0)
       --ip filter                           Show all flows originating or terminating at the given IP address. Each of the IPs can be specified as an exact match (e.g. '1.1.1.1') or as a CIDR range (e.g.'1.1.1.0/24').
+      --ip-trace-id filter                  Show only flows which match this IP trace ID
       --ip-version filter                   Show only IPv4, IPv6 flows or non IP flows (e.g. ARP packets) (ie: "none", "v4", "v6")
   -4, --ipv4 filter[=v4]                    Show only IPv4 flows
   -6, --ipv6 filter[=v6]                    Show only IPv6 flows
@@ -156,15 +157,15 @@ Server Flags:
       --request-timeout duration      Unary Request timeout. Only applies to non-streaming RPCs (ServerStatus, ListNodes, ListNamespaces). (default 12s)
       --server string                 Address of a Hubble server. Ignored when --input-file or --port-forward is provided. (default "localhost:4245")
       --timeout duration              Hubble server dialing timeout (default 5s)
-      --tls                           Specify that TLS must be used when establishing a connection to a Hubble server.
+      --tls                           Specify that TLS must be used when establishing a connection to a Hubble server.
                                       By default, TLS is only enabled if the server address starts with 'tls://'.
-      --tls-allow-insecure            Allows the client to skip verifying the server's certificate chain and host name.
-                                      This option is NOT recommended as, in this mode, TLS is susceptible to machine-in-the-middle attacks.
+      --tls-allow-insecure            Allows the client to skip verifying the server's certificate chain and host name.
+                                      This option is NOT recommended as, in this mode, TLS is susceptible to machine-in-the-middle attacks.
                                       See also the 'tls-server-name' option which allows setting the server name.
       --tls-ca-cert-files strings     Paths to custom Certificate Authority (CA) certificate files.The files must contain PEM encoded data.
-      --tls-client-cert-file string   Path to the public key file for the client certificate to connect to a Hubble server (implies TLS).
+      --tls-client-cert-file string   Path to the public key file for the client certificate to connect to a Hubble server (implies TLS).
                                       The file must contain PEM encoded data.
-      --tls-client-key-file string    Path to the private key file for the client certificate to connect a Hubble server (implies TLS).
+      --tls-client-key-file string    Path to the private key file for the client certificate to connect a Hubble server (implies TLS).
                                       The file must contain PEM encoded data.
       --tls-server-name string        Specify a server name to verify the hostname on the returned certificate (eg: 'instance.hubble-relay.cilium.io').
 

pkg/hubble/filters/filters.go

@@ -149,5 +149,6 @@ func DefaultFilters(log *slog.Logger) []OnBuildFilter {
 		&TrafficDirectionFilter{},
 		&CELExpressionFilter{log: log},
 		&NetworkInterfaceFilter{},
+		&IPTraceIDFilter{},
 	}
 }

pkg/hubble/filters/ip_tracing.go

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Authors of Hubble
+
+package filters
+
+import (
+	"context"
+	"slices"
+
+	flowpb "github.com/cilium/cilium/api/v1/flow"
+	v1 "github.com/cilium/cilium/pkg/hubble/api/v1"
+)
+
+func filterByIPTraceID(tids []uint64) FilterFunc {
+	return func(ev *v1.Event) bool {
+		trace := ev.GetFlow().GetIpTraceId().GetTraceId()
+		return slices.Contains(tids, trace)
+	}
+}
+
+// TraceIDFilter implements filtering based on IP trace IDs.
+type IPTraceIDFilter struct{}
+
+// OnBuildFilter builds a IP trace ID filter.
+func (t *IPTraceIDFilter) OnBuildFilter(_ context.Context, ff *flowpb.FlowFilter) ([]FilterFunc, error) {
+	var fs []FilterFunc
+	if ids := ff.GetIpTraceId(); len(ids) > 0 {
+		fs = append(fs, filterByIPTraceID(ids))
+	}
+	return fs, nil
+}

pkg/hubble/filters/ip_tracing_test.go

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright Authors of Hubble
+
+package filters
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	flowpb "github.com/cilium/cilium/api/v1/flow"
+	v1 "github.com/cilium/cilium/pkg/hubble/api/v1"
+)
+
+func TestIPTraceIDFilter(t *testing.T) {
+	ctx := context.Background()
+	tests := []struct {
+		name string
+		f    []*flowpb.FlowFilter
+		ev   *v1.Event
+		want bool
+	}{
+		{
+			name: "match_single_filter",
+			f: []*flowpb.FlowFilter{
+				{IpTraceId: []uint64{1}},
+			},
+			ev: &v1.Event{
+				Event: &flowpb.Flow{
+					IpTraceId: &flowpb.IPTraceID{
+						TraceId: 1,
+					},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "match_multiple_filters",
+			f: []*flowpb.FlowFilter{
+				{IpTraceId: []uint64{1}},
+				{IpTraceId: []uint64{2}},
+			},
+			ev: &v1.Event{
+				Event: &flowpb.Flow{
+					IpTraceId: &flowpb.IPTraceID{
+						TraceId: 2,
+					},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "no_filter",
+			ev: &v1.Event{
+				Event: &flowpb.Flow{
+					IpTraceId: &flowpb.IPTraceID{
+						TraceId: 1,
+					},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "mismatch",
+			f: []*flowpb.FlowFilter{
+				{IpTraceId: []uint64{1}},
+			},
+			ev: &v1.Event{
+				Event: &flowpb.Flow{
+					IpTraceId: &flowpb.IPTraceID{
+						TraceId: 2,
+					},
+				},
+			},
+			want: false,
+		},
+		{
+			name: "no_trace_id",
+			f: []*flowpb.FlowFilter{
+				{IpTraceId: []uint64{1}},
+			},
+			ev: &v1.Event{
+				Event: &flowpb.Flow{},
+			},
+			want: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fl, err := BuildFilterList(ctx, tt.f, []OnBuildFilter{&IPTraceIDFilter{}})
+			if err != nil {
+				t.Fatalf("Faile to build filter: %v", err)
+			}
+			assert.Equal(t, tt.want, fl.MatchOne(tt.ev))
+		})
+	}
+}