oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/analyzers/protocols/industrial/profinet/dcp.py

@@ -0,0 +1,263 @@
+"""DCP (Discovery and Configuration Protocol) implementation for PROFINET.
+
+DCP is used for device identification, configuration, and network assignment
+in PROFINET networks. It runs directly on Ethernet Layer 2.
+
+References:
+    PROFINET Specification V2.4 - Section 4.3 DCP
+    IEC 61158-6-10:2014
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+
+class DCPParser:
+    """DCP (Discovery and Configuration Protocol) frame parser.
+
+    DCP is used for device discovery, identification, and configuration
+    in PROFINET networks. It operates at Layer 2 (Ethernet).
+
+    Attributes:
+        SERVICE_IDS: Mapping of DCP service IDs to names.
+        SERVICE_TYPES: Mapping of service types to names.
+        OPTIONS: Mapping of DCP option codes to names.
+    """
+
+    # DCP Service IDs (Request/Response)
+    SERVICE_IDS: ClassVar[dict[int, str]] = {
+        0x00: "Reserved",
+        0x01: "Get",
+        0x02: "Set",
+        0x03: "Identify",
+        0x04: "Hello",
+    }
+
+    # DCP Service Types
+    SERVICE_TYPES: ClassVar[dict[int, str]] = {
+        0x00: "Request",
+        0x01: "Response Success",
+        0x05: "Response Not Supported",
+    }
+
+    # DCP Options
+    OPTIONS: ClassVar[dict[int, str]] = {
+        0x01: "IP",
+        0x02: "Device Properties",
+        0x03: "DHCP",
+        0x04: "Reserved",
+        0x05: "Control",
+        0x06: "Device Initiative",
+        0xFF: "All Selector",
+    }
+
+    # DCP Suboptions for Device Properties (Option 0x02)
+    DEVICE_PROPS_SUBOPTIONS: ClassVar[dict[int, str]] = {
+        0x01: "Manufacturer specific",
+        0x02: "Name of Station",
+        0x03: "Device ID",
+        0x04: "Device Role",
+        0x05: "Device Options",
+        0x06: "Alias Name",
+        0x07: "Device Instance",
+        0x08: "OEM Device ID",
+    }
+
+    # DCP Suboptions for IP (Option 0x01)
+    IP_SUBOPTIONS: ClassVar[dict[int, str]] = {
+        0x01: "MAC address",
+        0x02: "IP parameter",
+        0x03: "Full IP Suite",
+    }
+
+    @staticmethod
+    def parse_frame(data: bytes) -> dict[str, Any]:
+        """Parse complete DCP frame.
+
+        DCP Frame Format:
+        - Service ID (1 byte)
+        - Service Type (1 byte)
+        - XID (4 bytes) - Transaction ID
+        - Response Delay (2 bytes)
+        - DCPDataLength (2 bytes)
+        - Blocks (variable)
+
+        Args:
+            data: Raw DCP frame data (without Ethernet header).
+
+        Returns:
+            Parsed DCP frame data.
+
+        Raises:
+            ValueError: If frame is too short or invalid.
+
+        Example:
+            >>> parser = DCPParser()
+            >>> result = parser.parse_frame(dcp_data)
+            >>> print(f"Service: {result['service']}, Blocks: {len(result['blocks'])}")
+        """
+        if len(data) < 10:
+            raise ValueError(f"DCP frame too short: {len(data)} bytes (minimum 10)")
+
+        service_id = data[0]
+        service_type = data[1]
+        xid = int.from_bytes(data[2:6], "big")
+        response_delay = int.from_bytes(data[6:8], "big")
+        dcp_data_length = int.from_bytes(data[8:10], "big")
+
+        blocks = []
+        offset = 10
+
+        # Parse DCP blocks
+        while offset < len(data) and offset < 10 + dcp_data_length:
+            if offset + 4 > len(data):
+                break
+
+            option = data[offset]
+            suboption = data[offset + 1]
+            block_length = int.from_bytes(data[offset + 2 : offset + 4], "big")
+
+            if offset + 4 + block_length > len(data):
+                break
+
+            block_data = data[offset + 4 : offset + 4 + block_length]
+
+            # Parse block data based on option/suboption
+            parsed_block = DCPParser._parse_block(option, suboption, block_data)
+            blocks.append(parsed_block)
+
+            offset += 4 + block_length
+            # Align to 2-byte boundary
+            if block_length % 2:
+                offset += 1
+
+        return {
+            "service": DCPParser.SERVICE_IDS.get(service_id, f"Unknown (0x{service_id:02X})"),
+            "service_id": service_id,
+            "service_type": DCPParser.SERVICE_TYPES.get(
+                service_type, f"Unknown (0x{service_type:02X})"
+            ),
+            "service_type_raw": service_type,
+            "transaction_id": xid,
+            "response_delay": response_delay,
+            "data_length": dcp_data_length,
+            "blocks": blocks,
+        }
+
+    @staticmethod
+    def _parse_block(option: int, suboption: int, data: bytes) -> dict[str, Any]:
+        """Parse individual DCP block based on option/suboption.
+
+        Args:
+            option: DCP option code.
+            suboption: DCP suboption code.
+            data: Block data bytes.
+
+        Returns:
+            Parsed block data.
+        """
+        block: dict[str, Any] = {
+            "option": DCPParser.OPTIONS.get(option, f"Unknown (0x{option:02X})"),
+            "option_raw": option,
+            "suboption": suboption,
+            "length": len(data),
+        }
+
+        # Parse based on option type
+        if option == 0x01:  # IP
+            DCPParser._parse_ip_option(block, suboption, data)
+        elif option == 0x02:  # Device Properties
+            DCPParser._parse_device_properties(block, suboption, data)
+        else:
+            block["data_hex"] = data.hex()
+
+        return block
+
+    @staticmethod
+    def _parse_ip_option(block: dict[str, Any], suboption: int, data: bytes) -> None:
+        """Parse IP option suboptions.
+
+        Args:
+            block: Block dictionary to update.
+            suboption: IP suboption code.
+            data: Block data bytes.
+        """
+        block["suboption_name"] = DCPParser.IP_SUBOPTIONS.get(
+            suboption, f"Unknown (0x{suboption:02X})"
+        )
+
+        if suboption == 0x01 and len(data) >= 6:  # MAC address
+            block["mac_address"] = ":".join(f"{b:02x}" for b in data[:6])
+        elif suboption == 0x02 and len(data) >= 12:  # IP parameter
+            DCPParser._parse_ip_parameter(block, data)
+        else:
+            block["data_hex"] = data.hex()
+
+    @staticmethod
+    def _parse_ip_parameter(block: dict[str, Any], data: bytes) -> None:
+        """Parse IP parameter suboption (IP, subnet, gateway).
+
+        Args:
+            block: Block dictionary to update.
+            data: Block data bytes (must be >= 12 bytes).
+        """
+        block["ip_address"] = ".".join(str(b) for b in data[0:4])
+        block["subnet_mask"] = ".".join(str(b) for b in data[4:8])
+        block["gateway"] = ".".join(str(b) for b in data[8:12])
+
+    @staticmethod
+    def _parse_device_properties(block: dict[str, Any], suboption: int, data: bytes) -> None:
+        """Parse Device Properties option.
+
+        Args:
+            block: Block dictionary to update.
+            suboption: Device property suboption code.
+            data: Block data bytes.
+        """
+        block["suboption_name"] = DCPParser.DEVICE_PROPS_SUBOPTIONS.get(
+            suboption, f"Unknown (0x{suboption:02X})"
+        )
+
+        if suboption == 0x02:  # Name of Station
+            DCPParser._parse_device_name(block, data)
+        elif suboption == 0x03 and len(data) >= 4:  # Device ID
+            DCPParser._parse_device_id(block, data)
+        elif suboption == 0x04 and len(data) >= 2:  # Device Role
+            DCPParser._parse_device_role(block, data)
+        else:
+            block["data_hex"] = data.hex()
+
+    @staticmethod
+    def _parse_device_name(block: dict[str, Any], data: bytes) -> None:
+        """Parse device name."""
+        try:
+            block["device_name"] = data.decode("ascii").rstrip("\x00")
+        except UnicodeDecodeError:
+            block["device_name_hex"] = data.hex()
+
+    @staticmethod
+    def _parse_device_id(block: dict[str, Any], data: bytes) -> None:
+        """Parse device ID (vendor + device)."""
+        block["vendor_id"] = int.from_bytes(data[0:2], "big")
+        block["device_id"] = int.from_bytes(data[2:4], "big")
+
+    @staticmethod
+    def _parse_device_role(block: dict[str, Any], data: bytes) -> None:
+        """Parse device role bitmask."""
+        device_role = int.from_bytes(data[0:2], "big")
+        block["device_role"] = device_role
+
+        roles = []
+        if device_role & 0x01:
+            roles.append("IO-Device")
+        if device_role & 0x02:
+            roles.append("IO-Controller")
+        if device_role & 0x04:
+            roles.append("IO-Multidevice")
+        if device_role & 0x08:
+            roles.append("IO-Supervisor")
+        block["role_names"] = roles
+
+
+__all__ = ["DCPParser"]

oscura/analyzers/protocols/industrial/profinet/ptcp.py

@@ -0,0 +1,200 @@
+"""PTCP (Precision Transparent Clock Protocol) implementation for PROFINET.
+
+PTCP provides time synchronization for PROFINET IRT (Isochronous Real-Time)
+communication with sub-microsecond accuracy.
+
+References:
+    PROFINET Specification V2.4 - Section 4.7 PTCP
+    IEC 61158-6-10:2014
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+
+class PTCPParser:
+    """PTCP (Precision Transparent Clock Protocol) frame parser.
+
+    PTCP provides precise time synchronization for PROFINET networks,
+    supporting IRT communication with sub-microsecond accuracy.
+
+    Attributes:
+        TLV_TYPES: Mapping of PTCP TLV (Type-Length-Value) types.
+    """
+
+    # PTCP Frame Types (based on Frame ID range 0xFF20-0xFF8F)
+    FRAME_TYPES: ClassVar[dict[int, str]] = {
+        0xFF40: "RTSync PDU with Follow-Up",
+        0xFF41: "RTSync PDU",
+        0xFF42: "Follow-Up",
+        0xFF43: "Delay Request",
+        0xFF44: "Delay Response with Follow-Up",
+        0xFF45: "Delay Response",
+    }
+
+    # PTCP TLV Types
+    TLV_TYPES: ClassVar[dict[int, str]] = {
+        0x00: "End",
+        0x01: "Subdomain UUID",
+        0x02: "Time",
+        0x03: "Time Extension",
+        0x04: "Master Source Address",
+        0x05: "Port Parameter",
+        0x06: "Delay Parameter",
+        0x07: "Port Time",
+        0x08: "Optional",
+    }
+
+    @staticmethod
+    def parse_frame(frame_id: int, data: bytes) -> dict[str, Any]:
+        """Parse PTCP frame.
+
+        PTCP Frame Format:
+        - Sequence ID (2 bytes)
+        - Reserved (2 bytes)
+        - TLV blocks (variable)
+
+        Args:
+            frame_id: PROFINET frame ID (0xFF20-0xFF8F range).
+            data: Raw PTCP frame data.
+
+        Returns:
+            Parsed PTCP frame data.
+
+        Raises:
+            ValueError: If frame is too short or invalid.
+
+        Example:
+            >>> parser = PTCPParser()
+            >>> result = parser.parse_frame(0xFF41, ptcp_data)
+            >>> print(f"Type: {result['frame_type']}, Sequence: {result['sequence_id']}")
+        """
+        if len(data) < 4:
+            raise ValueError(f"PTCP frame too short: {len(data)} bytes (minimum 4)")
+
+        sequence_id = int.from_bytes(data[0:2], "big")
+        reserved = int.from_bytes(data[2:4], "big")
+
+        result: dict[str, Any] = {
+            "frame_id": frame_id,
+            "frame_type": PTCPParser.FRAME_TYPES.get(frame_id, f"Unknown (0x{frame_id:04X})"),
+            "sequence_id": sequence_id,
+            "reserved": reserved,
+            "tlv_blocks": [],
+        }
+
+        # Parse TLV blocks
+        offset = 4
+        while offset < len(data):
+            if offset + 2 > len(data):
+                break
+
+            tlv_type = data[offset]
+            tlv_length = data[offset + 1]
+
+            if tlv_type == 0x00:  # End marker
+                break
+
+            if offset + 2 + tlv_length > len(data):
+                break
+
+            tlv_data = data[offset + 2 : offset + 2 + tlv_length]
+            tlv_block = PTCPParser._parse_tlv(tlv_type, tlv_data)
+            result["tlv_blocks"].append(tlv_block)
+
+            offset += 2 + tlv_length
+
+        return result
+
+    @staticmethod
+    def _parse_tlv(tlv_type: int, data: bytes) -> dict[str, Any]:
+        """Parse PTCP TLV (Type-Length-Value) block.
+
+        Args:
+            tlv_type: TLV type code.
+            data: TLV data bytes.
+
+        Returns:
+            Parsed TLV block data.
+        """
+        block: dict[str, Any] = {
+            "type": PTCPParser.TLV_TYPES.get(tlv_type, f"Unknown (0x{tlv_type:02X})"),
+            "type_raw": tlv_type,
+            "length": len(data),
+        }
+
+        # Parse based on TLV type
+        if tlv_type == 0x01 and len(data) >= 16:
+            PTCPParser._parse_subdomain_uuid(block, data)
+        elif tlv_type == 0x02 and len(data) >= 10:
+            PTCPParser._parse_time(block, data)
+        elif tlv_type == 0x03 and len(data) >= 6:
+            PTCPParser._parse_time_extension(block, data)
+        elif tlv_type == 0x04 and len(data) >= 6:
+            PTCPParser._parse_master_source_address(block, data)
+        elif tlv_type == 0x05 and len(data) >= 14:
+            PTCPParser._parse_port_parameter(block, data)
+        elif tlv_type == 0x06 and len(data) >= 20:
+            PTCPParser._parse_delay_parameter(block, data)
+        elif tlv_type == 0x07 and len(data) >= 10:
+            PTCPParser._parse_port_time(block, data)
+        else:
+            block["data_hex"] = data.hex()
+
+        return block
+
+    @staticmethod
+    def _parse_subdomain_uuid(block: dict[str, Any], data: bytes) -> None:
+        """Parse Subdomain UUID TLV."""
+        block["subdomain_uuid"] = data[:16].hex()
+
+    @staticmethod
+    def _parse_time(block: dict[str, Any], data: bytes) -> None:
+        """Parse Time TLV."""
+        seconds = int.from_bytes(data[0:6], "big")
+        nanoseconds = int.from_bytes(data[6:10], "big")
+        block["seconds"] = seconds
+        block["nanoseconds"] = nanoseconds
+        block["timestamp"] = seconds + nanoseconds / 1e9
+
+    @staticmethod
+    def _parse_time_extension(block: dict[str, Any], data: bytes) -> None:
+        """Parse Time Extension TLV."""
+        epoch = int.from_bytes(data[0:2], "big")
+        seconds_high = int.from_bytes(data[2:6], "big")
+        block["epoch"] = epoch
+        block["seconds_high"] = seconds_high
+
+    @staticmethod
+    def _parse_master_source_address(block: dict[str, Any], data: bytes) -> None:
+        """Parse Master Source Address TLV."""
+        block["mac_address"] = ":".join(f"{b:02x}" for b in data[:6])
+
+    @staticmethod
+    def _parse_port_parameter(block: dict[str, Any], data: bytes) -> None:
+        """Parse Port Parameter TLV."""
+        block["t2_port_rx_delay"] = int.from_bytes(data[0:4], "big")
+        block["t3_port_tx_delay"] = int.from_bytes(data[4:8], "big")
+        block["port_mac_address"] = ":".join(f"{b:02x}" for b in data[8:14])
+
+    @staticmethod
+    def _parse_delay_parameter(block: dict[str, Any], data: bytes) -> None:
+        """Parse Delay Parameter TLV."""
+        block["request_port_rx_delay"] = int.from_bytes(data[0:4], "big")
+        block["request_port_tx_delay"] = int.from_bytes(data[4:8], "big")
+        block["response_port_rx_delay"] = int.from_bytes(data[8:12], "big")
+        block["response_port_tx_delay"] = int.from_bytes(data[12:16], "big")
+        block["cable_delay"] = int.from_bytes(data[16:20], "big")
+
+    @staticmethod
+    def _parse_port_time(block: dict[str, Any], data: bytes) -> None:
+        """Parse Port Time TLV."""
+        seconds = int.from_bytes(data[0:6], "big")
+        nanoseconds = int.from_bytes(data[6:10], "big")
+        block["seconds"] = seconds
+        block["nanoseconds"] = nanoseconds
+        block["timestamp"] = seconds + nanoseconds / 1e9
+
+
+__all__ = ["PTCPParser"]