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

oscura/{search → utils/search}/pattern.py

@@ -77,7 +77,38 @@ def find_pattern(
     if trace.size == 0:
         return []
 
-    # Convert pattern to array if integer
+    # Phase 1: Input normalization
+    pattern_arr = _normalize_pattern(pattern)
+    mask_arr = _normalize_mask(mask, pattern_arr)
+
+    # Phase 2: Convert trace to digital format
+    digital_packed = _convert_trace_to_digital(trace, threshold)
+
+    if digital_packed.size < pattern_arr.size:
+        return []
+
+    # Phase 3: Sliding window search with mask
+    return _sliding_window_search(digital_packed, pattern_arr, mask_arr, min_spacing)
+
+
+def _normalize_pattern(pattern: int | NDArray[np.uint8]) -> NDArray[np.uint8]:
+    """Normalize pattern input to numpy array.
+
+    Args:
+        pattern: Pattern as integer or array.
+
+    Returns:
+        Pattern as uint8 numpy array.
+
+    Raises:
+        ValueError: If pattern is negative or empty.
+
+    Example:
+        >>> _normalize_pattern(0xAA)
+        array([170], dtype=uint8)
+        >>> _normalize_pattern(0x1234)
+        array([18, 52], dtype=uint8)
+    """
     if isinstance(pattern, int):
         if pattern < 0:
             raise ValueError("Pattern must be non-negative")
@@ -97,7 +128,31 @@ def find_pattern(
     if pattern_arr.size == 0:
         raise ValueError("Pattern cannot be empty")
 
-    # Convert mask to array if integer
+    return pattern_arr
+
+
+def _normalize_mask(
+    mask: int | NDArray[np.uint8] | None, pattern_arr: NDArray[np.uint8]
+) -> NDArray[np.uint8]:
+    """Normalize mask input to numpy array matching pattern length.
+
+    Args:
+        mask: Mask as integer, array, or None.
+        pattern_arr: Pattern array to match length to.
+
+    Returns:
+        Mask as uint8 numpy array with same length as pattern.
+
+    Raises:
+        ValueError: If mask and pattern have different lengths.
+
+    Example:
+        >>> pattern = np.array([0xAA, 0x55], dtype=np.uint8)
+        >>> _normalize_mask(0xFF, pattern)
+        array([255, 255], dtype=uint8)
+        >>> _normalize_mask(None, pattern)
+        array([255, 255], dtype=uint8)
+    """
     if mask is not None:
         if isinstance(mask, int):
             mask_bytes: list[int] = []
@@ -117,7 +172,32 @@ def find_pattern(
         # Default: all bits matter
         mask_arr = np.full(pattern_arr.size, 0xFF, dtype=np.uint8)
 
-    # Convert analog trace to digital if needed
+    return mask_arr
+
+
+def _convert_trace_to_digital(
+    trace: NDArray[np.float64] | NDArray[np.uint8], threshold: float | None
+) -> NDArray[np.uint8]:
+    """Convert trace to digital packed format.
+
+    If trace is already digital (uint8), returns as-is.
+    If trace is analog (float), converts using threshold and packs bits.
+
+    Args:
+        trace: Input trace (analog or digital).
+        threshold: Threshold for analog-to-digital conversion.
+
+    Returns:
+        Digital trace as packed uint8 array.
+
+    Raises:
+        ValueError: If analog trace provided without threshold.
+
+    Example:
+        >>> analog = np.array([1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0])
+        >>> _convert_trace_to_digital(analog, 0.5)
+        array([170], dtype=uint8)  # 0b10101010 = 0xAA
+    """
     if trace.dtype != np.uint8:
         if threshold is None:
             raise ValueError(
@@ -136,10 +216,33 @@ def find_pattern(
     else:
         digital_packed = cast("NDArray[np.uint8]", trace)
 
-    if digital_packed.size < pattern_arr.size:
-        return []
+    return digital_packed
+
 
-    # Sliding window pattern matching with mask
+def _sliding_window_search(
+    digital_packed: NDArray[np.uint8],
+    pattern_arr: NDArray[np.uint8],
+    mask_arr: NDArray[np.uint8],
+    min_spacing: int,
+) -> list[tuple[int, NDArray[np.uint8]]]:
+    """Perform sliding window pattern matching with mask.
+
+    Args:
+        digital_packed: Digital trace data.
+        pattern_arr: Pattern to search for.
+        mask_arr: Mask for wildcard matching.
+        min_spacing: Minimum spacing between matches.
+
+    Returns:
+        List of (index, matched_data) tuples.
+
+    Example:
+        >>> data = np.array([0xAA, 0x55, 0xAA], dtype=np.uint8)
+        >>> pattern = np.array([0xAA], dtype=np.uint8)
+        >>> mask = np.array([0xFF], dtype=np.uint8)
+        >>> _sliding_window_search(data, pattern, mask, 1)
+        [(0, array([170], dtype=uint8)), (2, array([170], dtype=uint8))]
+    """
     matches: list[tuple[int, NDArray[np.uint8]]] = []
     i = 0
 
@@ -147,10 +250,10 @@ def find_pattern(
         window = digital_packed[i : i + len(pattern_arr)]
 
         # Apply mask and compare
-        masked_window = window & mask_arr
-        masked_pattern = pattern_arr & mask_arr
-
-        if np.array_equal(masked_window, masked_pattern):
+        if _matches_pattern(window, pattern_arr, mask_arr):
+            # NECESSARY COPY: window is a numpy view that gets reused.
+            # Without .copy(), all matches would reference same memory location.
+            # Could optimize: store indices + lazy evaluation instead of copies.
             matches.append((i, window.copy()))
             # Skip ahead by min_spacing to avoid overlapping matches
             i += max(1, min_spacing)
@@ -158,3 +261,28 @@ def find_pattern(
             i += 1
 
     return matches
+
+
+def _matches_pattern(
+    window: NDArray[np.uint8], pattern: NDArray[np.uint8], mask: NDArray[np.uint8]
+) -> bool:
+    """Check if window matches pattern with mask.
+
+    Args:
+        window: Data window to check.
+        pattern: Pattern to match.
+        mask: Mask for wildcard positions.
+
+    Returns:
+        True if window matches pattern under mask.
+
+    Example:
+        >>> window = np.array([0xA5], dtype=np.uint8)
+        >>> pattern = np.array([0xA0], dtype=np.uint8)
+        >>> mask = np.array([0xF0], dtype=np.uint8)
+        >>> _matches_pattern(window, pattern, mask)
+        True
+    """
+    masked_window = window & mask
+    masked_pattern = pattern & mask
+    return bool(np.array_equal(masked_window, masked_pattern))

oscura/utils/serial.py

@@ -0,0 +1,51 @@
+"""Serial port connection utilities.
+
+This module provides serial port connection helpers used across validation modules.
+"""
+
+from typing import Any
+
+
+def connect_serial_port(
+    port: str,
+    baud_rate: int,
+    timeout: float = 1.0,
+    **kwargs: Any,
+) -> Any:
+    """Connect to serial port with validation.
+
+    Args:
+        port: Serial port path (e.g., '/dev/ttyUSB0', 'COM3')
+        baud_rate: Baud rate (e.g., 9600, 115200)
+        timeout: Read timeout in seconds
+        **kwargs: Additional arguments passed to serial.Serial
+
+    Returns:
+        Serial connection object
+
+    Raises:
+        ImportError: If pyserial is not installed
+        ValueError: If port is not a string
+        OSError: If serial port cannot be opened
+
+    Example:
+        >>> conn = connect_serial_port('/dev/ttyUSB0', 115200)
+        >>> conn.write(b'test')
+        >>> conn.close()
+    """
+    try:
+        import serial  # type: ignore[import-untyped]
+    except ImportError as e:
+        raise ImportError(
+            "pyserial is required for serial interface. Install with: pip install pyserial"
+        ) from e
+
+    if not isinstance(port, str):
+        raise ValueError(f"Serial port must be string, got {type(port)}")
+
+    return serial.Serial(
+        port=port,
+        baudrate=baud_rate,
+        timeout=timeout,
+        **kwargs,
+    )

oscura/utils/storage/__init__.py

@@ -0,0 +1,61 @@
+"""Storage backends for persisting analysis results.
+
+This module provides database backends for storing and querying
+reverse engineering session data, protocol analysis results,
+and decoded messages.
+
+Example:
+    >>> from oscura.utils.storage import DatabaseBackend, DatabaseConfig
+    >>>
+    >>> # Create database backend
+    >>> config = DatabaseConfig(url="sqlite:///analysis.db")
+    >>> db = DatabaseBackend(config)
+    >>>
+    >>> # Create project and session
+    >>> project_id = db.create_project("IoT Device RE", "Unknown protocol analysis")
+    >>> session_id = db.create_session(project_id, "blackbox", {"capture": "device.bin"})
+    >>>
+    >>> # Store protocol analysis
+    >>> protocol_id = db.store_protocol(
+    ...     session_id,
+    ...     name="IoT Protocol",
+    ...     spec_json={"fields": [...]},
+    ...     confidence=0.85
+    ... )
+    >>>
+    >>> # Store decoded messages
+    >>> db.store_message(protocol_id, timestamp=0.0, data=b"\\xaa\\x55", decoded={"id": 1})
+    >>>
+    >>> # Query results
+    >>> protocols = db.find_protocols(min_confidence=0.8)
+    >>> sessions = db.get_sessions(project_id)
+    >>> messages = db.query_messages(protocol_id, time_range=(0.0, 1.0))
+
+Available classes:
+    - DatabaseConfig: Configuration dataclass
+    - DatabaseBackend: Main database interface
+    - Project/Session/Protocol/Message: Result dataclasses
+    - QueryResult: Paginated query results
+"""
+
+from oscura.utils.storage.database import (
+    AnalysisResult,
+    DatabaseBackend,
+    DatabaseConfig,
+    Message,
+    Project,
+    Protocol,
+    QueryResult,
+    Session,
+)
+
+__all__ = [
+    "AnalysisResult",
+    "DatabaseBackend",
+    "DatabaseConfig",
+    "Message",
+    "Project",
+    "Protocol",
+    "QueryResult",
+    "Session",
+]