testprotocols 0.1.0__py3-none-any.whl

testprotocols/models/wifi.py

@@ -0,0 +1,183 @@
+"""WiFi-domain data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class WifiDfsState:
+    """DFS state of a radio.
+
+    A radio is in CAC for ~60s after tuning to a DFS channel; during CAC it
+    cannot transmit. Channels on which radar was recently detected enter the
+    Non-Occupancy List for ~30 minutes and are unavailable until the NOL ages out.
+    """
+
+    is_in_cac: bool
+    cac_remaining_seconds: int | None  # None when not in CAC
+    nol_channels: list[int] = field(default_factory=list[int])
+
+
+@dataclass
+class WifiCaptiveConfig:
+    """Per-BSS captive-portal state."""
+
+    enabled: bool
+    redirect_url: str | None
+
+
+@dataclass
+class WifiBssConfig:
+    """Configuration of a single BSS, as returned by WifiBss read methods.
+
+    *passphrase* is intentionally absent — write-only across the contract.
+    """
+
+    name: str  # stable logical handle
+    band: str
+    ssid: str  # broadcast SSID string
+    bssid: str  # MAC address assigned to this BSS
+    enabled: bool
+    broadcast_enabled: bool
+    security_mode: str
+    radius_server_name: str | None  # references RadiusClient registry; None when not Enterprise
+    mfp: str  # "off" | "optional" | "required"
+    vlan_id: int | None
+    max_clients: int | None
+    dtim_period: int
+    captive_portal: WifiCaptiveConfig
+
+
+@dataclass
+class WifiStation:
+    """An associated station's identity, capabilities, and current stats.
+
+    Stats are point-in-time snapshots; cumulative counters (bytes, packets,
+    retries) are since the start of the current association.
+    """
+
+    mac: str  # canonical: lowercase colon-separated
+    bss_name: str  # logical BSS handle the station is associated to
+    band: str  # "2.4GHz" / "5GHz" / "6GHz"
+    ip_address: str | None  # station's IP if known to the AP (e.g. via DHCP snooping)
+    associated_since: float  # Unix timestamp
+    rssi_dbm: int
+    snr_db: int | None  # None if the driver doesn't report SNR
+    tx_rate_mbps: float  # last known PHY rate AP -> station
+    rx_rate_mbps: float  # last known PHY rate station -> AP
+    tx_bytes: int
+    rx_bytes: int
+    tx_packets: int
+    rx_packets: int
+    tx_retries: int
+    capability_flags: list[str] = field(default_factory=list[str])
+    # capability_flags examples: ["HT", "VHT", "HE"], or ["EHT", "MLO"] for Wi-Fi 7
+
+
+@dataclass
+class WifiAcl:
+    """Per-BSS MAC access-control list state."""
+
+    bss_name: str
+    mode: str  # "disabled" | "allow" | "deny"
+    # MACs, canonical lowercase colon-separated
+    entries: list[str] = field(default_factory=list[str])
+
+
+@dataclass
+class WifiNeighbor:
+    """A neighbour BSS observed by an off-channel scan."""
+
+    bssid: str  # MAC, canonical lowercase colon-separated
+    ssid: str  # may be empty for hidden SSIDs
+    band: str  # the band the scanner observed it on
+    channel: int  # operating channel of the neighbour
+    rssi_dbm: int
+    security_mode: str  # best-effort identification
+    last_seen: float  # Unix timestamp of the last beacon/probe-response
+
+
+@dataclass
+class WifiChannelUtilization:
+    """Per-radio channel-utilization breakdown.
+
+    All fields are 0-100. ``busy_pct`` is always populated; the
+    component splits (tx/rx/interference) are populated only on drivers
+    that report them separately.
+    """
+
+    band: str
+    busy_pct: int  # total channel occupancy
+    tx_pct: int | None  # own transmissions
+    rx_pct: int | None  # all reception (own BSS + neighbours)
+    interference_pct: int | None  # non-WiFi interference, where the driver can distinguish
+
+
+@dataclass
+class WifiRadioStats:
+    """Cumulative per-radio TX/RX/retry counters."""
+
+    band: str
+    tx_bytes: int
+    rx_bytes: int
+    tx_packets: int
+    rx_packets: int
+    tx_retries: int  # retransmitted frames
+    tx_failed: int  # frames the driver gave up on (max retries exceeded)
+
+
+@dataclass
+class WifiTransitionConfig:
+    """Per-BSS k/v/r configuration snapshot."""
+
+    bss_name: str
+    rrm_enabled: bool  # 802.11k
+    btm_enabled: bool  # 802.11v
+    ft_enabled: bool  # 802.11r
+    # 802.11r over-the-DS (True) vs over-the-air (False); meaningful only when ft_enabled
+    ft_over_ds: bool
+
+
+@dataclass
+class WifiMeshLink:
+    """A wireless backhaul link between mesh agents."""
+
+    band: str  # "2.4GHz" / "5GHz" / "6GHz"
+    channel: int
+    rssi_dbm: int  # signal strength on the link
+    capacity_mbps: float  # estimated PHY-rate capacity in Mbps
+
+
+@dataclass
+class WifiMeshStatus:
+    """A mesh participant's local status snapshot."""
+
+    # "controller" | "agent" | "controller-and-agent" | "uncommissioned"
+    role: str
+    enabled: bool
+    parent_mac: str | None  # MAC of this agent's parent; None for the controller / root
+    hop_count: int  # 0 for the controller; N for an agent N hops away
+    backhaul_link: WifiMeshLink | None  # None when no uplink (root) or mesh disabled
+
+
+@dataclass
+class WifiMeshNode:
+    """Identity and position of a mesh agent in the topology."""
+
+    mac: str  # canonical lowercase colon-separated
+    role: str  # "controller" | "agent" | "controller-and-agent"
+    parent_mac: str | None  # None for the controller / root
+    hop_count: int
+
+
+@dataclass
+class WifiMeshTopology:
+    """The mesh as known to the querying participant.
+
+    Controllers populate the full agent list; pure agents populate
+    only the parent + any peers they directly observe.
+    """
+
+    controller_mac: str
+    agents: list[WifiMeshNode] = field(default_factory=list[WifiMeshNode])

testprotocols/multicast_client.py

@@ -0,0 +1,20 @@
+"""Multicast client template.
+
+Defines the abstract contract for sending multicast group membership reports
+from a test client device.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.multicast import MulticastGroupRecord
+
+
+@runtime_checkable
+class MulticastClient(Protocol):
+    """Abstract contract for multicast client operations."""
+
+    def send_mldv2_report(self, mcast_group_record: MulticastGroupRecord, count: int) -> None:
+        """Send *count* MLDv2 membership report packets for the given group records."""
+        ...

testprotocols/nat.py

@@ -0,0 +1,87 @@
+"""Firewall / NAT template.
+
+Defines the abstract contract for low-level NAT primitives — SNAT,
+DNAT, and 1:1 / static NAT. Rules are identified by a stable logical
+*name* and expressed as transport-agnostic ``NatRule`` records.
+
+In scope: rule lifecycle (add / remove / list / get / flush), enable
+toggles, and per-rule packet/byte counters.
+
+Out of scope: high-level / named port-forwarding entries (see the
+port-mapping surface on ``firewall.Firewall``), packet-filter rules
+(see ``packet_filter`` or the rule-administration surface inherited
+by ``firewall.Firewall``), and zone-level masquerade (a per-zone flag
+on ``firewall_zones``).
+
+NAT and packet-filter rules are kept in separate templates because a
+device may legitimately compose one without the other (e.g. a transit
+router does NAT only; a host firewall does packet-filter only).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.firewall import NatRule
+
+
+@runtime_checkable
+class Nat(Protocol):
+    """Abstract contract for low-level NAT primitives."""
+
+    # --- Rule lifecycle ---
+
+    def add_nat_rule(self, rule: NatRule) -> None:
+        """Install a NAT rule.
+
+        Validates that *rule.mode* is one of ``"snat"``, ``"dnat"``,
+        ``"1to1"`` and that the per-mode field invariants hold (see
+        ``NatRule`` docstring). Raises ValueError on a duplicate
+        ``rule.name``, on an unknown mode, or on mode/field
+        inconsistency (e.g. *translated_src* set with ``mode="dnat"``).
+        """
+        ...
+
+    def remove_nat_rule(self, name: str) -> None:
+        """Remove the NAT rule identified by *name*.
+
+        Raises KeyError if no rule with that name exists.
+        """
+        ...
+
+    def list_nat_rules(self, mode: str | None = None) -> list[NatRule]:
+        """Return installed NAT rules, optionally filtered by *mode*.
+
+        *mode* is one of ``None`` (all), ``"snat"``, ``"dnat"``,
+        ``"1to1"``. Raises ValueError if *mode* is set but not one of
+        the recognized values.
+        """
+        ...
+
+    def get_nat_rule(self, name: str) -> NatRule:
+        """Return the NAT rule identified by *name*.
+
+        Raises KeyError if no rule with that name exists.
+        """
+        ...
+
+    def set_nat_rule_enabled(self, name: str, enabled: bool) -> None:
+        """Enable or disable an existing NAT rule without removing it.
+
+        Raises KeyError if no rule with that name exists.
+        """
+        ...
+
+    def flush_nat_rules(self) -> None:
+        """Remove every NAT rule on this device."""
+        ...
+
+    # --- Counters ---
+
+    def get_nat_rule_counters(self, name: str) -> tuple[int, int]:
+        """Return ``(packets, bytes)`` matched by the rule since it was added.
+
+        Raises KeyError if no rule with that name exists.
+        Drivers without per-rule counter support raise NotImplementedError.
+        """
+        ...

testprotocols/netem_controller.py

@@ -0,0 +1,42 @@
+"""Traffic / NetemController template.
+
+Defines the abstract contract for network emulation (netem) impairment
+control on device interfaces.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from testprotocols.models.impairment import ImpairmentProfile
+
+
+@runtime_checkable
+class NetemController(Protocol):
+    """Abstract contract for netem-based network impairment control."""
+
+    def set_impairment_profile(self, profile: ImpairmentProfile | dict[str, Any]) -> None:
+        """Apply *profile* as the default impairment on all managed interfaces."""
+        ...
+
+    def set_interface_profile(
+        self, interface: str, profile: ImpairmentProfile | dict[str, Any]
+    ) -> None:
+        """Apply *profile* as the impairment on a specific *interface*."""
+        ...
+
+    def get_interface_profile(self, interface: str) -> ImpairmentProfile:
+        """Return the current impairment profile for *interface*."""
+        ...
+
+    def get_interface_profiles(self) -> dict[str, ImpairmentProfile]:
+        """Return a mapping of interface names to their current impairment profiles."""
+        ...
+
+    def clear(self) -> None:
+        """Remove all active impairments from all managed interfaces."""
+        ...
+
+    def inject_transient(self, event: str, duration_ms: int, **kwargs: float | int) -> None:
+        """Inject a transient impairment *event* lasting *duration_ms* milliseconds."""
+        ...

testprotocols/network_endpoint.py

@@ -0,0 +1,32 @@
+"""Network endpoint template.
+
+Defines the abstract contract for a *logical* network endpoint's identity
+— the address a peer would use to reach a device's named role (the CPE's
+WAN side, a server's data-plane interface, etc.). Distinct from
+``IpInterface``, which is the per-physical-interface query surface:
+``NetworkEndpoint`` is what the test wants ("give me the WAN address"),
+``IpInterface`` is one of the things a driver might use under the hood
+to satisfy it.
+
+Drivers attach one ``NetworkEndpoint`` per logical role they expose, so
+the device shape remains a clean aggregation of capability namespaces
+rather than accreting role-specific accessor methods.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NetworkEndpoint(Protocol):
+    """Abstract contract for a logical network endpoint's identity."""
+
+    def get_ipv4_addr(self) -> str:
+        """Return the IPv4 address for this logical endpoint.
+
+        The resolution strategy is driver-internal: it may query a live
+        interface, read inventory metadata, lift a value from a TR-069
+        data model, etc. Callers see only the address.
+        """
+        ...

testprotocols/network_probe.py

@@ -0,0 +1,27 @@
+"""Network reachability probe template.
+
+Defines the abstract contract for L3/L4 reachability checks initiated from
+a host toward an external target. Distinct from ``HttpClient`` (which is
+app-layer): a ``NetworkProbe`` verifies whether the SYN/ACK handshake
+completes, not whether an HTTP responder is configured at the far end.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NetworkProbe(Protocol):
+    """Abstract contract for L3/L4 reachability probes."""
+
+    def tcp_can_connect(self, host: str, port: int, timeout: int = 5) -> bool:
+        """Attempt a TCP connection to *host*:*port* and return reachability.
+
+        Returns ``True`` if the three-way handshake completes within
+        *timeout* seconds, ``False`` otherwise (connection refused, no
+        route, filtered, timed out). The probe is read-only — no data is
+        sent on the connection — so it is safe to call against arbitrary
+        targets without side effects on the destination.
+        """
+        ...

testprotocols/nmap_scanner.py

@@ -0,0 +1,27 @@
+"""Nmap / Scanner template.
+
+Defines the abstract contract for network scanning operations using nmap.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NmapScanner(Protocol):
+    """Abstract contract for nmap network scanning operations."""
+
+    def nmap(
+        self,
+        ipaddr: str,
+        ip_type: str,
+        port: str | int | None = None,
+        protocol: str | None = None,
+        max_retries: int | None = None,
+        min_rate: int | None = None,
+        opts: str | None = None,
+        timeout: int = 30,
+    ) -> dict[str, Any]:
+        """Run an nmap scan against *ipaddr* and return the parsed results."""
+        ...

testprotocols/ntp_client.py

@@ -0,0 +1,26 @@
+"""NTP / Client template.
+
+Defines the abstract contract for NTP client operations including
+date retrieval, date setting, and time synchronisation.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NtpClient(Protocol):
+    """Abstract contract for NTP client operations."""
+
+    def get_date(self) -> str | None:
+        """Return the current date/time string from the device."""
+        ...
+
+    def set_date(self, opt: str, date_string: str) -> bool:
+        """Set the device date/time using *opt* and *date_string*."""
+        ...
+
+    def execute_time_sync(self, time_server: str) -> str:
+        """Synchronise device time against *time_server* and return status."""
+        ...

testprotocols/ntp_config.py

@@ -0,0 +1,25 @@
+"""NTP-server configuration — the time-sync sibling of syslog_config.
+
+Small and generic. Distinct from the operational ``ntp_client`` (get/set/sync
+time): this is server-list config. A cloud-managed product that sets time
+itself (timezone-only) raises unsupported-capability.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import NtpServer
+
+
+@runtime_checkable
+class NtpConfig(Protocol):
+    """Abstract contract for NTP-server configuration."""
+
+    def set_ntp_servers(self, servers: list[NtpServer]) -> None:
+        """Replace the NTP-server list."""
+        ...
+
+    def get_ntp_servers(self) -> list[NtpServer]:
+        """Return the configured NTP servers."""
+        ...

testprotocols/ospf.py

@@ -0,0 +1,24 @@
+"""OSPF dynamic-routing configuration (whole-config replace)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch_routing import OspfConfig
+
+
+@runtime_checkable
+class Ospf(Protocol):
+    """Abstract contract for OSPF configuration.
+
+    A product that runs OSPF only on a gateway (not the L3 switch) raises
+    unsupported-capability.
+    """
+
+    def set_ospf_config(self, config: OspfConfig) -> None:
+        """Replace the OSPF configuration."""
+        ...
+
+    def get_ospf_config(self) -> OspfConfig:
+        """Return the OSPF configuration."""
+        ...

testprotocols/packet_filter.py

@@ -0,0 +1,144 @@
+"""Firewall / PacketFilter template.
+
+Defines the abstract contract for stateless and stateful packet-filtering
+rules on a device's INPUT, OUTPUT, and FORWARD paths. Rules are addressed
+by a stable logical *name* and expressed as transport-agnostic
+``FirewallRule`` records — drivers translate into iptables, nftables,
+pf, or vendor CLI as appropriate.
+
+In scope: per-chain rule administration (add / remove / list / get /
+flush), chain default-policy control, and per-rule packet/byte counters.
+
+Out of scope: NAT (see ``nat``), high-level port forwarding (see the
+``Firewall`` Protocol in ``firewall``, which extends ``PacketFilter``
+with port-mapping methods), conntrack inspection (see ``conntrack``),
+zone-based policy (see ``firewall_zones``), and L7 application-aware
+classification (see ``l7_firewall`` for managed appliances).
+
+The IPv4 / IPv6 split is not a contract dimension — each rule's address
+family is inferred from its CIDR fields. Drivers that maintain separate
+v4/v6 tables internally do so transparently.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.firewall import FirewallRule
+
+
+@runtime_checkable
+class PacketFilter(Protocol):
+    """Abstract contract for stateless / stateful packet filtering."""
+
+    # --- Rule lifecycle ---
+
+    def add_rule(
+        self,
+        chain: str,
+        rule: FirewallRule,
+        position: int | None = None,
+    ) -> None:
+        """Insert *rule* into *chain* at *position*.
+
+        *chain* is one of ``"INPUT"``, ``"OUTPUT"``, ``"FORWARD"``.
+        *position* is 1-based: ``1`` inserts at the top, ``None`` appends
+        at the end.
+
+        Raises ValueError if *chain* is unknown, if a rule named
+        ``rule.name`` already exists in *chain*, or if *position* is
+        less than 1.
+        """
+        ...
+
+    def remove_rule(self, chain: str, name: str) -> None:
+        """Remove the rule identified by *name* from *chain*.
+
+        Raises ValueError if *chain* is unknown.
+        Raises KeyError if no rule with that name exists in *chain*.
+        """
+        ...
+
+    def list_rules(self, chain: str) -> list[FirewallRule]:
+        """Return all rules currently installed in *chain*, in evaluation order.
+
+        Raises ValueError if *chain* is unknown.
+        """
+        ...
+
+    def get_rule(self, chain: str, name: str) -> FirewallRule:
+        """Return the rule identified by *name* in *chain*.
+
+        Raises ValueError if *chain* is unknown.
+        Raises KeyError if no rule with that name exists in *chain*.
+        """
+        ...
+
+    def flush_chain(self, chain: str) -> None:
+        """Remove every rule from *chain*. Default policy is unchanged.
+
+        Raises ValueError if *chain* is unknown.
+        """
+        ...
+
+    # --- Default policy ---
+
+    def set_default_policy(self, chain: str, policy: str) -> None:
+        """Set the default action for traffic on *chain* that matches no rule.
+
+        *policy* is one of ``"accept"``, ``"drop"``, ``"reject"``.
+        Raises ValueError if *chain* is unknown or *policy* is not
+        a valid value.
+        """
+        ...
+
+    def get_default_policy(self, chain: str) -> str:
+        """Return the current default policy of *chain*.
+
+        Raises ValueError if *chain* is unknown.
+        """
+        ...
+
+    # --- Counters ---
+
+    def get_rule_counters(self, chain: str, name: str) -> tuple[int, int]:
+        """Return ``(packets, bytes)`` matched by the rule since it was added.
+
+        Raises ValueError if *chain* is unknown.
+        Raises KeyError if no rule with that name exists in *chain*.
+        Drivers without per-rule counter support raise NotImplementedError.
+        """
+        ...
+
+
+@runtime_checkable
+class PacketFilterWhiteBox(PacketFilter, Protocol):
+    """White-box extension of PacketFilter for raw kernel-level introspection.
+
+    Linux drivers that can shell into the box satisfy this extension by
+    capturing the underlying iptables / nftables ruleset. Vendor-RTOS or
+    locked-down devices typically satisfy only the base ``PacketFilter``
+    Protocol; tests requiring kernel-level rule verification should pin
+    against ``PacketFilterWhiteBox`` 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. Tests
+        parse this to verify rules landed at the kernel level rather than
+        only in the driver's intermediate state.
+        """
+        ...
+
+    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. Returns
+        the entire ruleset across all tables and families; tests grep
+        for the rules they care about.
+        """
+        ...

testprotocols/pcap_capture.py

@@ -0,0 +1,39 @@
+"""Pcap / Capture template.
+
+Defines the abstract contract for packet capture operations using
+tcpdump and tshark.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PcapCapture(Protocol):
+    """Abstract contract for packet capture operations."""
+
+    def start_tcpdump(
+        self,
+        interface: str,
+        port: str | None,
+        output_file: str = "pkt_capture.pcap",
+        filters: dict[str, Any] | None = None,
+        additional_filters: str | None = "",
+    ) -> str:
+        """Start a tcpdump capture on *interface* and return the process identifier."""
+        ...
+
+    def stop_tcpdump(self, process_id: str) -> None:
+        """Stop the tcpdump process identified by *process_id*."""
+        ...
+
+    def tshark_read_pcap(
+        self,
+        fname: str,
+        additional_args: str | None = None,
+        timeout: int = 30,
+        rm_pcap: bool = False,
+    ) -> str:
+        """Read and parse pcap file *fname* using tshark and return the output."""
+        ...