feat(qemu): add QEMU_NET_CIDR to override SLIRP internal network (#2564)

## What

Add an opt-in QEMU_NET_CIDR environment variable that overrides SLIRP's
default internal network (10.0.2.0/24) by appending net=<cidr> to the
SLIRP netdev args. Validates the input as a sane IPv4 CIDR with prefix
length between 8 and 30.

## Why

SLIRP user-mode networking treats its default 10.0.2.0/24 network as
part of its own NAT space. When the host needs to reach VPC-internal
addresses that fall within the 10.0.0.0/8 range (e.g., a Private Service
Connect endpoint at 10.10.0.108), SLIRP may not forward those
connections to the host's network stack, causing the guest VM to time
out.

Setting QEMU_NET_CIDR to a non-conflicting range (e.g., 192.168.76.0/24)
moves SLIRP's internal NAT off the 10.x.x.x space so 10.x.x.x addresses
route through the host normally.

## Notes

- Opt-in via environment variable; default behavior unchanged.
- Follows the existing QEMU_DNS_SEARCH pattern for env-driven netdev
  configuration.
- Input validation rejects IPv6, prefixes outside [8, 30], and any
  injection attempts via embedded commas or whitespace.

Signed-off-by: jmeridth <jmeridth@gmail.com>

Author: jmeridth

pkg/container/qemu_runner.go

@@ -798,6 +798,22 @@ func createMicroVM(ctx context.Context, cfg *Config) error {
 	baseargs = append(baseargs, serialArgs...)
 	// use -netdev + -device instead of -nic, as this is better supported by microvm machine type
 	netdevArgs := "user,id=id1,hostfwd=tcp:" + cfg.SSHAddress + "-:22,hostfwd=tcp:" + cfg.SSHControlAddress + "-:2223"
+	// QEMU_NET_CIDR overrides SLIRP's default internal network (10.0.2.0/24).
+	// This is necessary when the host needs to reach VPC-internal addresses
+	// that fall within the 10.0.0.0/8 range, since SLIRP treats its default
+	// network as part of its own NAT space and may not correctly forward
+	// connections to other 10.x.x.x addresses on the host's network.
+	// The value must be a valid IPv4 CIDR. SLIRP automatically assigns the
+	// gateway, DNS, and DHCP range based on the supplied network.
+	// Example: QEMU_NET_CIDR="192.168.76.0/24"
+	if netCIDR, ok := os.LookupEnv("QEMU_NET_CIDR"); ok {
+		cidr, err := parseAndValidateNetCIDR(netCIDR)
+		if err != nil {
+			return fmt.Errorf("invalid QEMU_NET_CIDR value %q: %w", netCIDR, err)
+		}
+		log.Infof("qemu: QEMU_NET_CIDR set to %s, overriding SLIRP default network", cidr)
+		netdevArgs += ",net=" + cidr
+	}
 	// QEMU_DNS_SEARCH allows configuring DNS search domains inside the guest VM.
 	// This is useful for builds that need to resolve short hostnames via search
 	// domains, or when the build environment requires specific DNS resolution
@@ -2543,6 +2559,36 @@ func parseDNSSearchDomains(input string) ([]string, error) {
 	return domains, nil
 }
 
+// parseAndValidateNetCIDR validates an IPv4 CIDR string for use as the SLIRP
+// internal network. The CIDR must be a valid IPv4 network with a prefix length
+// between 8 and 30 (SLIRP requires at least 4 usable addresses). The input is
+// returned unchanged on success so it can be passed directly to SLIRP.
+func parseAndValidateNetCIDR(input string) (string, error) {
+	input = strings.TrimSpace(input)
+	if input == "" {
+		return "", fmt.Errorf("empty CIDR")
+	}
+
+	ip, ipnet, err := net.ParseCIDR(input)
+	if err != nil {
+		return "", fmt.Errorf("parse CIDR: %w", err)
+	}
+
+	if ip.To4() == nil {
+		return "", fmt.Errorf("CIDR must be IPv4")
+	}
+
+	ones, bits := ipnet.Mask.Size()
+	if bits != 32 {
+		return "", fmt.Errorf("CIDR must be IPv4 (got %d-bit mask)", bits)
+	}
+	if ones < 8 || ones > 30 {
+		return "", fmt.Errorf("CIDR prefix length must be between 8 and 30 (got /%d)", ones)
+	}
+
+	return ipnet.String(), nil
+}
+
 // buildDNSSearchNetdevArgs constructs the QEMU netdev dnssearch options string.
 // Returns empty string if no domains provided.
 // Each domain produces a separate ",dnssearch=<domain>" option.

pkg/container/qemu_runner_test.go

@@ -492,6 +492,90 @@ func TestBuildDNSSearchNetdevArgs(t *testing.T) {
 	}
 }
 
+func TestParseAndValidateNetCIDR(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+		wantErr  bool
+	}{
+		{
+			name:     "valid /24",
+			input:    "192.168.76.0/24",
+			expected: "192.168.76.0/24",
+		},
+		{
+			name:     "valid /16",
+			input:    "192.168.0.0/16",
+			expected: "192.168.0.0/16",
+		},
+		{
+			name:     "non-zero host bits normalized",
+			input:    "192.168.76.5/24",
+			expected: "192.168.76.0/24",
+		},
+		{
+			name:     "whitespace trimmed",
+			input:    "  192.168.76.0/24  ",
+			expected: "192.168.76.0/24",
+		},
+		{
+			name:    "empty",
+			input:   "",
+			wantErr: true,
+		},
+		{
+			name:    "not a CIDR",
+			input:   "192.168.76.0",
+			wantErr: true,
+		},
+		{
+			name:    "garbage",
+			input:   "not-a-cidr",
+			wantErr: true,
+		},
+		{
+			name:    "IPv6",
+			input:   "fd00::/64",
+			wantErr: true,
+		},
+		{
+			name:    "prefix too short",
+			input:   "10.0.0.0/7",
+			wantErr: true,
+		},
+		{
+			name:    "prefix too long",
+			input:   "192.168.76.0/31",
+			wantErr: true,
+		},
+		{
+			name:    "injection via comma",
+			input:   "192.168.76.0/24,dnssearch=evil.com",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := parseAndValidateNetCIDR(tt.input)
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("parseAndValidateNetCIDR(%q) expected error, got nil with result %q", tt.input, result)
+				}
+				return
+			}
+			if err != nil {
+				t.Errorf("parseAndValidateNetCIDR(%q) unexpected error: %v", tt.input, err)
+				return
+			}
+			if result != tt.expected {
+				t.Errorf("parseAndValidateNetCIDR(%q) = %q, expected %q", tt.input, result, tt.expected)
+			}
+		})
+	}
+}
+
 func TestGetPackageCacheSuffix(t *testing.T) {
 	tests := []struct {
 		name     string