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

oscura/session/session.py

@@ -15,17 +15,26 @@ Example:
 from __future__ import annotations
 
 import gzip
+import hashlib
+import hmac
 import pickle
+import warnings
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 import numpy as np
 
+from oscura.core.exceptions import SecurityError
 from oscura.session.annotations import AnnotationLayer
 from oscura.session.history import OperationHistory
 
+# Session file format constants
+_SESSION_MAGIC = b"OSC1"  # Magic bytes for new format with signature
+_SESSION_SIGNATURE_SIZE = 32  # SHA256 hash size in bytes
+_SECURITY_KEY = hashlib.sha256(b"oscura-session-v1").digest()
+
 
 @dataclass
 class Session:
@@ -273,7 +282,7 @@ class Session:
         include_traces: bool = True,
         compress: bool = True,
     ) -> Path:
-        """Save session to file.
+        """Save session to file with HMAC signature for integrity verification.
 
         Args:
             path: Output path (default: use existing or generate).
@@ -287,9 +296,10 @@ class Session:
             >>> session.save('analysis.tks')
 
         Security Note:
-            Session files use pickle serialization for flexibility. Share
-            session files only with trusted parties. For secure data exchange
-            with untrusted parties, use JSON or HDF5 export formats instead.
+            Session files now include HMAC signatures for integrity verification.
+            Files are still pickle-based - only load from trusted sources.
+            For secure data exchange with untrusted parties, use JSON or HDF5
+            export formats instead.
         """
         if path is None:
             path = self._file_path or Path(f"{self.name.replace(' ', '_')}.tks")
@@ -302,13 +312,23 @@ class Session:
         # Build session data
         data = self._to_dict(include_traces=include_traces)
 
-        # Serialize
+        # Serialize with pickle
+        serialized = pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL)
+
+        # Compute HMAC signature
+        signature = hmac.new(_SECURITY_KEY, serialized, hashlib.sha256).digest()
+
+        # Write: magic bytes + signature + pickled data
         if compress:
             with gzip.open(path, "wb") as f:
-                pickle.dump(data, f)
+                f.write(_SESSION_MAGIC)
+                f.write(signature)
+                f.write(serialized)
         else:
             with open(path, "wb") as f:
-                pickle.dump(data, f)
+                f.write(_SESSION_MAGIC)
+                f.write(signature)
+                f.write(serialized)
 
         self.history.record("save", {"path": str(path)})
 
@@ -401,15 +421,20 @@ class Session:
         return "\n".join(lines)
 
 
-def load_session(path: str | Path) -> Session:
-    """Load session from file.
+def load_session(path: str | Path, *, verify_signature: bool = True) -> Session:
+    """Load session from file with optional signature verification.
 
     Args:
         path: Path to session file (.tks).
+        verify_signature: Verify HMAC signature (default: True). Set to False
+            only when loading legacy session files without signatures.
 
     Returns:
         Loaded Session object.
 
+    Raises:
+        SecurityError: If signature verification fails.
+
     Example:
         >>> session = load_session('debug_session.tks')
         >>> print(session.list_traces())
@@ -419,19 +444,61 @@ def load_session(path: str | Path) -> Session:
         trusted sources. Loading a malicious .tks file could execute arbitrary
         code. Never load session files from untrusted or unknown sources.
 
+        New session files include HMAC signatures for integrity verification.
+        Legacy files without signatures will trigger a warning.
+
         For secure data exchange, consider exporting to JSON or HDF5 formats
         instead of using pickle-based session files.
     """
     path = Path(path)
 
+    # Helper to load with signature verification
+    def _load_with_verification(f: Any, is_compressed: bool = False) -> dict[str, Any]:
+        # Read magic bytes to detect format
+        magic = f.read(len(_SESSION_MAGIC))
+
+        if magic == _SESSION_MAGIC:
+            # New format with signature
+            signature = f.read(_SESSION_SIGNATURE_SIZE)
+            serialized = f.read()
+
+            if verify_signature:
+                # Verify HMAC signature
+                expected = hmac.new(_SECURITY_KEY, serialized, hashlib.sha256).digest()
+                if not hmac.compare_digest(signature, expected):
+                    raise SecurityError(
+                        "Session file signature verification failed",
+                        file_path=str(path),
+                        check_type="HMAC signature",
+                        details="File may be corrupted or tampered with",
+                    )
+
+            # Deserialize verified data
+            data = cast("dict[str, Any]", pickle.loads(serialized))
+        else:
+            # Legacy format without signature
+            warnings.warn(
+                f"Loading legacy session file without signature verification: {path}. "
+                "Re-save the session to enable security features.",
+                UserWarning,
+                stacklevel=3,
+            )
+
+            # Rewind and load as legacy pickle
+            f.seek(0)
+            data = cast("dict[str, Any]", pickle.load(f))
+
+        return data
+
+    # Try loading (compressed or uncompressed)
     try:
         # Try gzip compressed first
         with gzip.open(path, "rb") as f:
-            data = pickle.load(f)
+            data = _load_with_verification(f, is_compressed=True)
     except gzip.BadGzipFile:
         # Fall back to uncompressed
-        with open(path, "rb") as f:
-            data = pickle.load(f)
+        with open(path, "rb") as f:  # type: ignore[assignment]
+            data = _load_with_verification(f, is_compressed=False)
 
     session = Session._from_dict(data)
     session._file_path = path

oscura/testing/synthetic.py

@@ -4,6 +4,8 @@ Provides utilities for generating synthetic test data with known properties
 for validation and testing purposes.
 """
 
+from __future__ import annotations
+
 import struct
 from dataclasses import dataclass, field
 from pathlib import Path

oscura/ui/formatters.py

@@ -19,10 +19,12 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Literal
+from typing import Any, Literal, TypeAlias
 
 # Type alias for color names accepted by colorize()
-type ColorName = Literal["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white"]
+ColorName: TypeAlias = Literal[
+    "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white"
+]
 
 
 class Color(Enum):

oscura/utils/buffer.py

@@ -16,7 +16,7 @@ References:
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, TypeVar, overload
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload
 
 import numpy as np
 
@@ -26,7 +26,7 @@ if TYPE_CHECKING:
 T = TypeVar("T")
 
 
-class CircularBuffer[T]:
+class CircularBuffer(Generic[T]):
     """Fixed-size circular buffer with O(1) operations.
 
     Thread-safe for single producer, single consumer pattern.

oscura/utils/lazy.py

@@ -18,18 +18,18 @@ References:
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 import numpy as np
 from numpy.typing import NDArray
 
+T = TypeVar("T")
+
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-T = TypeVar("T")
-
 
-class LazyProxy[T](ABC):
+class LazyProxy(ABC, Generic[T]):
     """Abstract base class for lazy evaluation proxies.
 
     Defers computation until explicitly requested via .compute().
@@ -169,7 +169,7 @@ class LazyOperation(LazyProxy[Any]):
         return self._operation(*evaluated_operands, **self._kwargs)
 
 
-def lazy_operation[T](
+def lazy_operation(
     func: Callable[..., T],
     *args: Any,
     **kwargs: Any,

oscura/utils/memory_advanced.py

@@ -20,7 +20,7 @@ from collections import OrderedDict
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 import numpy as np
 
@@ -664,7 +664,7 @@ T = TypeVar("T")
 
 
 @dataclass
-class CacheEntry[T]:
+class CacheEntry(Generic[T]):
     """Cache entry with metadata.
 
     Attributes:

oscura/utils/memory_extensions.py

@@ -22,7 +22,7 @@ import hashlib
 import os
 import time
 from collections import OrderedDict
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 import numpy as np
 
@@ -102,7 +102,7 @@ class ArrayManager(ResourceManager):
 # =============================================================================
 
 
-class LRUCache[T]:
+class LRUCache(Generic[T]):
     """Least-Recently-Used cache with memory-based eviction.
 
     Caches intermediate results with automatic eviction when

oscura/visualization/colors.py

@@ -14,8 +14,6 @@ References:
     ColorBrewer schemes
 """
 
-from __future__ import annotations
-
 from typing import Literal
 
 import numpy as np

oscura/visualization/power.py

@@ -5,6 +5,8 @@ This module provides comprehensive power visualization including
 time-domain plots, energy accumulation, and multi-channel views.
 """
 
+from __future__ import annotations
+
 from pathlib import Path
 
 import matplotlib.pyplot as plt

oscura/workflows/multi_trace.py

@@ -3,6 +3,8 @@
 Provides workflows for processing and analyzing multiple traces together.
 """
 
+from __future__ import annotations
+
 import concurrent.futures
 from collections.abc import Iterator
 from dataclasses import dataclass, field

{oscura-0.1.2.dist-info → oscura-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oscura
-Version: 0.1.2
+Version: 0.3.0
 Summary: Unified hardware reverse engineering framework. Extract all information from any system through signals and data. Unknown protocol discovery, state machine extraction, CRC recovery, security analysis. 16+ protocols, IEEE-compliant measurements.
 Project-URL: Homepage, https://github.com/oscura-re/oscura
 Project-URL: Documentation, https://github.com/oscura-re/oscura/tree/main/docs
@@ -39,7 +39,7 @@ Requires-Dist: pyyaml<7.0.0,>=6.0
 Requires-Dist: scipy<2.0.0,>=1.10.0
 Requires-Dist: tm-data-types<1.0.0,>=0.3.0
 Provides-Extra: all
-Requires-Dist: asammdf<8.0.0,>=7.4.0; extra == 'all'
+Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'all'
 Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'all'
 Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'all'
 Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'all'
@@ -51,6 +51,7 @@ Requires-Dist: nbconvert<8.0.0,>=7.0.0; extra == 'all'
 Requires-Dist: networkx<4.0.0,>=3.0; extra == 'all'
 Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'all'
 Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'all'
+Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'all'
 Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'all'
 Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'all'
 Requires-Dist: pytest<10.0.0,>=8.0; extra == 'all'
@@ -67,7 +68,7 @@ Requires-Dist: networkx<4.0.0,>=3.0; extra == 'analysis'
 Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'analysis'
 Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'analysis'
 Provides-Extra: automotive
-Requires-Dist: asammdf<8.0.0,>=7.4.0; extra == 'automotive'
+Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'automotive'
 Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'automotive'
 Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'automotive'
 Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'automotive'
@@ -75,6 +76,7 @@ Provides-Extra: dev
 Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'dev'
 Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'dev'
 Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'dev'
+Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'dev'
 Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'dev'
 Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'dev'
 Requires-Dist: pytest<10.0.0,>=8.0; extra == 'dev'
@@ -98,10 +100,26 @@ Description-Content-Type: text/markdown
 
 **Unified hardware reverse engineering framework. Extract all information from any system through signals and data.**
 
-[![PyPI version](https://badge.fury.io/py/oscura.svg)](https://badge.fury.io/py/oscura)
+**Build Status:**
+[![CI](https://github.com/oscura-re/oscura/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/oscura-re/oscura/actions/workflows/ci.yml)
+[![Code Quality](https://github.com/oscura-re/oscura/actions/workflows/code-quality.yml/badge.svg?branch=main)](https://github.com/oscura-re/oscura/actions/workflows/code-quality.yml)
+[![Documentation](https://github.com/oscura-re/oscura/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/oscura-re/oscura/actions/workflows/docs.yml)
+[![Test Quality](https://github.com/oscura-re/oscura/actions/workflows/test-quality.yml/badge.svg?branch=main)](https://github.com/oscura-re/oscura/actions/workflows/test-quality.yml)
+
+**Package:**
+[![PyPI version](https://img.shields.io/pypi/v/oscura)](https://pypi.org/project/oscura/)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![CI](https://github.com/oscura-re/oscura/workflows/CI/badge.svg)](https://github.com/oscura-re/oscura/actions)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/oscura)](https://pypi.org/project/oscura/)
+
+**Code Quality:**
+[![codecov](https://codecov.io/gh/oscura-re/oscura/graph/badge.svg)](https://codecov.io/gh/oscura-re/oscura)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Docstring Coverage](https://raw.githubusercontent.com/oscura-re/oscura/main/docs/badges/interrogate_badge.svg)](https://github.com/oscura-re/oscura/tree/main/docs)
+
+**Project Status:**
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/oscura-re/oscura/graphs/commit-activity)
+[![Last Commit](https://img.shields.io/github/last-commit/oscura-re/oscura)](https://github.com/oscura-re/oscura/commits/main)
 
 ---
 
@@ -126,11 +144,11 @@ uv pip install oscura
 # Or with pip
 pip install oscura
 
-# Development install
+# Development install (RECOMMENDED)
 git clone https://github.com/oscura-re/oscura.git
 cd oscura
-uv sync --all-extras
-./scripts/setup/install-hooks.sh
+./scripts/setup.sh            # Complete setup (dependencies + hooks)
+./scripts/verify-setup.sh     # Verify environment is ready
 ```
 
 ---
@@ -192,7 +210,7 @@ messages = decoder.decode(trace)
 
 ```bash
 # Generate demo data
-python demos/data_generation/generate_all_demo_data.py
+python demos/generate_all_demo_data.py
 
 # Run a demo
 uv run python demos/01_waveform_analysis/comprehensive_wfm_analysis.py
@@ -225,17 +243,20 @@ Tektronix WFM • Rigol WFM • LeCroy TRC • Sigrok • VCD • CSV • NumPy
 ## Command Line Interface
 
 ```bash
-# Analyze a waveform
-oscura analyze capture.wfm
+# Characterize signal measurements
+oscura characterize capture.wfm
 
 # Decode protocol
-oscura decode capture.wfm --protocol uart --baud 115200
+oscura decode uart.wfm --protocol uart
+
+# Batch process multiple files
+oscura batch '*.wfm' --analysis characterize
 
-# Generate report
-oscura report capture.wfm -o report.pdf
+# Compare two signals
+oscura compare before.wfm after.wfm
 
-# Convert formats
-oscura convert input.wfm output.csv
+# Interactive shell
+oscura shell
 ```
 
 See [CLI Reference](docs/cli.md) for complete documentation.