testprotocols 0.1.0__py3-none-any.whl

testprotocols/models/__init__.py

@@ -0,0 +1,304 @@
+"""Shared data models for palco-templates."""
+
+from __future__ import annotations
+
+from testprotocols.models.dhcp import DHCPTraceData, DHCPV6TraceData
+from testprotocols.models.firewall import (
+    Connection,
+    ConntrackStats,
+    FirewallRule,
+    NatRule,
+    PortMapping,
+    Zone,
+    ZonePolicy,
+)
+from testprotocols.models.impairment import ImpairmentProfile
+from testprotocols.models.multicast import (
+    McastGroup,
+    McastSource,
+    MulticastGroupRecord,
+    MulticastGroupRecordType,
+)
+from testprotocols.models.networking import HTTPResult, ICMPPacketData, IPAddresses
+from testprotocols.models.packets import RIPv2PacketData
+from testprotocols.models.qoe import MeasurementSpec, QoEResult
+from testprotocols.models.sdwan_appliance import (
+    ApplicationCategory,
+    BgpConfig,
+    BgpNeighbor,
+    BgpPeerStatus,
+    BgpSessionState,
+    ContentCategory,
+    DhcpLease,
+    DhcpMode,
+    DhcpOption,
+    DhcpOptionType,
+    DhcpReservation,
+    FlowMatch,
+    IntrusionConfig,
+    IntrusionMode,
+    IntrusionSensitivity,
+    L3Rule,
+    L7MatchType,
+    L7Rule,
+    MalwareConfig,
+    MalwareMode,
+    NatInboundAllow,
+    OneToManyNatRule,
+    OneToOneNatRule,
+    PortForwardRule,
+    RuleAction,
+    RuleProtocol,
+    SecurityAction,
+    SecurityEvent,
+    ShapingPriority,
+    ShapingRule,
+    SiteToSiteVpnConfig,
+    StaticRoute,
+    SteeringScope,
+    SyslogRole,
+    SyslogServer,
+    ThreatCategory,
+    UplinkSelectionRule,
+    UplinkState,
+    UplinkStatus,
+    VlanConfig,
+    VpnHub,
+    VpnPeerState,
+    VpnPeerStatus,
+    VpnRole,
+    VpnSubnet,
+)
+from testprotocols.models.l2_common import (
+    MacTableEntry,
+    StpGuard,
+    StpMode,
+    StpPortState,
+)
+from testprotocols.models.switch import (
+    AccessPolicy,
+    AccessPolicyType,
+    AclDirection,
+    AggregationMode,
+    BindingSource,
+    DiscoveryProtocol,
+    Duplex,
+    FhsBinding,
+    FhsScope,
+    FhsTrustState,
+    LinkAggregationGroup,
+    LinkState,
+    LldpNeighbor,
+    NtpServer,
+    PoePortStatus,
+    PoePriority,
+    PoeStatus,
+    PortAdminState,
+    PortMode,
+    PortStatusEntry,
+    QosRule,
+    QosTrustMode,
+    StormControlConfig,
+    StormControlType,
+    StpPortConfig,
+    SwitchAclRule,
+    SwitchPort,
+    VlanDef,
+)
+from testprotocols.models.radius import (
+    RadiusAccountingRecord,
+    RadiusServerConfig,
+    RadiusSession,
+    RadiusUser,
+)
+from testprotocols.models.tr069 import CpeConnectionStatus
+from testprotocols.models.traffic import TrafficResult, TrafficSpec
+from testprotocols.models.switch_routing import (
+    InterfaceDhcpConfig,
+    InterfaceMode,
+    OspfConfig,
+    OspfInterfaceSettings,
+    OspfVersion,
+    RedundancyGroup,
+    RedundancyRole,
+    RoutedInterface,
+)
+from testprotocols.models.wan_edge import (
+    AppFlow,
+    LinkHealthReport,
+    LinkStatus,
+    PathMetrics,
+    RouteEntry,
+    RouteOrigin,
+    SLAPolicy,
+    TrafficShapingRule,
+    VPNPeerStatus,
+)
+from testprotocols.models.wifi import (
+    WifiAcl,
+    WifiBssConfig,
+    WifiCaptiveConfig,
+    WifiChannelUtilization,
+    WifiDfsState,
+    WifiMeshLink,
+    WifiMeshNode,
+    WifiMeshStatus,
+    WifiMeshTopology,
+    WifiNeighbor,
+    WifiRadioStats,
+    WifiStation,
+    WifiTransitionConfig,
+)
+
+__all__ = [
+    # l2_common
+    "MacTableEntry",
+    "StpGuard",
+    "StpMode",
+    "StpPortState",
+    # switch
+    "AccessPolicy",
+    "AccessPolicyType",
+    "AclDirection",
+    "AggregationMode",
+    "BindingSource",
+    "DiscoveryProtocol",
+    "Duplex",
+    "FhsBinding",
+    "FhsScope",
+    "FhsTrustState",
+    "LinkAggregationGroup",
+    "LinkState",
+    "LldpNeighbor",
+    "NtpServer",
+    "PoePortStatus",
+    "PoePriority",
+    "PoeStatus",
+    "PortAdminState",
+    "PortMode",
+    "PortStatusEntry",
+    "QosRule",
+    "QosTrustMode",
+    "StormControlConfig",
+    "StormControlType",
+    "StpPortConfig",
+    "SwitchAclRule",
+    "SwitchPort",
+    "VlanDef",
+    # switch_routing
+    "InterfaceDhcpConfig",
+    "InterfaceMode",
+    "OspfConfig",
+    "OspfInterfaceSettings",
+    "OspfVersion",
+    "RedundancyGroup",
+    "RedundancyRole",
+    "RoutedInterface",
+    # wan_edge
+    "AppFlow",
+    # firewall
+    "Connection",
+    "ConntrackStats",
+    # tr069
+    "CpeConnectionStatus",
+    # dhcp
+    "DHCPTraceData",
+    "DHCPV6TraceData",
+    "FirewallRule",
+    # networking
+    "HTTPResult",
+    "ICMPPacketData",
+    "IPAddresses",
+    # impairment
+    "ImpairmentProfile",
+    # sdwan_appliance
+    "ApplicationCategory",
+    "BgpConfig",
+    "BgpNeighbor",
+    "BgpPeerStatus",
+    "BgpSessionState",
+    "ContentCategory",
+    "DhcpLease",
+    "DhcpMode",
+    "DhcpOption",
+    "DhcpOptionType",
+    "DhcpReservation",
+    "FlowMatch",
+    "IntrusionConfig",
+    "IntrusionMode",
+    "IntrusionSensitivity",
+    "L3Rule",
+    "L7MatchType",
+    "L7Rule",
+    "MalwareConfig",
+    "MalwareMode",
+    "NatInboundAllow",
+    "OneToManyNatRule",
+    "OneToOneNatRule",
+    "PortForwardRule",
+    "RuleAction",
+    "RuleProtocol",
+    "SecurityAction",
+    "SecurityEvent",
+    "ShapingPriority",
+    "ShapingRule",
+    "SiteToSiteVpnConfig",
+    "StaticRoute",
+    "SteeringScope",
+    "SyslogRole",
+    "SyslogServer",
+    "ThreatCategory",
+    "UplinkSelectionRule",
+    "UplinkState",
+    "UplinkStatus",
+    "VlanConfig",
+    "VpnHub",
+    "VpnPeerState",
+    "VpnPeerStatus",
+    "VpnRole",
+    "VpnSubnet",
+    "LinkHealthReport",
+    "LinkStatus",
+    # multicast
+    "McastGroup",
+    "McastSource",
+    # qoe
+    "MeasurementSpec",
+    "MulticastGroupRecord",
+    "MulticastGroupRecordType",
+    "NatRule",
+    "PathMetrics",
+    "PortMapping",
+    "QoEResult",
+    # packets
+    "RIPv2PacketData",
+    # radius
+    "RadiusAccountingRecord",
+    "RadiusServerConfig",
+    "RadiusSession",
+    "RadiusUser",
+    "RouteEntry",
+    "RouteOrigin",
+    "SLAPolicy",
+    # traffic
+    "TrafficResult",
+    "TrafficShapingRule",
+    "TrafficSpec",
+    "VPNPeerStatus",
+    # wifi
+    "WifiAcl",
+    "WifiBssConfig",
+    "WifiCaptiveConfig",
+    "WifiChannelUtilization",
+    "WifiDfsState",
+    "WifiMeshLink",
+    "WifiMeshNode",
+    "WifiMeshStatus",
+    "WifiMeshTopology",
+    "WifiNeighbor",
+    "WifiRadioStats",
+    "WifiStation",
+    "WifiTransitionConfig",
+    "Zone",
+    "ZonePolicy",
+]

testprotocols/models/dhcp.py

@@ -0,0 +1,28 @@
+"""DHCP and DHCPv6 packet trace data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from testprotocols.models.networking import IPAddresses
+
+
+@dataclass
+class DHCPTraceData:
+    """Holds a captured DHCPv4 packet with source/destination addresses and message type."""
+
+    source: IPAddresses
+    destination: IPAddresses
+    dhcp_packet: dict[str, Any]
+    dhcp_message_type: int
+
+
+@dataclass
+class DHCPV6TraceData:
+    """Holds a captured DHCPv6 packet with source/destination addresses and message type."""
+
+    source: IPAddresses
+    destination: IPAddresses
+    dhcpv6_packet: dict[str, Any]
+    dhcpv6_message_type: int

testprotocols/models/firewall.py

@@ -0,0 +1,197 @@
+"""Firewall-domain data models.
+
+Shared across the ``packet_filter``, ``firewall``, ``nat``,
+``conntrack``, ``firewall_zones``, and ``sdwan_policy_manager`` templates.
+Transport-agnostic: drivers translate these structures into iptables /
+nftables / pf / TR-069 / vendor CLI as appropriate.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FirewallRule:
+    """Holds a stateless or stateful packet-filter rule with match criteria and action.
+
+    Used by the ``packet_filter`` and ``firewall`` templates (per-chain
+    rule lists). The IPv4 / IPv6 split is not a contract dimension
+    — each rule's address family is inferred from its CIDR fields.
+
+    *action* is one of ``"allow"``, ``"deny"``, ``"reject"``, ``"log"``.
+    *protocol* is one of ``"tcp"``, ``"udp"``, ``"icmp"``, ``"any"``.
+    *dst_port* is a port number, a range like ``"1024-65535"``, or ``"any"``.
+    *application* / *application_category* are L7 classifiers used by
+    SD-WAN policy; they are ignored by simple packet-filter drivers.
+    """
+
+    name: str
+    action: str
+    protocol: str
+    src_cidr: str
+    dst_cidr: str
+    dst_port: str
+    application: str | None = None
+    application_category: str | None = None
+    log: bool = True
+
+
+@dataclass
+class NatRule:
+    """A NAT translation rule.
+
+    Three modes are supported via the *mode* discriminator:
+
+    - ``"snat"`` — source-NAT (rewrite source on egress). Requires
+      *translated_src* (or empty string to fall back to the egress
+      interface address). *translated_dst* and *translated_port* must
+      be empty.
+    - ``"dnat"`` — destination-NAT / port-forward primitive (rewrite
+      destination on ingress). Requires *translated_dst*; *translated_port*
+      is optional. *translated_src* must be empty.
+    - ``"1to1"`` — bidirectional one-to-one NAT (static mapping between
+      an outside and inside address). Requires *translated_dst* (the
+      inside address). Port fields must be empty.
+
+    Match criteria default to ``""`` meaning "any". *interface* is the
+    egress interface for snat / 1to1, the ingress interface for dnat;
+    drivers may also accept a logical name resolved via ``IpInterface``.
+    """
+
+    name: str
+    mode: str
+    interface: str
+    protocol: str = "any"
+    src_cidr: str = ""
+    dst_cidr: str = ""
+    dst_port: str = ""
+    translated_src: str = ""
+    translated_dst: str = ""
+    translated_port: str = ""
+    enabled: bool = True
+
+
+@dataclass
+class PortMapping:
+    """A named external-port → internal-host:port mapping.
+
+    Higher-level than ``NatRule``: drivers may lower a ``PortMapping`` to
+    a DNAT primitive, a TR-069 ``Device.NAT.PortMapping`` object, a
+    UPnP-IGD / PCP entry, or a vendor port-forward CLI — tests never
+    need to know which.
+
+    *protocol* is one of ``"tcp"``, ``"udp"``, ``"tcp-udp"``.
+    *external_interface* of ``None`` means "all external interfaces".
+    *src_cidr* may restrict the mapping to a specific source range
+    (firewall hardening); the default ``"0.0.0.0/0"`` accepts any source.
+    """
+
+    name: str
+    external_port: int
+    protocol: str
+    internal_host: str
+    internal_port: int
+    external_interface: str | None = None
+    src_cidr: str = "0.0.0.0/0"
+    description: str = ""
+    enabled: bool = True
+
+
+@dataclass
+class Connection:
+    """A single tracked connection / flow as observed by the conntrack template.
+
+    Direction is original → reply. *bytes_orig* / *packets_orig* count
+    the original direction; *bytes_reply* / *packets_reply* count the
+    reverse path.
+
+    *state* is protocol-specific:
+
+    - TCP: ``"SYN_SENT"``, ``"SYN_RECV"``, ``"ESTABLISHED"``,
+      ``"FIN_WAIT"``, ``"CLOSE_WAIT"``, ``"LAST_ACK"``, ``"TIME_WAIT"``,
+      ``"CLOSE"``, ``"LISTEN"``.
+    - UDP / ICMP / other: ``"UNREPLIED"``, ``"ASSURED"``, or
+      driver-specific values.
+
+    *translated_src* / *translated_dst* are populated (non-None) when NAT
+    is altering this flow. *src_port* / *dst_port* are ``None`` for ICMP.
+    """
+
+    protocol: str
+    src_ip: str
+    dst_ip: str
+    src_port: int | None
+    dst_port: int | None
+    state: str
+    timeout_seconds: int
+    bytes_orig: int
+    bytes_reply: int
+    packets_orig: int
+    packets_reply: int
+    translated_src: str | None = None
+    translated_dst: str | None = None
+    mark: int | None = None
+    zone: str | None = None
+
+
+@dataclass
+class ConntrackStats:
+    """Conntrack table-level aggregate counters.
+
+    *count* and *max* are the only universally available values; the
+    remaining fields are populated where the driver can report them.
+    ``None`` means "driver does not expose this counter", not zero.
+    """
+
+    count: int
+    max: int
+    inserted: int | None = None
+    deleted: int | None = None
+    drops: int | None = None
+    early_drops: int | None = None
+    invalid: int | None = None
+    search_restarts: int | None = None
+
+
+@dataclass
+class Zone:
+    """A named firewall zone — a group of interfaces and / or networks
+    sharing default-input / default-forward / default-output policy.
+
+    Models the OpenWrt-style zone model (also maps to firewalld zones,
+    pfSense interface groups, etc.). Empty *interfaces* and *networks*
+    lists are valid (zone exists but is not yet bound).
+
+    *default_input* / *default_forward* / *default_output* are one of
+    ``"accept"``, ``"drop"``, ``"reject"`` and govern traffic that
+    doesn't match any explicit rule. *masquerade* enables auto-SNAT on
+    egress traffic from this zone; *mss_clamping* enables PMTU clamping
+    (helpful on PPPoE WAN zones).
+    """
+
+    name: str
+    interfaces: list[str] = field(default_factory=list[str])
+    networks: list[str] = field(default_factory=list[str])
+    default_input: str = "drop"
+    default_forward: str = "drop"
+    default_output: str = "accept"
+    masquerade: bool = False
+    mss_clamping: bool = False
+
+
+@dataclass
+class ZonePolicy:
+    """Default forwarding action between two zones.
+
+    Models the per-zone-pair forwarding link in OpenWrt-style firewalls.
+    More specific traffic between the same pair is still controlled by
+    ``FirewallRule`` records (in ``packet_filter`` or ``firewall``);
+    this is the fall-through.
+
+    *action* is one of ``"accept"``, ``"drop"``, ``"reject"``.
+    """
+
+    src_zone: str
+    dst_zone: str
+    action: str

testprotocols/models/impairment.py

@@ -0,0 +1,18 @@
+"""Network impairment profile data model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ImpairmentProfile:
+    """Holds parameters describing a network impairment scenario (latency, jitter, loss, etc.)."""
+
+    latency_ms: int
+    jitter_ms: int
+    loss_percent: float
+    bandwidth_limit_mbps: int | None = None
+    reorder_percent: float = 0.0
+    corrupt_percent: float = 0.0
+    duplicate_percent: float = 0.0

testprotocols/models/l2_common.py

@@ -0,0 +1,53 @@
+"""Shared L2 vocabulary for the switch archetypes and the future CPE L2 bridge.
+
+STP and FDB concepts are common to a hardware switch (``SpanningTree`` /
+``MacTable``) and a Linux bridge (the deferred ``L2Bridge``, see GAPS.md). The
+normalized vocabularies live here, in a neutral module, so neither
+``models/switch.py`` nor a future bridge model depends on the other.
+
+Vendor neutrality is part of the contract: members are plain strings (trivial to
+serialize), constructing from a value validates it, and a testbed plugin maps its
+product's terms to/from these neutral values. No vendor identifier appears here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class StpMode(StrEnum):
+    """IEEE spanning-tree mode (802.1D / 802.1w / 802.1s). Seeded in full."""
+
+    STP = "stp"
+    RSTP = "rstp"
+    MSTP = "mstp"
+    UNKNOWN = "unknown"
+
+
+class StpGuard(StrEnum):
+    """Per-port spanning-tree guard."""
+
+    NONE = "none"
+    ROOT = "root"
+    BPDU = "bpdu"
+    LOOP = "loop"
+
+
+class StpPortState(StrEnum):
+    """Observed per-port spanning-tree state."""
+
+    FORWARDING = "forwarding"
+    BLOCKING = "blocking"
+    LEARNING = "learning"
+    LISTENING = "listening"
+    DISABLED = "disabled"
+
+
+@dataclass
+class MacTableEntry:
+    """A single forwarding-database (FDB) entry — normalized."""
+
+    mac: str
+    port: str
+    vlan: int

testprotocols/models/multicast.py

@@ -0,0 +1,22 @@
+"""Multicast group record types and type aliases."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class MulticastGroupRecordType(Enum):
+    """IGMPv3 group record type codes as defined in RFC 3376."""
+
+    MODE_IS_INCLUDE = 1
+    MODE_IS_EXCLUDE = 2
+    CHANGE_TO_INCLUDE_MODE = 3
+    CHANGE_TO_EXCLUDE_MODE = 4
+    ALLOW_NEW_SOURCES = 5
+    BLOCK_OLD_SOURCES = 6
+
+
+McastSource = str
+McastGroup = str
+MulticastGroupRecord = list[tuple[list[McastSource], McastGroup, MulticastGroupRecordType]]
+"""A list of (sources, group, record_type) tuples representing IGMPv3 group records."""

testprotocols/models/networking.py

@@ -0,0 +1,50 @@
+"""Networking data models for IP addresses and protocol results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from ipaddress import IPv4Address, IPv6Address
+
+
+@dataclass
+class IPAddresses:
+    """Holds optional IPv4, IPv6, and link-local IPv6 addresses for a network endpoint."""
+
+    ipv4: IPv4Address | None
+    ipv6: IPv6Address | None
+    link_local_ipv6: IPv6Address | None
+
+
+@dataclass
+class ICMPPacketData:
+    """Holds ICMP packet fields including query code and source/destination addresses."""
+
+    query_code: int
+    source: IPAddresses
+    destination: IPAddresses
+
+
+class HTTPResult:
+    """Parses and holds an HTTP response string, exposing the status code and body."""
+
+    def __init__(self, response: str) -> None:
+        self.raw = response
+        self.code, self.beautified_text, _ = self._parse_response(response)
+
+    @staticmethod
+    def _parse_response(response: str) -> tuple[str, str, str]:
+        lines = response.split("\r\n", 1) if "\r\n" in response else response.split("\n", 1)
+        status_line = lines[0] if lines else ""
+        parts = status_line.split(" ", 2)
+        code = parts[1] if len(parts) > 1 else ""
+        reason = parts[2] if len(parts) > 2 else ""
+        body = lines[1] if len(lines) > 1 else ""
+        if "\r\n\r\n" in body:
+            body = body.split("\r\n\r\n", 1)[1]
+        elif "\n\n" in body:
+            body = body.split("\n\n", 1)[1]
+        elif body.startswith("\r\n"):
+            body = body[2:]
+        elif body.startswith("\n"):
+            body = body[1:]
+        return code, body, reason

testprotocols/models/packets.py

@@ -0,0 +1,21 @@
+"""Protocol-specific packet data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from ipaddress import IPv4Address, IPv4Interface, IPv6Interface
+
+
+@dataclass
+class RIPv2PacketData:
+    """Holds fields extracted from a RIPv2 packet.
+
+    Includes source, destination, and route entries.
+    """
+
+    source: IPv4Address
+    destination: IPv4Address
+    ip_address: list[IPv4Address]
+    subnet: list[IPv4Interface | IPv6Interface]
+    frame_time: datetime | None = None