testprotocols 0.1.0__py3-none-any.whl

testprotocols/devices/traffic.py

@@ -0,0 +1,53 @@
+"""Traffic device archetypes — impairment injection and load generation."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.ip_interface import IpInterface
+from testprotocols.iperf_generator import IperfGenerator
+from testprotocols.netem_controller import NetemController
+from testprotocols.pcap_capture import PcapCapture
+from testprotocols.syslog_config import SyslogConfig
+
+
+@runtime_checkable
+class TrafficControllerDevice(BaseDeviceProtocol, Protocol):
+    """Traffic controller archetype — inline impairment injector.
+
+    Sits in the data path to apply latency, loss, jitter, and rate-limit
+    impairments via netem. Being inline on the path, it is also the device that
+    **captures** traffic crossing it (pcap) — the capture role the host/appliance
+    and switch archetypes deliberately exclude as "the TrafficControllerDevice's
+    job" (SPLITS.md). Also exposes IP interface management for placement on the
+    test topology.
+    """
+
+    netem: NetemController
+    ip_interface: IpInterface
+    pcap: PcapCapture
+    syslog: SyslogConfig
+    """Where this host forwards its syslog stream (management-plane telemetry).
+
+    Testbed-driven: the driver auto-applies the configured collector at
+    configure time; a testbed with no collector simply leaves it unset.
+    """
+
+
+@runtime_checkable
+class IperfTrafficGeneratorDevice(BaseDeviceProtocol, Protocol):
+    """Iperf traffic generator archetype — multi-flow load source.
+
+    Drives concurrent iperf flows (UDP / TCP, configurable rate / count) to
+    saturate or stress a path under test. IP interface management for
+    placement on the test topology.
+    """
+
+    iperf_generator: IperfGenerator
+    ip_interface: IpInterface
+
+
+register_device_type("linux_traffic_controller", TrafficControllerDevice)
+register_device_type("iperf_traffic_generator", IperfTrafficGeneratorDevice)

testprotocols/devices/voice.py

@@ -0,0 +1,69 @@
+"""Voice device archetypes — SIP phone and SIP server."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.dhcp_client import DhcpClient
+from testprotocols.file_transfer import FileTransfer
+from testprotocols.ip_interface import IpInterface
+from testprotocols.pcap_capture import PcapCapture
+from testprotocols.sip_phone import SipPhone
+from testprotocols.sip_server import SipServer
+
+
+@runtime_checkable
+class SipPhoneDevice(BaseDeviceProtocol, Protocol):
+    """SIP phone archetype — endpoint that registers with a SIP server and places calls.
+
+    Used to drive call-control scenarios (register / invite / cancel / bye) and
+    media-plane verification against a SIP server under test.
+
+    A phone has one or more SIP accounts (lines). Most testbeds run single-line
+    phones; multi-line phones expose additional entries in ``aors``.
+
+    ``aors`` is the list of registered SIP URIs in RFC 3261 §6 address-of-record
+    form (``sip:user@host`` with optional ``;params``). ``host`` may be an FQDN,
+    an IPv4 literal (``10.0.0.5``), or an IPv6 bracketed literal
+    (``[2001:db8::5]``) — the driver decides which form matches its testbed's
+    address-resolution context. The list is never empty; ``aors[0]`` is the
+    primary line that single-line operations (``sip_phone.dial``,
+    ``sip_phone.answer``, MWI subscriptions, …) act on.
+
+    ``number`` is the user-part of ``aors[0]`` — the SIP phone's E.164 /
+    dial-string identifier for its primary line. Provided as a convenience so
+    single-line callers don't have to parse SIP URIs.
+
+    ``device_name`` / ``device_type`` come from :class:`BaseDeviceProtocol`.
+    """
+
+    sip_phone: SipPhone
+    ip_interface: IpInterface
+    dhcp_client: DhcpClient
+    number: str
+    aors: list[str]
+
+
+@runtime_checkable
+class SipServerDevice(BaseDeviceProtocol, Protocol):
+    """SIP server archetype — registrar / proxy for SIP phones in voice tests.
+
+    Provides the server-side SIP surface plus packet capture and file transfer
+    for inspecting and exporting signalling exchanges.
+
+    ``aor_domain`` is the host part that callers should embed in SIP AORs
+    targeting this server (``sip:user@<aor_domain>``). May be an FQDN, an
+    IPv4 literal, or an IPv6 bracketed literal — the driver decides which
+    form matches its testbed's address-resolution context.
+    """
+
+    sip_server: SipServer
+    pcap: PcapCapture
+    file_transfer: FileTransfer
+    aor_domain: str
+
+
+register_device_type("linux_sip_phone", SipPhoneDevice)
+register_device_type("linux_sip_server", SipServerDevice)

testprotocols/devices/wan.py

@@ -0,0 +1,60 @@
+"""WAN device archetypes — upstream-side server endpoints for end-to-end tests."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.conntrack import Conntrack
+from testprotocols.devices import register_device_type
+from testprotocols.devices.base import BaseDeviceProtocol
+from testprotocols.dhcp_client import DhcpClient
+from testprotocols.dns_client import DnsClient
+from testprotocols.file_transfer import FileTransfer
+from testprotocols.http_client import HttpClient
+from testprotocols.http_server import HttpServer
+from testprotocols.ip_interface import IpInterface
+from testprotocols.ip_routing import IpRouting
+from testprotocols.iperf_client import IperfClient
+from testprotocols.iperf_server import IperfServer
+from testprotocols.nat import Nat
+from testprotocols.network_endpoint import NetworkEndpoint
+from testprotocols.network_probe import NetworkProbe
+from testprotocols.nmap_scanner import NmapScanner
+from testprotocols.ntp_client import NtpClient
+from testprotocols.packet_filter import PacketFilter
+from testprotocols.pcap_capture import PcapCapture
+from testprotocols.snmp_client import SnmpClient
+
+
+@runtime_checkable
+class WanServerDevice(BaseDeviceProtocol, Protocol):
+    """WAN server archetype — far-side host for end-to-end traffic and protocol tests.
+
+    Sits on the WAN side of the topology to act as the remote endpoint for
+    HTTP, DNS, iperf, NTP, and SNMP exchanges initiated from the LAN through a
+    CPE / SD-WAN router under test. Includes L3 (IP, routing, DHCP, NAT,
+    conntrack), packet capture, host packet-filtering, network scanning, and
+    file transfer for orchestration of test artefacts.
+    """
+
+    ip_interface: IpInterface
+    ip_routing: IpRouting
+    dhcp_client: DhcpClient
+    http_client: HttpClient
+    http_server: HttpServer
+    dns_client: DnsClient
+    iperf_client: IperfClient
+    iperf_server: IperfServer
+    pcap: PcapCapture
+    ntp_client: NtpClient
+    nmap_scanner: NmapScanner
+    file_transfer: FileTransfer
+    snmp_client: SnmpClient
+    packet_filter: PacketFilter
+    nat: Nat
+    conntrack: Conntrack
+    network_probe: NetworkProbe
+    data_plane_endpoint: NetworkEndpoint
+
+
+register_device_type("linux_wan_server", WanServerDevice)

testprotocols/dhcp_client.py

@@ -0,0 +1,30 @@
+"""DHCP / Client template.
+
+Defines the abstract contract for DHCP client operations including lease
+release and renewal for both IPv4 and IPv6.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DhcpClient(Protocol):
+    """Abstract contract for DHCP client operations."""
+
+    def release_dhcp(self, interface: str) -> None:
+        """Release the DHCPv4 lease on *interface*."""
+        ...
+
+    def renew_dhcp(self, interface: str) -> None:
+        """Renew the DHCPv4 lease on *interface*."""
+        ...
+
+    def release_ipv6(self, interface: str, stateless: bool = False) -> None:
+        """Release the DHCPv6 lease on *interface*."""
+        ...
+
+    def renew_ipv6(self, interface: str, stateless: bool = False) -> None:
+        """Renew the DHCPv6 lease on *interface*."""
+        ...

testprotocols/dhcp_server.py

@@ -0,0 +1,23 @@
+"""DHCP / Server template.
+
+Defines the abstract contract for DHCP server operations such as CPE
+provisioning.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DhcpServer(Protocol):
+    """Abstract contract for DHCP server operations."""
+
+    def provision_cpe(
+        self,
+        cpe_mac: str,
+        dhcpv4_options: dict[str, Any],
+        dhcpv6_options: dict[str, Any],
+    ) -> None:
+        """Provision a CPE device by MAC address with the given DHCP options."""
+        ...

testprotocols/discovery.py

@@ -0,0 +1,20 @@
+"""Read-only link-layer neighbour discovery (LLDP-normalized)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import LldpNeighbor
+
+
+@runtime_checkable
+class Discovery(Protocol):
+    """Abstract contract for neighbour discovery (read-only).
+
+    A product that also runs a proprietary discovery protocol maps its neighbour
+    data onto this LLDP-shaped read.
+    """
+
+    def get_neighbors(self, port: str | None = None) -> list[LldpNeighbor]:
+        """Return discovered neighbours, optionally filtered to one *port*."""
+        ...

testprotocols/dns_client.py

@@ -0,0 +1,23 @@
+"""DNS / Client template.
+
+Defines the abstract contract for DNS client operations including
+name resolution lookups.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DnsClient(Protocol):
+    """Abstract contract for DNS client operations."""
+
+    def dns_lookup(
+        self,
+        domain_name: str,
+        record_type: str,
+        opts: str = "",
+    ) -> list[dict[str, Any]]:
+        """Perform a DNS lookup for *domain_name* and return matching records."""
+        ...

testprotocols/file_transfer.py

@@ -0,0 +1,22 @@
+"""File Transfer template.
+
+Defines the abstract contract for file transfer operations including
+deletion and secure copy.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class FileTransfer(Protocol):
+    """Abstract contract for file transfer operations."""
+
+    def delete_file(self, filename: str) -> None:
+        """Delete *filename* from the device."""
+        ...
+
+    def scp_device_file_to_local(self, local_path: str, source_path: str) -> None:
+        """Copy *source_path* from the device to *local_path* via SCP."""
+        ...

testprotocols/firewall.py

@@ -0,0 +1,121 @@
+"""Firewall template — gateway-tier rule administration + port forwarding.
+
+Extends ``PacketFilter`` with port-forwarding methods (named external→internal
+port mappings, DMZ host). Models the OpenWrt-UCI ``firewall`` config and
+TR-181 ``Device.Firewall.*`` subtree as one coherent gateway subsystem:
+admins reason about packet rules and port forwards together, and an
+``iptables-save`` dump captures both in one stream.
+
+In scope: the full ``PacketFilter`` rule-lifecycle surface (inherited)
+plus port-mapping lifecycle and the single DMZ-host shortcut.
+
+Out of scope: low-level NAT primitives (see ``nat``), zone-based policy
+(see ``firewall_zones``), conntrack inspection (see ``conntrack``), and
+client-side UPnP-IGD rule injection (see ``upnp_client``).
+
+Devices that have rule administration but no port forwarding (clients,
+infra services) satisfy only the narrower ``PacketFilter`` Protocol; they
+should not be typed against ``Firewall``.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.firewall import PortMapping
+from testprotocols.packet_filter import PacketFilter
+
+
+@runtime_checkable
+class Firewall(PacketFilter, Protocol):
+    """Gateway-tier firewall: rule administration + port forwarding.
+
+    Liskov extension of ``PacketFilter``. Any driver satisfying ``Firewall``
+    automatically satisfies ``PacketFilter`` via Protocol inheritance.
+    """
+
+    # --- Port-mapping lifecycle ---
+
+    def add_port_mapping(self, mapping: PortMapping) -> None:
+        """Install a port mapping.
+
+        Raises ValueError on a duplicate ``mapping.name``, on
+        *external_port* / *internal_port* outside ``1..65535``, or on
+        *protocol* not in ``{"tcp", "udp", "tcp-udp"}``.
+        """
+        ...
+
+    def remove_port_mapping(self, name: str) -> None:
+        """Remove the port mapping identified by *name*.
+
+        Raises KeyError if no mapping with that name exists.
+        """
+        ...
+
+    def list_port_mappings(self) -> list[PortMapping]:
+        """Return all installed port mappings."""
+        ...
+
+    def get_port_mapping(self, name: str) -> PortMapping:
+        """Return the port mapping identified by *name*.
+
+        Raises KeyError if no mapping with that name exists.
+        """
+        ...
+
+    def set_port_mapping_enabled(self, name: str, enabled: bool) -> None:
+        """Enable or disable an existing port mapping without removing it.
+
+        Raises KeyError if no mapping with that name exists.
+        """
+        ...
+
+    # --- DMZ host ---
+
+    def set_dmz_host(self, host: str | None) -> None:
+        """Set the DMZ-host destination, or pass ``None`` to clear DMZ.
+
+        When set, all unsolicited inbound traffic that does not match
+        any other port mapping is forwarded to *host*.
+
+        Raises ValueError if *host* is not a parseable IP address.
+        """
+        ...
+
+    def get_dmz_host(self) -> str | None:
+        """Return the current DMZ host, or ``None`` if no DMZ host is set."""
+        ...
+
+
+@runtime_checkable
+class FirewallWhiteBox(Firewall, Protocol):
+    """White-box extension of Firewall for raw kernel-level introspection.
+
+    Linux drivers that can shell into the box satisfy this extension by
+    capturing the underlying iptables / nftables ruleset (which natively
+    covers both filter rules and DNAT / port-forward entries in one
+    serialisation). Vendor-RTOS or locked-down devices typically satisfy
+    only the base ``Firewall`` Protocol; tests requiring kernel-level
+    verification should pin against ``FirewallWhiteBox`` and accept the
+    collection-skip on drivers that don't satisfy it (per the
+    ``@white_box`` scenario tag rule).
+    """
+
+    def get_kernel_iptables_dump(self) -> str:
+        """Return the raw ``iptables-save`` output (legacy iptables backend).
+
+        For drivers running on a Linux kernel with the legacy iptables
+        backend. Format is the standard iptables-save serialisation,
+        spanning filter chains, NAT chains, and DNAT / port-forward
+        entries in one stream.
+        """
+        ...
+
+    def get_nftables_ruleset(self) -> str:
+        """Return the raw ``nft list ruleset`` output (nftables backend).
+
+        For drivers running on a Linux kernel with the nftables backend.
+        Format is the standard nftables ruleset serialisation, spanning
+        the full ruleset across all tables and families.
+        """
+        ...

testprotocols/firewall_zones.py

@@ -0,0 +1,133 @@
+"""Firewall / Zones template.
+
+Defines the abstract contract for zone-based firewall administration —
+the OpenWrt / firewalld / pfSense interface-group model in which traffic
+policy is expressed at the zone level rather than as flat chain rules.
+
+A zone groups one or more interfaces and / or CIDR networks under a
+shared default-input / default-forward / default-output action. Per-zone-
+pair forwarding policy controls fall-through traffic between zones; more
+specific rules go in the ``packet_filter`` template (or the inherited
+rule-administration surface on ``firewall.Firewall`` for gateway
+devices) — on a zone-aware device they target a zone instead of a
+chain, which drivers map internally.
+
+In scope: zone CRUD, interface / network membership, zone defaults,
+masquerade and MSS-clamping toggles, and zone-pair forwarding policy.
+
+Out of scope: per-flow filtering (see ``packet_filter`` / ``firewall``),
+NAT rules (see ``nat``), and per-zone counters (deferred — not all
+drivers expose them).
+
+Devices on a flat-chain firewall (no zones) should not compose this
+template; ``packet_filter`` (or ``firewall`` for gateways) alone is
+sufficient for them.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.firewall import Zone, ZonePolicy
+
+
+@runtime_checkable
+class FirewallZones(Protocol):
+    """Abstract contract for zone-based firewall administration."""
+
+    # --- Zone lifecycle ---
+
+    def create_zone(self, zone: Zone) -> None:
+        """Create a new zone.
+
+        Raises ValueError on a duplicate ``zone.name`` or on default
+        action values outside ``{"accept", "drop", "reject"}``.
+        """
+        ...
+
+    def delete_zone(self, name: str) -> None:
+        """Delete the zone identified by *name*.
+
+        Raises KeyError if no zone with that name exists.
+        """
+        ...
+
+    def list_zones(self) -> list[Zone]:
+        """Return all zones currently configured on the device."""
+        ...
+
+    def get_zone(self, name: str) -> Zone:
+        """Return the zone identified by *name*.
+
+        Raises KeyError if no zone with that name exists.
+        """
+        ...
+
+    # --- Membership ---
+
+    def add_zone_interface(self, zone_name: str, interface: str) -> None:
+        """Add *interface* to *zone_name*. No-op if already a member.
+
+        Raises KeyError if no zone with that name exists.
+        """
+        ...
+
+    def remove_zone_interface(self, zone_name: str, interface: str) -> None:
+        """Remove *interface* from *zone_name*. No-op if not a member.
+
+        Raises KeyError if no zone with that name exists.
+        """
+        ...
+
+    def add_zone_network(self, zone_name: str, cidr: str) -> None:
+        """Add the *cidr* network to *zone_name*. No-op if already a member.
+
+        Raises KeyError if no zone with that name exists.
+        Raises ValueError if *cidr* is malformed.
+        """
+        ...
+
+    def remove_zone_network(self, zone_name: str, cidr: str) -> None:
+        """Remove the *cidr* network from *zone_name*. No-op if not a member.
+
+        Raises KeyError if no zone with that name exists.
+        """
+        ...
+
+    # --- Per-zone defaults ---
+
+    def set_zone_defaults(
+        self,
+        zone_name: str,
+        *,
+        input_action: str | None = None,
+        forward_action: str | None = None,
+        output_action: str | None = None,
+        masquerade: bool | None = None,
+        mss_clamping: bool | None = None,
+    ) -> None:
+        """Update one or more default-policy fields of *zone_name*.
+
+        Only fields passed (non-None) are changed. Action values must be
+        one of ``"accept"``, ``"drop"``, ``"reject"``.
+
+        Raises KeyError if no zone with that name exists.
+        Raises ValueError on a bad action value.
+        """
+        ...
+
+    # --- Zone-pair forwarding ---
+
+    def set_forwarding(self, src_zone: str, dst_zone: str, action: str) -> None:
+        """Set the default forwarding action between *src_zone* and *dst_zone*.
+
+        *action* is one of ``"accept"``, ``"drop"``, ``"reject"``.
+
+        Raises KeyError if either zone is unknown.
+        Raises ValueError on a bad action value.
+        """
+        ...
+
+    def list_forwarding(self) -> list[ZonePolicy]:
+        """Return every configured zone-pair forwarding policy."""
+        ...

testprotocols/first_hop_security.py

@@ -0,0 +1,52 @@
+"""First-hop security — DHCP snooping + Dynamic ARP Inspection.
+
+Rogue-DHCP control is the DHCP-snooping *intent*: divergent vendor shapes
+(server allow/block, port-trust snooping, IMPB) normalize onto one surface.
+Per-port trust / rate-limit / binding-table read are optional sub-methods; a
+driver lacking one raises unsupported-capability rather than failing the
+baseline. IP Source Guard is a deferred optional extension (see GAPS.md).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import BindingSource, FhsBinding, FhsScope, FhsTrustState
+
+
+@runtime_checkable
+class FirstHopSecurity(Protocol):
+    """Abstract contract for DHCP snooping + Dynamic ARP Inspection."""
+
+    def set_dhcp_snooping(
+        self, scope: FhsScope, enabled: bool, vlan: int | None = None
+    ) -> None:
+        """Enable/disable DHCP snooping globally or per-VLAN. A switch-wide-only
+        product maps ``PER_VLAN`` to ``GLOBAL`` or raises unsupported-capability."""
+        ...
+
+    def set_dhcp_snooping_trust(self, port: str, trust: FhsTrustState) -> None:
+        """Set the per-port snooping trust state. Optional — unsupported-capability
+        where the product has no per-port trust (e.g. MAC allow/block only)."""
+        ...
+
+    def get_dhcp_bindings(self) -> list[FhsBinding]:
+        """Return the snooping binding table. Optional — unsupported-capability
+        where no binding table is published."""
+        ...
+
+    def set_dai(
+        self,
+        scope: FhsScope,
+        enabled: bool,
+        vlan: int | None = None,
+        binding_source: BindingSource = BindingSource.DYNAMIC_SNOOPING,
+    ) -> None:
+        """Enable/disable Dynamic ARP Inspection. Products without DAI raise
+        unsupported-capability."""
+        ...
+
+    def set_arp_trust(self, port: str, trust: FhsTrustState) -> None:
+        """Set the per-port ARP-inspection trust state. Optional — unsupported-capability
+        where the product has no per-port ARP trust."""
+        ...

testprotocols/gateway_redundancy.py

@@ -0,0 +1,29 @@
+"""First-hop gateway redundancy — virtual IP + role per group."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch_routing import RedundancyGroup
+
+
+@runtime_checkable
+class GatewayRedundancy(Protocol):
+    """Abstract contract for first-hop redundancy.
+
+    Normalized to a virtual-IP + role group so VRRP, HSRP, and warm-spare map
+    onto one concept. A product with no switch-side FHR raises
+    unsupported-capability.
+    """
+
+    def list_groups(self) -> list[RedundancyGroup]:
+        """Return every redundancy group."""
+        ...
+
+    def get_group(self, group_id: int) -> RedundancyGroup:
+        """Return the redundancy group *group_id*. Raises KeyError if absent."""
+        ...
+
+    def set_group(self, group: RedundancyGroup) -> None:
+        """Create or replace the redundancy group ``group.group_id``."""
+        ...

testprotocols/http_client.py

@@ -0,0 +1,36 @@
+"""HTTP / Client template.
+
+Defines the abstract contract for HTTP client operations including curl
+and GET requests.
+"""
+
+from __future__ import annotations
+
+from ipaddress import IPv4Address
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.networking import HTTPResult
+
+
+@runtime_checkable
+class HttpClient(Protocol):
+    """Abstract contract for HTTP client operations."""
+
+    def curl(
+        self,
+        url: str | IPv4Address,
+        protocol: str,
+        port: str | int | None = None,
+        options: str = "",
+    ) -> bool:
+        """Execute a curl request to *url* using *protocol*."""
+        ...
+
+    def http_get(
+        self,
+        url: str,
+        timeout: int = 20,
+        options: str = "",
+    ) -> HTTPResult:
+        """Perform an HTTP GET request to *url* and return the result."""
+        ...