oscura 0.5.0

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.

Oscura

Unified hardware reverse engineering framework. Extract all information from any system through signals and data.

Build Status:

Package:

Code Quality:

Project Status:

---

What is Oscura?

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 • 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

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 • Cryptographic research

---

Installation

# Using uv (recommended)
uv pip install oscura

# Or with pip
pip install oscura

# Development install (RECOMMENDED)
git clone https://github.com/oscura-re/oscura.git
cd oscura
./scripts/setup.sh            # Complete setup (dependencies + hooks)
./scripts/verify-setup.sh     # Verify environment is ready

---

Quick Start

Signal Analysis

import oscura as osc

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

# Basic measurements
print(f"Frequency: {osc.frequency(trace) / 1e6:.3f} MHz")
print(f"Rise time: {osc.rise_time(trace) * 1e9:.1f} ns")

# Decode protocol
from oscura.protocols import UARTDecoder
decoder = UARTDecoder(baud_rate=115200)
messages = decoder.decode(trace)

Black-Box Protocol Reverse Engineering

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

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

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

Core Capabilities

Demo	Description
01_waveform_analysis	Load and analyze Tektronix, Rigol, LeCroy captures
02_file_format_io	CSV, HDF5, NumPy, custom binary formats
03_custom_daq	Streaming loaders for custom DAQ systems
04_serial_protocols	UART, SPI, I2C, 1-Wire decoding
05_protocol_decoding	Protocol auto-detection and decoding
06_udp_packet_analysis	Network packet capture and analysis

Advanced Analysis

Demo	Description
07_protocol_inference	State machine learning, CRC reverse engineering
08_automotive_protocols	CAN, CAN-FD, LIN, FlexRay analysis
09_automotive	OBD-II, UDS, J1939 diagnostics
10_timing_measurements	Rise/fall time, duty cycle (IEEE 181)
11_mixed_signal	Analog + digital combined analysis
12_spectral_compliance	FFT, THD, SNR, SINAD (IEEE 1241)
13_jitter_analysis	TIE, RJ/DJ, eye diagrams (IEEE 2414)
14_power_analysis	DC-DC, ripple, efficiency (IEEE 1459)
15_signal_integrity	TDR, S-parameters, setup/hold timing
16_emc_compliance	CISPR, FCC, MIL-STD testing
17_signal_reverse_engineering	Complete unknown signal analysis
18_advanced_inference	Bayesian inference, Protocol DSL
19_complete_workflows	End-to-end reverse engineering

Run Your First Demo

# Generate demo data
python demos/generate_all_demo_data.py

# Run a demo
uv run python demos/01_waveform_analysis/comprehensive_wfm_analysis.py

---

Key Features

Protocols (16+)

UART • SPI • I2C • 1-Wire • CAN • CAN-FD • LIN • FlexRay • JTAG • SWD • Manchester • Miller • USB • HDLC • I2S • MDIO • DMX512

File Formats (18+)

Tektronix WFM • Rigol WFM • LeCroy TRC • Sigrok • VCD • CSV • NumPy • HDF5 • MATLAB • WAV • JSON • BLF • MF4 • PCAP • PCAPNG

Standards Compliance

IEEE 181-2011: Rise/fall time, pulse width, overshoot

IEEE 1241-2010: SNR, SINAD, THD, SFDR, ENOB

IEEE 1459-2010: Power factor, harmonics, efficiency

IEEE 2414-2020: TIE, period jitter, RJ/DJ

---

Command Line Interface

# Characterize signal measurements
oscura characterize capture.wfm

# Decode protocol
oscura decode uart.wfm --protocol uart

# Batch process multiple files
oscura batch '*.wfm' --analysis characterize

# Compare two signals
oscura compare before.wfm after.wfm

# Interactive shell
oscura shell

See CLI Reference for complete documentation.

---

Contributing

We welcome contributions! See CONTRIBUTING.md for development setup and guidelines.

# Quick setup
git clone https://github.com/oscura-re/oscura.git
cd oscura
uv sync --all-extras
./scripts/setup/install-hooks.sh

# Run tests
./scripts/test.sh

# Quality checks
./scripts/check.sh

---

Documentation

Getting Started

• Quick Start Guide - Begin here
• Demos - Working examples for every feature
• Migration Guide - Upgrade from older versions

User Guides

• Black-Box Protocol Analysis - Unknown protocol reverse engineering
• Hardware Acquisition - Direct hardware integration (Phase 2)
• Side-Channel Analysis - Power/timing/EM attacks
• Workflows - Complete analysis workflows

API Reference

• API Reference - Complete API documentation
• Session Management - Interactive analysis sessions
• CLI Reference - Command line usage

Development

• Architecture - Design principles and patterns
• Testing Guide - Test suite architecture
• CHANGELOG - Version history

---

License

MIT License - see LICENSE for details.

---

Citation

If you use Oscura in research:

@software{oscura,
  title = {Oscura: Signal Reverse Engineering Toolkit},
  author = {Oscura Contributors},
  year = {2026},
  url = {https://github.com/oscura-re/oscura}
}

Machine-readable: CITATION.cff

---

Support

• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and community

---

Oscura • Reverse engineer any system from captured waveforms