Metadata-Version: 2.4
Name: oscura
Version: 0.5.1
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
Project-URL: Repository, https://github.com/oscura-re/oscura
Project-URL: Changelog, https://github.com/oscura-re/oscura/blob/main/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/oscura-re/oscura/issues
Project-URL: Discussions, https://github.com/oscura-re/oscura/discussions
License-Expression: MIT
License-File: LICENSE
Keywords: automotive-protocols,can-bus,crc-recovery,device-replication,embedded-systems,exploitation,hardware-reverse-engineering,hardware-security,i2c,ieee-compliance,logic-analyzer,obd-ii,oscilloscope,protocol-analysis,protocol-decoder,protocol-inference,reverse-engineering,right-to-repair,security-research,signal-analysis,spectral-analysis,spi,state-machine-learning,uart,unknown-protocol,vulnerability-analysis,waveform-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Security
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: dpkt<2.0.0,>=1.9.0
Requires-Dist: jinja2<4.0.0,>=3.1
Requires-Dist: matplotlib<4.0.0,>=3.7.0
Requires-Dist: numpy<3.0.0,>=1.24.0
Requires-Dist: pandas<3.0.0,>=2.0.0
Requires-Dist: psutil<7.0.0,>=5.9.0
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<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'
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'all'
Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'all'
Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'all'
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'all'
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: rapidfuzz<4.0.0,>=3.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'
Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'all'
Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'all'
Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'all'
Provides-Extra: analysis
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<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'
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: fuzzy
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'fuzzy'
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
Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'jupyter'
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'jupyter'
Requires-Dist: nbconvert<8.0.0,>=7.0.0; extra == 'jupyter'
Provides-Extra: oscilloscopes
Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'oscilloscopes'
Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'oscilloscopes'
Provides-Extra: reporting
Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'reporting'
Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'reporting'
Provides-Extra: routing
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'routing'
Description-Content-Type: text/markdown

# Oscura

**Hardware Reverse Engineering Framework**

Extract complete system understanding from any signal source—oscilloscopes, logic analyzers, network captures, side-channel traces—through:

- Unknown protocol reverse engineering (physical layer detection, message format inference, field boundaries, CRC recovery)
- State machine extraction and protocol behavior analysis
- Side-channel cryptanalysis (power analysis, timing attacks, EM leakage)
- IEEE-compliant measurements and signal characterization

[![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)
[![codecov](https://codecov.io/gh/oscura-re/oscura/graph/badge.svg)](https://codecov.io/gh/oscura-re/oscura)
[![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)

---

## Vision

Hardware systems are obscured through proprietary protocols, undocumented interfaces, cryptographic obfuscation, and black-box designs. Whether imposed by vendors, governments, or time itself—**Oscura illuminates what others obscure.**

**Built For:**

- **Security researchers** analyzing embedded systems, IoT vulnerabilities, side-channel leakage
- **Hardware engineers** validating signal integrity, power supply design, EMC compliance
- **Protocol developers** testing implementations against IEEE standards
- **Automotive engineers** analyzing CAN/LIN/FlexRay for diagnostics and security research
- **Right-to-repair advocates** documenting and replicating undocumented interfaces
- **Academic researchers** studying signal processing, cryptanalysis, and hardware security
- **Vintage computing enthusiasts** preserving and analyzing retro hardware (1960s–present)
- **Defense and intelligence analysts** for forensics and threat assessment

**What We Enable:**

- **Protocol Reverse Engineering**: CRC recovery, message format inference, state machine extraction for security research, protocol development, right-to-repair documentation
- **Signal Intelligence**: Auto-classify unknown signals (digital/analog, periodicity, SNR) to guide reverse engineering strategy
- **Cryptographic Analysis**: Side-channel attacks (DPA/CPA, timing, mutual information) for vulnerability assessment and implementation validation
- **Automotive Reverse Engineering**: CAN/LIN/FlexRay analysis (differential, stimulus-response, hypothesis-driven discovery) for aftermarket, diagnostics, security research (no vendor lock-in)
- **Debug Interface Analysis**: JTAG/SWD/UART for firmware extraction, bootloader analysis, and development/recovery workflows
- **Binary Format Recovery**: 100+ magic bytes, structure alignment, auto-parser generation for right-to-repair and vulnerability research
- **Obsolete System Replication**: Logic family auto-detection (ECL/RTL/DTL/TTL, 1960s-present), IC timing validation, modern replacements for vintage hardware preservation
- **Evidence-Based Discovery**: Hypothesis tracking, statistical validation, confidence scoring, full audit trails for reproducible reverse engineering
- **Attack Surface Mapping**: State machine extraction, stimulus-response correlation, differential analysis for vulnerability discovery and exploitation
- **Intelligence Sharing**: Wireshark dissectors (validated Lua), DBC files, auto-generated parsers, multi-format reports (PDF/HTML/PPTX) for collaboration

---

## Installation

```bash
# Production use
pip install oscura

# Development (recommended - includes quality tools)
git clone https://github.com/oscura-re/oscura.git
cd oscura
./scripts/setup.sh
```

**Requirements:** Python 3.12+ | [See pyproject.toml for dependencies](pyproject.toml)

---

## Quick Start

### Decode Unknown Protocol in 5 Lines

```python
import oscura as osc

# Load oscilloscope capture
trace = osc.load("mystery_device.wfm")

# Auto-detect and decode
decoder = osc.auto_detect_protocol(trace)
messages = decoder.decode(trace)
print(f"Decoded {len(messages)} {decoder.name} messages")
```

### Side-Channel Attack on AES

```python
from oscura.loaders import load_chipwhisperer
from oscura.analyzers.side_channel import CPAAnalyzer

# Load power traces from ChipWhisperer capture
traces = load_chipwhisperer("aes_traces.npy")

# Correlation Power Analysis
cpa = CPAAnalyzer(leakage_model="hamming_weight", target_byte=0)
result = cpa.analyze(traces.traces, traces.plaintexts)

print(f"Key byte: 0x{result.key_guess:02X}")
print(f"Correlation: {result.max_correlation:.4f}")
print(f"Confidence: {'HIGH' if result.max_correlation > 0.8 else 'LOW'}")
```

### Black-Box Protocol Reverse Engineering

```python
from oscura.sessions import BlackBoxSession

# Create analysis session
session = BlackBoxSession(name="IoT Device RE")

# Differential analysis: compare device states
session.add_recording("idle", "idle.bin")
session.add_recording("button_press", "button.bin")
diff = session.compare("idle", "button_press")

# Automatic field detection
spec = session.generate_protocol_spec()
print(f"Found {len(spec['fields'])} protocol fields")

# Export Wireshark dissector
session.export_results("dissector", "protocol.lua")
```

### Automotive CAN Bus Analysis

```python
from oscura.automotive.can import CANSession

session = CANSession(name="Vehicle RE")
session.add_recording("idle", "idle.blf")
session.add_recording("accelerate", "accel.blf")

# Identify changed CAN IDs
diff = session.compare("idle", "accelerate")
print(f"Changed IDs: {diff.details['changed_ids']}")

# Export DBC file for further analysis
session.export_dbc("vehicle.dbc")
```

**More examples:** [20 demo categories](demonstrations/) with 112 comprehensive demonstrations covering every capability

---

## Core Capabilities

### Protocol Reverse Engineering & Development

| Capability                    | Use Cases (Development / Reverse Engineering)                                                                                                                                                                                                 | Location                                                |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **CRC Recovery & Validation** | Checksum development validation / XOR differential technique recovers polynomial, init, xor_out, reflection flags from 4+ message-CRC pairs. Identifies 12+ standard algorithms or brute-forces custom CRCs for proprietary checksum breaking | [`inference/`](src/oscura/inference/)                   |
| **Message Format Inference**  | Protocol documentation / IPART-style ensemble analysis (entropy, alignment, variance, distribution, n-grams) with confidence-scored field boundaries and automatic checksum/counter/timestamp detection                                       | [`inference/`](src/oscura/inference/)                   |
| **State Machine Extraction**  | Protocol testing with L\* active learning (systematic querying) and RPNI passive learning / Map authentication flows, command sequences, and hidden states for attack surface analysis with evidence-based hypothesis testing                 | [`inference/`](src/oscura/inference/)                   |
| **Binary Format Recovery**    | Firmware documentation / Magic byte detection (100+ formats including executables, images, archives), structure alignment inference (1/2/4/8/16-byte), auto-generate Python parsers and YAML specs for proprietary file format analysis       | [`inference/`](src/oscura/inference/)                   |
| **Signal Intelligence**       | Automatic analysis guidance / Auto-classify digital vs analog signals, detect periodicity (autocorrelation + FFT), estimate SNR, recommend suitable measurement techniques for unknown signal sources                                         | [`inference/`](src/oscura/inference/)                   |
| **Pattern Discovery**         | Sync marker identification / Find repeating signatures, frame boundaries, magic bytes in raw captures (malware C2, IoT traffic, proprietary protocols)                                                                                        | [`analyzers/patterns/`](src/oscura/analyzers/patterns/) |
| **Physical Layer Detection**  | PCB debugging / Auto-detect baud rates, clock frequencies, logic levels for unknown test points and debug interfaces on embedded devices                                                                                                      | [`inference/`](src/oscura/inference/)                   |
| **Stream Reassembly**         | Protocol validation / TCP/UDP stream reconstruction, framing detection, and packet boundary recovery from fragmented captures                                                                                                                 | [`inference/`](src/oscura/inference/)                   |
| **BlackBox Workflow**         | End-to-end RE pipeline / Differential analysis → field hypothesis generation → state machine inference → multi-format export (Wireshark dissectors, DBC, parsers) with full evidence tracking and confidence scoring                          | [`sessions/`](src/oscura/sessions/)                     |

### Cryptographic & Security Analysis

| Capability                      | Use Cases (Validation / Reverse Engineering)                                                                                                                                                                   | Location                                                        |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Power Analysis (DPA/CPA)**    | Crypto implementation validation / Differential and Correlation Power Analysis for key extraction from smart cards, TPMs, secure enclaves with configurable leakage models (Hamming weight/distance)           | [`analyzers/side_channel/`](src/oscura/analyzers/side_channel/) |
| **Timing Attack Analysis**      | Constant-time validation / Statistical timing analysis with mutual information calculation (quantify leakage in bits), effect size measurement (Cohen's d), and outlier detection for vulnerability assessment | [`analyzers/side_channel/`](src/oscura/analyzers/side_channel/) |
| **ChipWhisperer Integration**   | Educational side-channel labs / Direct integration for power/EM trace collection and analysis with standardized formats (.npy, .trs)                                                                           | [`loaders/`](src/oscura/loaders/)                               |
| **Jitter Analysis (IEEE 2414)** | Clock quality validation / TIE, period jitter, RJ/DJ decomposition for detecting clock glitching, fault injection attacks, and timing manipulation                                                             | [`analyzers/jitter/`](src/oscura/analyzers/jitter/)             |
| **Power Supply Analysis**       | DC-DC converter design / Voltage rail characterization for identifying fault injection targets (brownout thresholds, transient response, ripple analysis)                                                      | [`analyzers/power/`](src/oscura/analyzers/power/)               |

### Protocol Decoding

| Category             | Use Cases (Development / Reverse Engineering)                                 | Protocols                                     |
| -------------------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
| **Serial**           | Sensor development, device debugging / Debug console access, flash extraction | UART, SPI, I2C, 1-Wire, I2S, Manchester, HDLC |
| **Automotive**       | Diagnostics, aftermarket dev / ECU security analysis, CAN injection testing   | CAN, CAN-FD, LIN, FlexRay, J1939              |
| **Debug Interfaces** | Firmware development, recovery / Firmware extraction, bootloader analysis     | JTAG (TAP state), SWD, USB                    |
| **Parallel Bus**     | Vintage hardware restoration, instrument control / Industrial system security | IEEE-488 (GPIB), Centronics, ISA              |

**Location:** [`analyzers/protocols/`](src/oscura/analyzers/protocols/) | [`automotive/`](src/oscura/automotive/)

**Auto-detection:** Baud rate recovery, clock extraction, logic level adaptation, confidence scoring

### File Format Support

| Category            | Formats                                       | Location                                                |
| ------------------- | --------------------------------------------- | ------------------------------------------------------- |
| **Oscilloscopes**   | Tektronix (.wfm), Rigol (.wfm), LeCroy (.trc) | [`loaders/`](src/oscura/loaders/)                       |
| **Logic Analyzers** | Sigrok (.sr), VCD (Value Change Dump)         | [`loaders/`](src/oscura/loaders/)                       |
| **Network**         | PCAP, PCAPNG (Wireshark-compatible)           | [`loaders/`](src/oscura/loaders/)                       |
| **Automotive**      | Vector BLF/ASC, ASAM MDF/MF4, DBC, CSV        | [`automotive/loaders/`](src/oscura/automotive/loaders/) |
| **Scientific**      | TDMS (LabVIEW), HDF5, NumPy (.npz), WAV, CSV  | [`loaders/`](src/oscura/loaders/)                       |
| **RF/Network**      | Touchstone S-parameters (.s1p-.s8p)           | [`loaders/`](src/oscura/loaders/)                       |
| **Side-Channel**    | ChipWhisperer (.npy, .trs)                    | [`loaders/`](src/oscura/loaders/)                       |

**Memory-efficient:** Lazy loading, memory-mapped files, chunked processing for TB-scale datasets

### Automotive Engineering & Security

| Capability                       | Use Cases (Development / Reverse Engineering)                                                                                                                                           | Location                                            |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Evidence-Based Discovery**     | Protocol documentation / Hypothesis-driven CAN message field detection with statistical validation, confidence scoring, and evidence tracking for reproducible reverse engineering      | [`automotive/can/`](src/oscura/automotive/can/)     |
| **Stimulus-Response Mapping**    | Input correlation analysis / Correlate user actions (button press, sensor input, vehicle events) to CAN message changes for attack surface identification and control message discovery | [`automotive/can/`](src/oscura/automotive/can/)     |
| **CAN State Machine Extraction** | ECU behavior modeling / Extract protocol state machines from CAN traffic for security analysis and vulnerability discovery                                                              | [`automotive/can/`](src/oscura/automotive/can/)     |
| **Pattern Recognition**          | Signal validation / Auto-detect counters (rolling, wraparound), checksums (XOR, SUM, CRC), sensor encoding patterns in CAN messages                                                     | [`automotive/can/`](src/oscura/automotive/can/)     |
| **Differential Analysis**        | Signal validation / Compare CAN captures (idle vs accelerate, locked vs unlocked) to identify control messages and security-critical signals                                            | [`automotive/can/`](src/oscura/automotive/can/)     |
| **Discovery Persistence**        | Collaboration / Save/load RE progress in .tkcan format with hypothesis tracking for team collaboration and long-term projects                                                           | [`automotive/can/`](src/oscura/automotive/can/)     |
| **DBC Export**                   | Protocol documentation / Generate Vector DBC files from discoveries for integration with industry tools (CANalyzer, Wireshark, Vehicle Spy)                                             | [`automotive/dbc/`](src/oscura/automotive/dbc/)     |
| **J1939 Protocol**               | Heavy vehicle diagnostics / Complete J1939 decoder for truck, construction, agricultural equipment security research (PGN, SPN, suspect/FMI decoding)                                   | [`automotive/j1939/`](src/oscura/automotive/j1939/) |
| **OBD-II Diagnostics**           | Diagnostics development / Complete OBD-II Mode 01-09 support for PIDs, freeze frames, DTCs, VIN extraction                                                                              | [`automotive/obd/`](src/oscura/automotive/obd/)     |
| **UDS Protocol**                 | Security testing / Complete Unified Diagnostic Services decoder for ECU programming, security access, routine control, and diagnostic command fuzzing                                   | [`automotive/uds/`](src/oscura/automotive/uds/)     |

### IEEE-Compliant Measurements

| Standard               | Measurements                                       | Hardware Hacking Relevance                                 |
| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
| **IEEE 181** (Pulse)   | Rise/fall time, pulse width, overshoot, duty cycle | Signal integrity validation for protocol analysis          |
| **IEEE 1241** (ADC)    | SNR, SINAD, THD, SFDR, ENOB                        | ADC characterization for side-channel analysis             |
| **IEEE 1459** (Power)  | Active/reactive power, harmonics, power factor     | Power supply analysis for fault injection targeting        |
| **IEEE 2414** (Jitter) | TIE, period jitter, RJ/DJ decomposition, BER       | Clock glitching attack detection, fault injection analysis |

**Location:** [`analyzers/waveform/`](src/oscura/analyzers/waveform/) | [`analyzers/spectral/`](src/oscura/analyzers/spectral/) | [`analyzers/power/`](src/oscura/analyzers/power/) | [`analyzers/jitter/`](src/oscura/analyzers/jitter/)

### Hardware Acquisition

| Source           | Description                                     | Status      | Location                                  |
| ---------------- | ----------------------------------------------- | ----------- | ----------------------------------------- |
| **File-Based**   | All supported file formats                      | ✅ Complete | [`loaders/`](src/oscura/loaders/)         |
| **SocketCAN**    | Linux CAN interfaces (vcan, physical CAN)       | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
| **Saleae Logic** | Direct Logic analyzer streaming                 | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
| **PyVISA**       | Oscilloscopes (Tektronix, Keysight, Rigol, R&S) | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
| **Synthetic**    | Programmable signal generation for testing      | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |

### Export & Intelligence Sharing

| Format                    | Hardware Hacking Use Case                                                                                                                                                                                   | Location                                            |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Wireshark Dissectors**  | Auto-generate validated Lua dissectors with ProtoField type mapping, variable-length field support, TCP/UDP port registration, and checksum validation for live traffic analysis and protocol documentation | [`export/wireshark/`](src/oscura/export/wireshark/) |
| **Binary Parsers**        | Auto-generate Python parsers and YAML specifications from inferred binary formats for firmware analysis, file format documentation, and automated data extraction                                           | [`inference/`](src/oscura/inference/)               |
| **DBC Files**             | Export CAN discoveries to Vector DBC format for integration with industry tools (CANalyzer, Vehicle Spy, Wireshark CAN plugins)                                                                             | [`automotive/dbc/`](src/oscura/automotive/dbc/)     |
| **Multi-Format Reports**  | Generate comprehensive evidence reports in PDF, HTML, PPTX, and Markdown with charts, tables, hypothesis tracking, confidence scoring, and full audit trails for reproducible research                      | [`reporting/`](src/oscura/reporting/)               |
| **Batch Processing**      | Generate comparison reports for entire capture directories with statistical analysis, correlation matrices, and trend visualization                                                                         | [`reporting/`](src/oscura/reporting/)               |
| **Discovery Archives**    | Save/load reverse engineering progress in structured .tkcan format (YAML-based) with hypothesis tracking, field candidates, and validation status for team collaboration                                    | [`automotive/can/`](src/oscura/automotive/can/)     |
| **WaveDrom Diagrams**     | Generate publication-quality timing diagrams from protocol specifications for documentation, academic papers, and technical communication                                                                   | [`export/`](src/oscura/export/)                     |
| **Vintage Logic Reports** | Specialized reports for retro computing with IC identification, timing validation, modern replacement recommendations, and restoration guidance                                                             | [`reporting/`](src/oscura/reporting/)               |

### Obsolete System Characterization & Replication

**For vintage computing restoration, industrial equipment repair, and hardware preservation (1960s-present)**

| Feature                         | Replication Use Case                                                                                                                                                                         | Location                                              |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| **Logic Family Auto-Detection** | Identify unknown vintage chips by voltage levels: ECL (-1.75V), RTL (3.6V), DTL (5V), PMOS (-12V), NMOS (+12V), TTL variants, HC-CMOS, 4000-series for functional cloning without datasheets | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
| **IC Timing Database**          | Validate against 74xx series, 4000 series specifications (propagation delay, setup/hold times) for functional replication and modern FPGA/CPLD implementations                               | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
| **IC Identification**           | Match measured timing characteristics to specific ICs (7400, 74LS138, 74HC595, etc.) for part identification when markings are illegible or missing                                          | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
| **Modern Replacement Mapping**  | Recommend current-production substitutes (74HC → 74LS, CD4000 → 74HC) for restoration projects when original parts are unavailable                                                           | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
| **Open-Collector Detection**    | Identify open-collector/open-drain outputs requiring pull-up resistors for accurate replication                                                                                              | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
| **Protocol Preservation**       | Extract and document undocumented legacy protocols (parallel buses, proprietary serial) for data recovery and system emulation                                                               | [`inference/`](src/oscura/inference/)                 |

---

## Learn By Example

**Demos are the documentation.** Each category includes working code with validation and comprehensive explanations.

### Getting Started (Beginner)

| Demo                                                | What You'll Learn                                 |
| --------------------------------------------------- | ------------------------------------------------- |
| [01_waveform_analysis](demos/01_waveform_analysis/) | Load Tektronix/Rigol captures, basic measurements |
| [02_file_format_io](demos/02_file_format_io/)       | CSV, HDF5, NumPy, custom binary formats           |
| [04_serial_protocols](demos/04_serial_protocols/)   | UART, SPI, I2C decoding with auto-detection       |
| [05_protocol_decoding](demos/05_protocol_decoding/) | Protocol auto-detection pipeline                  |

### Reverse Engineering (Intermediate)

| Demo                                                                  | What You'll Learn                                     |
| --------------------------------------------------------------------- | ----------------------------------------------------- |
| [07_protocol_inference](demos/07_protocol_inference/)                 | State machine learning, CRC recovery, field detection |
| [08_automotive_protocols](demos/08_automotive_protocols/)             | CAN, CAN-FD, LIN, FlexRay analysis                    |
| [17_signal_reverse_engineering](demos/17_signal_reverse_engineering/) | Complete unknown signal analysis workflow             |
| [18_advanced_inference](demos/18_advanced_inference/)                 | Bayesian inference, binary format DSL                 |

### Security & Compliance (Advanced)

| Demo                                                    | What You'll Learn                                  |
| ------------------------------------------------------- | -------------------------------------------------- |
| [12_spectral_compliance](demos/12_spectral_compliance/) | FFT, THD, SNR, SINAD (IEEE 1241)                   |
| [13_jitter_analysis](demos/13_jitter_analysis/)         | TIE, RJ/DJ decomposition, eye diagrams (IEEE 2414) |
| [14_power_analysis](demos/14_power_analysis/)           | DC-DC converter analysis, efficiency (IEEE 1459)   |
| [15_signal_integrity](demos/15_signal_integrity/)       | TDR, S-parameters, setup/hold timing               |
| [16_emc_compliance](demos/16_emc_compliance/)           | CISPR, FCC, MIL-STD electromagnetic compatibility  |

### Complete Workflows (Expert)

| Demo                                                  | What You'll Learn                        |
| ----------------------------------------------------- | ---------------------------------------- |
| [19_complete_workflows](demos/19_complete_workflows/) | End-to-end reverse engineering pipelines |

### Run Your First Demo

```bash
# Generate test data
python demos/generate_all_demo_data.py

# Run waveform analysis demo
python demos/01_waveform_analysis/comprehensive_wfm_analysis.py

# Run protocol inference demo
python demos/07_protocol_inference/01_state_machine_inference.py
```

**Browse all demos:** [demos/](demos/) | [Demo index with descriptions](demos/README.md)

---

## Command Line Interface

```bash
# Signal characterization
oscura characterize capture.wfm

# Protocol decoding
oscura decode uart_capture.wfm --protocol uart --baud 115200

# Batch processing
oscura batch '*.wfm' --analysis characterize

# Differential analysis
oscura compare baseline.wfm modified.wfm

# Interactive REPL
oscura shell

# Generate synthetic test signals
oscura generate --protocol spi --frequency 1MHz --output test.bin
```

**Full reference:** [docs/cli.md](docs/cli.md)

---

## Quality & Testing

Comprehensive test suite with property-based testing, stress tests, and CI enforcement. Current metrics visible in [CI dashboard](https://github.com/oscura-re/oscura/actions) and [code coverage reports](https://codecov.io/gh/oscura-re/oscura).

```bash
# Run test suite (uses pytest in parallel with coverage)
./scripts/test.sh

# Quality checks (linting, type checking, formatting)
./scripts/check.sh

# Auto-fix issues
./scripts/fix.sh

# Full CI validation (pre-push)
./scripts/pre-push.sh
```

**Quality infrastructure:**

- Pre-commit hooks (format, lint, type check)
- Merge queue CI (prevents untested commits)
- Property-based testing (Hypothesis)
- Nightly stress tests
- Security scanning (Bandit, Safety)

**See:** [Testing architecture](docs/testing/) | [Quality gates](.github/workflows/)

---

## Contributing

**We need your expertise.** Whether you're adding a new protocol decoder, improving inference algorithms, or documenting use cases - every contribution illuminates more hardware.

### Quick Start

```bash
git clone https://github.com/oscura-re/oscura.git
cd oscura
./scripts/setup.sh                    # Complete setup with hooks
./scripts/test.sh                     # Verify environment
```

### What We Need

- **Protocol Decoders:** Proprietary protocols you've reverse engineered
- **File Format Loaders:** Oscilloscope/LA formats we don't support yet
- **Inference Algorithms:** Better state machine learning, field detection
- **Hardware Sources:** Integration with more DAQ systems
- **Documentation:** Real-world case studies and tutorials
- **Validation:** Test our tools on your captures

**Full guide:** [CONTRIBUTING.md](CONTRIBUTING.md) | [Architecture docs](docs/architecture/)

---

## Documentation

### User Guides

- [Quick Start Guide](docs/guides/quick-start.md) - Installation and first steps
- [Black-Box Protocol Analysis](docs/guides/blackbox-analysis.md) - Unknown protocol RE
- [Side-Channel Analysis](docs/guides/side-channel-analysis.md) - DPA/CPA/timing attacks
- [Hardware Acquisition](docs/guides/hardware-acquisition.md) - Direct instrument control
- [Complete Workflows](docs/guides/workflows.md) - End-to-end analysis pipelines

### API Reference

- [API Documentation](docs/api/) - Complete API reference
- [Session Management](docs/api/session-management.md) - Interactive analysis sessions
- [CLI Reference](docs/cli.md) - Command-line interface

### Development

- [Architecture](docs/architecture/) - Design principles and patterns
- [Testing Guide](docs/testing/) - Test suite architecture
- [CHANGELOG](CHANGELOG.md) - Version history and migration guides

---

## Project Status

**Latest Release:** [See current version and release notes](https://github.com/oscura-re/oscura/releases/latest)

**Active Development Areas:**

- Side-channel analysis and cryptographic attack frameworks
- Vintage computing support (retro logic families, IC identification)
- Industrial and automotive protocol decoders
- Hardware acquisition from diverse sources
- Inference and machine learning for unknown protocols

**See:** [Full changelog](CHANGELOG.md) | [Roadmap discussions](https://github.com/oscura-re/oscura/discussions)

---

## Support

- **Issues:** [GitHub Issues](https://github.com/oscura-re/oscura/issues) - Bug reports and feature requests
- **Discussions:** [GitHub Discussions](https://github.com/oscura-re/oscura/discussions) - Questions and community
- **Security:** [SECURITY.md](SECURITY.md) - Responsible disclosure

---

## Citation

If Oscura helps your research, please cite:

```bibtex
@software{oscura2026,
  title = {Oscura: Hardware Reverse Engineering Framework},
  author = {Oscura Contributors},
  year = {2026},
  url = {https://github.com/oscura-re/oscura},
  version = {0.5.0}
}
```

**Machine-readable:** [CITATION.cff](CITATION.cff)

---

## License

MIT License - [LICENSE](LICENSE)

**Built with:** Python, NumPy, SciPy, Hypothesis

**Standards:** IEEE 181/1241/1459/2414, ISO/IEC, CISPR

**Supported by:** Security researchers, right-to-repair advocates, open source community

---

**Oscura** - _Illuminate what others obscure_
