feat: add user-defined NetworkNeighborhood support

Add support for user-defined NetworkNeighborhood profiles that allow
pre-configured network policies without requiring a learning phase.

Changes:
- Load user-defined NN in container lifecycle (lifecycle.go)
- NN cache support for user-defined profiles (networkneighborhoodcache.go)
- SharedContainerData: add UserDefinedNetwork field
- Enable R0005 (DNS Anomalies) and R0011 (Unexpected Egress) alert triggers
- Component tests: Test_27 (wildcard AP matching) and Test_28 (user-defined NN alerts)
- Test resources: known profiles, deployment YAMLs, helper scripts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: entlein <einentlein@gmail.com>

Author: entlein

pkg/containerprofilemanager/v1/lifecycle.go

@@ -92,14 +92,17 @@ func (cpm *ContainerProfileManager) addContainer(container *containercollection.
 		return fmt.Errorf("failed to get shared data for container %s: %w", containerID, err)
 	}
 
-	// Check if the container should use a user-defined profile
+	// Check if the container should use a user-defined profile.
+	// When both an ApplicationProfile and a NetworkNeighborhood are
+	// user-provided, skip ALL recording — there is nothing to learn.
 	if sharedData.UserDefinedProfile != "" {
 		logger.L().Debug("ignoring container with a user-defined profile",
 			helpers.String("containerID", containerID),
 			helpers.String("containerName", container.Runtime.ContainerName),
 			helpers.String("podName", container.K8s.PodName),
 			helpers.String("namespace", container.K8s.Namespace),
-			helpers.String("userDefinedProfile", sharedData.UserDefinedProfile))
+			helpers.String("userDefinedProfile", sharedData.UserDefinedProfile),
+			helpers.String("userDefinedNetwork", sharedData.UserDefinedNetwork))
 		// Close ready channel before removing entry
 		if entry, exists := cpm.getContainerEntry(containerID); exists {
 			entry.readyOnce.Do(func() {

pkg/objectcache/networkneighborhoodcache/networkneighborhoodcache.go

@@ -30,6 +30,7 @@ type ContainerInfo struct {
 	InstanceTemplateHash      string
 	Namespace                 string
 	SeenContainerFromTheStart bool // True if container was seen from the start
+	UserDefinedNetwork        string // Non-empty when pod has a user-defined NN label
 }
 
 // NetworkNeighborhoodCacheImpl implements the NetworkNeighborhoodCache interface
@@ -204,6 +205,13 @@ func (nnc *NetworkNeighborhoodCacheImpl) updateAllNetworkNeighborhoods(ctx conte
 				continue
 			}
 
+			// Never overwrite a user-defined network neighborhood with an
+			// auto-learned one.  Check if any container for this workload
+			// has a user-defined-network label.
+			if nnc.workloadHasUserDefinedNetwork(workloadID) {
+				continue
+			}
+
 			// If we have a "new" container (seen from start) and the network neighborhood is partial,
 			// skip it - we don't want to use partial profiles for containers we're tracking from the start
 			if hasNewContainer && nn.Annotations[helpersv1.CompletionMetadataKey] == helpersv1.Partial {
@@ -419,11 +427,48 @@ func (nnc *NetworkNeighborhoodCacheImpl) addContainer(container *containercollec
 			InstanceTemplateHash:      sharedData.InstanceID.GetTemplateHash(),
 			Namespace:                 container.K8s.Namespace,
 			SeenContainerFromTheStart: !sharedData.PreRunningContainer,
+			UserDefinedNetwork:        sharedData.UserDefinedNetwork,
 		}
 
 		// Add to container info map
 		nnc.containerIDToInfo.Set(containerID, containerInfo)
 
+		// If the container has a user-defined network neighborhood, load it
+		// directly into the cache — skip learning entirely for this workload.
+		if sharedData.UserDefinedNetwork != "" {
+			fullNN, err := nnc.storageClient.GetNetworkNeighborhood(
+				container.K8s.Namespace, sharedData.UserDefinedNetwork)
+			if err != nil {
+				logger.L().Error("failed to get user-defined network neighborhood",
+					helpers.String("containerID", containerID),
+					helpers.String("workloadID", workloadID),
+					helpers.String("namespace", container.K8s.Namespace),
+					helpers.String("nnName", sharedData.UserDefinedNetwork),
+					helpers.Error(err))
+				profileState := &objectcache.ProfileState{
+					Error: err,
+				}
+				nnc.workloadIDToProfileState.Set(workloadID, profileState)
+				return nil
+			}
+
+			nnc.workloadIDToNetworkNeighborhood.Set(workloadID, fullNN)
+			profileState := &objectcache.ProfileState{
+				Completion: helpersv1.Full,
+				Status:     helpersv1.Completed,
+				Name:       fullNN.Name,
+				Error:      nil,
+			}
+			nnc.workloadIDToProfileState.Set(workloadID, profileState)
+
+			logger.L().Debug("added user-defined network neighborhood to cache",
+				helpers.String("containerID", containerID),
+				helpers.String("workloadID", workloadID),
+				helpers.String("namespace", container.K8s.Namespace),
+				helpers.String("nnName", sharedData.UserDefinedNetwork))
+			return nil
+		}
+
 		// Create workload ID to state mapping
 		if _, exists := nnc.workloadIDToProfileState.Load(workloadID); !exists {
 			nnc.workloadIDToProfileState.Set(workloadID, nil)
@@ -718,6 +763,20 @@ func (nnc *NetworkNeighborhoodCacheImpl) mergeNetworkPorts(normalPorts, userPort
 	return normalPorts
 }
 
+// workloadHasUserDefinedNetwork returns true if any container tracked for
+// the given workloadID has a user-defined-network label set.
+func (nnc *NetworkNeighborhoodCacheImpl) workloadHasUserDefinedNetwork(workloadID string) bool {
+	found := false
+	nnc.containerIDToInfo.Range(func(_ string, info *ContainerInfo) bool {
+		if info.WorkloadID == workloadID && info.UserDefinedNetwork != "" {
+			found = true
+			return false // stop iteration
+		}
+		return true
+	})
+	return found
+}
+
 func isUserManagedNN(nn *v1beta1.NetworkNeighborhood) bool {
 	return nn.Annotations != nil &&
 		nn.Annotations[helpersv1.ManagedByMetadataKey] == helpersv1.ManagedByUserValue &&

pkg/objectcache/shared_container_data.go

@@ -20,6 +20,11 @@ import (
 	"k8s.io/apimachinery/pkg/util/validation"
 )
 
+// UserDefinedNetworkMetadataKey is the pod label that references a
+// user-provided NetworkNeighborhood resource by name (analogous to
+// helpersv1.UserDefinedProfileMetadataKey for ApplicationProfiles).
+const UserDefinedNetworkMetadataKey = "kubescape.io/user-defined-network"
+
 type ContainerType int
 
 const (
@@ -82,6 +87,7 @@ type WatchedContainerData struct {
 	PreviousReportTimestamp time.Time
 	CurrentReportTimestamp  time.Time
 	UserDefinedProfile      string
+	UserDefinedNetwork      string
 }
 
 type ContainerInfo struct {
@@ -167,6 +173,16 @@ func (watchedContainer *WatchedContainerData) SetContainerInfo(wl workloadinterf
 			watchedContainer.UserDefinedProfile = userDefinedProfile
 		}
 	}
+	// check for user defined network neighborhood
+	if userDefinedNetwork, ok := labels[UserDefinedNetworkMetadataKey]; ok {
+		if userDefinedNetwork != "" {
+			logger.L().Info("container has a user defined network neighborhood",
+				helpers.String("network", userDefinedNetwork),
+				helpers.String("container", containerName),
+				helpers.String("workload", wl.GetName()))
+			watchedContainer.UserDefinedNetwork = userDefinedNetwork
+		}
+	}
 	podSpec, err := wl.GetPodSpec()
 	if err != nil {
 		return fmt.Errorf("failed to get pod spec: %w", err)

tests/chart/templates/node-agent/default-rules.yaml

@@ -122,7 +122,7 @@ spec:
         profileDependency: 0
         severity: 1
         supportPolicy: false
-        isTriggerAlert: false
+        isTriggerAlert: true
         mitreTactic: "TA0011"
         mitreTechnique: "T1071.004"
         tags:
@@ -245,7 +245,7 @@ spec:
           - "anomaly"
           - "applicationprofile"
       - name: "Unexpected Egress Network Traffic"
-        enabled: false
+        enabled: true
         id: "R0011"
         description: "Detecting unexpected egress network traffic that is not whitelisted by application profile."
         expressions:
@@ -257,7 +257,7 @@ spec:
         profileDependency: 0
         severity: 5 # Medium
         supportPolicy: false
-        isTriggerAlert: false
+        isTriggerAlert: true
         mitreTactic: "TA0010"
         mitreTechnique: "T1041"
         tags: