oscura 0.7.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.
- oscura/__init__.py +19 -19
- oscura/analyzers/__init__.py +2 -0
- oscura/analyzers/digital/extraction.py +2 -3
- oscura/analyzers/digital/quality.py +1 -1
- oscura/analyzers/digital/timing.py +1 -1
- oscura/analyzers/eye/__init__.py +5 -1
- oscura/analyzers/eye/generation.py +501 -0
- oscura/analyzers/jitter/__init__.py +6 -6
- oscura/analyzers/jitter/timing.py +419 -0
- oscura/analyzers/patterns/__init__.py +94 -0
- oscura/analyzers/patterns/reverse_engineering.py +991 -0
- oscura/analyzers/power/__init__.py +35 -12
- oscura/analyzers/power/basic.py +3 -3
- oscura/analyzers/power/soa.py +1 -1
- oscura/analyzers/power/switching.py +3 -3
- oscura/analyzers/signal_classification.py +529 -0
- oscura/analyzers/signal_integrity/sparams.py +3 -3
- oscura/analyzers/statistics/__init__.py +4 -0
- oscura/analyzers/statistics/basic.py +152 -0
- oscura/analyzers/statistics/correlation.py +47 -6
- oscura/analyzers/validation.py +1 -1
- oscura/analyzers/waveform/__init__.py +2 -0
- oscura/analyzers/waveform/measurements.py +329 -163
- oscura/analyzers/waveform/measurements_with_uncertainty.py +91 -35
- oscura/analyzers/waveform/spectral.py +498 -54
- oscura/api/dsl/commands.py +15 -6
- oscura/api/server/templates/base.html +137 -146
- oscura/api/server/templates/export.html +84 -110
- oscura/api/server/templates/home.html +248 -267
- oscura/api/server/templates/protocols.html +44 -48
- oscura/api/server/templates/reports.html +27 -35
- oscura/api/server/templates/session_detail.html +68 -78
- oscura/api/server/templates/sessions.html +62 -72
- oscura/api/server/templates/waveforms.html +54 -64
- oscura/automotive/__init__.py +1 -1
- oscura/automotive/can/session.py +1 -1
- oscura/automotive/dbc/generator.py +638 -23
- oscura/automotive/dtc/data.json +102 -17
- oscura/automotive/uds/decoder.py +99 -6
- oscura/cli/analyze.py +8 -2
- oscura/cli/batch.py +36 -5
- oscura/cli/characterize.py +18 -4
- oscura/cli/export.py +47 -5
- oscura/cli/main.py +2 -0
- oscura/cli/onboarding/wizard.py +10 -6
- oscura/cli/pipeline.py +585 -0
- oscura/cli/visualize.py +6 -4
- oscura/convenience.py +400 -32
- oscura/core/config/loader.py +0 -1
- oscura/core/measurement_result.py +286 -0
- oscura/core/progress.py +1 -1
- oscura/core/schemas/device_mapping.json +8 -2
- oscura/core/schemas/packet_format.json +24 -4
- oscura/core/schemas/protocol_definition.json +12 -2
- oscura/core/types.py +300 -199
- oscura/correlation/multi_protocol.py +1 -1
- oscura/export/legacy/__init__.py +11 -0
- oscura/export/legacy/wav.py +75 -0
- oscura/exporters/__init__.py +19 -0
- oscura/exporters/wireshark.py +809 -0
- oscura/hardware/acquisition/file.py +5 -19
- oscura/hardware/acquisition/saleae.py +10 -10
- oscura/hardware/acquisition/socketcan.py +4 -6
- oscura/hardware/acquisition/synthetic.py +1 -5
- oscura/hardware/acquisition/visa.py +6 -6
- oscura/hardware/security/side_channel_detector.py +5 -508
- oscura/inference/message_format.py +686 -1
- oscura/jupyter/display.py +2 -2
- oscura/jupyter/magic.py +3 -3
- oscura/loaders/__init__.py +17 -12
- oscura/loaders/binary.py +1 -1
- oscura/loaders/chipwhisperer.py +1 -2
- oscura/loaders/configurable.py +1 -1
- oscura/loaders/csv_loader.py +2 -2
- oscura/loaders/hdf5_loader.py +1 -1
- oscura/loaders/lazy.py +6 -1
- oscura/loaders/mmap_loader.py +0 -1
- oscura/loaders/numpy_loader.py +8 -7
- oscura/loaders/preprocessing.py +3 -5
- oscura/loaders/rigol.py +21 -7
- oscura/loaders/sigrok.py +2 -5
- oscura/loaders/tdms.py +3 -2
- oscura/loaders/tektronix.py +38 -32
- oscura/loaders/tss.py +20 -27
- oscura/loaders/vcd.py +13 -8
- oscura/loaders/wav.py +1 -6
- oscura/pipeline/__init__.py +76 -0
- oscura/pipeline/handlers/__init__.py +165 -0
- oscura/pipeline/handlers/analyzers.py +1045 -0
- oscura/pipeline/handlers/decoders.py +899 -0
- oscura/pipeline/handlers/exporters.py +1103 -0
- oscura/pipeline/handlers/filters.py +891 -0
- oscura/pipeline/handlers/loaders.py +640 -0
- oscura/pipeline/handlers/transforms.py +768 -0
- oscura/reporting/__init__.py +88 -1
- oscura/reporting/automation.py +348 -0
- oscura/reporting/citations.py +374 -0
- oscura/reporting/core.py +54 -0
- oscura/reporting/formatting/__init__.py +11 -0
- oscura/reporting/formatting/measurements.py +320 -0
- oscura/reporting/html.py +57 -0
- oscura/reporting/interpretation.py +431 -0
- oscura/reporting/summary.py +329 -0
- oscura/reporting/templates/enhanced/protocol_re.html +504 -503
- oscura/reporting/visualization.py +542 -0
- oscura/side_channel/__init__.py +38 -57
- oscura/utils/builders/signal_builder.py +5 -5
- oscura/utils/comparison/compare.py +7 -9
- oscura/utils/comparison/golden.py +1 -1
- oscura/utils/filtering/convenience.py +2 -2
- oscura/utils/math/arithmetic.py +38 -62
- oscura/utils/math/interpolation.py +20 -20
- oscura/utils/pipeline/__init__.py +4 -17
- oscura/utils/progressive.py +1 -4
- oscura/utils/triggering/edge.py +1 -1
- oscura/utils/triggering/pattern.py +2 -2
- oscura/utils/triggering/pulse.py +2 -2
- oscura/utils/triggering/window.py +3 -3
- oscura/validation/hil_testing.py +11 -11
- oscura/visualization/__init__.py +47 -284
- oscura/visualization/batch.py +160 -0
- oscura/visualization/plot.py +542 -53
- oscura/visualization/styles.py +184 -318
- oscura/workflows/__init__.py +2 -0
- oscura/workflows/batch/advanced.py +1 -1
- oscura/workflows/batch/aggregate.py +7 -8
- oscura/workflows/complete_re.py +251 -23
- oscura/workflows/digital.py +27 -4
- oscura/workflows/multi_trace.py +136 -17
- oscura/workflows/waveform.py +788 -0
- {oscura-0.7.0.dist-info → oscura-0.10.0.dist-info}/METADATA +59 -79
- {oscura-0.7.0.dist-info → oscura-0.10.0.dist-info}/RECORD +135 -149
- oscura/side_channel/dpa.py +0 -1025
- oscura/utils/optimization/__init__.py +0 -19
- oscura/utils/optimization/parallel.py +0 -443
- oscura/utils/optimization/search.py +0 -532
- oscura/utils/pipeline/base.py +0 -338
- oscura/utils/pipeline/composition.py +0 -248
- oscura/utils/pipeline/parallel.py +0 -449
- oscura/utils/pipeline/pipeline.py +0 -375
- oscura/utils/search/__init__.py +0 -16
- oscura/utils/search/anomaly.py +0 -424
- oscura/utils/search/context.py +0 -294
- oscura/utils/search/pattern.py +0 -288
- oscura/utils/storage/__init__.py +0 -61
- oscura/utils/storage/database.py +0 -1166
- oscura/visualization/accessibility.py +0 -526
- oscura/visualization/annotations.py +0 -371
- oscura/visualization/axis_scaling.py +0 -305
- oscura/visualization/colors.py +0 -451
- oscura/visualization/digital.py +0 -436
- oscura/visualization/eye.py +0 -571
- oscura/visualization/histogram.py +0 -281
- oscura/visualization/interactive.py +0 -1035
- oscura/visualization/jitter.py +0 -1042
- oscura/visualization/keyboard.py +0 -394
- oscura/visualization/layout.py +0 -400
- oscura/visualization/optimization.py +0 -1079
- oscura/visualization/palettes.py +0 -446
- oscura/visualization/power.py +0 -508
- oscura/visualization/power_extended.py +0 -955
- oscura/visualization/presets.py +0 -469
- oscura/visualization/protocols.py +0 -1246
- oscura/visualization/render.py +0 -223
- oscura/visualization/rendering.py +0 -444
- oscura/visualization/reverse_engineering.py +0 -838
- oscura/visualization/signal_integrity.py +0 -989
- oscura/visualization/specialized.py +0 -643
- oscura/visualization/spectral.py +0 -1226
- oscura/visualization/thumbnails.py +0 -340
- oscura/visualization/time_axis.py +0 -351
- oscura/visualization/waveform.py +0 -454
- {oscura-0.7.0.dist-info → oscura-0.10.0.dist-info}/WHEEL +0 -0
- {oscura-0.7.0.dist-info → oscura-0.10.0.dist-info}/entry_points.txt +0 -0
- {oscura-0.7.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.
|
|
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
|
|
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
|
[](https://github.com/oscura-re/oscura/actions/workflows/ci.yml)
|
|
154
133
|
[](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 (
|
|
168
|
-
3. Decode protocols (
|
|
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
|
|
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 (
|
|
200
|
-
3. Decoding protocols (
|
|
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
|
|
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
|
-
###
|
|
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** |
|
|
309
|
-
| **Statistical Protocol Auto-Detect** | Waveform analysis (timing, voltage, patterns) → protocol identification |
|
|
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
|
|
312
|
-
| **Automotive Security Analysis** | Stimulus-response correlation, hypothesis testing, UDS/OBD-II decoding | Research-focused
|
|
313
|
-
| **State Machine Extraction (Passive)** | RPNI algorithm for passive observation (vs
|
|
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
|
-
###
|
|
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
|
-
|
|
|
319
|
-
| -------------------------- |
|
|
320
|
-
| **Protocol Decoding** |
|
|
321
|
-
| **Side-Channel Analysis** |
|
|
322
|
-
| **Signal Processing** | IEEE-based measurements using scipy/numpy | [scipy.signal](https://docs.scipy.org/doc/scipy/reference/signal.html)
|
|
323
|
-
| **
|
|
324
|
-
| **
|
|
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
|
-
**
|
|
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/)
|
|
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:**
|
|
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
|
-
- **
|
|
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
|
-
- **
|
|
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
|
|
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
|
-
| **
|
|
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 +
|
|
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
|
-
- **
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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.
|
|
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.
|
|
619
|
+
version = {0.9.0}
|
|
640
620
|
}
|
|
641
621
|
```
|
|
642
622
|
|