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。