oscura 0.10.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

Workflow automation for hardware reverse engineering. Stop juggling seven different tools to analyze one capture. Oscura provides unified Python workflows—from oscilloscope files to Wireshark dissectors without manual conversions or context switching.

---

The Problem

Hardware reverse engineering means juggling specialized tools:

1. Export oscilloscope waveforms (vendor-specific formats)
2. Convert formats for analysis (custom scripts, manual conversion)
3. Decode protocols (separate decoder tools)
4. Infer unknown protocols (Netzob, manual analysis)
5. Reverse checksums (CRC RevEng, separate tool)
6. Generate documentation (manual Wireshark dissectors, DBC files)
7. Repeat for each new capture

Each step requires different tools, manual file conversions, and context switching. Binary reverse engineering solved this decades ago with integrated platforms (Ghidra, radare2, IDA). Hardware RE remains fragmented.

The Solution

Oscura automates complete workflows in Python:

What We Provide:

• Native protocol decoders for 16 formats: UART, SPI, I2C, CAN, CAN-FD, LIN, FlexRay, JTAG, SWD, USB, I2S, 1-Wire, HDLC, Manchester
• Hypothesis-driven RE workflows with differential analysis and confidence scoring
• Automatic Wireshark dissector generation from inferred protocols
• DBC file generation from raw CAN captures (no manual signal definition)
• Multi-format file loading (Tektronix, Rigol, Sigrok .sr, BLF, PCAP, ChipWhisperer, VCD, WAV, CSV, HDF5)
• CRC/checksum recovery from message-checksum pairs
• Unified Python API eliminating tool-hopping and format conversions
• Signal processing with scipy/numpy
• Automotive protocol support (cantools integration)

Value proposition: Write one Python script instead of:

1. Exporting from oscilloscope software (vendor GUI)
2. Converting formats (custom scripts, manual conversion)
3. Decoding protocols (separate decoder tool manual configuration)
4. Inferring message formats (Netzob or manual)
5. Recovering checksums (CRC RevEng separate invocation)
6. Writing dissectors (manual Lua coding)
7. Documenting findings (manual reports)

---

Quick Start

Installation

# Production use
pip install oscura

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

Requirements: Python 3.12+ | Dependencies

Workflow Examples

Reverse engineer unknown protocol (differential analysis):

from oscura.sessions import BlackBoxSession

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

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

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

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

Generate automotive DBC from raw CAN captures:

from oscura.automotive.can import CANSession

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

# Statistical stimulus-response analysis
diff = session.compare("idle", "accelerate")
print(f"Changed CAN IDs: {diff.details['changed_ids']}")

# Generate DBC file (signal definitions inferred automatically)
session.export_dbc("vehicle.dbc")  # Import into CANalyzer, Vehicle Spy, Wireshark

Recover CRC specification from unknown protocol:

from oscura.inference.crc_reverse import CRCReverser

# Just 4 message-checksum pairs needed
messages = [b"\x01\x02\x03", b"\x04\x05\x06", b"\x07\x08\x09", b"\x0a\x0b\x0c"]
checksums = [0x12, 0x34, 0x56, 0x78]

# Recover complete CRC specification
reverser = CRCReverser(message_bits=8)
crc = reverser.find_crc(list(zip(messages, checksums)))

print(f"Polynomial: 0x{crc.polynomial:02X}")
print(f"Init: 0x{crc.init_value:02X}, XOR out: 0x{crc.xor_out:02X}")
print(f"Standard: {crc.standard_name or 'Custom'}")  # Matches CRC-8, CRC-16, etc.

Auto-detect protocol from oscilloscope capture:

import oscura as osc

# Load Tektronix/Rigol waveform
trace = osc.load("mystery_device.wfm")

# Statistical protocol detection (timing, voltage levels, bit patterns)
result = osc.auto_decode(trace)
print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")

See demos/README.md for 100+ working demonstrations organized by skill level (36 comprehensive workflows across 19 categories).

---

Core Capabilities

What Oscura Does Uniquely

Capability	What We Provide	Why It Matters
Hypothesis-Driven RE	BlackBoxSession with differential analysis, field detection, confidence scoring, audit trails	Systematic unknown protocol analysis vs manual guesswork
DBC Auto-Generation	Statistical CAN signal inference from captures → DBC export	Open-source alternative to Vector CANalyzer ($$$)
Wireshark Dissector Generation	Infer protocol → generate validated Lua dissector	End-to-end automation (others require manual YAML specs)
Multi-Format File Loading	22 format loaders: oscilloscopes (Tektronix WFM, Rigol), logic analyzers (Sigrok .sr, VCD), automotive (BLF, MF4), ChipWhisperer, PCAP, WAV, CSV, HDF5	Eliminate format conversion steps
Statistical Protocol Auto-Detect	Waveform analysis (timing, voltage, patterns) → protocol identification	Automatic protocol detection without manual configuration
Unified Workflow API	Single Python script: oscilloscope file → decode → infer → export dissector	Replace 7-tool chains with one script
CRC Recovery	Message-checksum pairs → polynomial, init, XOR out, reflection	Practical automation for common cases
Automotive Security Analysis	Stimulus-response correlation, hypothesis testing, UDS/OBD-II decoding	Research-focused workflow automation
State Machine Extraction (Passive)	RPNI algorithm for passive observation (vs active learning requiring oracle)	Different use case from Netzob's active L* algorithm
Evidence-Based Discovery	Confidence scoring, hypothesis tracking, statistical validation, reproducible audit trails	Scientific rigor for research publication

When to Use Alternatives

Oscura automates workflows but isn't always the best tool for every job. Use specialized tools when appropriate:

Need	Oscura Capability	When to Use Alternative Instead
Protocol Decoding	Native decoders for 16 protocols (UART, SPI, I2C, CAN, LIN, FlexRay, JTAG, SWD, USB, I2S, 1-Wire, HDLC, Manchester, CAN-FD, OneWire)	Use sigrok if you need 100+ protocol decoders, real-time hardware acquisition, or mature PulseView GUI
Side-Channel Analysis	Demo-level DPA/CPA, ChipWhisperer trace loading, basic power analysis	Use ChipWhisperer for production side-channel attacks—superior capabilities, hardware integration, mature attack implementations
Signal Processing	IEEE-based measurements using scipy/numpy	Use scipy.signal or MATLAB for advanced DSP, optimized performance, comprehensive filter design
CRC Recovery	Message-checksum pairs → CRC spec (common cases)	Use CRC RevEng for edge cases, exhaustive search, or when our heuristics fail
CAN Bus Analysis	DBC generation, cantools integration, automotive protocol support	Use python-can for low-level CAN interface control, or CANalyzer for professional automotive work
File Format Conversion	Loaders for 22 formats with unified API	Use vendor software for proprietary formats we don't support, or when you need 100% format fidelity

Oscura's sweet spot: Chaining multiple RE steps in scripted workflows with hypothesis-driven analysis. If you only need one specialized capability, use the dedicated tool.

---

When to Use Oscura

Choose Oscura when:

• You need end-to-end workflows (capture → analysis → documentation) in Python
• You're reverse engineering unknown protocols with differential analysis
• You want DBC files generated from CAN captures without CANalyzer ($$$)
• You need Wireshark dissectors generated automatically from inferred protocols
• You're working with multiple oscilloscope/LA formats and want unified API
• You value reproducible research with hypothesis tracking and confidence scoring
• You want to chain multiple RE tools together in one script

Use specialized tools directly when:

• You only need protocol decoding → sigrok has 100+ decoders and hardware support
• You're doing production side-channel attacks → ChipWhisperer has superior capabilities
• You only need signal processing → scipy/MATLAB are more comprehensive and optimized
• You need the most robust CRC recovery → CRC RevEng handles edge cases better
• You have vendor-specific needs → vendor tools have more format support
• You need real-time hardware acquisition → sigrok, vendor tools, or python-can have better hardware integration

Oscura's sweet spot: Workflow automation that chains multiple RE steps with hypothesis-driven analysis.

---

Where This Excels

Security Research

• Protocol reverse engineering with hypothesis tracking and validation
• Automotive ECU security via CAN stimulus-response analysis
• Attack surface mapping through state machine extraction
• Side-channel trace analysis workflows (demo-level DPA/CPA—use ChipWhisperer for production attacks)

Right-to-Repair & Modernization

• Document undocumented protocols with generated Wireshark dissectors
• Replicate vintage hardware (1960s-present logic family auto-detection)
• Overcome vendor lock-in through protocol reverse engineering
• Generate interoperable interfaces without vendor cooperation

Academic Research

• Reproducible workflows with evidence tracking and audit trails
• Statistical validation with confidence scoring
• IEEE-based measurements for publishable results (181/1241/1459/2414)
• 475 test files with 80%+ coverage ensure reliability

Industrial & Automotive

• CAN bus security research with open-source DBC generation
• Signal integrity validation for high-speed designs
• Component characterization without datasheets
• Compliance testing (EMC, automotive standards)

---

Built On

Oscura builds on proven open-source tools:

Component	What We Use	Why
Signal Processing	scipy/numpy	Industry-standard numerical computing
Protocol Decoders	Native Python implementations (16 protocols)	Full control, Python integration, no external dependencies
File Format Loaders	Custom parsers for 22 formats (WFM, Rigol, .sr, BLF, PCAP, etc.)	Support oscilloscopes, logic analyzers, automotive, ChipWhisperer
CAN Protocols	cantools, python-can	Robust CAN message parsing and encoding
Testing	pytest, Hypothesis	Property-based testing for algorithm validation
Type Safety	mypy	Static type checking (strict mode)

Our contribution: Unified API + hypothesis-driven RE workflows + 22 format loaders + 16 native protocol decoders + export automation (Wireshark, DBC, Scapy).

---

Technical Foundation

Quality Metrics

Production-ready validation:

• 475 test files with comprehensive unit, integration, and property-based tests (Hypothesis)
• 80%+ code coverage enforced with branch coverage enabled
• Pre-commit hooks (format, lint, type check) enforce consistency
• Merge queue CI prevents untested code from landing
• Nightly stress tests validate edge cases and memory usage
• Security scanning (Bandit, Safety) on every commit

View current metrics: CI Dashboard | Coverage Reports

Standards Implementation

We implement measurements based on IEEE specifications:

Standard	Coverage	Hardware RE Relevance
IEEE 181	Pulse timing, rise/fall, overshoot, duty cycle	Protocol physical layer validation
IEEE 1241	SNR, SINAD, THD, SFDR, ENOB	ADC characterization for side-channel analysis
IEEE 1459	Active/reactive power, harmonics, power factor	Power supply profiling, fault injection targets
IEEE 2414	TIE, period jitter, RJ/DJ decomposition, BER	Clock glitch detection, timing attack analysis

Architecture Principles

Built for extensibility:

• Type-safe: MyPy strict mode, comprehensive type hints
• Modular: Protocol decoders, loaders, and analyzers are plug-and-play
• Memory-efficient: Lazy loading, memory-mapped files, chunked processing (TB-scale datasets)
• Documented: Google-style docstrings, 95% documentation coverage
• Reproducible: Hypothesis tracking, confidence scoring, full audit trails

---

Learn By Doing

Working Demonstrations

100+ working demos organized into 19 categories covering:

• Data Loading - All file format loaders (oscilloscopes, logic analyzers, automotive, scientific)
• Basic Analysis - Waveform measurements, digital analysis, spectral analysis, filtering
• Protocol Decoding - UART, SPI, I2C, CAN, LIN, FlexRay, JTAG, SWD, I2S, USB
• Advanced Analysis - Jitter, eye diagrams, power analysis, signal integrity, TDR
• Domain Specific - Automotive diagnostics, EMC compliance, side-channel analysis, IEEE 181 timing
• Reverse Engineering - CRC recovery, state machines, Wireshark dissectors, ML classification
• Advanced Features - Lazy loading, memory management, performance optimization, batch processing
• Extensibility - Custom analyzers, plugins, templates
• Integration - CI/CD, hardware, external tools, web dashboards
• Export & Visualization - All export formats, plotting, reporting
• Complete Workflows - End-to-end production pipelines
• Standards Compliance - IEEE 181/1241/1459/2414, automotive standards

Comprehensive Demonstrations

36 comprehensive workflows organized by skill level and domain:

• Getting Started - File loading, basic measurements, format export (Beginner, 2-4 hours)
• Protocol Decoding - UART, SPI, I2C, Manchester, JTAG, USB, PCAP (Intermediate, 6-10 hours)
• Reverse Engineering - CRC recovery, state machines, Wireshark dissectors, automotive protocols (Advanced, 12-20 hours)
• Standards Compliance - IEEE 181/1241/1459/2414, CISPR 32, IEC 61000 (Advanced/Expert)
• Complete Workflows - End-to-end production pipelines with ML inference (Expert, 20-40 hours)

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

See full demo catalog with learning paths

Run Your First Demo

# Install development dependencies
./scripts/setup.sh

# Run your first demo
python demos/00_getting_started/00_hello_world.py

# Or try a specific topic
python demos/05_domain_specific/05_side_channel_basics.py

---

Command-Line Interface

# Signal characterization
oscura characterize capture.wfm

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

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

# Differential analysis (compare baseline to modified)
oscura compare baseline.wfm modified.wfm

# Interactive REPL for exploration
oscura shell

Full CLI reference

---

Why This Exists

Legitimate Use Cases

Hardware reverse engineering serves critical needs across security, repair, modernization, and defense:

Security Research: Vulnerability discovery requires understanding how hardware actually works, not how vendors claim it works. Protocol reverse engineering reveals authentication bypasses. State machine analysis maps attack surfaces.

Right-to-Repair: Proprietary protocols and vendor lock-in prevent owners from fixing their own equipment. Reverse engineering restores agency. Open documentation enables interoperable replacements.

Modernization: Legacy systems run critical infrastructure but use obsolete components. Replication requires extracting specifications from working hardware when documentation is lost or was never public.

National Defense: Intelligence and threat assessment depend on understanding adversary capabilities. Forensic analysis of captured equipment requires comprehensive signal analysis and protocol decoding.

Academic Research: Understanding existing systems informs better designs. Teaching security requires demonstrating real vulnerabilities. Open tools advance the field collectively.

The Open Source Philosophy

We believe security through obscurity is a temporary business model at best and a vulnerability at worst. Real security comes from open scrutiny, not information hiding. Real value comes from services and expertise, not gatekeeping knowledge.

Vendors who hide protocol specifications aren't protecting trade secrets—they're preventing interoperability and limiting repair. We're building tools to level that playing field.

Join the Effort

Hardware reverse engineering requires diverse expertise: signal processing, protocol design, automotive systems, vintage computing, embedded security. No single person knows it all. We need your knowledge.

• Reverse engineered a proprietary protocol? Contribute the decoder.
• Built workflow automation techniques? Add them to the framework.
• Work with file formats we don't support? Write a loader.
• Found vulnerabilities using these tools? Share sanitized case studies.
• Teaching hardware security? Use Oscura and improve the documentation.

Every contribution pools our collective expertise and makes the next reverse engineering project easier for everyone.

---

Getting Involved

Contributing

# Clone and setup development environment
git clone https://github.com/oscura-re/oscura.git
cd oscura
./scripts/setup.sh                    # Complete setup with hooks

# Run quality checks (required before commit)
./scripts/check.sh                    # Linting, type checking, tests
./scripts/test.sh                     # Full test suite with coverage

# Validate everything passes
python3 .claude/hooks/validate_all.py # Must show 5/5 passing

What We Need:

Contribution Type	Examples	Impact
Workflow Automation	New analysis pipelines, export formats, integration scripts	Core value proposition
File Format Loaders	Oscilloscope/LA formats not yet supported	Eliminate conversion steps
Inference Algorithms	Better state machine learning, field detection, pattern discovery	Improve automatic analysis quality
Protocol Decoders	Proprietary protocols you've reversed	Enable others to analyze same systems
Hardware Integration	DAQ systems, instrument drivers, live capture workflows	Enable real-time analysis
Real-World Validation	Test on your captures, report issues	Ensure reliability across use cases
Documentation & Case Studies	Tutorials, sanitized RE workflows, academic papers using Oscura	Lower entry barrier, demonstrate capabilities

Contributing Guide | Architecture Documentation

Community

• Issues: GitHub Issues - Bug reports, feature requests
• Discussions: GitHub Discussions - Questions, ideas, collaboration
• Security: SECURITY.md - Responsible disclosure process

---

Documentation

User Guides

• Quick Start Guide - Installation and first steps
• Black-Box Protocol Analysis - Unknown protocol RE workflow
• Side-Channel Analysis - Using ChipWhisperer traces with Oscura
• Hardware Acquisition - Direct instrument control
• Complete Workflows - End-to-end pipelines

API Reference

• API Documentation - Complete function reference
• Session Management - Interactive analysis sessions
• CLI Reference - Command-line interface

Development

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

---

Project Status

Current Version: 0.9.0 (2026-01-31)

Active Development Areas:

• Hypothesis-driven RE workflows and confidence scoring
• Automotive protocol analysis (CAN-FD, J1939, OBD-II, UDS)
• Unknown protocol inference (state machines, field detection, CRC recovery)
• Multi-format file loading and export automation
• Vintage computing support (retro logic families, IC identification, 1960s-present)

Stability: Production-ready for security research, right-to-repair, academic use. APIs may evolve as we add capabilities—breaking changes documented in CHANGELOG.

Release History | Roadmap Discussions

---

Citation

If Oscura contributes to your research, please cite:

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

Machine-readable: CITATION.cff

---

Legal

License: MIT License - Permissive use, modification, distribution

Disclaimer: This framework is intended for legitimate security research, right-to-repair, academic study, and authorized testing. Users are responsible for compliance with applicable laws and regulations. Unauthorized access to systems or networks is illegal and unethical.

Dependencies: Built with Python, NumPy, SciPy, Matplotlib, Hypothesis. See pyproject.toml for complete dependency list.

Supported by: Security researchers, right-to-repair advocates, academic institutions, and the open source community.

---

Oscura - Illuminate what others obscure.

Hardware systems are black boxes by design, obscured through proprietary protocols, cryptographic obfuscation, and undocumented interfaces. Whether imposed by vendors, governments, or the passage of time—we bring light to the darkness. Join us in building the workflow automation framework that hardware reverse engineering deserves.