oscura 0.8.0__py3-none-any.whl → 0.10.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 (151) hide show
  1. oscura/__init__.py +19 -19
  2. oscura/analyzers/__init__.py +2 -0
  3. oscura/analyzers/digital/extraction.py +2 -3
  4. oscura/analyzers/digital/quality.py +1 -1
  5. oscura/analyzers/digital/timing.py +1 -1
  6. oscura/analyzers/patterns/__init__.py +66 -0
  7. oscura/analyzers/power/basic.py +3 -3
  8. oscura/analyzers/power/soa.py +1 -1
  9. oscura/analyzers/power/switching.py +3 -3
  10. oscura/analyzers/signal_classification.py +529 -0
  11. oscura/analyzers/signal_integrity/sparams.py +3 -3
  12. oscura/analyzers/statistics/basic.py +10 -7
  13. oscura/analyzers/validation.py +1 -1
  14. oscura/analyzers/waveform/measurements.py +200 -156
  15. oscura/analyzers/waveform/measurements_with_uncertainty.py +91 -35
  16. oscura/analyzers/waveform/spectral.py +164 -73
  17. oscura/api/dsl/commands.py +15 -6
  18. oscura/api/server/templates/base.html +137 -146
  19. oscura/api/server/templates/export.html +84 -110
  20. oscura/api/server/templates/home.html +248 -267
  21. oscura/api/server/templates/protocols.html +44 -48
  22. oscura/api/server/templates/reports.html +27 -35
  23. oscura/api/server/templates/session_detail.html +68 -78
  24. oscura/api/server/templates/sessions.html +62 -72
  25. oscura/api/server/templates/waveforms.html +54 -64
  26. oscura/automotive/__init__.py +1 -1
  27. oscura/automotive/can/session.py +1 -1
  28. oscura/automotive/dbc/generator.py +638 -23
  29. oscura/automotive/uds/decoder.py +99 -6
  30. oscura/cli/analyze.py +8 -2
  31. oscura/cli/batch.py +36 -5
  32. oscura/cli/characterize.py +18 -4
  33. oscura/cli/export.py +47 -5
  34. oscura/cli/main.py +2 -0
  35. oscura/cli/onboarding/wizard.py +10 -6
  36. oscura/cli/pipeline.py +585 -0
  37. oscura/cli/visualize.py +6 -4
  38. oscura/convenience.py +400 -32
  39. oscura/core/measurement_result.py +286 -0
  40. oscura/core/progress.py +1 -1
  41. oscura/core/types.py +232 -239
  42. oscura/correlation/multi_protocol.py +1 -1
  43. oscura/export/legacy/__init__.py +11 -0
  44. oscura/export/legacy/wav.py +75 -0
  45. oscura/exporters/__init__.py +19 -0
  46. oscura/exporters/wireshark.py +809 -0
  47. oscura/hardware/acquisition/file.py +5 -19
  48. oscura/hardware/acquisition/saleae.py +10 -10
  49. oscura/hardware/acquisition/socketcan.py +4 -6
  50. oscura/hardware/acquisition/synthetic.py +1 -5
  51. oscura/hardware/acquisition/visa.py +6 -6
  52. oscura/hardware/security/side_channel_detector.py +5 -508
  53. oscura/inference/message_format.py +686 -1
  54. oscura/jupyter/display.py +2 -2
  55. oscura/jupyter/magic.py +3 -3
  56. oscura/loaders/__init__.py +17 -12
  57. oscura/loaders/binary.py +1 -1
  58. oscura/loaders/chipwhisperer.py +1 -2
  59. oscura/loaders/configurable.py +1 -1
  60. oscura/loaders/csv_loader.py +2 -2
  61. oscura/loaders/hdf5_loader.py +1 -1
  62. oscura/loaders/lazy.py +6 -1
  63. oscura/loaders/mmap_loader.py +0 -1
  64. oscura/loaders/numpy_loader.py +8 -7
  65. oscura/loaders/preprocessing.py +3 -5
  66. oscura/loaders/rigol.py +21 -7
  67. oscura/loaders/sigrok.py +2 -5
  68. oscura/loaders/tdms.py +3 -2
  69. oscura/loaders/tektronix.py +38 -32
  70. oscura/loaders/tss.py +20 -27
  71. oscura/loaders/vcd.py +13 -8
  72. oscura/loaders/wav.py +1 -6
  73. oscura/pipeline/__init__.py +76 -0
  74. oscura/pipeline/handlers/__init__.py +165 -0
  75. oscura/pipeline/handlers/analyzers.py +1045 -0
  76. oscura/pipeline/handlers/decoders.py +899 -0
  77. oscura/pipeline/handlers/exporters.py +1103 -0
  78. oscura/pipeline/handlers/filters.py +891 -0
  79. oscura/pipeline/handlers/loaders.py +640 -0
  80. oscura/pipeline/handlers/transforms.py +768 -0
  81. oscura/reporting/formatting/measurements.py +55 -14
  82. oscura/reporting/templates/enhanced/protocol_re.html +504 -503
  83. oscura/side_channel/__init__.py +38 -57
  84. oscura/utils/builders/signal_builder.py +5 -5
  85. oscura/utils/comparison/compare.py +7 -9
  86. oscura/utils/comparison/golden.py +1 -1
  87. oscura/utils/filtering/convenience.py +2 -2
  88. oscura/utils/math/arithmetic.py +38 -62
  89. oscura/utils/math/interpolation.py +20 -20
  90. oscura/utils/pipeline/__init__.py +4 -17
  91. oscura/utils/progressive.py +1 -4
  92. oscura/utils/triggering/edge.py +1 -1
  93. oscura/utils/triggering/pattern.py +2 -2
  94. oscura/utils/triggering/pulse.py +2 -2
  95. oscura/utils/triggering/window.py +3 -3
  96. oscura/validation/hil_testing.py +11 -11
  97. oscura/visualization/__init__.py +46 -284
  98. oscura/visualization/batch.py +72 -433
  99. oscura/visualization/plot.py +542 -53
  100. oscura/visualization/styles.py +184 -318
  101. oscura/workflows/batch/advanced.py +1 -1
  102. oscura/workflows/batch/aggregate.py +7 -8
  103. oscura/workflows/complete_re.py +251 -23
  104. oscura/workflows/digital.py +27 -4
  105. oscura/workflows/multi_trace.py +136 -17
  106. oscura/workflows/waveform.py +11 -6
  107. {oscura-0.8.0.dist-info → oscura-0.10.0.dist-info}/METADATA +59 -79
  108. {oscura-0.8.0.dist-info → oscura-0.10.0.dist-info}/RECORD +111 -136
  109. oscura/side_channel/dpa.py +0 -1025
  110. oscura/utils/optimization/__init__.py +0 -19
  111. oscura/utils/optimization/parallel.py +0 -443
  112. oscura/utils/optimization/search.py +0 -532
  113. oscura/utils/pipeline/base.py +0 -338
  114. oscura/utils/pipeline/composition.py +0 -248
  115. oscura/utils/pipeline/parallel.py +0 -449
  116. oscura/utils/pipeline/pipeline.py +0 -375
  117. oscura/utils/search/__init__.py +0 -16
  118. oscura/utils/search/anomaly.py +0 -424
  119. oscura/utils/search/context.py +0 -294
  120. oscura/utils/search/pattern.py +0 -288
  121. oscura/utils/storage/__init__.py +0 -61
  122. oscura/utils/storage/database.py +0 -1166
  123. oscura/visualization/accessibility.py +0 -526
  124. oscura/visualization/annotations.py +0 -371
  125. oscura/visualization/axis_scaling.py +0 -305
  126. oscura/visualization/colors.py +0 -451
  127. oscura/visualization/digital.py +0 -436
  128. oscura/visualization/eye.py +0 -571
  129. oscura/visualization/histogram.py +0 -281
  130. oscura/visualization/interactive.py +0 -1035
  131. oscura/visualization/jitter.py +0 -1042
  132. oscura/visualization/keyboard.py +0 -394
  133. oscura/visualization/layout.py +0 -400
  134. oscura/visualization/optimization.py +0 -1079
  135. oscura/visualization/palettes.py +0 -446
  136. oscura/visualization/power.py +0 -508
  137. oscura/visualization/power_extended.py +0 -955
  138. oscura/visualization/presets.py +0 -469
  139. oscura/visualization/protocols.py +0 -1246
  140. oscura/visualization/render.py +0 -223
  141. oscura/visualization/rendering.py +0 -444
  142. oscura/visualization/reverse_engineering.py +0 -838
  143. oscura/visualization/signal_integrity.py +0 -989
  144. oscura/visualization/specialized.py +0 -643
  145. oscura/visualization/spectral.py +0 -1226
  146. oscura/visualization/thumbnails.py +0 -340
  147. oscura/visualization/time_axis.py +0 -351
  148. oscura/visualization/waveform.py +0 -454
  149. {oscura-0.8.0.dist-info → oscura-0.10.0.dist-info}/WHEEL +0 -0
  150. {oscura-0.8.0.dist-info → oscura-0.10.0.dist-info}/entry_points.txt +0 -0
  151. {oscura-0.8.0.dist-info → oscura-0.10.0.dist-info}/licenses/LICENSE +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: oscura
3
- Version: 0.8.0
3
+ Version: 0.10.0
4
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
5
  Project-URL: Homepage, https://github.com/oscura-re/oscura
6
6
  Project-URL: Documentation, https://github.com/oscura-re/oscura/tree/main/docs
@@ -28,16 +28,26 @@ Classifier: Topic :: System :: Hardware
28
28
  Classifier: Topic :: System :: Hardware :: Hardware Drivers
29
29
  Classifier: Typing :: Typed
30
30
  Requires-Python: >=3.12
31
+ Requires-Dist: cantools<40.0.0,>=39.4.0
31
32
  Requires-Dist: click<9.0.0,>=8.1.0
32
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
33
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
34
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
35
45
  Requires-Dist: scipy<2.0.0,>=1.10.0
36
46
  Requires-Dist: tm-data-types<1.0.0,>=0.3.0
37
47
  Requires-Dist: tqdm<5.0.0,>=4.65.0
48
+ Requires-Dist: weasyprint<64.0.0,>=63.0
38
49
  Provides-Extra: all
39
50
  Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'all'
40
- Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'all'
41
51
  Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'all'
42
52
  Requires-Dist: coverage[toml]<8.0.0,>=7.0; extra == 'all'
43
53
  Requires-Dist: cryptography<47.0.0,>=44.0.1; extra == 'all'
@@ -45,17 +55,12 @@ Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'all'
45
55
  Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'all'
46
56
  Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'all'
47
57
  Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'all'
48
- Requires-Dist: jinja2<4.0.0,>=3.1; extra == 'all'
49
58
  Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'all'
50
- Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == 'all'
51
59
  Requires-Dist: mypy<2.0.0,>=1.0; extra == 'all'
52
60
  Requires-Dist: nbconvert!=7.16.6,<8.0.0,>=7.0.0; extra == 'all'
53
61
  Requires-Dist: networkx<4.0.0,>=3.0; extra == 'all'
54
62
  Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'all'
55
- Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'all'
56
- Requires-Dist: pandas<3.0.0,>=2.0.0; extra == 'all'
57
63
  Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'all'
58
- Requires-Dist: psutil<7.0.0,>=5.9.0; extra == 'all'
59
64
  Requires-Dist: pyserial<4.0.0,>=3.5; extra == 'all'
60
65
  Requires-Dist: pytest-asyncio<1.0.0,>=0.23.0; extra == 'all'
61
66
  Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'all'
@@ -66,16 +71,12 @@ Requires-Dist: pytest-split<1.0.0,>=0.10.0; extra == 'all'
66
71
  Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'all'
67
72
  Requires-Dist: pytest-xdist<4.0.0,>=3.0; extra == 'all'
68
73
  Requires-Dist: pytest<10.0.0,>=8.0; extra == 'all'
69
- Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'all'
70
- Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'all'
71
74
  Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'all'
72
75
  Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'all'
73
76
  Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'all'
74
77
  Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'all'
75
- Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'all'
76
78
  Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'all'
77
79
  Requires-Dist: ruff<1.0.0,>=0.8.0; extra == 'all'
78
- Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'all'
79
80
  Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == 'all'
80
81
  Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'all'
81
82
  Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'all'
@@ -85,12 +86,6 @@ Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'analysis'
85
86
  Requires-Dist: scikit-learn<2.0.0,>=1.3.0; extra == 'analysis'
86
87
  Provides-Extra: automotive
87
88
  Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'automotive'
88
- Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'automotive'
89
- Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'automotive'
90
- Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'automotive'
91
- Provides-Extra: dataframes
92
- Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'dataframes'
93
- Requires-Dist: pandas<3.0.0,>=2.0.0; extra == 'dataframes'
94
89
  Provides-Extra: dev
95
90
  Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'dev'
96
91
  Requires-Dist: coverage[toml]<8.0.0,>=7.0; extra == 'dev'
@@ -127,28 +122,12 @@ Requires-Dist: nbconvert!=7.16.6,<8.0.0,>=7.0.0; extra == 'jupyter'
127
122
  Provides-Extra: oscilloscopes
128
123
  Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'oscilloscopes'
129
124
  Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'oscilloscopes'
130
- Provides-Extra: reporting
131
- Requires-Dist: jinja2<4.0.0,>=3.1; extra == 'reporting'
132
- Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == 'reporting'
133
- Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'reporting'
134
- Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'reporting'
135
125
  Provides-Extra: standard
136
- Requires-Dist: jinja2<4.0.0,>=3.1; extra == 'standard'
137
- Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == 'standard'
138
- Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'standard'
139
- Requires-Dist: pandas<3.0.0,>=2.0.0; extra == 'standard'
140
- Requires-Dist: psutil<7.0.0,>=5.9.0; extra == 'standard'
141
- Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'standard'
142
- Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'standard'
143
- Provides-Extra: system
144
- Requires-Dist: psutil<7.0.0,>=5.9.0; extra == 'system'
145
- Provides-Extra: visualization
146
- Requires-Dist: matplotlib<4.0.0,>=3.7.0; extra == 'visualization'
147
126
  Description-Content-Type: text/markdown
148
127
 
149
128
  # Oscura
150
129
 
151
- **Workflow automation for hardware reverse engineering.** Stop juggling seven different tools to analyze one capture. Oscura chains specialized tools (sigrok, ChipWhisperer, scipy) into unified Python workflows—from oscilloscope files to Wireshark dissectors without manual conversions or context switching.
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.
152
131
 
153
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)
154
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)
@@ -164,8 +143,8 @@ Description-Content-Type: text/markdown
164
143
  Hardware reverse engineering means juggling specialized tools:
165
144
 
166
145
  1. Export oscilloscope waveforms (vendor-specific formats)
167
- 2. Convert formats for analysis (sigrok, custom scripts)
168
- 3. Decode protocols (PulseView, separate decoders)
146
+ 2. Convert formats for analysis (custom scripts, manual conversion)
147
+ 3. Decode protocols (separate decoder tools)
169
148
  4. Infer unknown protocols (Netzob, manual analysis)
170
149
  5. Reverse checksums (CRC RevEng, separate tool)
171
150
  6. Generate documentation (manual Wireshark dissectors, DBC files)
@@ -177,27 +156,23 @@ Hardware reverse engineering means juggling specialized tools:
177
156
 
178
157
  Oscura automates complete workflows in Python:
179
158
 
180
- **What We Integrate:**
181
-
182
- - Protocol decoding via [sigrok](https://sigrok.org/) (UART, SPI, I2C, CAN, etc.)
183
- - Signal processing with scipy/numpy
184
- - Side-channel trace formats (ChipWhisperer)
185
- - Automotive protocols (cantools integration)
186
-
187
- **What We Add:**
159
+ **What We Provide:**
188
160
 
161
+ - **Native protocol decoders for 16 formats**: UART, SPI, I2C, CAN, CAN-FD, LIN, FlexRay, JTAG, SWD, USB, I2S, 1-Wire, HDLC, Manchester
189
162
  - **Hypothesis-driven RE workflows** with differential analysis and confidence scoring
190
163
  - **Automatic Wireshark dissector generation** from inferred protocols
191
164
  - **DBC file generation** from raw CAN captures (no manual signal definition)
192
- - **Multi-format file loading** (Tektronix, Rigol, Sigrok, BLF, PCAP, ChipWhisperer)
165
+ - **Multi-format file loading** (Tektronix, Rigol, Sigrok .sr, BLF, PCAP, ChipWhisperer, VCD, WAV, CSV, HDF5)
193
166
  - **CRC/checksum recovery** from message-checksum pairs
194
167
  - **Unified Python API** eliminating tool-hopping and format conversions
168
+ - Signal processing with scipy/numpy
169
+ - Automotive protocol support (cantools integration)
195
170
 
196
171
  **Value proposition:** Write one Python script instead of:
197
172
 
198
173
  1. Exporting from oscilloscope software (vendor GUI)
199
- 2. Converting formats (sigrok-cli, custom scripts)
200
- 3. Decoding protocols (PulseView manual selection)
174
+ 2. Converting formats (custom scripts, manual conversion)
175
+ 3. Decoding protocols (separate decoder tool manual configuration)
201
176
  4. Inferring message formats (Netzob or manual)
202
177
  5. Recovering checksums (CRC RevEng separate invocation)
203
178
  6. Writing dissectors (manual Lua coding)
@@ -292,38 +267,41 @@ result = osc.auto_decode(trace)
292
267
  print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
293
268
  ```
294
269
 
295
- **[See demos/README.md](demos/README.md)** for 105+ comprehensive demonstrations organized by skill level.
270
+ **[See demos/README.md](demos/README.md)** for 100+ working demonstrations organized by skill level (36 comprehensive workflows across 19 categories).
296
271
 
297
272
  ---
298
273
 
299
274
  ## Core Capabilities
300
275
 
301
- ### Unique Contributions
276
+ ### What Oscura Does Uniquely
302
277
 
303
278
  | Capability | What We Provide | Why It Matters |
304
279
  | ------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
305
280
  | **Hypothesis-Driven RE** | BlackBoxSession with differential analysis, field detection, confidence scoring, audit trails | Systematic unknown protocol analysis vs manual guesswork |
306
281
  | **DBC Auto-Generation** | Statistical CAN signal inference from captures → DBC export | Open-source alternative to Vector CANalyzer ($$$) |
307
282
  | **Wireshark Dissector Generation** | Infer protocol → generate validated Lua dissector | End-to-end automation (others require manual YAML specs) |
308
- | **Multi-Format File Loading** | Oscilloscopes (Tektronix WFM, Rigol), logic analyzers (Sigrok, VCD), automotive BLF | Eliminate format conversion steps |
309
- | **Statistical Protocol Auto-Detect** | Waveform analysis (timing, voltage, patterns) → protocol identification | Goes beyond sigrok's signal name matching |
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 |
310
285
  | **Unified Workflow API** | Single Python script: oscilloscope file → decode → infer → export dissector | Replace 7-tool chains with one script |
311
- | **CRC Recovery** | Message-checksum pairs → polynomial, init, XOR out, reflection | Practical automation (CRC RevEng is more robust for edge cases) |
312
- | **Automotive Security Analysis** | Stimulus-response correlation, hypothesis testing, UDS/OBD-II decoding | Research-focused (CANToolz covers security, python-can covers low-level) |
313
- | **State Machine Extraction (Passive)** | RPNI algorithm for passive observation (vs Netzob's active L\* requiring oracle) | Different use case from existing tools |
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 |
314
289
  | **Evidence-Based Discovery** | Confidence scoring, hypothesis tracking, statistical validation, reproducible audit trails | Scientific rigor for research publication |
315
290
 
316
- ### Integration Capabilities
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:
317
294
 
318
- | Category | Implementation | Best Alternative |
319
- | -------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
320
- | **Protocol Decoding** | Integrated sigrok decoders (UART, SPI, I2C, CAN, LIN, JTAG, etc.) via Python API | [sigrok](https://sigrok.org/) directly (100+ decoders) |
321
- | **Side-Channel Analysis** | Load ChipWhisperer traces, basic DPA/CPA implementations | [ChipWhisperer](https://chipwhisperer.com/) (superior capabilities) |
322
- | **Signal Processing** | IEEE-based measurements using scipy/numpy | [scipy.signal](https://docs.scipy.org/doc/scipy/reference/signal.html) directly or MATLAB |
323
- | **CAN Parsing** | cantools integration for DBC parsing and message encoding | [cantools](https://github.com/cantools/cantools) + [python-can](https://python-can.readthedocs.io/) |
324
- | **File Format Conversion** | Loaders for 13+ formats with unified API | Vendor software + manual export |
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 |
325
303
 
326
- **Our philosophy:** Integrate best-in-class tools rather than reimplementing them. Add value through workflow automation and novel analysis methods.
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.
327
305
 
328
306
  ---
329
307
 
@@ -337,16 +315,18 @@ print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
337
315
  - You need Wireshark dissectors generated automatically from inferred protocols
338
316
  - You're working with multiple oscilloscope/LA formats and want unified API
339
317
  - You value reproducible research with hypothesis tracking and confidence scoring
318
+ - You want to chain multiple RE tools together in one script
340
319
 
341
320
  **Use specialized tools directly when:**
342
321
 
343
- - You only need protocol decoding → [sigrok](https://sigrok.org/) has 100+ decoders
344
- - You're doing side-channel attacks → [ChipWhisperer](https://chipwhisperer.com/) is superior
345
- - You only need signal processing → [scipy](https://scipy.org/)/MATLAB are more optimized
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
346
325
  - You need the most robust CRC recovery → [CRC RevEng](https://reveng.sourceforge.io/) handles edge cases better
347
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
348
328
 
349
- **Oscura's sweet spot:** Chaining multiple RE steps in scripted workflows with novel hypothesis-driven analysis.
329
+ **Oscura's sweet spot:** Workflow automation that chains multiple RE steps with hypothesis-driven analysis.
350
330
 
351
331
  ---
352
332
 
@@ -357,7 +337,7 @@ print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
357
337
  - **Protocol reverse engineering** with hypothesis tracking and validation
358
338
  - **Automotive ECU security** via CAN stimulus-response analysis
359
339
  - **Attack surface mapping** through state machine extraction
360
- - **Cryptographic implementation validation** (use ChipWhisperer for attacks, Oscura for trace analysis workflows)
340
+ - **Side-channel trace analysis workflows** (demo-level DPA/CPA—use ChipWhisperer for production attacks)
361
341
 
362
342
  ### Right-to-Repair & Modernization
363
343
 
@@ -371,7 +351,7 @@ print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
371
351
  - **Reproducible workflows** with evidence tracking and audit trails
372
352
  - **Statistical validation** with confidence scoring
373
353
  - **IEEE-based measurements** for publishable results (181/1241/1459/2414)
374
- - **22,000+ comprehensive tests, 80%+ coverage** ensure reliability
354
+ - **475 test files with 80%+ coverage** ensure reliability
375
355
 
376
356
  ### Industrial & Automotive
377
357
 
@@ -384,18 +364,18 @@ print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
384
364
 
385
365
  ## Built On
386
366
 
387
- Oscura integrates proven open-source tools:
367
+ Oscura builds on proven open-source tools:
388
368
 
389
369
  | Component | What We Use | Why |
390
370
  | ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
391
- | **Protocol Engine** | [sigrok](https://sigrok.org/) libsigrokdecode | 100+ mature, community-supported protocol decoders |
392
371
  | **Signal Processing** | [scipy](https://scipy.org/)/[numpy](https://numpy.org/) | Industry-standard numerical computing |
393
- | **Side-Channel Traces** | [ChipWhisperer](https://chipwhisperer.com/) formats | De facto standard for side-channel research |
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 |
394
374
  | **CAN Protocols** | [cantools](https://github.com/cantools/cantools), [python-can](https://python-can.readthedocs.io/) | Robust CAN message parsing and encoding |
395
375
  | **Testing** | [pytest](https://pytest.org/), [Hypothesis](https://hypothesis.readthedocs.io/) | Property-based testing for algorithm validation |
396
376
  | **Type Safety** | [mypy](https://mypy-lang.org/) | Static type checking (strict mode) |
397
377
 
398
- **Our contribution:** Unified API + novel hypothesis-driven RE workflows + format handling + export automation.
378
+ **Our contribution:** Unified API + hypothesis-driven RE workflows + 22 format loaders + 16 native protocol decoders + export automation (Wireshark, DBC, Scapy).
399
379
 
400
380
  ---
401
381
 
@@ -405,8 +385,8 @@ Oscura integrates proven open-source tools:
405
385
 
406
386
  Production-ready validation:
407
387
 
408
- - **22,000+ comprehensive tests** with property-based validation (Hypothesis)
409
- - **80%+ code coverage** with branch coverage enabled
388
+ - **475 test files** with comprehensive unit, integration, and property-based tests (Hypothesis)
389
+ - **80%+ code coverage** enforced with branch coverage enabled
410
390
  - **Pre-commit hooks** (format, lint, type check) enforce consistency
411
391
  - **Merge queue CI** prevents untested code from landing
412
392
  - **Nightly stress tests** validate edge cases and memory usage
@@ -441,7 +421,7 @@ Built for extensibility:
441
421
 
442
422
  ### Working Demonstrations
443
423
 
444
- **105+ comprehensive demos** organized into 12 categories covering:
424
+ **100+ working demos** organized into 19 categories covering:
445
425
 
446
426
  - **Data Loading** - All file format loaders (oscilloscopes, logic analyzers, automotive, scientific)
447
427
  - **Basic Analysis** - Waveform measurements, digital analysis, spectral analysis, filtering
@@ -458,7 +438,7 @@ Built for extensibility:
458
438
 
459
439
  ### Comprehensive Demonstrations
460
440
 
461
- **33+ in-depth demos** organized by skill level and domain:
441
+ **36 comprehensive workflows** organized by skill level and domain:
462
442
 
463
443
  - **[Getting Started](demos/README.md#beginner-path-2-4-hours)** - File loading, basic measurements, format export (Beginner, 2-4 hours)
464
444
  - **[Protocol Decoding](demos/README.md#intermediate-path-6-10-hours)** - UART, SPI, I2C, Manchester, JTAG, USB, PCAP (Intermediate, 6-10 hours)
@@ -610,7 +590,7 @@ python3 .claude/hooks/validate_all.py # Must show 5/5 passing
610
590
 
611
591
  ## Project Status
612
592
 
613
- **Current Version:** [0.6.0](https://github.com/oscura-re/oscura/releases/latest) (2026-01-25)
593
+ **Current Version:** [0.9.0](https://github.com/oscura-re/oscura/releases/latest) (2026-01-31)
614
594
 
615
595
  **Active Development Areas:**
616
596
 
@@ -636,7 +616,7 @@ If Oscura contributes to your research, please cite:
636
616
  author = {Oscura Contributors},
637
617
  year = {2026},
638
618
  url = {https://github.com/oscura-re/oscura},
639
- version = {0.6.0}
619
+ version = {0.9.0}
640
620
  }
641
621
  ```
642
622