oscura 0.1.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

oscura/analyzers/side_channel/timing.py

@@ -0,0 +1,369 @@
+"""Timing side-channel analysis.
+
+This module implements timing attack analysis for extracting secrets from
+execution time variations in cryptographic implementations.
+
+Example:
+    >>> from oscura.analyzers.side_channel.timing import TimingAnalyzer
+    >>> analyzer = TimingAnalyzer(confidence_level=0.95)
+    >>> result = analyzer.analyze(timings, inputs)
+    >>> if result.has_leak:
+    ...     print(f"Timing leak detected with {result.confidence:.2%} confidence")
+
+References:
+    Kocher "Timing Attacks on Implementations of Diffie-Hellman, RSA, DSS" (CRYPTO 1996)
+    Brumley & Boneh "Remote Timing Attacks are Practical" (USENIX Security 2003)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from scipy import stats
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+__all__ = [
+    "TimingAnalyzer",
+    "TimingAttackResult",
+    "TimingLeak",
+]
+
+
+@dataclass
+class TimingLeak:
+    """Detected timing leak information.
+
+    Attributes:
+        input_bit: Bit position causing leak (if bit-level analysis).
+        input_byte: Byte position causing leak (if byte-level analysis).
+        mean_difference: Mean timing difference between groups.
+        t_statistic: T-test statistic.
+        p_value: Statistical p-value.
+        confidence: Confidence level (1 - p_value).
+        effect_size: Cohen's d effect size.
+    """
+
+    input_bit: int | None
+    input_byte: int | None
+    mean_difference: float
+    t_statistic: float
+    p_value: float
+    confidence: float
+    effect_size: float
+
+    @property
+    def is_significant(self) -> bool:
+        """Check if leak is statistically significant (p < 0.05)."""
+        return self.p_value < 0.05
+
+
+@dataclass
+class TimingAttackResult:
+    """Result of timing attack analysis.
+
+    Attributes:
+        has_leak: Whether timing leak detected.
+        leaks: List of detected leaks.
+        confidence: Overall confidence in leak detection.
+        timing_statistics: Summary statistics of timings.
+    """
+
+    has_leak: bool
+    leaks: list[TimingLeak]
+    confidence: float
+    timing_statistics: dict[str, float]
+
+
+class TimingAnalyzer:
+    """Timing side-channel attack analyzer.
+
+    Detects timing leaks in cryptographic implementations by analyzing
+    execution time variations correlated with input data.
+
+    Args:
+        confidence_level: Confidence level for leak detection (default 0.95).
+        min_samples: Minimum samples required for analysis (default 100).
+
+    Example:
+        >>> analyzer = TimingAnalyzer(confidence_level=0.99)
+        >>> # Measure RSA decryption times
+        >>> timings = measure_decryption_times(ciphertexts)
+        >>> result = analyzer.analyze(timings, ciphertexts)
+        >>> for leak in result.leaks:
+        ...     print(f"Leak at bit {leak.input_bit}: p={leak.p_value:.6f}")
+
+    References:
+        Kocher "Timing Attacks on Implementations of Diffie-Hellman, RSA, DSS"
+    """
+
+    def __init__(self, confidence_level: float = 0.95, min_samples: int = 100) -> None:
+        """Initialize timing analyzer.
+
+        Args:
+            confidence_level: Confidence level (0.0-1.0).
+            min_samples: Minimum number of samples.
+
+        Raises:
+            ValueError: If parameters out of range.
+        """
+        if not 0.0 < confidence_level < 1.0:
+            raise ValueError(f"confidence_level must be in (0, 1), got {confidence_level}")
+        if min_samples < 10:
+            raise ValueError(f"min_samples must be >= 10, got {min_samples}")
+
+        self.confidence_level = confidence_level
+        self.min_samples = min_samples
+
+    def analyze(
+        self,
+        timings: NDArray[np.floating[Any]],
+        inputs: NDArray[np.integer[Any]],
+    ) -> TimingAttackResult:
+        """Analyze timing measurements for leaks.
+
+        Performs statistical analysis (t-tests) to detect correlations
+        between input bits/bytes and execution time.
+
+        Args:
+            timings: Execution times (n_samples,).
+            inputs: Input values (n_samples, input_size) or (n_samples,).
+
+        Returns:
+            TimingAttackResult with detected leaks.
+
+        Raises:
+            ValueError: If inputs invalid or insufficient samples.
+
+        Example:
+            >>> timings = np.array([...])  # Measured execution times
+            >>> inputs = np.random.randint(0, 256, (1000, 16), dtype=np.uint8)
+            >>> result = analyzer.analyze(timings, inputs)
+            >>> print(f"Leaks detected: {len(result.leaks)}")
+        """
+        if len(timings) < self.min_samples:
+            raise ValueError(f"Insufficient samples: {len(timings)} < {self.min_samples}")
+
+        if len(timings) != len(inputs):
+            raise ValueError(f"Timings ({len(timings)}) and inputs ({len(inputs)}) length mismatch")
+
+        # Compute timing statistics
+        timing_stats = {
+            "mean": float(np.mean(timings)),
+            "std": float(np.std(timings)),
+            "min": float(np.min(timings)),
+            "max": float(np.max(timings)),
+            "median": float(np.median(timings)),
+        }
+
+        # Detect leaks
+        leaks: list[TimingLeak] = []
+
+        if inputs.ndim == 1:
+            # Single byte per input
+            byte_leaks = self._analyze_byte_leaks(timings, inputs, byte_pos=0)
+            leaks.extend(byte_leaks)
+        else:
+            # Multiple bytes per input
+            for byte_pos in range(inputs.shape[1]):
+                byte_leaks = self._analyze_byte_leaks(timings, inputs[:, byte_pos], byte_pos)
+                leaks.extend(byte_leaks)
+
+        # Overall confidence is max of individual leak confidences
+        overall_confidence = max([leak.confidence for leak in leaks], default=0.0)
+
+        return TimingAttackResult(
+            has_leak=len(leaks) > 0,
+            leaks=leaks,
+            confidence=overall_confidence,
+            timing_statistics=timing_stats,
+        )
+
+    def _analyze_byte_leaks(
+        self,
+        timings: NDArray[np.floating[Any]],
+        byte_values: NDArray[np.integer[Any]],
+        byte_pos: int,
+    ) -> list[TimingLeak]:
+        """Analyze timing leaks for specific byte position.
+
+        Args:
+            timings: Execution times.
+            byte_values: Byte values at this position.
+            byte_pos: Byte position index.
+
+        Returns:
+            List of detected leaks for this byte.
+        """
+        leaks: list[TimingLeak] = []
+
+        # Test each bit position in the byte
+        for bit_pos in range(8):
+            # Partition timings by bit value
+            bit_mask = 1 << bit_pos
+            bit_set = (byte_values & bit_mask) != 0
+
+            timings_0 = timings[~bit_set]
+            timings_1 = timings[bit_set]
+
+            # Need sufficient samples in each group
+            if len(timings_0) < 10 or len(timings_1) < 10:
+                continue
+
+            # Welch's t-test (unequal variances)
+            t_stat, p_value = stats.ttest_ind(timings_0, timings_1, equal_var=False)
+
+            # Check for significance
+            alpha = 1.0 - self.confidence_level
+            if p_value < alpha:
+                # Calculate effect size (Cohen's d)
+                mean_diff = float(np.mean(timings_1) - np.mean(timings_0))
+                pooled_std = np.sqrt((np.var(timings_0) + np.var(timings_1)) / 2)
+                effect_size = mean_diff / pooled_std if pooled_std > 0 else 0.0
+
+                leak = TimingLeak(
+                    input_bit=bit_pos,
+                    input_byte=byte_pos,
+                    mean_difference=mean_diff,
+                    t_statistic=float(t_stat),
+                    p_value=float(p_value),
+                    confidence=1.0 - float(p_value),
+                    effect_size=float(effect_size),
+                )
+                leaks.append(leak)
+
+        return leaks
+
+    def analyze_with_partitioning(
+        self,
+        timings: NDArray[np.floating[Any]],
+        inputs: NDArray[np.integer[Any]],
+        partition_func: Callable[[NDArray[np.integer[Any]]], NDArray[np.bool_]],
+    ) -> tuple[float, float, float]:
+        """Analyze timing with custom partitioning function.
+
+        Allows custom grouping criteria beyond bit values.
+
+        Args:
+            timings: Execution times.
+            inputs: Input values.
+            partition_func: Function mapping inputs to boolean partition.
+
+        Returns:
+            Tuple of (mean_difference, t_statistic, p_value).
+
+        Example:
+            >>> # Partition by high/low byte value
+            >>> def partition(x):
+            ...     return x >= 128
+            >>> diff, t_stat, p_val = analyzer.analyze_with_partitioning(
+            ...     timings, inputs, partition
+            ... )
+        """
+        partition = partition_func(inputs)
+
+        timings_0 = timings[~partition]
+        timings_1 = timings[partition]
+
+        if len(timings_0) < 10 or len(timings_1) < 10:
+            return 0.0, 0.0, 1.0
+
+        t_stat, p_value = stats.ttest_ind(timings_0, timings_1, equal_var=False)
+        mean_diff = float(np.mean(timings_1) - np.mean(timings_0))
+
+        return mean_diff, float(t_stat), float(p_value)
+
+    def detect_outliers(
+        self,
+        timings: NDArray[np.floating[Any]],
+        threshold: float = 3.0,
+    ) -> NDArray[np.bool_]:
+        """Detect outlier measurements using modified Z-score.
+
+        Outliers may indicate measurement errors or specific attack scenarios.
+
+        Args:
+            timings: Execution times.
+            threshold: Z-score threshold for outliers (default 3.0).
+
+        Returns:
+            Boolean array marking outliers.
+
+        Example:
+            >>> outliers = analyzer.detect_outliers(timings)
+            >>> clean_timings = timings[~outliers]
+        """
+        median = np.median(timings)
+        mad = np.median(np.abs(timings - median))
+
+        # Modified Z-score (more robust than standard Z-score)
+        if mad == 0:
+            # All values identical
+            return np.zeros(len(timings), dtype=bool)
+
+        modified_z_scores = 0.6745 * (timings - median) / mad
+        outliers: NDArray[np.bool_] = np.abs(modified_z_scores) > threshold
+
+        return outliers
+
+    def compute_mutual_information(
+        self,
+        timings: NDArray[np.floating[Any]],
+        inputs: NDArray[np.integer[Any]],
+        n_bins: int = 10,
+    ) -> float:
+        """Compute mutual information between timings and inputs.
+
+        Measures information leakage in bits.
+
+        Args:
+            timings: Execution times.
+            inputs: Input values.
+            n_bins: Number of bins for discretization.
+
+        Returns:
+            Mutual information in bits.
+
+        Example:
+            >>> mi = analyzer.compute_mutual_information(timings, inputs)
+            >>> print(f"Information leakage: {mi:.4f} bits")
+        """
+        # Discretize timings into bins
+        timing_bins = np.digitize(
+            timings,
+            bins=np.linspace(np.min(timings), np.max(timings), n_bins),
+        )
+
+        # Discretize inputs
+        if inputs.ndim == 1:
+            input_bins = inputs
+        else:
+            # Hash multi-dimensional inputs
+            input_bins = np.sum(inputs * np.arange(inputs.shape[1]), axis=1)
+
+        # Compute joint histogram
+        joint_hist, _, _ = np.histogram2d(
+            timing_bins,
+            input_bins,
+            bins=[n_bins, len(np.unique(input_bins))],
+        )
+        joint_prob = joint_hist / np.sum(joint_hist)
+
+        # Marginal distributions
+        timing_prob = np.sum(joint_prob, axis=1)
+        input_prob = np.sum(joint_prob, axis=0)
+
+        # Mutual information: I(X; Y) = sum p(x,y) * log(p(x,y) / (p(x) * p(y)))
+        mi = 0.0
+        for i in range(len(timing_prob)):
+            for j in range(len(input_prob)):
+                if joint_prob[i, j] > 0:
+                    mi += joint_prob[i, j] * np.log2(
+                        joint_prob[i, j] / (timing_prob[i] * input_prob[j])
+                    )
+
+        return float(mi)

oscura/analyzers/signal_integrity/embedding.py

@@ -12,8 +12,6 @@ References:
     IEEE 370-2020: Standard for Electrical Characterization of PCBs
 """
 
-from __future__ import annotations
-
 import numpy as np
 
 from oscura.analyzers.signal_integrity.sparams import (

oscura/analyzers/signal_integrity/sparams.py

@@ -1,11 +1,14 @@
-"""S-Parameter handling and Touchstone file support.
+"""S-Parameter handling and analysis.
 
-This module provides Touchstone file loading and S-parameter
-calculations including return loss and insertion loss.
+This module provides S-parameter calculations including return loss and
+insertion loss for signal integrity analysis.
 
+For loading Touchstone files, use:
+    >>> from oscura.loaders import load_touchstone
 
 Example:
-    >>> from oscura.analyzers.signal_integrity.sparams import load_touchstone
+    >>> from oscura.loaders import load_touchstone
+    >>> from oscura.analyzers.signal_integrity.sparams import return_loss
     >>> s_params = load_touchstone("cable.s2p")
     >>> rl = return_loss(s_params, frequency=1e9)
 
@@ -16,16 +19,11 @@ References:
 
 from __future__ import annotations
 
-import contextlib
-import re
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
-from oscura.core.exceptions import FormatError, LoaderError
-
 if TYPE_CHECKING:
     from numpy.typing import NDArray
 
@@ -94,201 +92,6 @@ class SParameterData:
         )
 
 
-def load_touchstone(path: str | Path) -> SParameterData:
-    """Load S-parameter data from Touchstone file.
-
-    Supports .s1p through .s8p formats and both Touchstone 1.0
-    and 2.0 file formats.
-
-    Args:
-        path: Path to Touchstone file.
-
-    Returns:
-        SParameterData with loaded S-parameters.
-
-    Raises:
-        LoaderError: If file cannot be read.
-        FormatError: If file format is invalid.
-
-    Example:
-        >>> s_params = load_touchstone("cable.s2p")
-        >>> print(f"Loaded {s_params.n_ports}-port, {len(s_params.frequencies)} points")
-
-    References:
-        Touchstone 2.0 File Format Specification
-    """
-    path = Path(path)
-
-    if not path.exists():
-        raise LoaderError(f"File not found: {path}")
-
-    # Determine number of ports from extension
-    suffix = path.suffix.lower()
-    match = re.match(r"\.s(\d+)p", suffix)
-    if not match:
-        raise FormatError(f"Unsupported file extension: {suffix}")
-
-    n_ports = int(match.group(1))
-
-    try:
-        with open(path) as f:
-            lines = f.readlines()
-    except Exception as e:
-        raise LoaderError(f"Failed to read file: {e}")  # noqa: B904
-
-    return _parse_touchstone(lines, n_ports, str(path))
-
-
-def _parse_touchstone(
-    lines: list[str],
-    n_ports: int,
-    source_file: str,
-) -> SParameterData:
-    """Parse Touchstone file content.
-
-    Args:
-        lines: File lines.
-        n_ports: Number of ports.
-        source_file: Source file path.
-
-    Returns:
-        Parsed SParameterData.
-
-    Raises:
-        FormatError: If file format is invalid.
-    """
-    comments = []
-    option_line = None
-    data_lines = []
-
-    for line in lines:
-        line = line.strip()
-
-        if not line:
-            continue
-
-        if line.startswith("!"):
-            comments.append(line[1:].strip())
-        elif line.startswith("#"):
-            option_line = line
-        else:
-            data_lines.append(line)
-
-    # Parse option line
-    freq_unit = 1e9  # Default GHz
-    format_type = "ma"  # Default MA (magnitude/angle)
-    z0 = 50.0
-
-    if option_line:
-        option_line = option_line.lower()
-        parts = option_line.split()
-
-        for i, part in enumerate(parts):
-            if part in ("hz", "khz", "mhz", "ghz"):
-                freq_unit = {
-                    "hz": 1.0,
-                    "khz": 1e3,
-                    "mhz": 1e6,
-                    "ghz": 1e9,
-                }[part]
-            elif part in ("db", "ma", "ri"):
-                format_type = part
-            elif part == "r":
-                # Reference impedance follows
-                if i + 1 < len(parts):
-                    with contextlib.suppress(ValueError):
-                        z0 = float(parts[i + 1])
-
-    # Parse data
-    frequencies = []
-    s_data = []
-
-    # Number of S-parameters per frequency
-    n_s_params = n_ports * n_ports
-
-    i = 0
-    while i < len(data_lines):
-        # First line has frequency and first S-parameters
-        parts = data_lines[i].split()
-
-        if len(parts) < 1:
-            i += 1
-            continue
-
-        freq = float(parts[0]) * freq_unit
-        frequencies.append(freq)
-
-        # Collect all S-parameter values for this frequency
-        s_values = []
-
-        # Add values from first line
-        for j in range(1, len(parts), 2):
-            if j + 1 < len(parts):
-                val1 = float(parts[j])
-                val2 = float(parts[j + 1])
-                s_values.append((val1, val2))
-
-        i += 1
-
-        # Continue collecting from subsequent lines if needed
-        while len(s_values) < n_s_params and i < len(data_lines):
-            parts = data_lines[i].split()
-
-            # Check if this is a new frequency (has odd number of values)
-            try:
-                float(parts[0])
-                if len(parts) % 2 == 1:
-                    break  # New frequency line
-            except (ValueError, IndexError):
-                pass
-
-            for j in range(0, len(parts), 2):
-                if j + 1 < len(parts):
-                    val1 = float(parts[j])
-                    val2 = float(parts[j + 1])
-                    s_values.append((val1, val2))
-
-            i += 1
-
-        # Convert to complex based on format
-        s_complex = []
-        for val1, val2 in s_values:
-            if format_type == "ri":
-                # Real/Imaginary
-                s_complex.append(complex(val1, val2))
-            elif format_type == "ma":
-                # Magnitude/Angle (degrees)
-                mag = val1
-                angle_rad = np.radians(val2)
-                s_complex.append(mag * np.exp(1j * angle_rad))
-            elif format_type == "db":
-                # dB/Angle (degrees)
-                mag = 10 ** (val1 / 20)
-                angle_rad = np.radians(val2)
-                s_complex.append(mag * np.exp(1j * angle_rad))
-
-        # Reshape into matrix
-        if len(s_complex) == n_s_params:
-            s_matrix = np.array(s_complex).reshape(n_ports, n_ports)
-            s_data.append(s_matrix)
-
-    if len(frequencies) == 0:
-        raise FormatError("No valid frequency points found")
-
-    frequencies_arr = np.array(frequencies, dtype=np.float64)
-    s_matrix_arr = np.array(s_data, dtype=np.complex128)
-
-    return SParameterData(
-        frequencies=frequencies_arr,
-        s_matrix=s_matrix_arr,
-        n_ports=n_ports,
-        z0=z0,
-        format=format_type,
-        source_file=source_file,
-        comments=comments,
-    )
-
-
 def return_loss(
     s_params: SParameterData,
     frequency: float | None = None,
@@ -474,11 +277,30 @@ def _abcd_to_s_single(abcd: NDArray[np.complex128], z0: float) -> NDArray[np.com
     return np.array([[S11, S12], [S21, S22]], dtype=np.complex128)
 
 
+# Backward compatibility: load_touchstone moved to loaders module
+# Import with deprecation warning
+def __getattr__(name: str) -> Any:
+    """Provide backward compatibility for load_touchstone."""
+    if name == "load_touchstone":
+        import warnings
+
+        from oscura.loaders.touchstone import load_touchstone
+
+        warnings.warn(
+            "Importing load_touchstone from oscura.analyzers.signal_integrity.sparams "
+            "is deprecated. Use 'from oscura.loaders import load_touchstone' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return load_touchstone
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
 __all__ = [
     "SParameterData",
     "abcd_to_s",
     "insertion_loss",
-    "load_touchstone",
+    # Note: load_touchstone moved to oscura.loaders module (backward compat via __getattr__)
     "return_loss",
     "s_to_abcd",
 ]

oscura/analyzers/spectral/fft.py

@@ -4,8 +4,6 @@ This module provides FFT-based spectral analysis including chunked processing
 for large datasets.
 """
 
-from __future__ import annotations
-
 from typing import Any
 
 import numpy as np

oscura/analyzers/statistical/__init__.py

@@ -17,6 +17,8 @@ Requirements:
 - RE-ENT-002: Byte Frequency Distribution
 """
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING, Union
 
 import numpy as np
@@ -134,9 +136,7 @@ entropy = shannon_entropy
 DataType = Union[bytes, bytearray, "NDArray[np.uint8]"]
 
 
-def entropy_windowed(
-    data: DataType, window_size: int = 256, step: int = 1
-) -> "NDArray[np.float64]":
+def entropy_windowed(data: DataType, window_size: int = 256, step: int = 1) -> NDArray[np.float64]:
     """Windowed entropy calculation (alias for sliding_entropy)."""
     return sliding_entropy(data, window_size=window_size, step=step)
 

oscura/analyzers/statistical/checksum.py

@@ -5,6 +5,8 @@ This module provides tools for detecting checksum and CRC fields in binary
 messages by analyzing field correlations and testing common algorithms.
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal, Union
 

oscura/analyzers/statistical/classification.py

@@ -6,6 +6,8 @@ binary, compressed, encrypted, or padding using multiple statistical tests
 and heuristics.
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 from typing import Any, Literal, Union