From e7a540ee3a624263eef26e90f3f76e3361b1ebea Mon Sep 17 00:00:00 2001 From: codex Date: Fri, 23 Oct 2026 03:01:32 +0800 Subject: [PATCH] feat(agent): pin VM filters to assigned IPs --- agent/hypervisor/domain_xml.go | 50 ++++++++++++++++- agent/hypervisor/domain_xml_test.go | 56 +++++++++++++++++++ agent/hypervisor/libvirt_adapter.go | 3 +- agent/hypervisor/libvirt_domain_features.go | 21 +++++++ .../hypervisor/libvirt_reconcile_features.go | 4 +- agent/hypervisor/libvirt_safety_test.go | 6 +- docs/AGENT_API.md | 1 + docs/DEPLOYMENT.md | 1 + 8 files changed, 138 insertions(+), 4 deletions(-) diff --git a/agent/hypervisor/domain_xml.go b/agent/hypervisor/domain_xml.go index eeb0d526..497977f8 100644 --- a/agent/hypervisor/domain_xml.go +++ b/agent/hypervisor/domain_xml.go @@ -159,7 +159,11 @@ func BuildDomainXML(definition DomainDefinition) (string, error) { } } if definition.FilterName != "" { - iface.FilterRef = &libvirtxml.DomainInterfaceFilterRef{Filter: definition.FilterName} + filterRef, err := newManagedInterfaceFilterRef(definition.FilterName, definition.PublicIPCIDR) + if err != nil { + return "", err + } + iface.FilterRef = filterRef } if attachment.MAC != "" { iface.MAC = &libvirtxml.DomainInterfaceMAC{Address: strings.ToLower(attachment.MAC)} @@ -178,6 +182,50 @@ func BuildDomainXML(definition DomainDefinition) (string, error) { return document, nil } +const managedInterfaceIPParameter = "IP" + +func newManagedInterfaceFilterRef(filterName, publicIPCIDR string) (*libvirtxml.DomainInterfaceFilterRef, error) { + address, err := publicIPv4Address(publicIPCIDR) + if err != nil { + return nil, err + } + return &libvirtxml.DomainInterfaceFilterRef{ + Filter: filterName, + Parameters: []libvirtxml.DomainInterfaceFilterParam{{ + Name: managedInterfaceIPParameter, Value: address, + }}, + }, nil +} + +func publicIPv4Address(publicIPCIDR string) (string, error) { + prefix, err := netip.ParsePrefix(publicIPCIDR) + if err != nil || !prefix.Addr().Is4() { + return "", NewError(ErrInvalid, "invalid_public_ip", "public_ip_cidr must contain an IPv4 address and prefix", err) + } + return prefix.Addr().String(), nil +} + +func managedInterfaceFilterIPMatches(iface *libvirtxml.DomainInterface, filterName, publicIPCIDR string) bool { + address, err := publicIPv4Address(publicIPCIDR) + if err != nil || iface == nil || iface.FilterRef == nil || iface.FilterRef.Filter != filterName || len(iface.FilterRef.Parameters) != 1 { + return false + } + parameter := iface.FilterRef.Parameters[0] + return parameter.Name == managedInterfaceIPParameter && parameter.Value == address +} + +func updateManagedInterfaceFilterIP(iface *libvirtxml.DomainInterface, filterName, currentIPCIDR, targetIPCIDR string) error { + if !managedInterfaceFilterIPMatches(iface, filterName, currentIPCIDR) { + return NewError(ErrConflict, "network_filter_binding_changed", "managed VM network filter IP binding does not match its recorded public address", nil) + } + address, err := publicIPv4Address(targetIPCIDR) + if err != nil { + return err + } + iface.FilterRef.Parameters[0].Value = address + return nil +} + const domainMetadataNamespace = "https://virt.example/schema/domain/1" type domainMetadataXML struct { diff --git a/agent/hypervisor/domain_xml_test.go b/agent/hypervisor/domain_xml_test.go index 563d2d97..4d0a6807 100644 --- a/agent/hypervisor/domain_xml_test.go +++ b/agent/hypervisor/domain_xml_test.go @@ -4,6 +4,7 @@ import ( "crypto/sha256" "encoding/hex" "encoding/json" + "errors" "strings" "testing" @@ -117,6 +118,61 @@ func TestBuildDomainXMLRejectsSecureBootAndUnsafePaths(t *testing.T) { } } +func TestBuildDomainXMLBindsManagedFilterToAllocatedIPv4(t *testing.T) { + definition := validDomainDefinition() + definition.FilterName = "virt-123e4567-e89b-42d3-a456-426614174000" + document, err := BuildDomainXML(definition) + if err != nil { + t.Fatal(err) + } + var domain libvirtxml.Domain + if err := domain.Unmarshal(document); err != nil { + t.Fatal(err) + } + if len(domain.Devices.Interfaces) != 1 || !managedInterfaceFilterIPMatches( + &domain.Devices.Interfaces[0], definition.FilterName, definition.PublicIPCIDR, + ) { + t.Fatalf("managed interface IP binding is missing: %s", document) + } + parameter := domain.Devices.Interfaces[0].FilterRef.Parameters[0] + if parameter.Value != "8.8.8.10" || strings.Contains(parameter.Value, "/") { + t.Fatalf("filter IP parameter = %q, want bare IPv4 address", parameter.Value) + } +} + +func TestManagedInterfaceFilterIPUpdateRequiresExistingExactBinding(t *testing.T) { + const filterName = "virt-123e4567-e89b-42d3-a456-426614174000" + bound, err := newManagedInterfaceFilterRef(filterName, "8.8.8.10/24") + if err != nil { + t.Fatal(err) + } + iface := libvirtxml.DomainInterface{FilterRef: bound} + if err := updateManagedInterfaceFilterIP(&iface, filterName, "8.8.8.10/24", "8.8.8.11/24"); err != nil { + t.Fatal(err) + } + if !managedInterfaceFilterIPMatches(&iface, filterName, "8.8.8.11/24") { + t.Fatalf("updated filter binding is wrong: %#v", iface.FilterRef) + } + + for name, legacy := range map[string]libvirtxml.DomainInterface{ + "missing parameter": {FilterRef: &libvirtxml.DomainInterfaceFilterRef{Filter: filterName}}, + "stale address": { + FilterRef: &libvirtxml.DomainInterfaceFilterRef{Filter: filterName, Parameters: []libvirtxml.DomainInterfaceFilterParam{{Name: "IP", Value: "8.8.8.9"}}}, + }, + "duplicate parameter": { + FilterRef: &libvirtxml.DomainInterfaceFilterRef{Filter: filterName, Parameters: []libvirtxml.DomainInterfaceFilterParam{{Name: "IP", Value: "8.8.8.10"}, {Name: "IP", Value: "8.8.8.9"}}}, + }, + } { + t.Run(name, func(t *testing.T) { + err := updateManagedInterfaceFilterIP(&legacy, filterName, "8.8.8.10/24", "8.8.8.11/24") + var public *Error + if !errors.As(err, &public) || public.Code != "network_filter_binding_changed" { + t.Fatalf("legacy binding error = %v, want network_filter_binding_changed", err) + } + }) + } +} + func TestBuildPlatformFilterXMLUsesValidatedDropRules(t *testing.T) { request := validIntentCreateRequest(t) document, err := BuildPlatformFilterXML("virt-123e4567-e89b-42d3-a456-426614174000", request.PlatformNetworkPolicy) diff --git a/agent/hypervisor/libvirt_adapter.go b/agent/hypervisor/libvirt_adapter.go index a8619525..4eee66ae 100644 --- a/agent/hypervisor/libvirt_adapter.go +++ b/agent/hypervisor/libvirt_adapter.go @@ -667,7 +667,8 @@ func (l *Libvirt) verifyCreatedDomain(domain *libvirt.Domain, request CreateVMRe return NewError(ErrConflict, "firewall_observation_mismatch", "new domain platform policy metadata did not match the requested snapshot", err) } iface := definition.Devices.Interfaces[0] - if iface.MAC == nil || !strings.EqualFold(iface.MAC.Address, mac) || iface.FilterRef == nil || iface.FilterRef.Filter != filterName { + if iface.MAC == nil || !strings.EqualFold(iface.MAC.Address, mac) || + !managedInterfaceFilterIPMatches(&iface, filterName, request.PublicIPCIDR) { return NewError(ErrConflict, "firewall_observation_mismatch", "new domain did not attach the expected network filter", nil) } return l.verifyManagedFilter(filterName, storedPolicy) diff --git a/agent/hypervisor/libvirt_domain_features.go b/agent/hypervisor/libvirt_domain_features.go index 82e9bfe6..ce3dfda7 100644 --- a/agent/hypervisor/libvirt_domain_features.go +++ b/agent/hypervisor/libvirt_domain_features.go @@ -146,6 +146,22 @@ func (l *Libvirt) ChangeNetwork(ctx context.Context, uuid string, request Change if err := requirePersistentWithoutSnapshots(domain); err != nil { return VMMetadata{}, err } + preflightXML, err := domain.GetXMLDesc(libvirt.DOMAIN_XML_INACTIVE) + if err != nil { + return VMMetadata{}, translateLibvirtError("read domain network filter binding", err) + } + preflightDefinition, preflightMetadata, err := parseManagedDomain(preflightXML) + if err != nil { + return VMMetadata{}, err + } + if preflightDefinition.Devices == nil || len(preflightDefinition.Devices.Interfaces) != 1 { + return VMMetadata{}, NewError(ErrConflict, "network_layout_changed", "managed VM must have exactly one public interface", nil) + } + if !managedInterfaceFilterIPMatches( + &preflightDefinition.Devices.Interfaces[0], networkFilterName(uuid), preflightMetadata.PublicIPCIDR, + ) { + return VMMetadata{}, NewError(ErrConflict, "network_filter_binding_changed", "managed VM network filter IP binding does not match its recorded public address", nil) + } seed, err := l.lookupOptionalManagedVolume(l.storagePoolName(StorageRoleSeed), seedVolumeName(uuid)) if err != nil { return VMMetadata{}, err @@ -179,6 +195,11 @@ func (l *Libvirt) ChangeNetwork(ctx context.Context, uuid string, request Change if iface.MAC == nil || !strings.EqualFold(iface.MAC.Address, mac) { return NewError(ErrConflict, "network_identity_changed", "domain and NoCloud interface identities do not match", nil) } + if err := updateManagedInterfaceFilterIP( + iface, networkFilterName(uuid), metadata.PublicIPCIDR, request.PublicIPCIDR, + ); err != nil { + return err + } iface.Source = &libvirtxml.DomainInterfaceSource{} switch source.Type { case "bridge": diff --git a/agent/hypervisor/libvirt_reconcile_features.go b/agent/hypervisor/libvirt_reconcile_features.go index 264ed837..57548767 100644 --- a/agent/hypervisor/libvirt_reconcile_features.go +++ b/agent/hypervisor/libvirt_reconcile_features.go @@ -44,7 +44,8 @@ func (l *Libvirt) reconcileCreatedVM(domain *libvirt.Domain) (operation.Resoluti } seedAttached := false filterName := networkFilterName(definition.UUID) - filterAttached := len(definition.Devices.Interfaces) == 1 && definition.Devices.Interfaces[0].FilterRef != nil && definition.Devices.Interfaces[0].FilterRef.Filter == filterName + filterAttached := len(definition.Devices.Interfaces) == 1 && + managedInterfaceFilterIPMatches(&definition.Devices.Interfaces[0], filterName, metadata.PublicIPCIDR) for _, disk := range definition.Devices.Disks { if disk.Device == "cdrom" && disk.Target != nil && disk.Target.Dev == "sda" && disk.Source != nil && disk.Source.File != nil && disk.Source.File.File == seedPath && disk.ReadOnly != nil { seedAttached = true @@ -166,6 +167,7 @@ func (l *Libvirt) reconcileNetworkChange(ctx context.Context, record operation.R expected.PublicIPCIDR != publicCIDR || expected.Gateway != gateway || !slices.Equal(expected.DNSServers, dns) || definition.Devices == nil || len(definition.Devices.Interfaces) != 1 || definition.Devices.Interfaces[0].MAC == nil || !strings.EqualFold(definition.Devices.Interfaces[0].MAC.Address, mac) || + !managedInterfaceFilterIPMatches(&definition.Devices.Interfaces[0], networkFilterName(record.ResourceID), expected.PublicIPCIDR) || !domainNetworkSourceMatches(definition.Devices.Interfaces[0], expected.NetworkSourceType, expected.NetworkSourceName) { // Matching transition markers prove that both phases wrote state for // this operation. A payload mismatch is therefore ambiguous and must diff --git a/agent/hypervisor/libvirt_safety_test.go b/agent/hypervisor/libvirt_safety_test.go index bb89041b..f3ade69f 100644 --- a/agent/hypervisor/libvirt_safety_test.go +++ b/agent/hypervisor/libvirt_safety_test.go @@ -1493,7 +1493,7 @@ func TestNetworkAndFirewallReadOnlyEvidenceMatchers(t *testing.T) { func TestNetworkInterfaceLinkDocumentsBuildAllUpdatesBeforeMutation(t *testing.T) { document := `` + - `` + + `` + `` + `` for _, enabled := range []bool{false, true} { @@ -1513,6 +1513,10 @@ func TestNetworkInterfaceLinkDocumentsBuildAllUpdatesBeforeMutation(t *testing.T if iface.Link == nil || iface.Link.State != want { t.Fatalf("enabled=%v update=%s", enabled, update) } + if iface.MAC != nil && iface.MAC.Address == "52:54:00:00:00:01" && + !managedInterfaceFilterIPMatches(&iface, "virt-test", "203.0.113.10/24") { + t.Fatalf("network state update dropped managed IP binding: %s", update) + } } } if documents, err := networkInterfaceLinkDocuments(``, false); err == nil || len(documents) != 0 { diff --git a/docs/AGENT_API.md b/docs/AGENT_API.md index 773c04a1..b2f16681 100644 --- a/docs/AGENT_API.md +++ b/docs/AGENT_API.md @@ -183,6 +183,7 @@ Go context 无法可靠中止已进入 CGo/libvirt 的调用。父 Agent 到达 - VM 内部 libvirt 名称由 actor user ID 和完整 UUID 派生;面板名称只写受控 metadata。客户端不能指定 Domain 名或提交 XML。 - 新 Domain 固定 x86_64/q35、UEFI、Secure Boot 关闭。loader/VARS 路径来自本机配置与 `domcapabilities`,请求不能覆盖。 +- 新 Domain 的唯一公网网卡通过专属 `virt-` nwfilter 引用 `clean-traffic`,并把已分配的纯 IPv4 地址作为显式 `IP` 参数写入 Domain XML,禁止来宾伪造源 IP。换网操作必须在同一次 seed/Domain 事务中验证旧绑定并替换为新地址;缺少显式绑定的旧 Domain 不自动补齐。 - 正常删除先请求 ACPI 关机。只有同一次执行明确观察到关机请求已接受但等待结束仍活动,才返回 `force_required`;强删必须使用新的 operation、超级管理员与 `ack_data_loss=true`。 - 删除成功必须确认 Domain、全部面板受管磁盘、Seed、专属过滤器、NVRAM 和流量状态均已消失。任何证据不可读都返回失败且可能保留资源栅栏。 - `ShutdownFlags`、`Reboot` 等调用成功只表示 libvirt 接受请求,不统一表示来宾已达到最终电源状态;回执 result 必须准确描述实际被确认的语义。 diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index a9099d88..98e9851a 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -323,6 +323,7 @@ location = /agent/console { - 通过 WSS 转发 `/v1/health`、`/v1/capabilities` 的双层 HMAC、时间窗、nonce 重放和错误遮罩。 - 创建、启动、软/硬关机、软/硬重启、删除、重装、救援、快照、网络、防火墙、指标和控制台。 +- 新建 VM 的 Domain XML 必须在专属 nwfilter 引用中把已分配公网 IPv4 写为唯一 `IP` 参数;更换公网 IP 后该参数必须同步为新地址,旧地址与其他伪造源地址均不能发出流量。 - Q35 UEFI 启动且 Secure Boot 关闭;不同宿主机固件路径通过 capabilities 选择。 - 云镜像启动脚本只执行一次,并覆盖成功、非零退出、重启及 Agent 断线。 - 并发提交相同幂等键只能得到同一个任务;同一任务的宿主机 mutation 调用计数只能是 0 或 1。