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

oscura/inference/stream.py

@@ -182,71 +182,134 @@ class UDPStreamReassembler:
         key = flow_key or f"{segment.src}-{segment.dst}"
         self._segments[key].append(segment)
 
-    def get_stream(self, flow_key: str | None = None) -> ReassembledStream:
-        """Get reassembled stream for a flow.
+    def _get_empty_stream(self) -> ReassembledStream:
+        """Create empty stream result.
 
-        Implements RE-STR-001: UDP stream reconstruction.
+        Returns:
+            Empty ReassembledStream.
+        """
+        return ReassembledStream(
+            data=b"",
+            src="",
+            dst="",
+            start_time=0.0,
+            end_time=0.0,
+            segments=0,
+        )
+
+    def _resolve_flow_key(self, flow_key: str | None) -> str | None:
+        """Resolve flow key to actual key or None if empty.
 
         Args:
-            flow_key: Flow identifier.
+            flow_key: Requested flow key.
 
         Returns:
-            ReassembledStream with ordered data.
+            Resolved flow key or None.
         """
         if flow_key is None:
-            # Get first/only flow
             if not self._segments:
-                return ReassembledStream(
-                    data=b"",
-                    src="",
-                    dst="",
-                    start_time=0.0,
-                    end_time=0.0,
-                    segments=0,
-                )
-            flow_key = next(iter(self._segments.keys()))
+                return None
+            return next(iter(self._segments.keys()))
+        return flow_key
 
-        segments = self._segments.get(flow_key, [])
-        if not segments:
-            return ReassembledStream(
-                data=b"",
-                src="",
-                dst="",
-                start_time=0.0,
-                end_time=0.0,
-                segments=0,
-            )
-
-        # Sort by sequence number
-        sorted_segments = sorted(segments, key=lambda s: s.sequence_number)
+    def _count_out_of_order(self, segments: list[StreamSegment]) -> int:
+        """Count out-of-order segments.
 
-        # Concatenate data
-        data = b"".join(s.data for s in sorted_segments)
+        Args:
+            segments: List of segments (unsorted).
 
-        # Detect out-of-order: count segments that arrived after a higher sequence number
+        Returns:
+            Number of out-of-order segments.
+        """
         out_of_order = 0
         max_seq_seen = -1
         for segment in segments:
             if segment.sequence_number < max_seq_seen:
                 out_of_order += 1
             max_seq_seen = max(max_seq_seen, segment.sequence_number)
+        return out_of_order
 
-        # Detect gaps
-        gaps = []
+    def _detect_gaps(self, sorted_segments: list[StreamSegment]) -> list[tuple[int, int]]:
+        """Detect gaps in sequence numbers.
+
+        Args:
+            sorted_segments: Segments sorted by sequence number.
+
+        Returns:
+            List of (expected, actual) gap tuples.
+        """
+        gaps: list[tuple[int, int]] = []
         for i in range(1, len(sorted_segments)):
             expected = sorted_segments[i - 1].sequence_number + len(sorted_segments[i - 1].data)
             actual = sorted_segments[i].sequence_number
             if actual > expected:
                 gaps.append((expected, actual))
+        return gaps
+
+    def _get_time_range(self, sorted_segments: list[StreamSegment]) -> tuple[float, float]:
+        """Get start and end times from segments.
 
+        Args:
+            sorted_segments: List of segments.
+
+        Returns:
+            Tuple of (start_time, end_time).
+        """
         timestamps = [s.timestamp for s in sorted_segments if s.timestamp > 0]
+        if timestamps:
+            return min(timestamps), max(timestamps)
+        return 0.0, 0.0
+
+    def _extract_addresses(self, sorted_segments: list[StreamSegment]) -> tuple[str, str]:
+        """Extract source and destination addresses from segments.
+
+        Args:
+            sorted_segments: List of segments.
+
+        Returns:
+            Tuple of (src, dst).
+        """
+        if sorted_segments:
+            return sorted_segments[0].src, sorted_segments[0].dst
+        return "", ""
+
+    def get_stream(self, flow_key: str | None = None) -> ReassembledStream:
+        """Get reassembled stream for a flow.
+
+        Implements RE-STR-001: UDP stream reconstruction.
+
+        Args:
+            flow_key: Flow identifier.
+
+        Returns:
+            ReassembledStream with ordered data.
+        """
+        # Resolve flow key
+        resolved_key = self._resolve_flow_key(flow_key)
+        if resolved_key is None:
+            return self._get_empty_stream()
+
+        # Get segments
+        segments = self._segments.get(resolved_key, [])
+        if not segments:
+            return self._get_empty_stream()
+
+        # Sort by sequence number
+        sorted_segments = sorted(segments, key=lambda s: s.sequence_number)
+
+        # Build stream components
+        data = b"".join(s.data for s in sorted_segments)
+        out_of_order = self._count_out_of_order(segments)
+        gaps = self._detect_gaps(sorted_segments)
+        start_time, end_time = self._get_time_range(sorted_segments)
+        src, dst = self._extract_addresses(sorted_segments)
 
         return ReassembledStream(
             data=data,
-            src=sorted_segments[0].src if sorted_segments else "",
-            dst=sorted_segments[0].dst if sorted_segments else "",
-            start_time=min(timestamps) if timestamps else 0.0,
-            end_time=max(timestamps) if timestamps else 0.0,
+            src=src,
+            dst=dst,
+            start_time=start_time,
+            end_time=end_time,
             segments=len(sorted_segments),
             gaps=gaps,
             retransmits=0,
@@ -354,77 +417,84 @@ class TCPStreamReassembler:
 
         self._segments[key].append(seg)
 
-    def get_stream(self, flow_key: str | None = None) -> ReassembledStream:
-        """Get reassembled TCP stream.
-
-        Implements RE-STR-002: TCP stream reassembly.
+    def _extract_addresses(self, sorted_segments: list[StreamSegment]) -> tuple[str, str]:
+        """Extract source and destination addresses from segments.
 
         Args:
-            flow_key: Flow identifier.
+            sorted_segments: Sorted list of stream segments.
 
         Returns:
-            ReassembledStream with complete data.
+            Tuple of (source, destination) addresses.
         """
-        if flow_key is None:
-            if not self._segments:
-                return ReassembledStream(
-                    data=b"",
-                    src="",
-                    dst="",
-                    start_time=0.0,
-                    end_time=0.0,
-                    segments=0,
-                )
-            flow_key = next(iter(self._segments.keys()))
+        if not sorted_segments:
+            return ("", "")
+        return (sorted_segments[0].src, sorted_segments[0].dst)
 
-        segments = self._segments.get(flow_key, [])
-        if not segments:
-            return ReassembledStream(
-                data=b"",
-                src="",
-                dst="",
-                start_time=0.0,
-                end_time=0.0,
-                segments=0,
-            )
+    def _count_anomalies(self, segments: list[StreamSegment]) -> tuple[int, int]:
+        """Count retransmits and out-of-order segments.
 
-        isn = self._isn.get(flow_key, 0) or 0
+        Args:
+            segments: List of segments in arrival order.
 
-        # Count retransmits first (before filtering)
+        Returns:
+            Tuple of (retransmits, out_of_order) counts.
+        """
+        # Count retransmits
         retransmits = sum(1 for seg in segments if seg.is_retransmit)
 
-        # If ISN wasn't detected via SYN, use minimum sequence number
-        if isn == 0 or isn > min(s.sequence_number for s in segments):
-            isn = min(s.sequence_number for s in segments)
-
-        # Detect out-of-order by checking arrival order vs sequence order
-        # Count segments that arrived before a segment with lower sequence
+        # Count out-of-order segments
         out_of_order = 0
         for i, seg in enumerate(segments):
-            # Check if any earlier segment has higher sequence
             for j in range(i):
                 if segments[j].sequence_number > seg.sequence_number:
                     out_of_order += 1
                     break
 
-        # Sort by relative sequence number
-        sorted_segments = sorted(segments, key=lambda s: (s.sequence_number - isn) % (2**32))
+        return (retransmits, out_of_order)
+
+    def _detect_isn(self, flow_key: str, segments: list[StreamSegment]) -> int:
+        """Detect initial sequence number for flow.
+
+        Args:
+            flow_key: Flow identifier.
+            segments: List of segments.
+
+        Returns:
+            Initial sequence number.
+        """
+        isn = self._isn.get(flow_key, 0) or 0
+
+        # If ISN wasn't detected via SYN, use minimum sequence number
+        if isn == 0 or isn > min(s.sequence_number for s in segments):
+            isn = min(s.sequence_number for s in segments)
 
-        # Build stream handling overlaps and gaps
+        return isn
+
+    def _build_data_buffer(
+        self, sorted_segments: list[StreamSegment], isn: int
+    ) -> tuple[bytes, list[tuple[int, int]]]:
+        """Build data buffer from sorted segments, handling gaps and overlaps.
+
+        Args:
+            sorted_segments: Segments sorted by sequence number.
+            isn: Initial sequence number.
+
+        Returns:
+            Tuple of (reassembled_data, gaps).
+        """
         data_buffer = bytearray()
         current_offset = 0
         gaps = []
 
         for seg in sorted_segments:
             if seg.is_retransmit:
-                continue  # Skip retransmits when building data
+                continue
 
             rel_seq = (seg.sequence_number - isn) % (2**32)
 
             if rel_seq > current_offset:
                 # Gap detected
                 gaps.append((current_offset, rel_seq))
-                # Fill gap with zeros
                 data_buffer.extend(b"\x00" * (rel_seq - current_offset))
                 current_offset = rel_seq
 
@@ -438,12 +508,59 @@ class TCPStreamReassembler:
                 data_buffer.extend(seg.data)
                 current_offset += len(seg.data)
 
+        return (bytes(data_buffer), gaps)
+
+    def get_stream(self, flow_key: str | None = None) -> ReassembledStream:
+        """Get reassembled TCP stream.
+
+        Implements RE-STR-002: TCP stream reassembly.
+
+        Args:
+            flow_key: Flow identifier.
+
+        Returns:
+            ReassembledStream with complete data.
+        """
+        # Handle empty or default flow key
+        if flow_key is None:
+            if not self._segments:
+                return ReassembledStream(
+                    data=b"",
+                    src="",
+                    dst="",
+                    start_time=0.0,
+                    end_time=0.0,
+                    segments=0,
+                )
+            flow_key = next(iter(self._segments.keys()))
+
+        segments = self._segments.get(flow_key, [])
+        if not segments:
+            return ReassembledStream(
+                data=b"",
+                src="",
+                dst="",
+                start_time=0.0,
+                end_time=0.0,
+                segments=0,
+            )
+
+        # Detect ISN and count anomalies
+        isn = self._detect_isn(flow_key, segments)
+        retransmits, out_of_order = self._count_anomalies(segments)
+
+        # Sort and reassemble
+        sorted_segments = sorted(segments, key=lambda s: (s.sequence_number - isn) % (2**32))
+        data, gaps = self._build_data_buffer(sorted_segments, isn)
+
+        # Extract metadata
+        src, dst = self._extract_addresses(sorted_segments)
         timestamps = [s.timestamp for s in sorted_segments if s.timestamp > 0]
 
         return ReassembledStream(
-            data=bytes(data_buffer),
-            src=sorted_segments[0].src if sorted_segments else "",
-            dst=sorted_segments[0].dst if sorted_segments else "",
+            data=data,
+            src=src,
+            dst=dst,
             start_time=min(timestamps) if timestamps else 0.0,
             end_time=max(timestamps) if timestamps else 0.0,
             segments=len(sorted_segments),
@@ -542,7 +659,29 @@ class MessageFramer:
         Returns:
             Detected framing type string.
         """
-        # Check for common delimiters
+        # Check for delimiter-based framing
+        if self._is_delimiter_framed(data):
+            return "delimiter"
+
+        # Check for length-prefixed framing
+        if self._is_length_prefixed(data):
+            return "length_prefix"
+
+        # Check for fixed-size framing
+        if self._is_fixed_size(data):
+            return "fixed"
+
+        return "unknown"
+
+    def _is_delimiter_framed(self, data: bytes) -> bool:
+        """Check if data uses delimiter-based framing.
+
+        Args:
+            data: Sample data.
+
+        Returns:
+            True if delimiter framing detected.
+        """
         common_delimiters = [b"\r\n", b"\n", b"\x00", b"\r"]
         for delim in common_delimiters:
             count = data.count(delim)
@@ -550,35 +689,56 @@ class MessageFramer:
                 # Check for regular spacing
                 parts = data.split(delim)
                 if parts and len({len(p) for p in parts if p}) <= 3:
-                    return "delimiter"
-
-        # Check for length-prefixed
-        if len(data) >= 4:
-            # Try big-endian 2-byte length
-            for offset in range(min(8, len(data) - 2)):
-                length = int.from_bytes(data[offset : offset + 2], "big")
-                if 4 < length < len(data) and length < 65536:
-                    # Check if data continues with similar pattern
-                    next_offset = offset + length
-                    if next_offset + 2 < len(data):
-                        next_length = int.from_bytes(data[next_offset : next_offset + 2], "big")
-                        if 4 < next_length < len(data):
-                            return "length_prefix"
-
-        # Check for fixed size
-        if len(data) >= 32:
-            # Look for repeating pattern
-            for size in range(4, 128):
-                if len(data) % size == 0:
-                    chunks = [data[i : i + size] for i in range(0, len(data), size)]
-                    if len(chunks) >= 3:
-                        # Check structural similarity
-                        first = chunks[0][:4] if len(chunks[0]) >= 4 else chunks[0]
-                        matches = sum(1 for c in chunks[1:] if c[: len(first)] == first)
-                        if matches >= len(chunks) * 0.5:
-                            return "fixed"
+                    return True
+        return False
 
-        return "unknown"
+    def _is_length_prefixed(self, data: bytes) -> bool:
+        """Check if data uses length-prefixed framing.
+
+        Args:
+            data: Sample data.
+
+        Returns:
+            True if length-prefixed framing detected.
+        """
+        if len(data) < 4:
+            return False
+
+        # Try big-endian 2-byte length
+        for offset in range(min(8, len(data) - 2)):
+            length = int.from_bytes(data[offset : offset + 2], "big")
+            if 4 < length < len(data) and length < 65536:
+                # Check if data continues with similar pattern
+                next_offset = offset + length
+                if next_offset + 2 < len(data):
+                    next_length = int.from_bytes(data[next_offset : next_offset + 2], "big")
+                    if 4 < next_length < len(data):
+                        return True
+        return False
+
+    def _is_fixed_size(self, data: bytes) -> bool:
+        """Check if data uses fixed-size framing.
+
+        Args:
+            data: Sample data.
+
+        Returns:
+            True if fixed-size framing detected.
+        """
+        if len(data) < 32:
+            return False
+
+        # Look for repeating pattern
+        for size in range(4, 128):
+            if len(data) % size == 0:
+                chunks = [data[i : i + size] for i in range(0, len(data), size)]
+                if len(chunks) >= 3:
+                    # Check structural similarity
+                    first = chunks[0][:4] if len(chunks[0]) >= 4 else chunks[0]
+                    matches = sum(1 for c in chunks[1:] if c[: len(first)] == first)
+                    if matches >= len(chunks) * 0.5:
+                        return True
+        return False
 
     def _auto_frame(self, data: bytes) -> FramingResult:
         """Automatically detect and apply framing.

oscura/iot/__init__.py

@@ -0,0 +1,34 @@
+"""IoT protocol decoders package.
+
+Provides decoders for IoT wireless protocols including LoRaWAN, Zigbee, BLE, MQTT, CoAP, and more.
+"""
+
+from oscura.iot.coap.analyzer import (
+    CoAPAnalyzer,
+    CoAPExchange,
+    CoAPMessage,
+)
+from oscura.iot.lorawan.decoder import (
+    LoRaWANDecoder,
+    LoRaWANFrame,
+    LoRaWANKeys,
+    decode_lorawan_frame,
+)
+from oscura.iot.mqtt.analyzer import (
+    MQTTAnalyzer,
+    MQTTPacket,
+    MQTTSession,
+)
+
+__all__ = [
+    "CoAPAnalyzer",
+    "CoAPExchange",
+    "CoAPMessage",
+    "LoRaWANDecoder",
+    "LoRaWANFrame",
+    "LoRaWANKeys",
+    "MQTTAnalyzer",
+    "MQTTPacket",
+    "MQTTSession",
+    "decode_lorawan_frame",
+]

oscura/iot/coap/__init__.py

@@ -0,0 +1,32 @@
+"""CoAP (Constrained Application Protocol) analyzer.
+
+This module provides comprehensive CoAP (RFC 7252) protocol analysis including
+message parsing, request/response matching, blockwise transfer support, and
+observe extension support.
+
+Example:
+    >>> from oscura.iot.coap import CoAPAnalyzer, CoAPMessage
+    >>> analyzer = CoAPAnalyzer()
+    >>> data = bytes([0x40, 0x01, 0x00, 0x01])  # CON GET message
+    >>> message = analyzer.parse_message(data, timestamp=0.0)
+    >>> print(message.msg_type, message.code)
+    CON GET
+
+References:
+    RFC 7252: CoAP (Constrained Application Protocol)
+    RFC 7959: Blockwise Transfer in CoAP
+    RFC 7641: Observing Resources in CoAP
+"""
+
+from __future__ import annotations
+
+from oscura.iot.coap.analyzer import CoAPAnalyzer, CoAPExchange, CoAPMessage
+from oscura.iot.coap.options import CONTENT_FORMATS, OPTIONS
+
+__all__ = [
+    "CONTENT_FORMATS",
+    "OPTIONS",
+    "CoAPAnalyzer",
+    "CoAPExchange",
+    "CoAPMessage",
+]