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

oscura/sessions/generic.py

@@ -0,0 +1,189 @@
+"""Generic analysis session implementation.
+
+This module provides GenericSession - a concrete implementation of AnalysisSession
+for general-purpose signal analysis. It wraps the existing session.Session class
+to provide the unified AnalysisSession interface while maintaining backward
+compatibility.
+
+Example:
+    >>> from oscura.sessions import GenericSession
+    >>> from oscura.acquisition import FileSource
+    >>>
+    >>> # Create generic session
+    >>> session = GenericSession(name="Debug Session")
+    >>> session.add_recording("capture1", FileSource("signal1.wfm"))
+    >>> session.add_recording("capture2", FileSource("signal2.wfm"))
+    >>>
+    >>> # Compare recordings
+    >>> diff = session.compare("capture1", "capture2")
+    >>> print(f"Similarity: {diff.similarity_score:.2%}")
+    >>>
+    >>> # Analyze
+    >>> results = session.analyze()  # Generic waveform analysis
+
+Pattern:
+    GenericSession is the default session type for non-domain-specific
+    analysis. Use domain-specific sessions (CANSession, SerialSession, etc.)
+    when working within a specific protocol or analysis domain.
+
+Migration:
+    The existing oscura.session.Session class continues to work unchanged.
+    GenericSession provides the new AnalysisSession interface while
+    delegating to the existing Session implementation internally.
+
+References:
+    Architecture Plan Phase 0.3: AnalysisSession Generic Implementation
+    src/oscura/session/session.py: Legacy Session class
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from oscura.sessions.base import AnalysisSession
+
+
+class GenericSession(AnalysisSession):
+    """Generic analysis session for general-purpose signal analysis.
+
+    Provides the unified AnalysisSession interface for non-domain-specific
+    analysis. This is the default session type when you don't need CAN,
+    Serial, or other specialized functionality.
+
+    Example:
+        >>> from oscura.sessions import GenericSession
+        >>> from oscura.acquisition import FileSource
+        >>>
+        >>> session = GenericSession()
+        >>> session.add_recording("test1", FileSource("capture1.wfm"))
+        >>> session.add_recording("test2", FileSource("capture2.wfm"))
+        >>>
+        >>> # Compare traces
+        >>> diff = session.compare("test1", "test2")
+        >>> print(f"Changed: {diff.changed_bytes} samples")
+        >>>
+        >>> # Generic analysis
+        >>> results = session.analyze()
+        >>> print(results["num_recordings"])
+    """
+
+    def analyze(self) -> dict[str, Any]:
+        """Perform generic waveform analysis on all recordings.
+
+        Analyzes all loaded recordings and provides summary statistics,
+        basic waveform measurements, and comparison results.
+
+        Returns:
+            Dictionary with analysis results:
+                - num_recordings: Number of recordings
+                - recordings: List of recording names
+                - summary: Summary statistics for each recording
+
+        Example:
+            >>> session = GenericSession()
+            >>> session.add_recording("sig", FileSource("capture.wfm"))
+            >>> results = session.analyze()
+            >>> print(results["summary"]["sig"]["mean"])
+        """
+        import numpy as np
+
+        results: dict[str, Any] = {
+            "num_recordings": len(self.recordings),
+            "recordings": self.list_recordings(),
+            "summary": {},
+        }
+
+        # Analyze each recording
+        from oscura.core.types import IQTrace
+
+        for name in self.list_recordings():
+            trace = self.get_recording(name)
+
+            # Handle IQTrace separately
+            if isinstance(trace, IQTrace):
+                raise TypeError("IQTrace analysis not yet supported in GenericSession")
+
+            # Basic statistics
+            summary = {
+                "num_samples": len(trace.data),
+                "sample_rate": trace.metadata.sample_rate,
+                "duration": len(trace.data) / trace.metadata.sample_rate,
+                "mean": float(np.mean(trace.data)),
+                "std": float(np.std(trace.data)),
+                "min": float(np.min(trace.data)),
+                "max": float(np.max(trace.data)),
+                "rms": float(np.sqrt(np.mean(trace.data**2))),
+            }
+
+            results["summary"][name] = summary
+
+        # If multiple recordings, add comparisons
+        if len(self.recordings) >= 2:
+            results["comparisons"] = {}
+            names = self.list_recordings()
+            for i in range(len(names)):
+                for j in range(i + 1, len(names)):
+                    comparison_key = f"{names[i]}_vs_{names[j]}"
+                    comp_result = self.compare(names[i], names[j])
+                    results["comparisons"][comparison_key] = {
+                        "similarity": comp_result.similarity_score,
+                        "changed_samples": comp_result.changed_bytes,
+                    }
+
+        return results
+
+    def export_results(self, format: str, path: str | Path) -> None:
+        """Export analysis results to file.
+
+        Extends base export with additional formats for generic analysis.
+
+        Args:
+            format: Export format ("report", "json", "csv").
+            path: Output file path.
+
+        Raises:
+            ValueError: If format not supported.
+
+        Example:
+            >>> session.export_results("report", "analysis.txt")
+            >>> session.export_results("json", "results.json")
+        """
+        path = Path(path)
+
+        if format == "json":
+            # Export as JSON
+            import json
+
+            results = self.analyze()
+
+            with open(path, "w") as f:
+                json.dump(results, f, indent=2)
+
+        elif format == "csv":
+            # Export summary as CSV
+            import csv
+
+            results = self.analyze()
+
+            with open(path, "w", newline="") as f:
+                if not results["summary"]:
+                    return  # No data to export
+
+                # Get fieldnames from first recording
+                first_rec = next(iter(results["summary"].values()))
+                fieldnames = ["recording"] + list(first_rec.keys())
+
+                writer = csv.DictWriter(f, fieldnames=fieldnames)
+                writer.writeheader()
+
+                for name, summary in results["summary"].items():
+                    row = {"recording": name, **summary}
+                    writer.writerow(row)
+
+        else:
+            # Fall back to base implementation (text report)
+            super().export_results(format, path)
+
+
+__all__ = ["GenericSession"]

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.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oscura
-Version: 0.1.2
+Version: 0.4.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,11 +51,14 @@ 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'
 Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'all'
 Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'all'
+Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'all'
+Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'all'
 Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'all'
 Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'all'
 Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'all'
@@ -67,7 +70,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,11 +78,15 @@ 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'
 Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'dev'
 Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'dev'
+Provides-Extra: hardware
+Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'hardware'
+Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'hardware'
 Provides-Extra: hdf5
 Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'hdf5'
 Provides-Extra: jupyter
@@ -98,10 +105,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)
 
 ---
 
@@ -109,11 +132,15 @@ Description-Content-Type: text/markdown
 
 Oscura is a hardware reverse engineering framework for security researchers, right-to-repair advocates, defense analysts, and commercial intelligence teams. From oscilloscope captures to complete system understanding.
 
-**Reverse Engineering**: Unknown protocol discovery • State machine extraction • CRC/checksum recovery • Proprietary device replication • Security vulnerability analysis
+**Reverse Engineering**: Unknown protocol discovery • State machine extraction • CRC/checksum recovery • Proprietary device replication • Security vulnerability analysis • Black-box protocol analysis
+
+**Signal Analysis**: IEEE-compliant measurements (181/1241/1459/2414) • Comprehensive protocol decoding (16+ protocols) • Spectral analysis • Timing characterization • Side-channel analysis (DPA/CPA/timing attacks)
+
+**Unified Acquisition**: File-based • Hardware sources (SocketCAN, Saleae, PyVISA - Phase 2) • Synthetic generation • Polymorphic Source protocol
 
-**Signal Analysis**: IEEE-compliant measurements (181/1241/1459/2414) • Comprehensive protocol decoding (16+ protocols) • Spectral analysis • Timing characterization
+**Interactive Sessions**: Domain-specific analysis sessions • BlackBoxSession for protocol RE • Differential analysis • Field hypothesis generation • Protocol specification export
 
-**Built For**: Exploitation • Replication • Defense analysis • Commercial intelligence • Right-to-repair
+**Built For**: Exploitation • Replication • Defense analysis • Commercial intelligence • Right-to-repair • Cryptographic research
 
 ---
 
@@ -126,17 +153,19 @@ 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
 ```
 
 ---
 
 ## Quick Start
 
+### Signal Analysis
+
 ```python
 import oscura as osc
 
@@ -153,6 +182,57 @@ decoder = UARTDecoder(baud_rate=115200)
 messages = decoder.decode(trace)
 ```
 
+### Black-Box Protocol Reverse Engineering
+
+```python
+from oscura.sessions import BlackBoxSession
+from oscura.acquisition import FileSource
+
+# Create analysis session
+session = BlackBoxSession(name="IoT Device RE")
+
+# Add recordings from different stimuli
+session.add_recording("idle", FileSource("idle.bin"))
+session.add_recording("button_press", FileSource("button.bin"))
+
+# Differential analysis
+diff = session.compare("idle", "button_press")
+print(f"Changed bytes: {diff.changed_bytes}")
+
+# Generate protocol specification
+spec = session.generate_protocol_spec()
+print(f"Detected {len(spec['fields'])} protocol fields")
+
+# Export Wireshark dissector
+session.export_results("dissector", "protocol.lua")
+```
+
+### CAN Protocol Analysis
+
+```python
+from oscura.automotive.can import CANSession
+from oscura.acquisition import FileSource
+
+# Create session
+session = CANSession(name="Vehicle Analysis")
+
+# Add recordings from CAN bus captures
+session.add_recording("idle", FileSource("idle.blf"))
+session.add_recording("accelerate", FileSource("accelerate.blf"))
+
+# Analyze traffic
+analysis = session.analyze()
+print(f"Messages: {analysis['inventory']['total_messages']}")
+print(f"Unique IDs: {len(analysis['inventory']['message_ids'])}")
+
+# Compare recordings
+diff = session.compare("idle", "accelerate")
+print(f"Changed IDs: {len(diff.details['changed_ids'])}")
+
+# Export DBC file
+session.export_dbc("vehicle.dbc")
+```
+
 ---
 
 ## Learn by Example
@@ -192,7 +272,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 +305,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
 
-# Generate report
-oscura report capture.wfm -o report.pdf
+# Batch process multiple files
+oscura batch '*.wfm' --analysis characterize
 
-# Convert formats
-oscura convert input.wfm output.csv
+# Compare two signals
+oscura compare before.wfm after.wfm
+
+# Interactive shell
+oscura shell
 ```
 
 See [CLI Reference](docs/cli.md) for complete documentation.
@@ -264,9 +347,28 @@ uv sync --all-extras
 
 ## Documentation
 
-- **[Demos](demos/)** - Start here (working examples)
+### Getting Started
+
+- **[Quick Start Guide](docs/guides/quick-start.md)** - Begin here
+- **[Demos](demos/)** - Working examples for every feature
+- **[Migration Guide](docs/migration/v0-to-v1.md)** - Upgrade from older versions
+
+### User Guides
+
+- **[Black-Box Protocol Analysis](docs/guides/blackbox-analysis.md)** - Unknown protocol reverse engineering
+- **[Hardware Acquisition](docs/guides/hardware-acquisition.md)** - Direct hardware integration (Phase 2)
+- **[Side-Channel Analysis](docs/guides/side-channel-analysis.md)** - Power/timing/EM attacks
+- **[Workflows](docs/guides/workflows.md)** - Complete analysis workflows
+
+### API Reference
+
 - **[API Reference](docs/api/)** - Complete API documentation
+- **[Session Management](docs/api/session-management.md)** - Interactive analysis sessions
 - **[CLI Reference](docs/cli.md)** - Command line usage
+
+### Development
+
+- **[Architecture](docs/architecture/)** - Design principles and patterns
 - **[Testing Guide](docs/testing/)** - Test suite architecture
 - **[CHANGELOG](CHANGELOG.md)** - Version history