oscura 0.10.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (19) hide show
  1. oscura/__init__.py +1 -1
  2. oscura/__main__.py +4 -0
  3. oscura/analyzers/ml/signal_classifier.py +6 -0
  4. oscura/analyzers/waveform/spectral.py +18 -11
  5. oscura/automotive/__init__.py +1 -1
  6. oscura/automotive/dtc/data.json +17 -102
  7. oscura/automotive/flexray/fibex.py +9 -1
  8. oscura/core/schemas/device_mapping.json +2 -8
  9. oscura/core/schemas/packet_format.json +4 -24
  10. oscura/core/schemas/protocol_definition.json +2 -12
  11. oscura/loaders/validation.py +17 -10
  12. oscura/sessions/legacy.py +49 -1
  13. oscura/workflows/batch/aggregate.py +5 -1
  14. oscura-0.11.0.dist-info/METADATA +460 -0
  15. {oscura-0.10.0.dist-info → oscura-0.11.0.dist-info}/RECORD +18 -18
  16. oscura-0.10.0.dist-info/METADATA +0 -641
  17. {oscura-0.10.0.dist-info → oscura-0.11.0.dist-info}/WHEEL +0 -0
  18. {oscura-0.10.0.dist-info → oscura-0.11.0.dist-info}/entry_points.txt +0 -0
  19. {oscura-0.10.0.dist-info → oscura-0.11.0.dist-info}/licenses/LICENSE +0 -0
oscura-0.10.0.dist-info/METADATA DELETED
@@ -1,641 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: oscura
3
- Version: 0.10.0
4
- 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.
5
- Project-URL: Homepage, https://github.com/oscura-re/oscura
6
- Project-URL: Documentation, https://github.com/oscura-re/oscura/tree/main/docs
7
- Project-URL: Repository, https://github.com/oscura-re/oscura
8
- Project-URL: Changelog, https://github.com/oscura-re/oscura/blob/main/CHANGELOG.md
9
- Project-URL: Issue Tracker, https://github.com/oscura-re/oscura/issues
10
- Project-URL: Discussions, https://github.com/oscura-re/oscura/discussions
11
- License-Expression: MIT
12
- License-File: LICENSE
13
- 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
14
- Classifier: Development Status :: 3 - Alpha
15
- Classifier: Intended Audience :: Developers
16
- Classifier: Intended Audience :: Information Technology
17
- Classifier: Intended Audience :: Science/Research
18
- Classifier: Intended Audience :: Telecommunications Industry
19
- Classifier: License :: OSI Approved :: MIT License
20
- Classifier: Operating System :: OS Independent
21
- Classifier: Programming Language :: Python :: 3
22
- Classifier: Programming Language :: Python :: 3.12
23
- Classifier: Programming Language :: Python :: 3.13
24
- Classifier: Topic :: Scientific/Engineering
25
- Classifier: Topic :: Scientific/Engineering :: Information Analysis
26
- Classifier: Topic :: Security
27
- Classifier: Topic :: System :: Hardware
28
- Classifier: Topic :: System :: Hardware :: Hardware Drivers
29
- Classifier: Typing :: Typed
30
- Requires-Python: >=3.12
31
- Requires-Dist: cantools<40.0.0,>=39.4.0
32
- Requires-Dist: click<9.0.0,>=8.1.0
33
- Requires-Dist: dpkt<2.0.0,>=1.9.0
34
- Requires-Dist: jinja2<4.0.0,>=3.1
35
- Requires-Dist: matplotlib<4.0.0,>=3.7.0
36
- Requires-Dist: numpy<3.0.0,>=1.24.0
37
- Requires-Dist: openpyxl<4.0.0,>=3.0.0
38
- Requires-Dist: pandas<3.0.0,>=2.0.0
39
- Requires-Dist: psutil<7.0.0,>=5.9.0
40
- Requires-Dist: python-can<5.0.0,>=4.4.0
41
- Requires-Dist: python-pptx<1.0.0,>=0.6.21
42
- Requires-Dist: pyyaml<7.0.0,>=6.0
43
- Requires-Dist: reportlab<6.0.0,>=4.4.7
44
- Requires-Dist: scapy<3.0.0,>=2.5.0
45
- Requires-Dist: scipy<2.0.0,>=1.10.0
46
- Requires-Dist: tm-data-types<1.0.0,>=0.3.0
47
- Requires-Dist: tqdm<5.0.0,>=4.65.0
48
- Requires-Dist: weasyprint<64.0.0,>=63.0
49
- Provides-Extra: all
50
- Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'all'
51
- Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'all'
52
- Requires-Dist: coverage[toml]<8.0.0,>=7.0; extra == 'all'
53
- Requires-Dist: cryptography<47.0.0,>=44.0.1; extra == 'all'
54
- Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'all'
55
- Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'all'
56
- Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'all'
57
- Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'all'
58
- Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'all'
59
- Requires-Dist: mypy<2.0.0,>=1.0; extra == 'all'
60
- Requires-Dist: nbconvert!=7.16.6,<8.0.0,>=7.0.0; extra == 'all'
61
- Requires-Dist: networkx<4.0.0,>=3.0; extra == 'all'
62
- Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'all'
63
- Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'all'
64
- Requires-Dist: pyserial<4.0.0,>=3.5; extra == 'all'
65
- Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'all'
66
- Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'all'
67
- Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'all'
68
- Requires-Dist: pytest-randomly<4.0.0,>=3.0; extra == 'all'
69
- Requires-Dist: pytest-rerunfailures<17.0,>=16.0; extra == 'all'
70
- Requires-Dist: pytest-split<1.0.0,>=0.10.0; extra == 'all'
71
- Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'all'
72
- Requires-Dist: pytest-xdist<4.0.0,>=3.0; extra == 'all'
73
- Requires-Dist: pytest<10.0.0,>=8.0; extra == 'all'
74
- Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'all'
75
- Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'all'
76
- Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'all'
77
- Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'all'
78
- Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'all'
79
- Requires-Dist: ruff<1.0.0,>=0.8.0; extra == 'all'
80
- Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == 'all'
81
- Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'all'
82
- Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'all'
83
- Provides-Extra: analysis
84
- Requires-Dist: networkx<4.0.0,>=3.0; extra == 'analysis'
85
- Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'analysis'
86
- Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == 'analysis'
87
- Provides-Extra: automotive
88
- Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'automotive'
89
- Provides-Extra: dev
90
- Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'dev'
91
- Requires-Dist: coverage[toml]<8.0.0,>=7.0; extra == 'dev'
92
- Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'dev'
93
- Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'dev'
94
- Requires-Dist: mypy<2.0.0,>=1.0; extra == 'dev'
95
- Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'dev'
96
- Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'dev'
97
- Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'dev'
98
- Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'dev'
99
- Requires-Dist: pytest-randomly<4.0.0,>=3.0; extra == 'dev'
100
- Requires-Dist: pytest-rerunfailures<17.0,>=16.0; extra == 'dev'
101
- Requires-Dist: pytest-split<1.0.0,>=0.10.0; extra == 'dev'
102
- Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'dev'
103
- Requires-Dist: pytest-xdist<4.0.0,>=3.0; extra == 'dev'
104
- Requires-Dist: pytest<10.0.0,>=8.0; extra == 'dev'
105
- Requires-Dist: ruff<1.0.0,>=0.8.0; extra == 'dev'
106
- Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'dev'
107
- Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'dev'
108
- Provides-Extra: fuzzy
109
- Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'fuzzy'
110
- Provides-Extra: hardware
111
- Requires-Dist: pyserial<4.0.0,>=3.5; extra == 'hardware'
112
- Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'hardware'
113
- Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'hardware'
114
- Provides-Extra: hdf5
115
- Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'hdf5'
116
- Provides-Extra: iot
117
- Requires-Dist: cryptography<47.0.0,>=44.0.1; extra == 'iot'
118
- Provides-Extra: jupyter
119
- Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'jupyter'
120
- Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'jupyter'
121
- Requires-Dist: nbconvert!=7.16.6,<8.0.0,>=7.0.0; extra == 'jupyter'
122
- Provides-Extra: oscilloscopes
123
- Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'oscilloscopes'
124
- Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'oscilloscopes'
125
- Provides-Extra: standard
126
- Description-Content-Type: text/markdown
127
-
128
- # Oscura
129
-
130
- **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.
131
-
132
- [![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)
133
- [![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)
134
- [![codecov](https://codecov.io/gh/oscura-re/oscura/graph/badge.svg)](https://codecov.io/gh/oscura-re/oscura)
135
- [![PyPI version](https://img.shields.io/pypi/v/oscura)](https://pypi.org/project/oscura/)
136
- [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
137
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
138
-
139
- ---
140
-
141
- ## The Problem
142
-
143
- Hardware reverse engineering means juggling specialized tools:
144
-
145
- 1. Export oscilloscope waveforms (vendor-specific formats)
146
- 2. Convert formats for analysis (custom scripts, manual conversion)
147
- 3. Decode protocols (separate decoder tools)
148
- 4. Infer unknown protocols (Netzob, manual analysis)
149
- 5. Reverse checksums (CRC RevEng, separate tool)
150
- 6. Generate documentation (manual Wireshark dissectors, DBC files)
151
- 7. Repeat for each new capture
152
-
153
- **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.
154
-
155
- ## The Solution
156
-
157
- Oscura automates complete workflows in Python:
158
-
159
- **What We Provide:**
160
-
161
- - **Native protocol decoders for 16 formats**: UART, SPI, I2C, CAN, CAN-FD, LIN, FlexRay, JTAG, SWD, USB, I2S, 1-Wire, HDLC, Manchester
162
- - **Hypothesis-driven RE workflows** with differential analysis and confidence scoring
163
- - **Automatic Wireshark dissector generation** from inferred protocols
164
- - **DBC file generation** from raw CAN captures (no manual signal definition)
165
- - **Multi-format file loading** (Tektronix, Rigol, Sigrok .sr, BLF, PCAP, ChipWhisperer, VCD, WAV, CSV, HDF5)
166
- - **CRC/checksum recovery** from message-checksum pairs
167
- - **Unified Python API** eliminating tool-hopping and format conversions
168
- - Signal processing with scipy/numpy
169
- - Automotive protocol support (cantools integration)
170
-
171
- **Value proposition:** Write one Python script instead of:
172
-
173
- 1. Exporting from oscilloscope software (vendor GUI)
174
- 2. Converting formats (custom scripts, manual conversion)
175
- 3. Decoding protocols (separate decoder tool manual configuration)
176
- 4. Inferring message formats (Netzob or manual)
177
- 5. Recovering checksums (CRC RevEng separate invocation)
178
- 6. Writing dissectors (manual Lua coding)
179
- 7. Documenting findings (manual reports)
180
-
181
- ---
182
-
183
- ## Quick Start
184
-
185
- ### Installation
186
-
187
- ```bash
188
- # Production use
189
- pip install oscura
190
-
191
- # Development (recommended - includes all features)
192
- git clone https://github.com/oscura-re/oscura.git
193
- cd oscura
194
- ./scripts/setup.sh
195
- ```
196
-
197
- **Requirements:** Python 3.12+ | [Dependencies](pyproject.toml)
198
-
199
- ### Workflow Examples
200
-
201
- **Reverse engineer unknown protocol (differential analysis):**
202
-
203
- ```python
204
- from oscura.sessions import BlackBoxSession
205
-
206
- # Create analysis session with hypothesis tracking
207
- session = BlackBoxSession(name="IoT Device RE")
208
-
209
- # Differential analysis: idle vs active states
210
- session.add_recording("idle", "idle.bin")
211
- session.add_recording("button_press", "button.bin")
212
- diff = session.compare("idle", "button_press")
213
-
214
- # Automatic field detection with confidence scoring
215
- spec = session.generate_protocol_spec()
216
- print(f"Identified {len(spec['fields'])} protocol fields")
217
-
218
- # Export validated Wireshark dissector (Lua)
219
- session.export_results("dissector", "protocol.lua")
220
- ```
221
-
222
- **Generate automotive DBC from raw CAN captures:**
223
-
224
- ```python
225
- from oscura.automotive.can import CANSession
226
-
227
- session = CANSession(name="Vehicle RE")
228
- session.add_recording("idle", "idle.blf")
229
- session.add_recording("accelerate", "accel.blf")
230
-
231
- # Statistical stimulus-response analysis
232
- diff = session.compare("idle", "accelerate")
233
- print(f"Changed CAN IDs: {diff.details['changed_ids']}")
234
-
235
- # Generate DBC file (signal definitions inferred automatically)
236
- session.export_dbc("vehicle.dbc") # Import into CANalyzer, Vehicle Spy, Wireshark
237
- ```
238
-
239
- **Recover CRC specification from unknown protocol:**
240
-
241
- ```python
242
- from oscura.inference.crc_reverse import CRCReverser
243
-
244
- # Just 4 message-checksum pairs needed
245
- messages = [b"\x01\x02\x03", b"\x04\x05\x06", b"\x07\x08\x09", b"\x0a\x0b\x0c"]
246
- checksums = [0x12, 0x34, 0x56, 0x78]
247
-
248
- # Recover complete CRC specification
249
- reverser = CRCReverser(message_bits=8)
250
- crc = reverser.find_crc(list(zip(messages, checksums)))
251
-
252
- print(f"Polynomial: 0x{crc.polynomial:02X}")
253
- print(f"Init: 0x{crc.init_value:02X}, XOR out: 0x{crc.xor_out:02X}")
254
- print(f"Standard: {crc.standard_name or 'Custom'}") # Matches CRC-8, CRC-16, etc.
255
- ```
256
-
257
- **Auto-detect protocol from oscilloscope capture:**
258
-
259
- ```python
260
- import oscura as osc
261
-
262
- # Load Tektronix/Rigol waveform
263
- trace = osc.load("mystery_device.wfm")
264
-
265
- # Statistical protocol detection (timing, voltage levels, bit patterns)
266
- result = osc.auto_decode(trace)
267
- print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
268
- ```
269
-
270
- **[See demos/README.md](demos/README.md)** for 100+ working demonstrations organized by skill level (36 comprehensive workflows across 19 categories).
271
-
272
- ---
273
-
274
- ## Core Capabilities
275
-
276
- ### What Oscura Does Uniquely
277
-
278
- | Capability | What We Provide | Why It Matters |
279
- | ------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
280
- | **Hypothesis-Driven RE** | BlackBoxSession with differential analysis, field detection, confidence scoring, audit trails | Systematic unknown protocol analysis vs manual guesswork |
281
- | **DBC Auto-Generation** | Statistical CAN signal inference from captures → DBC export | Open-source alternative to Vector CANalyzer ($$$) |
282
- | **Wireshark Dissector Generation** | Infer protocol → generate validated Lua dissector | End-to-end automation (others require manual YAML specs) |
283
- | **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 |
284
- | **Statistical Protocol Auto-Detect** | Waveform analysis (timing, voltage, patterns) → protocol identification | Automatic protocol detection without manual configuration |
285
- | **Unified Workflow API** | Single Python script: oscilloscope file → decode → infer → export dissector | Replace 7-tool chains with one script |
286
- | **CRC Recovery** | Message-checksum pairs → polynomial, init, XOR out, reflection | Practical automation for common cases |
287
- | **Automotive Security Analysis** | Stimulus-response correlation, hypothesis testing, UDS/OBD-II decoding | Research-focused workflow automation |
288
- | **State Machine Extraction (Passive)** | RPNI algorithm for passive observation (vs active learning requiring oracle) | Different use case from Netzob's active L* algorithm |
289
- | **Evidence-Based Discovery** | Confidence scoring, hypothesis tracking, statistical validation, reproducible audit trails | Scientific rigor for research publication |
290
-
291
- ### When to Use Alternatives
292
-
293
- Oscura automates workflows but isn't always the best tool for every job. Use specialized tools when appropriate:
294
-
295
- | Need | Oscura Capability | When to Use Alternative Instead |
296
- | -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
297
- | **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](https://sigrok.org/)** if you need 100+ protocol decoders, real-time hardware acquisition, or mature PulseView GUI |
298
- | **Side-Channel Analysis** | Demo-level DPA/CPA, ChipWhisperer trace loading, basic power analysis | **Use [ChipWhisperer](https://chipwhisperer.com/)** for production side-channel attacks—superior capabilities, hardware integration, mature attack implementations |
299
- | **Signal Processing** | IEEE-based measurements using scipy/numpy | **Use [scipy.signal](https://docs.scipy.org/doc/scipy/reference/signal.html) or MATLAB** for advanced DSP, optimized performance, comprehensive filter design |
300
- | **CRC Recovery** | Message-checksum pairs → CRC spec (common cases) | **Use [CRC RevEng](https://reveng.sourceforge.io/)** for edge cases, exhaustive search, or when our heuristics fail |
301
- | **CAN Bus Analysis** | DBC generation, cantools integration, automotive protocol support | **Use [python-can](https://python-can.readthedocs.io/)** for low-level CAN interface control, or **[CANalyzer](https://www.vector.com/int/en/products/products-a-z/software/canalyzer/)** for professional automotive work |
302
- | **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 |
303
-
304
- **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.
305
-
306
- ---
307
-
308
- ## When to Use Oscura
309
-
310
- **Choose Oscura when:**
311
-
312
- - You need end-to-end workflows (capture → analysis → documentation) in Python
313
- - You're reverse engineering unknown protocols with differential analysis
314
- - You want DBC files generated from CAN captures without CANalyzer ($$$)
315
- - You need Wireshark dissectors generated automatically from inferred protocols
316
- - You're working with multiple oscilloscope/LA formats and want unified API
317
- - You value reproducible research with hypothesis tracking and confidence scoring
318
- - You want to chain multiple RE tools together in one script
319
-
320
- **Use specialized tools directly when:**
321
-
322
- - You only need protocol decoding → [sigrok](https://sigrok.org/) has 100+ decoders and hardware support
323
- - You're doing production side-channel attacks → [ChipWhisperer](https://chipwhisperer.com/) has superior capabilities
324
- - You only need signal processing → [scipy](https://scipy.org/)/MATLAB are more comprehensive and optimized
325
- - You need the most robust CRC recovery → [CRC RevEng](https://reveng.sourceforge.io/) handles edge cases better
326
- - You have vendor-specific needs → vendor tools have more format support
327
- - You need real-time hardware acquisition → sigrok, vendor tools, or python-can have better hardware integration
328
-
329
- **Oscura's sweet spot:** Workflow automation that chains multiple RE steps with hypothesis-driven analysis.
330
-
331
- ---
332
-
333
- ## Where This Excels
334
-
335
- ### Security Research
336
-
337
- - **Protocol reverse engineering** with hypothesis tracking and validation
338
- - **Automotive ECU security** via CAN stimulus-response analysis
339
- - **Attack surface mapping** through state machine extraction
340
- - **Side-channel trace analysis workflows** (demo-level DPA/CPA—use ChipWhisperer for production attacks)
341
-
342
- ### Right-to-Repair & Modernization
343
-
344
- - **Document undocumented protocols** with generated Wireshark dissectors
345
- - **Replicate vintage hardware** (1960s-present logic family auto-detection)
346
- - **Overcome vendor lock-in** through protocol reverse engineering
347
- - **Generate interoperable interfaces** without vendor cooperation
348
-
349
- ### Academic Research
350
-
351
- - **Reproducible workflows** with evidence tracking and audit trails
352
- - **Statistical validation** with confidence scoring
353
- - **IEEE-based measurements** for publishable results (181/1241/1459/2414)
354
- - **475 test files with 80%+ coverage** ensure reliability
355
-
356
- ### Industrial & Automotive
357
-
358
- - **CAN bus security research** with open-source DBC generation
359
- - **Signal integrity validation** for high-speed designs
360
- - **Component characterization** without datasheets
361
- - **Compliance testing** (EMC, automotive standards)
362
-
363
- ---
364
-
365
- ## Built On
366
-
367
- Oscura builds on proven open-source tools:
368
-
369
- | Component | What We Use | Why |
370
- | ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
371
- | **Signal Processing** | [scipy](https://scipy.org/)/[numpy](https://numpy.org/) | Industry-standard numerical computing |
372
- | **Protocol Decoders** | Native Python implementations (16 protocols) | Full control, Python integration, no external dependencies |
373
- | **File Format Loaders** | Custom parsers for 22 formats (WFM, Rigol, .sr, BLF, PCAP, etc.) | Support oscilloscopes, logic analyzers, automotive, ChipWhisperer |
374
- | **CAN Protocols** | [cantools](https://github.com/cantools/cantools), [python-can](https://python-can.readthedocs.io/) | Robust CAN message parsing and encoding |
375
- | **Testing** | [pytest](https://pytest.org/), [Hypothesis](https://hypothesis.readthedocs.io/) | Property-based testing for algorithm validation |
376
- | **Type Safety** | [mypy](https://mypy-lang.org/) | Static type checking (strict mode) |
377
-
378
- **Our contribution:** Unified API + hypothesis-driven RE workflows + 22 format loaders + 16 native protocol decoders + export automation (Wireshark, DBC, Scapy).
379
-
380
- ---
381
-
382
- ## Technical Foundation
383
-
384
- ### Quality Metrics
385
-
386
- Production-ready validation:
387
-
388
- - **475 test files** with comprehensive unit, integration, and property-based tests (Hypothesis)
389
- - **80%+ code coverage** enforced with branch coverage enabled
390
- - **Pre-commit hooks** (format, lint, type check) enforce consistency
391
- - **Merge queue CI** prevents untested code from landing
392
- - **Nightly stress tests** validate edge cases and memory usage
393
- - **Security scanning** (Bandit, Safety) on every commit
394
-
395
- View current metrics: [CI Dashboard](https://github.com/oscura-re/oscura/actions) | [Coverage Reports](https://codecov.io/gh/oscura-re/oscura)
396
-
397
- ### Standards Implementation
398
-
399
- We implement measurements based on IEEE specifications:
400
-
401
- | Standard | Coverage | Hardware RE Relevance |
402
- | --------------- | ---------------------------------------------- | ----------------------------------------------- |
403
- | **IEEE 181** | Pulse timing, rise/fall, overshoot, duty cycle | Protocol physical layer validation |
404
- | **IEEE 1241** | SNR, SINAD, THD, SFDR, ENOB | ADC characterization for side-channel analysis |
405
- | **IEEE 1459** | Active/reactive power, harmonics, power factor | Power supply profiling, fault injection targets |
406
- | **IEEE 2414** | TIE, period jitter, RJ/DJ decomposition, BER | Clock glitch detection, timing attack analysis |
407
-
408
- ### Architecture Principles
409
-
410
- Built for extensibility:
411
-
412
- - **Type-safe**: MyPy strict mode, comprehensive type hints
413
- - **Modular**: Protocol decoders, loaders, and analyzers are plug-and-play
414
- - **Memory-efficient**: Lazy loading, memory-mapped files, chunked processing (TB-scale datasets)
415
- - **Documented**: Google-style docstrings, 95% documentation coverage
416
- - **Reproducible**: Hypothesis tracking, confidence scoring, full audit trails
417
-
418
- ---
419
-
420
- ## Learn By Doing
421
-
422
- ### Working Demonstrations
423
-
424
- **100+ working demos** organized into 19 categories covering:
425
-
426
- - **Data Loading** - All file format loaders (oscilloscopes, logic analyzers, automotive, scientific)
427
- - **Basic Analysis** - Waveform measurements, digital analysis, spectral analysis, filtering
428
- - **Protocol Decoding** - UART, SPI, I2C, CAN, LIN, FlexRay, JTAG, SWD, I2S, USB
429
- - **Advanced Analysis** - Jitter, eye diagrams, power analysis, signal integrity, TDR
430
- - **Domain Specific** - Automotive diagnostics, EMC compliance, side-channel analysis, IEEE 181 timing
431
- - **Reverse Engineering** - CRC recovery, state machines, Wireshark dissectors, ML classification
432
- - **Advanced Features** - Lazy loading, memory management, performance optimization, batch processing
433
- - **Extensibility** - Custom analyzers, plugins, templates
434
- - **Integration** - CI/CD, hardware, external tools, web dashboards
435
- - **Export & Visualization** - All export formats, plotting, reporting
436
- - **Complete Workflows** - End-to-end production pipelines
437
- - **Standards Compliance** - IEEE 181/1241/1459/2414, automotive standards
438
-
439
- ### Comprehensive Demonstrations
440
-
441
- **36 comprehensive workflows** organized by skill level and domain:
442
-
443
- - **[Getting Started](demos/README.md#beginner-path-2-4-hours)** - File loading, basic measurements, format export (Beginner, 2-4 hours)
444
- - **[Protocol Decoding](demos/README.md#intermediate-path-6-10-hours)** - UART, SPI, I2C, Manchester, JTAG, USB, PCAP (Intermediate, 6-10 hours)
445
- - **[Reverse Engineering](demos/README.md#advanced-path-12-20-hours)** - CRC recovery, state machines, Wireshark dissectors, automotive protocols (Advanced, 12-20 hours)
446
- - **[Standards Compliance](demos/README.md#advanced-path-12-20-hours)** - IEEE 181/1241/1459/2414, CISPR 32, IEC 61000 (Advanced/Expert)
447
- - **[Complete Workflows](demos/README.md#expert-path-20-40-hours)** - End-to-end production pipelines with ML inference (Expert, 20-40 hours)
448
-
449
- **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
450
-
451
- [**See full demo catalog with learning paths**](demos/README.md)
452
-
453
- ### Run Your First Demo
454
-
455
- ```bash
456
- # Install development dependencies
457
- ./scripts/setup.sh
458
-
459
- # Run your first demo
460
- python demos/00_getting_started/00_hello_world.py
461
-
462
- # Or try a specific topic
463
- python demos/05_domain_specific/05_side_channel_basics.py
464
- ```
465
-
466
- ---
467
-
468
- ## Command-Line Interface
469
-
470
- ```bash
471
- # Signal characterization
472
- oscura characterize capture.wfm
473
-
474
- # Protocol decoding with auto-detection
475
- oscura decode uart_capture.wfm --protocol uart --baud 115200
476
-
477
- # Batch processing entire directories
478
- oscura batch '*.wfm' --analysis characterize
479
-
480
- # Differential analysis (compare baseline to modified)
481
- oscura compare baseline.wfm modified.wfm
482
-
483
- # Interactive REPL for exploration
484
- oscura shell
485
- ```
486
-
487
- [**Full CLI reference**](docs/cli.md)
488
-
489
- ---
490
-
491
- ## Why This Exists
492
-
493
- ### Legitimate Use Cases
494
-
495
- Hardware reverse engineering serves critical needs across security, repair, modernization, and defense:
496
-
497
- **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.
498
-
499
- **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.
500
-
501
- **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.
502
-
503
- **National Defense:** Intelligence and threat assessment depend on understanding adversary capabilities. Forensic analysis of captured equipment requires comprehensive signal analysis and protocol decoding.
504
-
505
- **Academic Research:** Understanding existing systems informs better designs. Teaching security requires demonstrating real vulnerabilities. Open tools advance the field collectively.
506
-
507
- ### The Open Source Philosophy
508
-
509
- 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.
510
-
511
- 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.
512
-
513
- ### Join the Effort
514
-
515
- 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.**
516
-
517
- - Reverse engineered a proprietary protocol? Contribute the decoder.
518
- - Built workflow automation techniques? Add them to the framework.
519
- - Work with file formats we don't support? Write a loader.
520
- - Found vulnerabilities using these tools? Share sanitized case studies.
521
- - Teaching hardware security? Use Oscura and improve the documentation.
522
-
523
- Every contribution pools our collective expertise and makes the next reverse engineering project easier for everyone.
524
-
525
- ---
526
-
527
- ## Getting Involved
528
-
529
- ### Contributing
530
-
531
- ```bash
532
- # Clone and setup development environment
533
- git clone https://github.com/oscura-re/oscura.git
534
- cd oscura
535
- ./scripts/setup.sh # Complete setup with hooks
536
-
537
- # Run quality checks (required before commit)
538
- ./scripts/check.sh # Linting, type checking, tests
539
- ./scripts/test.sh # Full test suite with coverage
540
-
541
- # Validate everything passes
542
- python3 .claude/hooks/validate_all.py # Must show 5/5 passing
543
- ```
544
-
545
- **What We Need:**
546
-
547
- | Contribution Type | Examples | Impact |
548
- | ------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------- |
549
- | **Workflow Automation** | New analysis pipelines, export formats, integration scripts | Core value proposition |
550
- | **File Format Loaders** | Oscilloscope/LA formats not yet supported | Eliminate conversion steps |
551
- | **Inference Algorithms** | Better state machine learning, field detection, pattern discovery | Improve automatic analysis quality |
552
- | **Protocol Decoders** | Proprietary protocols you've reversed | Enable others to analyze same systems |
553
- | **Hardware Integration** | DAQ systems, instrument drivers, live capture workflows | Enable real-time analysis |
554
- | **Real-World Validation** | Test on your captures, report issues | Ensure reliability across use cases |
555
- | **Documentation & Case Studies** | Tutorials, sanitized RE workflows, academic papers using Oscura | Lower entry barrier, demonstrate capabilities |
556
-
557
- [**Contributing Guide**](CONTRIBUTING.md) | [Architecture Documentation](docs/developer-guide/architecture.md)
558
-
559
- ### Community
560
-
561
- - **Issues:** [GitHub Issues](https://github.com/oscura-re/oscura/issues) - Bug reports, feature requests
562
- - **Discussions:** [GitHub Discussions](https://github.com/oscura-re/oscura/discussions) - Questions, ideas, collaboration
563
- - **Security:** [SECURITY.md](SECURITY.md) - Responsible disclosure process
564
-
565
- ---
566
-
567
- ## Documentation
568
-
569
- ### User Guides
570
-
571
- - [Quick Start Guide](docs/guides/quick-start.md) - Installation and first steps
572
- - [Black-Box Protocol Analysis](docs/guides/blackbox-analysis.md) - Unknown protocol RE workflow
573
- - [Side-Channel Analysis](docs/guides/side-channel-analysis.md) - Using ChipWhisperer traces with Oscura
574
- - [Hardware Acquisition](docs/guides/hardware-acquisition.md) - Direct instrument control
575
- - [Complete Workflows](docs/guides/workflows.md) - End-to-end pipelines
576
-
577
- ### API Reference
578
-
579
- - [API Documentation](docs/api/) - Complete function reference
580
- - [Session Management](docs/api/session-management.md) - Interactive analysis sessions
581
- - [CLI Reference](docs/cli.md) - Command-line interface
582
-
583
- ### Development
584
-
585
- - [Architecture](docs/developer-guide/architecture.md) - Design principles and patterns
586
- - [Testing Guide](docs/testing/) - Test suite architecture
587
- - [CHANGELOG](CHANGELOG.md) - Version history and migration guides
588
-
589
- ---
590
-
591
- ## Project Status
592
-
593
- **Current Version:** [0.9.0](https://github.com/oscura-re/oscura/releases/latest) (2026-01-31)
594
-
595
- **Active Development Areas:**
596
-
597
- - Hypothesis-driven RE workflows and confidence scoring
598
- - Automotive protocol analysis (CAN-FD, J1939, OBD-II, UDS)
599
- - Unknown protocol inference (state machines, field detection, CRC recovery)
600
- - Multi-format file loading and export automation
601
- - Vintage computing support (retro logic families, IC identification, 1960s-present)
602
-
603
- **Stability:** Production-ready for security research, right-to-repair, academic use. APIs may evolve as we add capabilities—breaking changes documented in [CHANGELOG](CHANGELOG.md).
604
-
605
- [**Release History**](https://github.com/oscura-re/oscura/releases) | [**Roadmap Discussions**](https://github.com/oscura-re/oscura/discussions)
606
-
607
- ---
608
-
609
- ## Citation
610
-
611
- If Oscura contributes to your research, please cite:
612
-
613
- ```bibtex
614
- @software{oscura2026,
615
- title = {Oscura: Hardware Reverse Engineering Framework},
616
- author = {Oscura Contributors},
617
- year = {2026},
618
- url = {https://github.com/oscura-re/oscura},
619
- version = {0.9.0}
620
- }
621
- ```
622
-
623
- **Machine-readable:** [CITATION.cff](CITATION.cff)
624
-
625
- ---
626
-
627
- ## Legal
628
-
629
- **License:** [MIT License](LICENSE) - Permissive use, modification, distribution
630
-
631
- **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.
632
-
633
- **Dependencies:** Built with Python, NumPy, SciPy, Matplotlib, Hypothesis. See [pyproject.toml](pyproject.toml) for complete dependency list.
634
-
635
- **Supported by:** Security researchers, right-to-repair advocates, academic institutions, and the open source community.
636
-
637
- ---
638
-
639
- **Oscura** - _Illuminate what others obscure._
640
-
641
- 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.