oscura 0.14.0

Python framework for hardware reverse engineering: signal analysis, protocol decoding, and automated dissector generation. Unified workflows from oscilloscope captures to Wireshark dissectors with IEEE-compliant measurements.

Oscura

Python framework for hardware reverse engineering: signal analysis, protocol decoding, and automated dissector generation.

Unified workflows from oscilloscope captures to Wireshark dissectors. IEEE-compliant measurements, native protocol decoders, differential analysis, and CRC recovery—all in Python without tool juggling.

---

What Oscura Provides

Unified Python framework for hardware reverse engineering workflows:

• File Format Loading - Oscilloscopes (Tektronix, Rigol), logic analyzers (Sigrok, VCD), network captures (PCAP), automotive (BLF), scientific instruments (HDF5, TDMS, Touchstone)
• Protocol Decoding - Serial (UART, SPI, I2C), automotive (CAN, LIN, FlexRay), debug (JTAG, SWD), industrial (Modbus, BACnet, EtherCAT, OPC UA, PROFINET), audio (I2S), wireless (BLE)
• Signal Analysis - Waveform measurements (IEEE 181), spectral analysis (IEEE 1241), jitter analysis (IEEE 2414), power analysis (IEEE 1459), eye diagrams, signal integrity
• Protocol Inference - CRC recovery, state machine extraction, field detection, format identification, magic byte discovery
• Export Automation - Wireshark dissectors, Scapy layers, DBC files, Kaitai Struct, 010 Editor templates, HTML/JSON reports

---

Installation

pip install oscura

For development setup or detailed installation options, see Installation Guide.

Requirements: Python 3.12+ | Dependencies: numpy, scipy, matplotlib, scikit-learn, cantools (all peer-reviewed, industry-standard libraries)

---

Usage Approaches

Oscura provides 5 usage patterns. → Choose your approach

Quick summary:

• Comprehensive Script - Immediate analysis (showcase)
• Convenience API - Python applications (examples)
• Expert API - Full control (API docs)
• YAML Pipeline - Config-driven (guide)
• CLI - Command-line (reference)

---

Example: Unknown Protocol Reverse Engineering

from oscura.sessions import BlackBoxSession

# Differential analysis to identify protocol structure
session = BlackBoxSession(name="Unknown Device")
session.add_recording("idle", "idle.bin")
session.add_recording("active", "active.bin")
diff = session.compare("idle", "active")

# Generate Wireshark dissector from inferred structure
session.export_results("dissector", "protocol.lua")

---

Capabilities Reference

File Format Support

Unified loader with automatic format detection via oscura.load(path):

• Oscilloscopes: Tektronix WFM/TSS, Rigol WFM
• Logic Analyzers: VCD, Sigrok .sr
• Network: PCAP/PCAPNG
• Scientific: HDF5, TDMS, Touchstone S-parameters
• Generic: WAV, CSV, NumPy, binary dumps
• Side-Channel: ChipWhisperer traces

Waveform Measurements (IEEE 181-2011)

Timing, amplitude, and quality measurements with sub-sample interpolation:

• Timing: rise/fall time, period, frequency, pulse width, duty cycle, phase, delay, slew rate
• Amplitude: peak-to-peak, RMS, mean, overshoot, undershoot, top, base
• Advanced: area, burst width, extinction ratio, quality factor

Spectral Analysis (IEEE 1241-2010)

FFT, PSD, quality metrics:

• Frequency Domain: FFT, PSD (Welch method), spectrogram, coherence
• Quality Metrics: THD, SNR, SINAD, SFDR, ENOB
• Advanced: Cepstrum, bispectrum, cross-spectrum, transfer function

Digital Signal Analysis

• Conversion: Threshold detection with hysteresis, edge detection, clock extraction
• Timing: Clock/baud rate detection, pulse width measurement, frame sync
• Logic Levels: TTL, CMOS, LVCMOS, LVDS, ECL detection
• Quality: Glitch detection, timing violations, signal quality metrics

Eye Diagram Analysis

Eye diagram generation and measurements: height, width, area, crossing percentage, Q-factor, BER estimation, mask testing.

Jitter Analysis (IEEE 2414-2020)

RJ/DJ decomposition using dual-Dirac model:

• Components: Random jitter (RJ), deterministic jitter (DJ), periodic jitter (PJ), data-dependent jitter (DDJ)
• Measurements: TIE, period jitter, cycle-to-cycle jitter
• Visualization: Bathtub curves for BER extrapolation

Power Analysis (IEEE 1459-2010)

• Basic: Instantaneous, average, peak, RMS power, energy
• AC Power: Active, reactive, apparent power, power factor
• Harmonics: THD, harmonic content, crest factor
• Quality: Ripple, sag/swell detection, flicker, unbalance

Statistical Analysis

• Descriptive: Mean, median, std dev, quartiles, percentiles
• Distribution: Histograms, skewness, kurtosis, normality tests
• Outliers: Z-score, IQR, MAD, isolation forest, DBSCAN
• Correlation: Auto/cross-correlation, Pearson, Spearman
• Time Series: Periodicity detection, trend analysis, change points

Pattern Recognition

• Period Detection: FFT-based, autocorrelation, multi-method
• Sequences: Repeating patterns, n-grams, Lempel-Ziv complexity
• Entropy: Shannon entropy, byte frequency, encrypted/compressed region detection
• Structure: Magic bytes, headers, delimiters, sync patterns, alignment

Protocol Decoders

Native state machine implementations:

• Serial: UART, SPI, I2C, 1-Wire
• Automotive: CAN, CAN-FD, LIN, FlexRay
• Debug: JTAG (IEEE 1149.1), SWD (ARM CoreSight)
• Industrial: Modbus, BACnet, EtherCAT, OPC UA, PROFINET, HDLC
• Audio: I2S
• Wireless: BLE advertising packets
• Parallel: Centronics, GPIB (IEEE 488.2)

Protocol Inference

• CRC Recovery: Brute-force parameter search, algorithm detection
• Field Detection: Statistical boundary inference, type classification
• Format Analysis: Magic bytes, framing, escaping detection
• Protocol Detection: Multi-heuristic with confidence scoring
• State Machines: RPNI algorithm for state extraction
• Dissector Generation: Wireshark (Lua), Scapy (Python), Kaitai Struct, 010 Editor

Automotive Analysis

• CAN: Frame decoding, ID identification, statistical analysis, differential analysis
• DBC Generation: Signal inference, automatic naming, scaling detection
• Diagnostics: OBD-II, UDS, J1939, DTC lookup
• Security: Replay detection, fuzzing, anomaly detection

Signal Integrity

TDR analysis, S-parameters (Touchstone), insertion/return loss, VSWR, impedance calculation, crosstalk detection.

Machine Learning

• Classification: Signal type, protocol identification, modulation detection (Random Forest/SVM)
• Feature Extraction: Timing, spectral, statistical features
• Clustering: K-means, DBSCAN, hierarchical
• Anomaly Detection: Isolation Forest, One-Class SVM

Visualization

Waveforms, FFT/PSD spectra, spectrograms, histograms, logic analyzer views, eye diagrams, bathtub curves, constellation diagrams, Smith charts, Bode/Nyquist plots, protocol timelines.

Export Formats

JSON, CSV, HTML reports, Wireshark dissectors (Lua), Scapy dissectors (Python), Kaitai Struct (YAML), DBC (CAN database), 010 Editor templates, WAV, VCD, NumPy, HDF5, MATLAB.

---

When to Use Oscura

Best suited for:

• End-to-end Python workflows (capture → analysis → documentation)
• Unknown protocol reverse engineering with differential analysis
• DBC generation from CAN captures (open-source CANalyzer alternative)
• Automatic Wireshark dissector generation from inferred protocols
• Unified API across 14 oscilloscope/logic analyzer formats
• Reproducible research with hypothesis tracking
• Scripted multi-tool RE pipelines

Oscura's strength: Workflow automation combining multiple RE steps with hypothesis-driven analysis.

---

Standards Compliance

Oscura implements measurements per IEEE specifications.

Standard	Coverage	Implementation
IEEE 181-2011	Pulse timing, rise/fall, overshoot, duty cycle	Native algorithms
IEEE 1241-2010	SNR, SINAD, THD, SFDR, ENOB	Native + scipy.signal
IEEE 1459-2010	Active/reactive power, harmonics, power factor	Native + scipy.signal
IEEE 2414-2020	TIE, RJ/DJ decomposition, bathtub curves	Native + scipy.stats

Validation: 475 test files with 80%+ code coverage, property-based testing via Hypothesis.

---

Quality Metrics

Testing: 475 test files, 80%+ coverage with branch coverage, property-based testing (Hypothesis), nightly stress tests

CI/CD: Pre-commit hooks (format, lint, type check), merge queue validation, security scanning (Bandit, Safety)

Type Safety: MyPy strict mode, comprehensive type hints

Documentation: Google-style docstrings, 95% documentation coverage

View metrics: CI Dashboard | Coverage

---

Demonstrations

Comprehensive working demonstrations covering all framework capabilities. See demos/README.md for complete catalog.

Categories: Waveform Analysis, File I/O, Custom DAQ, Serial Protocols, Protocol Decoding, UDP Analysis, Protocol Inference, Automotive, Timing, Mixed Signal, Spectral, Jitter, Power, Signal Integrity, EMC, Signal RE, Advanced Inference, Complete Workflows

Learning Paths:

• Beginner (2-4 hours): File loading, basic measurements, export
• Intermediate (6-10 hours): Protocol decoding (UART, SPI, I2C, PCAP)
• Advanced (12-20 hours): CRC recovery, state machines, Wireshark dissectors
• Expert (20-40 hours): Complete RE workflows with ML inference

./scripts/setup.sh
python demos/00_getting_started/00_hello_world.py

---

Documentation

User Guides:

• Quick Start - Installation and first steps
• Black-Box Analysis - Unknown protocol RE
• Side-Channel Analysis - ChipWhisperer integration
• Hardware Acquisition - Instrument control
• Complete Workflows - End-to-end pipelines

API Reference: docs/api/ - Complete function reference

Development: Architecture | Testing | CHANGELOG

---

Contributing

git clone https://github.com/oscura-re/oscura.git
cd oscura
./scripts/setup.sh                    # Setup with hooks
./scripts/check.sh                    # Quality checks
./scripts/test.sh                     # Test suite
python3 .claude/hooks/validate_all.py # Must pass 5/5

Needed Contributions:

• Workflow automation (new pipelines, export formats, integrations)
• File format loaders (oscilloscope/LA formats not yet supported)
• Inference algorithms (better state machine learning, field detection)
• Protocol decoders (proprietary protocols you've reversed)
• Hardware integration (DAQ systems, instrument drivers)
• Real-world validation (test on your captures, report issues)

Contributing Guide | Architecture

---

Project Status

Version: 0.13.0 (2026-02-03)

Active Development: Hypothesis-driven RE workflows, automotive protocol analysis (CAN-FD, J1939, OBD-II, UDS), unknown protocol inference (state machines, field detection, CRC recovery), multi-format loading, export automation

Stability: Production-ready for security research, right-to-repair, academic use. API evolution documented in CHANGELOG.

Release History | Roadmap

---

Legal

License: MIT License - Permissive use, modification, distribution

Disclaimer: Intended for legitimate security research, right-to-repair, academic study, and authorized testing. Users responsible for compliance with applicable laws. Unauthorized access is illegal and unethical.

Dependencies: Python, NumPy, SciPy, Matplotlib, scikit-learn, cantools, Hypothesis. See pyproject.toml.

---

Citation

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

Machine-readable: CITATION.cff

---

Oscura - Hardware reverse engineering framework providing unified workflows from signal capture to protocol specification. Built for security research, right-to-repair, academic study, and defense applications.