testprotocols 0.1.0__py3-none-any.whl

testprotocols/switch_ports.py

@@ -0,0 +1,28 @@
+"""Switchport configuration — the first-class object of a managed switch.
+
+Per-port access/trunk mode, native (PVID) + allowed VLANs, enable state, voice
+VLAN, and isolation. Read via a port listing; configured per whole-port object.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import SwitchPort
+
+
+@runtime_checkable
+class SwitchPorts(Protocol):
+    """Abstract contract for per-port switchport configuration."""
+
+    def list_ports(self) -> list[SwitchPort]:
+        """Return every switchport."""
+        ...
+
+    def get_port(self, name: str) -> SwitchPort:
+        """Return the port *name*. Raises KeyError if absent."""
+        ...
+
+    def set_port(self, port: SwitchPort) -> None:
+        """Create or replace the port identified by ``port.name``."""
+        ...

testprotocols/switch_qos.py

@@ -0,0 +1,33 @@
+"""Switch QoS — classification rules, DSCP->CoS map, and trust mode."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import QosRule, QosTrustMode
+
+
+@runtime_checkable
+class SwitchQos(Protocol):
+    """Abstract contract for switch QoS.
+
+    Explicit queue-scheduler / per-port rate-limit tuning is out of scope
+    (deferred); a product with limited scheduler control normalizes to
+    rules + trust/map.
+    """
+
+    def set_trust_mode(self, port: str, mode: QosTrustMode) -> None:
+        """Set the QoS trust mode on *port*."""
+        ...
+
+    def set_dscp_cos_map(self, mapping: dict[int, int]) -> None:
+        """Replace the DSCP->CoS map."""
+        ...
+
+    def set_rules(self, rules: list[QosRule]) -> None:
+        """Replace the ordered QoS classification rule list."""
+        ...
+
+    def get_rules(self) -> list[QosRule]:
+        """Return the QoS classification rules."""
+        ...

testprotocols/switch_vlans.py

@@ -0,0 +1,34 @@
+"""VLAN id/name registry for a managed switch.
+
+A switch VLAN registry tracks id/name membership and port assignment; this is
+distinct from an appliance VLAN surface, which pairs each VLAN with an SVI,
+DHCP scope, and routing policy. Keeping them separate lets each capability
+protocol stay minimal and composable.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import VlanDef
+
+
+@runtime_checkable
+class SwitchVlans(Protocol):
+    """Abstract contract for the switch VLAN registry."""
+
+    def list_vlans(self) -> list[VlanDef]:
+        """Return every configured VLAN."""
+        ...
+
+    def create_vlan(self, vlan: VlanDef) -> None:
+        """Create or rename the VLAN ``vlan.vlan_id``.
+
+        A driver whose product treats VLANs as implicit (no first-class CRUD)
+        raises unsupported-capability here.
+        """
+        ...
+
+    def delete_vlan(self, vlan_id: int) -> None:
+        """Delete VLAN *vlan_id*. Raises unsupported-capability where VLANs are implicit."""
+        ...

testprotocols/syslog_config.py

@@ -0,0 +1,31 @@
+"""Syslog-destination template.
+
+Defines the abstract contract for configuring where a device sends its syslog
+streams and which log roles each destination receives. Small and generic — any
+networked device with remote logging can satisfy it — scoped here to the SD-WAN
+appliance archetype where event/flow/security logging drives test evidence.
+
+In scope: read/replace the syslog-server list.
+
+Out of scope: reading the log contents themselves (that is the collector's job /
+the realtime-syslog path), and security-event retrieval (see ``threat_prevention``).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import SyslogServer
+
+
+@runtime_checkable
+class SyslogConfig(Protocol):
+    """Abstract contract for configuring syslog destinations."""
+
+    def set_syslog_servers(self, servers: list[SyslogServer]) -> None:
+        """Replace the configured syslog-destination list with *servers*."""
+        ...
+
+    def get_syslog_servers(self) -> list[SyslogServer]:
+        """Return the configured syslog destinations."""
+        ...

testprotocols/tftp_server.py

@@ -0,0 +1,22 @@
+"""TFTP / Server template.
+
+Defines the abstract contract for TFTP server operations including
+image download and lighttpd service management.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TftpServer(Protocol):
+    """Abstract contract for TFTP server operations."""
+
+    def download_image_from_uri(self, image_uri: str) -> str:
+        """Download an image from *image_uri* and return the local path."""
+        ...
+
+    def restart_lighttpd(self) -> None:
+        """Restart the lighttpd service on the TFTP server."""
+        ...

testprotocols/threat_prevention.py

@@ -0,0 +1,60 @@
+"""Threat-prevention template — IDS/IPS, anti-malware, and security events.
+
+Defines the abstract contract for a managed SD-WAN appliance's threat-prevention
+subsystem: configuring intrusion detection/prevention and anti-malware, and
+reading back security events.
+
+Security-event reads here are the *deferred*, settle-aware augmentation surface;
+realtime assertions in a testbed should still use the syslog backbone. Events
+carry only normalized fields (action + category, not vendor signature ids).
+
+In scope: intrusion mode/sensitivity, malware mode, security-event retrieval.
+
+Out of scope: firewall rules (see ``l3_firewall`` / ``l7_firewall``), content
+filtering (see ``content_filtering``), and syslog destination config (see
+``syslog_config``).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import (
+    IntrusionConfig,
+    IntrusionMode,
+    IntrusionSensitivity,
+    MalwareConfig,
+    MalwareMode,
+    SecurityEvent,
+)
+
+
+@runtime_checkable
+class ThreatPrevention(Protocol):
+    """Abstract contract for an appliance's IDS/IPS + anti-malware subsystem."""
+
+    def set_intrusion(
+        self, mode: IntrusionMode, sensitivity: IntrusionSensitivity | None = None
+    ) -> None:
+        """Set the IDS/IPS *mode* and optional ruleset *sensitivity*."""
+        ...
+
+    def get_intrusion(self) -> IntrusionConfig:
+        """Return the current IDS/IPS configuration."""
+        ...
+
+    def set_malware(self, mode: MalwareMode) -> None:
+        """Enable or disable anti-malware protection."""
+        ...
+
+    def get_malware(self) -> MalwareConfig:
+        """Return the current anti-malware configuration."""
+        ...
+
+    def get_security_events(self, since_s: int = 3600) -> list[SecurityEvent]:
+        """Return security events from the last *since_s* seconds.
+
+        Deferred / settle-aware augmentation surface — not the realtime
+        assertion path. Empty list when none.
+        """
+        ...

testprotocols/tr069_client.py

@@ -0,0 +1,47 @@
+"""TR-069 CPE client template.
+
+Defines the abstract contract for TR-069 client operations on a CPE
+device — the CPE-side counterpart to the ACS-side ``Tr069Server``
+Protocol. Covers connection status, log retrieval, the CPE's own
+identity, and the ability to force an immediate Inform.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Tr069Client(Protocol):
+    """Abstract contract for TR-069 client operations on a CPE device."""
+
+    def is_tr069_connected(self) -> bool:
+        """Return True if the CPE has an active TR-069 connection to the ACS."""
+        ...
+
+    def get_tr069_log(self) -> list[str]:
+        """Return the TR-069 client log as a list of log lines."""
+        ...
+
+    def get_id(self) -> str:
+        """Return the CPE's TR-069 device identifier as known to the ACS.
+
+        Per CWMP §A.3.3.1 this is the ``OUI-ProductClass-SerialNumber``
+        tuple the CPE uses in its Inform header. The ACS uses this as
+        its primary key when storing the per-CPE record. Implementations
+        should source the value from the CPE itself (e.g. the CWMP
+        daemon's UCI config) rather than from external inventory, so
+        the value is always self-consistent with what the ACS sees.
+        """
+        ...
+
+    def force_inform(self) -> None:
+        """Trigger an immediate Inform to the ACS, bypassing the periodic schedule.
+
+        Used to make queued ACS-side tasks execute promptly instead of
+        waiting for the next periodic Inform window (typically 300s).
+        Implementations route through whatever CWMP daemon ipc the CPE
+        provides (``ubus call tr069 inform`` on prplOS/iCWMPD, the
+        equivalent on other daemons).
+        """
+        ...

testprotocols/tr069_server.py

@@ -0,0 +1,151 @@
+"""TR-069 ACS server template.
+
+Defines the abstract contract for TR-069 ACS (Auto Configuration Server)
+operations, including all standard CWMP RPC methods and ACS-side state
+(inventory, per-CPE connection status, Inform timing).
+
+"CPE" follows TR-069 §2: any CWMP-managed device — gateway, set-top box,
+VoIP ATA, femtocell, IoT endpoint — not specifically a residential
+gateway.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from testprotocols.models.tr069 import CpeConnectionStatus
+
+
+@runtime_checkable
+class Tr069Server(Protocol):
+    """Abstract contract for TR-069 ACS operations."""
+
+    def GPV(
+        self,
+        param: str | list[str],
+        timeout: int | None = None,
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """GetParameterValues RPC."""
+        ...
+
+    def SPV(
+        self,
+        param_value: dict[str, Any] | list[dict[str, Any]],
+        timeout: int | None = None,
+        cpe_id: str | None = None,
+    ) -> int:
+        """SetParameterValues RPC."""
+        ...
+
+    def GPA(
+        self,
+        param: str,
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """GetParameterAttributes RPC."""
+        ...
+
+    def SPA(
+        self,
+        param: list[dict[str, Any]] | dict[str, Any],
+        notification_param: bool = True,
+        access_param: bool = False,
+        access_list: list[Any] | None = None,
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """SetParameterAttributes RPC."""
+        ...
+
+    def FactoryReset(self, cpe_id: str | None = None) -> list[dict[str, Any]]:
+        """FactoryReset RPC."""
+        ...
+
+    def Reboot(
+        self,
+        CommandKey: str = "reboot",
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Reboot RPC."""
+        ...
+
+    def AddObject(
+        self,
+        param: str,
+        param_key: str = "",
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """AddObject RPC."""
+        ...
+
+    def DelObject(
+        self,
+        param: str,
+        param_key: str = "",
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """DeleteObject RPC."""
+        ...
+
+    def GPN(
+        self,
+        param: str,
+        next_level: bool,
+        timeout: int | None = None,
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """GetParameterNames RPC."""
+        ...
+
+    def ScheduleInform(
+        self,
+        CommandKey: str = "Test",
+        DelaySeconds: int = 20,
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """ScheduleInform RPC."""
+        ...
+
+    def GetRPCMethods(self, cpe_id: str | None = None) -> list[dict[str, Any]]:
+        """GetRPCMethods RPC."""
+        ...
+
+    def Download(
+        self,
+        url: str,
+        filetype: str = "1 Firmware Upgrade Image",
+        targetfilename: str = "",
+        filesize: int = 200,
+        username: str = "",
+        password: str = "",
+        commandkey: str = "",
+        delayseconds: int = 10,
+        successurl: str = "",
+        failureurl: str = "",
+        cpe_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Download RPC."""
+        ...
+
+    def provision_cpe_via_tr069(
+        self,
+        tr069provision_api_list: list[dict[str, list[dict[str, str]]]],
+        cpe_id: str,
+    ) -> None:
+        """Provision a CPE by executing a sequence of TR-069 API calls."""
+        ...
+
+    def list_cpes(
+        self,
+        criteria: dict[str, str] | None = None,
+    ) -> list[str]:
+        """Return CPE IDs known to the ACS, optionally filtered by criteria."""
+        ...
+
+    def delete_cpe_record(self, cpe_id: str) -> bool:
+        """Delete the CPE record from the ACS inventory. Return True on success."""
+        ...
+
+    def get_cpe_connection_status(self, cpe_id: str) -> CpeConnectionStatus:
+        """Return the ACS-side view of the CPE's connection state and cached metadata."""
+        ...

testprotocols/traffic_shaping.py

@@ -0,0 +1,54 @@
+"""Traffic-shaping template — managed SD-WAN appliance.
+
+Defines the abstract contract for an appliance's bandwidth and QoS shaping:
+per-uplink bandwidth caps, a global per-client cap, and an ordered set of
+shaping rules that match a traffic class and limit / DSCP-mark / prioritize it.
+
+In scope: uplink bandwidth, global per-client bandwidth, and the shaping-rule
+list (which also carries DSCP marking).
+
+Support note: per-uplink caps, shaping rules, and DSCP marking are universal
+across reviewed appliance families; the **global per-client cap is not** —
+several families expose no per-client/per-host primitive, and their drivers
+raise unsupported-capability on the per-client methods (a coverage gap, not
+a contract leak).
+
+Out of scope: SD-WAN path selection / SLA steering (see ``sdwan_policy_manager``),
+firewall rules (see ``l3_firewall`` / ``l7_firewall``), and link impairment
+(``netem`` lives on the traffic-controller device, not the appliance).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import ShapingRule
+
+
+@runtime_checkable
+class TrafficShaping(Protocol):
+    """Abstract contract for an appliance's bandwidth / QoS shaping."""
+
+    def set_uplink_bandwidth(self, uplink: str, down_kbps: int, up_kbps: int) -> None:
+        """Set the down/up bandwidth limit (kbps) for the named WAN *uplink*."""
+        ...
+
+    def get_uplink_bandwidth(self) -> dict[str, tuple[int, int]]:
+        """Return ``{uplink: (down_kbps, up_kbps)}`` for every uplink."""
+        ...
+
+    def set_global_client_bandwidth(self, down_kbps: int, up_kbps: int) -> None:
+        """Set the global per-client down/up bandwidth limit (kbps)."""
+        ...
+
+    def get_global_client_bandwidth(self) -> tuple[int, int]:
+        """Return the global per-client ``(down_kbps, up_kbps)`` limit."""
+        ...
+
+    def set_shaping_rules(self, rules: list[ShapingRule]) -> None:
+        """Replace the ordered shaping-rule list with *rules*."""
+        ...
+
+    def get_shaping_rules(self) -> list[ShapingRule]:
+        """Return the shaping rules in evaluation order."""
+        ...

testprotocols/upnp_client.py

@@ -0,0 +1,37 @@
+"""UPnP / Client template.
+
+Defines the abstract contract for UPnP client operations including
+port mapping rule creation and deletion.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class UpnpClient(Protocol):
+    """Abstract contract for UPnP client operations."""
+
+    def create_upnp_rule(
+        self,
+        interface: str,
+        ipaddr: str,
+        int_port: str,
+        ext_port: str,
+        protocol: str,
+        extra_args: str,
+        url: str,
+    ) -> str:
+        """Create a UPnP port-mapping rule and return the result string."""
+        ...
+
+    def delete_upnp_rule(
+        self,
+        interface: str,
+        ext_port: str,
+        protocol: str,
+        url: str,
+    ) -> str:
+        """Delete a UPnP port-mapping rule and return the result string."""
+        ...

testprotocols/vlan_client.py

@@ -0,0 +1,22 @@
+"""VLAN / Client template.
+
+Defines the abstract contract for VLAN client operations including
+virtual interface creation and deletion.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class VlanClient(Protocol):
+    """Abstract contract for VLAN client operations."""
+
+    def add_vlan_interface(self, vlan_id: str) -> None:
+        """Create a VLAN interface for *vlan_id*."""
+        ...
+
+    def delete_vlan_interface(self, vlan_id: str) -> None:
+        """Delete the VLAN interface for *vlan_id*."""
+        ...

testprotocols/wan_link_admin.py

@@ -0,0 +1,34 @@
+"""WAN link administration template — host-substrate WAN edge.
+
+Defines the abstract contract for administratively bringing a WAN link down
+or up by label. This is a **host-substrate lever**: a Linux-based WAN edge
+(the digital twin) can admin-down its own uplink, but an API-managed
+appliance generally cannot — its management plane exposes no such operation,
+and link impairment for appliance tests is the traffic-controller's job (the
+same boundary as the netem precedent; see SPLITS.md). The methods moved here
+from ``router.Router`` so the read surface stays universal across both
+WAN-edge archetypes while link administration rides only on the twin.
+
+In scope: administrative up/down of a WAN link identified by label.
+
+Out of scope: link impairment — latency/loss/blackout shaping (see
+``netem_controller``), uplink status reads (see ``router`` /
+``appliance_uplinks``), and per-netdev interface config (see ``ip_interface``).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class WanLinkAdmin(Protocol):
+    """Abstract contract for administrative WAN link up/down."""
+
+    def bring_wan_down(self, label: str) -> None:
+        """Bring down the WAN interface identified by *label*."""
+        ...
+
+    def bring_wan_up(self, label: str) -> None:
+        """Bring up the WAN interface identified by *label*."""
+        ...