netstack 0.1.1 → 0.2.0

data/lib/netstack/configuration/validator.rb

@@ -0,0 +1,566 @@
+# frozen_string_literal: true
+
+# Adapted from Motor Netconf scenario definitions and safe template dialect.
+require_relative "support"
+
+require "ipaddr"
+require "socket"
+require_relative "bootstrap/validator"
+
+module Netstack
+  module Configuration
+    class Validator
+      include Bootstrap::Validator
+
+      Error = Class.new(Netstack::InputError)
+      MAX_ROWS = 64
+
+      def self.call(scenario:, vendor:, input:, system_config: {}, settings: {})
+        new(scenario:, vendor:, input:, system_config:, settings:).call
+      end
+
+      def initialize(scenario:, vendor:, input:, system_config: {}, settings: {})
+        @scenario = scenario.to_s
+        @vendor = vendor.to_s
+        @input = object!(input, "input")
+        @system_config = object!(system_config, "system_config")
+        @settings = object!(settings, "settings")
+      end
+
+      def call
+        Catalog.template_key(@scenario, @vendor)
+        send("validate_#{@scenario.tr("-", "_")}")
+      rescue KeyError => exception
+        raise Error, exception.message
+      end
+
+      def inspect = "#<#{self.class.name}>"
+
+      private
+
+      # Only omitted values and blank form text select defaults. Other types must
+      # reach the field validator instead of becoming a different configuration.
+      def provided?(value) = !value.nil? && (!value.is_a?(String) || value.present?)
+
+      def default_if_omitted(value, fallback) = provided?(value) ? value : fallback
+
+      def validate_bootstrap
+        common = take!(%w[hostname device_role mgmt mgmt_gateway snmp_location system access_auth_enabled access_auth_domain access_auth_vlan access_auth_interface_start access_auth_interface_end])
+        result = {
+          "hostname" => hostname!(common["hostname"], "hostname"),
+          "device_role" => enum!((default_if_omitted(common["device_role"], bootstrap_roles.first)).to_s.downcase, "device_role", bootstrap_roles),
+          "mgmt" => management_cidr!(common["mgmt"], "mgmt"),
+          "snmp_location" => description!(common["snmp_location"], "snmp_location")
+        }
+        validate_bootstrap_gateway!(result, common["mgmt_gateway"])
+        access_auth_enabled = @vendor == "h3c" && (common["access_auth_enabled"].nil? ? false : boolean!(common["access_auth_enabled"], "access_auth_enabled"))
+        if access_auth_enabled && common["access_auth_vlan"].blank?
+          raise Error, "access_auth_vlan is required when admission control is enabled"
+        end
+        result["system"] = system_configuration!(common["system"].nil? ? {} : common["system"], access_auth_enabled: access_auth_enabled)
+        return validate_h3c_bootstrap!(result, common, access_auth_enabled) if @vendor == "h3c"
+
+        validate_cisco_bootstrap!(result)
+      end
+
+      def validate_h3c_irf
+        values = take!(%w[port1 port2 port3 port4 mad_port1 mad_port2 mad_vlan mad_subnet])
+        result = {}
+        %w[port1 port2 port3 port4 mad_port1 mad_port2].each { |field| result[field] = interface!(values[field], field) }
+        result["mad_vlan"] = integer!(values["mad_vlan"], "mad_vlan", 1..4095)
+        result["mad_subnet"] = cidr!(values["mad_subnet"], "mad_subnet", network: true)
+        raise Error, "mad_subnet prefix must be between 1 and 30" unless result["mad_subnet"].split("/").last.to_i.between?(1, 30)
+        interfaces = result.values_at(*%w[port1 port2 port3 port4 mad_port1 mad_port2])
+        raise Error, "IRF and MAD interfaces must be unique" unless interfaces.map(&:downcase).uniq.size == 6
+        finish!(result)
+      end
+
+      def validate_distributed_gateway
+        values = take!(%w[gateways])
+        gateways = rows!(values["gateways"], "gateways").map.with_index do |row, index|
+          row = exact!(row, %w[vlan subnet gateway vni name mtu vrf acl], "gateways[#{index}]")
+          vlan = integer!(row["vlan"], "gateways[#{index}].vlan", 1..4094)
+          subnet = cidr!(row["subnet"], "gateways[#{index}].subnet", network: true)
+          raise Error, "gateways[#{index}].subnet prefix must be between 1 and 30" unless subnet.split("/").last.to_i.between?(1, 30)
+          gateway = provided?(row["gateway"]) ? ipv4!(row["gateway"], "gateways[#{index}].gateway") : last_usable(subnet)
+          raise Error, "gateways[#{index}].gateway must belong to subnet" unless IPAddr.new(subnet).include?(gateway)
+          subnet_range = IPAddr.new(subnet).to_range
+          if [ subnet_range.first.to_s, subnet_range.last.to_s ].include?(gateway)
+            raise Error, "gateways[#{index}].gateway must be a usable host address"
+          end
+          { "vlan" => vlan, "subnet" => subnet, "gateway" => gateway,
+            "vni" => provided?(row["vni"]) ? integer!(row["vni"], "gateways[#{index}].vni", 1..16_777_215) : 10_000 + vlan,
+            "name" => optional_description(row["name"], "gateways[#{index}].name"),
+            "mtu" => provided?(row["mtu"]) ? integer!(row["mtu"], "gateways[#{index}].mtu", 1280..9216) : 9216,
+            "vrf" => identifier!(default_if_omitted(row["vrf"], "VXLAN"), "gateways[#{index}].vrf"),
+            "acl" => optional_identifier(row["acl"], "gateways[#{index}].acl") }
+        end
+        raise Error, "gateway VLAN and VNI values must be unique" unless gateways.map { |row| row["vlan"] }.uniq.size == gateways.size && gateways.map { |row| row["vni"] }.uniq.size == gateways.size
+        finish!("gateways" => gateways)
+      end
+
+      def validate_cisco_n9k_vpc
+        values = take!(%w[
+          vpc_domain_id primary_role_priority secondary_role_priority
+          primary_keepalive_ip secondary_keepalive_ip primary_virtual_peer_link_ip
+          secondary_virtual_peer_link_ip vpc_peer_link_port_channel infra_vlan fabric_interfaces
+        ])
+        primary_keepalive = ipv4!(values["primary_keepalive_ip"], "primary_keepalive_ip")
+        secondary_keepalive = ipv4!(values["secondary_keepalive_ip"], "secondary_keepalive_ip")
+        raise Error, "vPC keepalive addresses must be different" if primary_keepalive == secondary_keepalive
+
+        primary_virtual = ipv4!(values["primary_virtual_peer_link_ip"], "primary_virtual_peer_link_ip")
+        secondary_virtual = ipv4!(values["secondary_virtual_peer_link_ip"], "secondary_virtual_peer_link_ip")
+        addresses = [ primary_keepalive, secondary_keepalive, primary_virtual, secondary_virtual ]
+        raise Error, "vPC endpoint addresses must be unique" unless addresses.uniq.size == addresses.size
+
+        primary_priority = integer!(default_if_omitted(values["primary_role_priority"], 100), "primary_role_priority", 1..65_535)
+        secondary_priority = integer!(default_if_omitted(values["secondary_role_priority"], 200), "secondary_role_priority", 1..65_535)
+        raise Error, "vPC role priorities must be different" if primary_priority == secondary_priority
+
+        raw_interfaces = values["fabric_interfaces"]
+        raw_interfaces = raw_interfaces.lines if raw_interfaces.is_a?(String)
+        unless raw_interfaces.is_a?(Array) && raw_interfaces.all? { |value| value.is_a?(String) }
+          raise Error, "fabric_interfaces must be text lines or an array of strings"
+        end
+        raw_interfaces = raw_interfaces.map(&:strip).reject(&:empty?)
+        unless raw_interfaces.size.between?(1, 16)
+          raise Error, "fabric_interfaces must contain 1 to 16 values"
+        end
+        interfaces = raw_interfaces.map.with_index do |interface, index|
+          interface!(interface, "fabric_interfaces[#{index}]")
+        end
+        raise Error, "fabric interfaces must be unique" unless interfaces.map(&:downcase).uniq.size == interfaces.size
+
+        finish!(
+          "vpc_domain_id" => integer!(values["vpc_domain_id"], "vpc_domain_id", 1..1000),
+          "primary_role_priority" => primary_priority,
+          "secondary_role_priority" => secondary_priority,
+          "primary_keepalive_ip" => primary_keepalive,
+          "secondary_keepalive_ip" => secondary_keepalive,
+          "primary_virtual_peer_link_ip" => primary_virtual,
+          "secondary_virtual_peer_link_ip" => secondary_virtual,
+          "vpc_peer_link_port_channel" => integer!(default_if_omitted(values["vpc_peer_link_port_channel"], 999), "vpc_peer_link_port_channel", 1..4096),
+          "infra_vlan" => integer!(default_if_omitted(values["infra_vlan"], 3967), "infra_vlan", 1..4094),
+          "fabric_interfaces" => interfaces
+        )
+      end
+
+      def validate_server_port
+        values = take!(%w[stack_mode allocations])
+        mode = enum!(default_if_omitted(values["stack_mode"], "standalone"), "stack_mode", @vendor == "h3c" ? %w[standalone irf] : %w[standalone vpc])
+        allocations = rows!(values["allocations"], "allocations").map.with_index do |row, index|
+          row = exact!(row, %w[local_iface local_description remote remote_iface vlan port_channel aggregate_id flag], "allocations[#{index}]")
+          aggregated = boolean!(row["port_channel"], "allocations[#{index}].port_channel")
+          local_iface = interface!(row["local_iface"], "allocations[#{index}].local_iface")
+          remote = hostname!(row["remote"], "allocations[#{index}].remote")
+          remote_iface = interface!(row["remote_iface"], "allocations[#{index}].remote_iface")
+          aggregate_id = integer!(row["aggregate_id"], "allocations[#{index}].aggregate_id", 1..4096) if aggregated && provided?(row["aggregate_id"])
+          { "local_iface" => local_iface,
+            "local_description" => description!(default_if_omitted(row["local_description"], automatic_local_description(remote, remote_iface, aggregated)), "allocations[#{index}].local_description"),
+            "remote" => remote,
+            "remote_iface" => remote_iface,
+            "vlan" => vlan_value!(row["vlan"], "allocations[#{index}].vlan"),
+            "port_channel" => aggregated,
+            "aggregate_id" => aggregate_id,
+            "flag" => optional_description(row["flag"], "allocations[#{index}].flag") }
+        end
+        assign_automatic_aggregate_ids!(allocations, mode)
+        raise Error, "local interfaces must be unique" unless allocations.map { |row| row["local_iface"].downcase }.uniq.size == allocations.size
+        aggregate_groups = allocations.select { |row| row["port_channel"] }.group_by { |row| row["aggregate_id"] }
+        unless aggregate_groups.values.all? { |rows| rows.map { |row| [ row["remote"].downcase, row["vlan"] ] }.uniq.one? }
+          raise Error, "ports in the same aggregate must use the same remote device and VLAN"
+        end
+        if mode == "vpc"
+          unless aggregate_groups.values.all?(&:one?)
+            raise Error, "vPC links must use unique aggregate identifiers"
+          end
+        elsif !aggregate_groups.values.all? { |rows| rows.size == 2 }
+          raise Error, "non-vPC aggregates must contain exactly two links"
+        end
+        finish!(
+          "stack_mode" => mode, "allocations" => allocations
+        )
+      end
+
+      def validate_hillstone_policy
+        values = take!(%w[policies])
+        policies = rows!(values["policies"], "policies").map.with_index do |row, index|
+          path = "policies[#{index}]"
+          row = exact!(row, %w[description src_zone src_addresses dst_zone dst_addresses protocol services action log], path)
+
+          {
+            "description" => policy_description!(row["description"], "#{path}.description"),
+            "src_zone" => policy_zone!(default_if_omitted(row["src_zone"], "any"), "#{path}.src_zone"),
+            "src_addresses" => policy_address_list!(row["src_addresses"], "#{path}.src_addresses"),
+            "dst_zone" => policy_zone!(default_if_omitted(row["dst_zone"], "any"), "#{path}.dst_zone"),
+            "dst_addresses" => policy_address_list!(row["dst_addresses"], "#{path}.dst_addresses"),
+            "protocol" => enum!(row["protocol"].to_s.downcase, "#{path}.protocol", %w[tcp udp]),
+            "services" => policy_service_list!(row["services"], "#{path}.services"),
+            "action" => enum!((default_if_omitted(row["action"], "permit")).to_s.downcase, "#{path}.action", %w[permit deny]),
+            "log" => row["log"].nil? ? true : boolean!(row["log"], "#{path}.log")
+          }
+        end
+        finish!("policies" => policies)
+      end
+
+      def validate_load_balancer
+        values = take!(%w[services])
+        services = rows!(values["services"], "services").map.with_index do |row, index|
+          row = exact!(row, %w[flag real_ips virtual_ip service_port proxy_ip app_port timeout group_name service_type health_check client_ip_persistence], "services[#{index}]")
+          real_ips = string_list!(row["real_ips"], "services[#{index}].real_ips").map.with_index do |ip, ip_index|
+            ipv4!(ip, "services[#{index}].real_ips[#{ip_index}]")
+          end
+          flag = identifier!(row["flag"], "services[#{index}].flag")
+          service_name = flag
+          virtual_ip = ipv4!(row["virtual_ip"], "services[#{index}].virtual_ip")
+          service_port = integer!(row["service_port"], "services[#{index}].service_port", 1..65_535)
+          app_port = provided?(row["app_port"]) ? integer!(row["app_port"], "services[#{index}].app_port", 1..65_535) : service_port
+          { "flag" => flag, "service_name" => service_name, "real_ips" => real_ips,
+            "virtual_ip" => virtual_ip, "service_port" => service_port,
+            "proxy_ip" => ipv4!(default_if_omitted(row["proxy_ip"], virtual_ip), "services[#{index}].proxy_ip"),
+            "app_port" => app_port,
+            "timeout" => provided?(row["timeout"]) ? integer!(row["timeout"], "services[#{index}].timeout", 1..86_400) : 30,
+            "group_name" => provided?(row["group_name"]) ? identifier!(row["group_name"], "services[#{index}].group_name") : automatic_group_name(flag, app_port),
+            "service_type" => enum!(default_if_omitted(row["service_type"], "basic-slb"), "services[#{index}].service_type", %w[basic-slb http https]),
+            "health_check" => optional_identifier(row["health_check"], "services[#{index}].health_check"),
+            "client_ip_persistence" => row["client_ip_persistence"].nil? ? false : boolean!(row["client_ip_persistence"], "services[#{index}].client_ip_persistence") }
+        end
+        keys = services.map { |row| [ row["virtual_ip"], row["service_port"] ] }
+        raise Error, "VIP address and port pairs must be unique" unless keys.uniq.size == keys.size
+        groups = services.group_by { |row| row["group_name"].downcase }
+        unless groups.values.all? { |rows| rows.map { |row| [ row["real_ips"], row["health_check"] ] }.uniq.one? }
+          raise Error, "services using the same group_name must use the same real_ips and health_check"
+        end
+        finish!(
+          "next_hop" => ipv4!(@settings.fetch("next_hop") { raise Error, "settings.next_hop is required" }, "settings.next_hop"),
+          "route_metric" => integer!(@settings.fetch("route_metric", 1), "settings.route_metric", 1..65_535),
+          "services" => services
+        )
+      end
+
+      def validate_ipsec_vpn
+        values = take!(%w[site_name tunnel local_interface local_address remote_ip add_route preshared_key local_subnets remote_subnets ike_version ike_encryption ike_authentication ike_dh_group ike_lifetime ipsec_encryption ipsec_authentication ipsec_lifetime virtual_router route_metric dpd_interval dpd_retry hillstone_sa_index tunnel_zone])
+        add_route = values["add_route"].nil? || boolean!(values["add_route"], "add_route")
+        encryption_options = @vendor == "hillstone" ? %w[aes-256-cbc 3des] : %w[aes-256-gcm aes-256-cbc 3des]
+        dh_group_options = @vendor == "hillstone" ? %w[group5 group2] : %w[group19 group14 group5 group2]
+        result = {
+          "site_name" => identifier!(values["site_name"], "site_name"),
+          "tunnel" => interface!(values["tunnel"], "tunnel"), "local_interface" => interface!(values["local_interface"], "local_interface"),
+          "local_address" => cidr!(values["local_address"], "local_address", host: true),
+          "remote_ip" => ipv4!(values["remote_ip"], "remote_ip"),
+          "preshared_key" => secret!(values["preshared_key"], "preshared_key"),
+          "local_subnets" => string_list!(values["local_subnets"], "local_subnets").map { |cidr| cidr!(cidr, "local_subnets", network: true) },
+          "remote_subnets" => string_list!(values["remote_subnets"], "remote_subnets").map { |cidr| cidr!(cidr, "remote_subnets", network: true) },
+          "ike_version" => enum!(values["ike_version"], "ike_version", %w[ikev1 ikev2]),
+          "ike_encryption" => enum!(values["ike_encryption"], "ike_encryption", encryption_options),
+          "ike_authentication" => enum!(values["ike_authentication"], "ike_authentication", %w[sha256 sha1 md5]),
+          "ike_dh_group" => enum!(values["ike_dh_group"], "ike_dh_group", dh_group_options),
+          "ike_lifetime" => integer!(values["ike_lifetime"], "ike_lifetime", 300..86_400),
+          "ipsec_encryption" => enum!(values["ipsec_encryption"], "ipsec_encryption", encryption_options),
+          "ipsec_authentication" => enum!(values["ipsec_authentication"], "ipsec_authentication", %w[sha256 sha1 md5]),
+          "ipsec_lifetime" => integer!(values["ipsec_lifetime"], "ipsec_lifetime", 300..86_400),
+          "add_route" => add_route,
+          "virtual_router" => identifier!(values["virtual_router"].nil? ? (@vendor == "hillstone" ? "trust-vr" : "default") : values["virtual_router"], "virtual_router"),
+          "route_metric" => integer!(values["route_metric"].nil? ? 10 : values["route_metric"], "route_metric", 1..65_535),
+          "dpd_interval" => integer!(values["dpd_interval"].nil? ? 10 : values["dpd_interval"], "dpd_interval", 1..3600),
+          "dpd_retry" => integer!(values["dpd_retry"].nil? ? (@vendor == "hillstone" ? 3 : 10) : values["dpd_retry"], "dpd_retry", 1..100)
+        }
+        if @vendor == "hillstone"
+          result["hillstone_sa_index"] = integer!(values["hillstone_sa_index"].nil? ? 35 : values["hillstone_sa_index"], "hillstone_sa_index", 1..65_535)
+          result["tunnel_zone"] = identifier!(values["tunnel_zone"].nil? ? "VPNHub" : values["tunnel_zone"], "tunnel_zone")
+        end
+        finish!(result)
+      end
+
+      def take!(fields)
+        fields.index_with { |field| @input.delete(field) }
+      end
+
+      def finish!(result)
+        raise Error, "unexpected fields: #{@input.keys.join(", ")}" if @input.any?
+        result
+      end
+
+      def object!(value, path)
+        Support.object(value, name: path)
+      end
+
+      def exact!(value, fields, path)
+        row = object!(value, path)
+        unexpected = row.keys - fields
+        raise Error, "unexpected #{path} fields: #{unexpected.join(", ")}" if unexpected.any?
+        fields.index_with { |field| row[field] }
+      end
+
+      def rows!(value, path)
+        raise Error, "#{path} must contain 1 to #{MAX_ROWS} rows" unless value.is_a?(Array) && value.size.between?(1, MAX_ROWS)
+        value
+      end
+
+      def string!(value, path)
+        raise Error, "#{path} is required" unless value.is_a?(String) && value.strip.present?
+        value.strip
+      end
+
+      def hostname!(value, path)
+        text = string!(value, path)
+        raise Error, "#{path} is invalid" unless text.match?(/\A(?=.{1,63}\z)[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?\z/)
+        text
+      end
+
+      def identifier!(value, path)
+        text = string!(value, path)
+        raise Error, "#{path} is invalid" unless text.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}\z/)
+        text
+      end
+
+      def optional_identifier(value, path) = provided?(value) ? identifier!(value, path) : nil
+
+      def description!(value, path)
+        text = string!(value, path)
+        raise Error, "#{path} is invalid" unless text.length <= 160 && !text.match?(/[\x00-\x1f\x7f;"\\]/)
+        text
+      end
+
+      def optional_description(value, path) = provided?(value) ? description!(value, path) : nil
+
+      def interface!(value, path)
+        text = string!(value, path)
+        raise Error, "#{path} is invalid" unless text.match?(/\A[a-zA-Z][a-zA-Z0-9._\/-]{0,63}\z/)
+        text
+      end
+
+      def ipv4!(value, path)
+        text = string!(value, path)
+        address = IPAddr.new(text)
+        raise Error, "#{path} must be IPv4" unless address.ipv4? && !text.include?("/")
+        text
+      rescue IPAddr::InvalidAddressError
+        raise Error, "#{path} must be IPv4"
+      end
+
+      def cidr!(value, path, network: false, host: false)
+        text = string!(value, path)
+        raise Error, "#{path} must be IPv4 CIDR" unless text.match?(/\A(?:\d{1,3}\.){3}\d{1,3}\/(?:[0-9]|[12][0-9]|3[0-2])\z/) && IPAddr.new(text).ipv4?
+        address = IPAddr.new(text)
+        raise Error, "#{path} must be a network address" if network && address.to_range.first.to_s != text.split("/").first
+        raise Error, "#{path} must be a host address" if host && [address.to_range.first.to_s, address.to_range.last.to_s].include?(text.split("/").first) && text.split("/").last.to_i < 31
+        text
+      rescue IPAddr::InvalidAddressError
+        raise Error, "#{path} must be IPv4 CIDR"
+      end
+
+      def integer!(value, path, range)
+        number = value if value.is_a?(Integer)
+        number = Integer(value, 10) if value.is_a?(String) && value.match?(/\A[0-9]+\z/)
+        raise Error, "#{path} is outside the allowed range" unless number&.in?(range)
+        number
+      end
+
+      def asn!(value, path) = integer!(value, path, 1..4_294_967_295)
+
+      def ospf_area!(value, path)
+        text = string!(value, path)
+        decimal = Integer(text, 10) if text.match?(/\A[0-9]{1,20}\z/)
+        dotted = text.match?(/\A(?:\d{1,3}\.){3}\d{1,3}\z/) && IPAddr.new(text).ipv4?
+        raise Error, "#{path} is invalid" unless decimal&.between?(0, 4_294_967_295) || dotted
+        decimal ? decimal.to_s : text
+      rescue IPAddr::InvalidAddressError
+        raise Error, "#{path} is invalid"
+      end
+
+      def management_cidr!(value, path)
+        cidr = cidr!(value, path, host: true)
+        raise Error, "#{path} prefix must be between 1 and 30" unless cidr.split("/").last.to_i.between?(1, 30)
+        cidr
+      end
+
+      def boolean!(value, path) = value.in?([ true, false ]) ? value : raise(Error, "#{path} must be boolean")
+      def enum!(value, path, options) = options.include?(value.to_s) ? value.to_s : raise(Error, "#{path} is invalid")
+
+      def vlan_value!(value, path)
+        text = string!(value, path).downcase
+        return "trunk" if text == "trunk"
+        item = /[0-9]{1,20}(?:-[0-9]{1,20})?/
+        raise Error, "#{path} is invalid" unless text.match?(/\A#{item}(?:(?: *, *| +)#{item})*\z/)
+
+        text.split(/[ ,]+/).map do |part|
+          bounds = part.split("-").map { |bound| integer!(bound, path, 1..4094) }
+          raise Error, "#{path} is invalid" if bounds.size == 2 && bounds.first > bounds.last
+
+          bounds.join("-")
+        end.join(",")
+      end
+
+      def secret!(value, path)
+        text = string!(value, path)
+        raise Error, "#{path} is invalid" unless text.match?(/\A[!-~]{8,128}\z/) && !text.match?(/["\\;`]/)
+        text
+      end
+
+      def string_list!(value, path)
+        raise Error, "#{path} must be an array or lines of text" unless value.is_a?(String) || (value.is_a?(Array) && value.all?(String))
+        values = value.is_a?(Array) ? value : value.lines
+        values = values.map { |item| item.to_s.strip }.reject(&:blank?).uniq
+        raise Error, "#{path} must contain 1 to #{MAX_ROWS} values" unless values.size.between?(1, MAX_ROWS)
+        values
+      end
+
+      def policy_zone!(value, path)
+        text = string!(value, path)
+        return "any" if text.casecmp?("any")
+        identifier!(text, path)
+      end
+
+      def policy_description!(value, path)
+        return unless provided?(value)
+        text = description!(value, path)
+        raise Error, "#{path} is invalid" if text.match?(/["\\]/)
+        text
+      end
+
+      def policy_address_list!(value, path)
+        values = string_list!(value, path).map.with_index do |address, index|
+          policy_address!(address, "#{path}[#{index}]")
+        end.uniq
+        if values.include?("any") && values.size > 1
+          raise Error, "#{path} cannot combine any with other addresses"
+        end
+        values
+      end
+
+      def policy_address!(value, path)
+        text = string!(value, path)
+        return "any" if text.casecmp?("any")
+        if text.include?("-")
+          bounds = text.split(/\s*-\s*/, -1)
+          raise Error, "#{path} must be IPv4, CIDR, range, or any" unless bounds.size == 2
+          first = ipv4!(bounds.first, path)
+          last = ipv4!(bounds.last, path)
+          raise Error, "#{path} range is reversed" if IPAddr.new(first).to_i > IPAddr.new(last).to_i
+          return "#{first}-#{last}"
+        end
+        return cidr!(text, path) if text.include?("/")
+        "#{ipv4!(text, path)}/32"
+      rescue IPAddr::InvalidAddressError
+        raise Error, "#{path} must be IPv4, CIDR, range, or any"
+      end
+
+      def policy_service_list!(value, path)
+        values = string_list!(value, path).map.with_index do |service, index|
+          policy_service!(service, "#{path}[#{index}]")
+        end.uniq
+        if values.include?("any") && values.size > 1
+          raise Error, "#{path} cannot combine any with other ports"
+        end
+        values
+      end
+
+      def policy_service!(value, path)
+        text = string!(value, path).downcase
+        return "any" if text == "any"
+        unless text.match?(/\A[0-9]{1,20}(?:\s*-\s*[0-9]{1,20})?\z/)
+          raise Error, "#{path} must be a port, port range, or any"
+        end
+        bounds = text.split(/\s*-\s*/, -1).map { |port| Integer(port, 10) }
+        unless bounds.size.between?(1, 2) && bounds.all? { |port| port&.between?(1, 65_535) }
+          raise Error, "#{path} must be a port, port range, or any"
+        end
+        raise Error, "#{path} range is reversed" if bounds.size == 2 && bounds.first > bounds.last
+        bounds.uniq.join("-")
+      end
+
+      def system_configuration!(overrides, access_auth_enabled: false)
+        config = SystemConfiguration.resolve(object!(overrides, "system"), defaults: @system_config)
+        unless config["local_users"].is_a?(Array) && config["local_users"].size.between?(1, 16)
+          raise Error, "system.local_users must contain 1 to 16 rows"
+        end
+        result = {
+          "domain_name" => domain!(config["domain_name"], "system.domain_name"),
+          "timezone" => enum!(config["timezone"], "system.timezone", %w[Beijing]),
+          "management_vlan" => integer!(config["management_vlan"], "system.management_vlan", 1..4094),
+          "ntp_servers" => ipv4_list!(config["ntp_servers"], "system.ntp_servers"),
+          "dns_servers" => ipv4_list!(config["dns_servers"], "system.dns_servers"),
+          "syslog_servers" => ipv4_list!(config["syslog_servers"], "system.syslog_servers"),
+          "snmp_community" => secret!(config["snmp_community"], "system.snmp_community"),
+          "tacacs_servers" => ipv4_list!(config["tacacs_servers"], "system.tacacs_servers"),
+          "tacacs_secret" => secret!(config["tacacs_secret"], "system.tacacs_secret"),
+          "ssh_acl_cidrs" => string_list!(config["ssh_acl_cidrs"], "system.ssh_acl_cidrs").map { |cidr| cidr!(cidr, "system.ssh_acl_cidrs") },
+          "local_users" => rows!(config["local_users"], "system.local_users").map.with_index { |user, index| system_user!(user, index) },
+          "base_security_enabled" => boolean!(config["base_security_enabled"], "system.base_security_enabled"),
+          "disable_telnet" => boolean!(config["disable_telnet"], "system.disable_telnet"),
+          "disable_http" => boolean!(config["disable_http"], "system.disable_http"),
+          "enable_bpdu_protection" => boolean!(config["enable_bpdu_protection"], "system.enable_bpdu_protection"),
+          "password_min_length" => integer!(config["password_min_length"], "system.password_min_length", 8..64),
+          "vty_timeout_minutes" => integer!(config["vty_timeout_minutes"], "system.vty_timeout_minutes", 1..120)
+        }
+        if access_auth_enabled
+          result["radius_servers"] = ipv4_list!(config["radius_servers"], "system.radius_servers")
+          result["radius_secret"] = secret!(config["radius_secret"], "system.radius_secret")
+        end
+        raise Error, "system local usernames must be unique" unless result["local_users"].map { |user| user["username"].downcase }.uniq.size == result["local_users"].size
+        result
+      rescue KeyError => exception
+        raise Error, exception.message
+      end
+
+      def system_user!(value, index)
+        user = exact!(value, %w[username password role], "system.local_users[#{index}]")
+        username = string!(user["username"], "system.local_users[#{index}].username")
+        raise Error, "system.local_users[#{index}].username is invalid" unless username.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_-]{2,31}\z/)
+        { "username" => username,
+          "password" => secret!(user["password"], "system.local_users[#{index}].password"),
+          "role" => enum!(user["role"], "system.local_users[#{index}].role", %w[admin operator read_only]) }
+      end
+
+      def ipv4_list!(value, path) = string_list!(value, path).map { |address| ipv4!(address, path) }
+
+      def domain!(value, path)
+        text = string!(value, path)
+        raise Error, "#{path} is invalid" unless text.match?(/\A(?=.{1,253}\z)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/i)
+        text
+      end
+
+      def last_usable(cidr)
+        range = IPAddr.new(cidr).to_range
+        IPAddr.new(range.last.to_i - 1, Socket::AF_INET).to_s
+      end
+
+      def automatic_local_description(remote, remote_iface, aggregated)
+        [ "TO", remote.upcase, (remote_iface.upcase unless aggregated) ].compact.join("_")
+      end
+
+      def automatic_group_name(flag, app_port)
+        identifier!("#{flag}_#{app_port}".first(64), "services.group_name")
+      end
+
+      def assign_automatic_aggregate_ids!(allocations, mode)
+        used = allocations.filter_map { |row| row["aggregate_id"] }.uniq
+        allocations.each_with_index do |row, index|
+          next unless row["port_channel"] && row["aggregate_id"].nil?
+
+          group = if mode == "vpc"
+            [ row ]
+          else
+            remote_rows = allocations.select { |item| item["port_channel"] && item["remote"].casecmp?(row["remote"]) }
+            position = remote_rows.index(row)
+            remote_rows.each_slice(2).to_a.fetch(position / 2)
+          end
+          aggregate_id = group.filter_map { |item| item["aggregate_id"] }.first
+          aggregate_id ||= automatic_aggregate_id(group.first.fetch("local_iface"), used, index)
+          group.each { |item| item["aggregate_id"] ||= aggregate_id }
+          used << aggregate_id
+        end
+      end
+
+      def automatic_aggregate_id(local_iface, used, index)
+        suffix = local_iface.scan(/\d+/).last.to_i
+        candidate = suffix.positive? ? suffix + 100 : index + 101
+        return candidate if candidate.between?(1, 4096) && !used.include?(candidate)
+
+        (101..4096).find { |value| !used.include?(value) }
+      end
+    end
+  end
+end

data/lib/netstack/connector/authentication.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+module Netstack
+  module Connector
+    # 密码或密钥登录与显式特权认证共用有界对话流程。
+    class Authentication
+      CONNECTION_FAILURES = {
+        /REMOTE HOST IDEN|IDENTIFICATION CHANGED/i => [ConnectionError, :host_key_changed],
+        /Host key verification failed/i => [ConnectionError, :host_key_untrusted],
+        /RSA modulus too small/i => [ConnectionError, :rsa_too_small],
+        /Selected cipher type <unknown> not supported by server/i => [ConnectionError, :unsupported_cipher],
+        /Connection refused/i => [ConnectionError, :connection_refused],
+        /No route to host/i => [ConnectionError, :no_route],
+        /Connection reset/i => [ConnectionError, :connection_reset],
+        /(?:Operation|Connection) timed out/i => [ConnectionError, :connection_timeout]
+      }.freeze
+      SSH_CONFIRMATION = %r{\(yes/no(?:/\[fingerprint\])?\)\?\s*\z}i
+
+      # 保存会话配置，并合并传输失败和设备认证失败模式。
+      def initialize(session, dialogue)
+        @session = session
+        @dialogue = dialogue
+        @config = session.configuration
+        @failures = CONNECTION_FAILURES.merge(
+          dialogue.authentication_errors.to_h { |pattern| [pattern, [AuthenticationError, :authentication_failed]] }
+        ).freeze
+      end
+
+      # 在登录提示或连接失败模式出现前读取登录响应。
+      def login
+        @session.reader.read(
+          prompt: @dialogue.login_prompt, interactions: login_interactions, failures: @failures,
+          timeout: @config.login_timeout, phase: :login
+        )
+      end
+
+      # 发送特权命令，并在截止时间内完成凭据交互。
+      def enable(command, prompt)
+        deadline = Expect.monotonic + @config.login_timeout
+        @session.write("#{command}\n", deadline: deadline, phase: :enable)
+        secret = @config.enable_password || @config.password
+        @session.reader.read(prompt: prompt, interactions: credential_interactions(secret), failures: @failures,
+                             deadline: deadline, phase: :enable)
+      end
+
+      private
+
+      # 为用户名和密码创建一次性敏感交互规则。
+      def credential_interactions(secret)
+        [
+          Interaction.new(@dialogue.username_prompt, ->(_prompt) { input_line(@config.username) },
+                          sensitive: true, limit: 1, capture: false),
+          Interaction.new(@dialogue.password_prompt, ->(_prompt) { input_line(secret) },
+                          sensitive: true, limit: 1, capture: false)
+        ]
+      end
+
+      # 组装主机密钥确认、厂商挑战和凭据交互。
+      def login_interactions
+        host_key = Interaction.new(SSH_CONFIRMATION, lambda { |_prompt|
+          if @config.host_key_policy == :strict
+            raise @session.build_error(ConnectionError, "host key confirmation rejected",
+                                       phase: :login, code: :host_key_untrusted), cause: nil
+          end
+          "yes\n"
+        }, limit: 1)
+        [host_key, *@dialogue.login_interactions, *@config.challenges.map(&:challenge),
+         *credential_interactions(@config.password)]
+      end
+
+      # 将可选凭据编码为带换行的设备输入。
+      def input_line(secret) = secret && "#{secret}\n"
+    end
+  end
+end

data/lib/netstack/connector/authentication_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Adapted from net-connector; copyright (c) 2026 net-connector contributors (MIT).
+
+require "expect/redactor"
+
+module Netstack
+  module Connector
+    class AuthenticationError < ConnectionError; end
+  end
+end