oscura 0.4.0__py3-none-any.whl → 0.5.1__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 +1 -1
- oscura/automotive/__init__.py +1 -1
- oscura/export/wireshark/README.md +15 -15
- oscura/inference/active_learning/README.md +7 -7
- oscura/pipeline/composition.py +10 -2
- oscura/reporting/templates/index.md +13 -13
- oscura-0.5.1.dist-info/METADATA +583 -0
- {oscura-0.4.0.dist-info → oscura-0.5.1.dist-info}/RECORD +11 -11
- oscura-0.4.0.dist-info/METADATA +0 -407
- {oscura-0.4.0.dist-info → oscura-0.5.1.dist-info}/WHEEL +0 -0
- {oscura-0.4.0.dist-info → oscura-0.5.1.dist-info}/entry_points.txt +0 -0
- {oscura-0.4.0.dist-info → oscura-0.5.1.dist-info}/licenses/LICENSE +0 -0
oscura/__init__.py
CHANGED
oscura/automotive/__init__.py
CHANGED
|
@@ -64,21 +64,21 @@ Then reload Lua plugins in Wireshark: **Analyze > Reload Lua Plugins** (Ctrl+Shi
|
|
|
64
64
|
|
|
65
65
|
## Supported Field Types
|
|
66
66
|
|
|
67
|
-
|Oscura Type|Wireshark Type|Size|Notes|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
67
|
+
| Oscura Type | Wireshark Type | Size | Notes |
|
|
68
|
+
| ----------- | ------------------- | -------- | ------------------------- |
|
|
69
|
+
| `uint8` | `ProtoField.uint8` | 1 byte | Unsigned 8-bit integer |
|
|
70
|
+
| `uint16` | `ProtoField.uint16` | 2 bytes | Unsigned 16-bit integer |
|
|
71
|
+
| `uint32` | `ProtoField.uint32` | 4 bytes | Unsigned 32-bit integer |
|
|
72
|
+
| `uint64` | `ProtoField.uint64` | 8 bytes | Unsigned 64-bit integer |
|
|
73
|
+
| `int8` | `ProtoField.int8` | 1 byte | Signed 8-bit integer |
|
|
74
|
+
| `int16` | `ProtoField.int16` | 2 bytes | Signed 16-bit integer |
|
|
75
|
+
| `int32` | `ProtoField.int32` | 4 bytes | Signed 32-bit integer |
|
|
76
|
+
| `int64` | `ProtoField.int64` | 8 bytes | Signed 64-bit integer |
|
|
77
|
+
| `float32` | `ProtoField.float` | 4 bytes | IEEE 754 single precision |
|
|
78
|
+
| `float64` | `ProtoField.double` | 8 bytes | IEEE 754 double precision |
|
|
79
|
+
| `bool` | `ProtoField.bool` | 1 byte | Boolean value |
|
|
80
|
+
| `bytes` | `ProtoField.bytes` | Variable | Raw byte array |
|
|
81
|
+
| `string` | `ProtoField.string` | Variable | Text string |
|
|
82
82
|
|
|
83
83
|
## Display Bases
|
|
84
84
|
|
|
@@ -140,13 +140,13 @@ Information and Computation, 75(2), 87-106.
|
|
|
140
140
|
|
|
141
141
|
## Comparison with RPNI
|
|
142
142
|
|
|
143
|
-
|Feature|L\* (Active)|RPNI (Passive)|
|
|
144
|
-
|
|
145
|
-
|Learning type|Active (queries oracle)|Passive (fixed dataset)|
|
|
146
|
-
|Minimal DFA|Yes|No (may have extra states)|
|
|
147
|
-
|Negative examples|Not required|Optional|
|
|
148
|
-
|Live learning|Yes|No|
|
|
149
|
-
|Query complexity|O(|Q
|
|
143
|
+
| Feature | L\* (Active) | RPNI (Passive) |
|
|
144
|
+
| ----------------- | ----------------------- | -------------------------- | --- | --- | --- | --- | ----------- |
|
|
145
|
+
| Learning type | Active (queries oracle) | Passive (fixed dataset) |
|
|
146
|
+
| Minimal DFA | Yes | No (may have extra states) |
|
|
147
|
+
| Negative examples | Not required | Optional |
|
|
148
|
+
| Live learning | Yes | No |
|
|
149
|
+
| Query complexity | O( | Q | ² | Σ | ) | N/A | ## See Also |
|
|
150
150
|
|
|
151
151
|
- `oscura.inference.state_machine`: RPNI passive learning
|
|
152
152
|
- `examples/lstar_demo.py`: Complete usage examples
|
oscura/pipeline/composition.py
CHANGED
|
@@ -60,8 +60,16 @@ def compose(*funcs: TraceFunc) -> TraceFunc:
|
|
|
60
60
|
# Apply functions in reverse order (right to left)
|
|
61
61
|
return reduce(lambda val, func: func(val), reversed(funcs), x)
|
|
62
62
|
|
|
63
|
-
# Preserve function metadata
|
|
64
|
-
|
|
63
|
+
# Preserve function metadata (handle functools.partial which lacks __name__)
|
|
64
|
+
func_names = []
|
|
65
|
+
for f in funcs:
|
|
66
|
+
if hasattr(f, "__name__"):
|
|
67
|
+
func_names.append(f.__name__)
|
|
68
|
+
elif hasattr(f, "func"): # functools.partial
|
|
69
|
+
func_names.append(f.func.__name__)
|
|
70
|
+
else:
|
|
71
|
+
func_names.append(repr(f))
|
|
72
|
+
composed.__name__ = "compose(" + ", ".join(func_names) + ")"
|
|
65
73
|
composed.__doc__ = f"Composition of {len(funcs)} functions"
|
|
66
74
|
|
|
67
75
|
return composed
|
|
@@ -2,22 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
## Report Metadata
|
|
4
4
|
|
|
5
|
-
|Field|Value|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
5
|
+
| Field | Value |
|
|
6
|
+
| --------------------- | -------------- |
|
|
7
|
+
| **Input File** | {{input_name}} |
|
|
8
|
+
| **File Size** | {{input_size}} |
|
|
9
|
+
| **Input Type** | {{input_type}} |
|
|
10
|
+
| **Generated** | {{timestamp}} |
|
|
11
|
+
| **Analysis Duration** | {{duration}} |
|
|
12
12
|
|
|
13
13
|
## Analysis Summary
|
|
14
14
|
|
|
15
|
-
|Metric|Count|
|
|
16
|
-
|
|
17
|
-
|Total Analyses|{{total_analyses}}|
|
|
18
|
-
|Successful|{{successful}}|
|
|
19
|
-
|Failed|{{failed}}|
|
|
20
|
-
|Analysis Domains|{{domains_count}}|
|
|
15
|
+
| Metric | Count |
|
|
16
|
+
| ---------------- | ------------------ |
|
|
17
|
+
| Total Analyses | {{total_analyses}} |
|
|
18
|
+
| Successful | {{successful}} |
|
|
19
|
+
| Failed | {{failed}} |
|
|
20
|
+
| Analysis Domains | {{domains_count}} |
|
|
21
21
|
|
|
22
22
|
{{#if has_errors}}
|
|
23
23
|
|
|
@@ -0,0 +1,583 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: oscura
|
|
3
|
+
Version: 0.5.1
|
|
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: click<9.0.0,>=8.1.0
|
|
32
|
+
Requires-Dist: dpkt<2.0.0,>=1.9.0
|
|
33
|
+
Requires-Dist: jinja2<4.0.0,>=3.1
|
|
34
|
+
Requires-Dist: matplotlib<4.0.0,>=3.7.0
|
|
35
|
+
Requires-Dist: numpy<3.0.0,>=1.24.0
|
|
36
|
+
Requires-Dist: pandas<3.0.0,>=2.0.0
|
|
37
|
+
Requires-Dist: psutil<7.0.0,>=5.9.0
|
|
38
|
+
Requires-Dist: pyyaml<7.0.0,>=6.0
|
|
39
|
+
Requires-Dist: scipy<2.0.0,>=1.10.0
|
|
40
|
+
Requires-Dist: tm-data-types<1.0.0,>=0.3.0
|
|
41
|
+
Provides-Extra: all
|
|
42
|
+
Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'all'
|
|
43
|
+
Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'all'
|
|
44
|
+
Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'all'
|
|
45
|
+
Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'all'
|
|
46
|
+
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'all'
|
|
47
|
+
Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'all'
|
|
48
|
+
Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'all'
|
|
49
|
+
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'all'
|
|
50
|
+
Requires-Dist: nbconvert<8.0.0,>=7.0.0; extra == 'all'
|
|
51
|
+
Requires-Dist: networkx<4.0.0,>=3.0; extra == 'all'
|
|
52
|
+
Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'all'
|
|
53
|
+
Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'all'
|
|
54
|
+
Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'all'
|
|
55
|
+
Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'all'
|
|
56
|
+
Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'all'
|
|
57
|
+
Requires-Dist: pytest<10.0.0,>=8.0; extra == 'all'
|
|
58
|
+
Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'all'
|
|
59
|
+
Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'all'
|
|
60
|
+
Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'all'
|
|
61
|
+
Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'all'
|
|
62
|
+
Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'all'
|
|
63
|
+
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'all'
|
|
64
|
+
Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'all'
|
|
65
|
+
Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'all'
|
|
66
|
+
Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'all'
|
|
67
|
+
Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'all'
|
|
68
|
+
Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'all'
|
|
69
|
+
Provides-Extra: analysis
|
|
70
|
+
Requires-Dist: networkx<4.0.0,>=3.0; extra == 'analysis'
|
|
71
|
+
Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'analysis'
|
|
72
|
+
Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'analysis'
|
|
73
|
+
Provides-Extra: automotive
|
|
74
|
+
Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'automotive'
|
|
75
|
+
Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'automotive'
|
|
76
|
+
Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'automotive'
|
|
77
|
+
Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'automotive'
|
|
78
|
+
Provides-Extra: dev
|
|
79
|
+
Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'dev'
|
|
80
|
+
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'dev'
|
|
81
|
+
Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'dev'
|
|
82
|
+
Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'dev'
|
|
83
|
+
Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'dev'
|
|
84
|
+
Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'dev'
|
|
85
|
+
Requires-Dist: pytest<10.0.0,>=8.0; extra == 'dev'
|
|
86
|
+
Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'dev'
|
|
87
|
+
Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'dev'
|
|
88
|
+
Provides-Extra: fuzzy
|
|
89
|
+
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'fuzzy'
|
|
90
|
+
Provides-Extra: hardware
|
|
91
|
+
Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'hardware'
|
|
92
|
+
Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'hardware'
|
|
93
|
+
Provides-Extra: hdf5
|
|
94
|
+
Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'hdf5'
|
|
95
|
+
Provides-Extra: jupyter
|
|
96
|
+
Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'jupyter'
|
|
97
|
+
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'jupyter'
|
|
98
|
+
Requires-Dist: nbconvert<8.0.0,>=7.0.0; extra == 'jupyter'
|
|
99
|
+
Provides-Extra: oscilloscopes
|
|
100
|
+
Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'oscilloscopes'
|
|
101
|
+
Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'oscilloscopes'
|
|
102
|
+
Provides-Extra: reporting
|
|
103
|
+
Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'reporting'
|
|
104
|
+
Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'reporting'
|
|
105
|
+
Provides-Extra: routing
|
|
106
|
+
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0; extra == 'routing'
|
|
107
|
+
Description-Content-Type: text/markdown
|
|
108
|
+
|
|
109
|
+
# Oscura
|
|
110
|
+
|
|
111
|
+
**Hardware Reverse Engineering Framework**
|
|
112
|
+
|
|
113
|
+
Extract complete system understanding from any signal source—oscilloscopes, logic analyzers, network captures, side-channel traces—through:
|
|
114
|
+
|
|
115
|
+
- Unknown protocol reverse engineering (physical layer detection, message format inference, field boundaries, CRC recovery)
|
|
116
|
+
- State machine extraction and protocol behavior analysis
|
|
117
|
+
- Side-channel cryptanalysis (power analysis, timing attacks, EM leakage)
|
|
118
|
+
- IEEE-compliant measurements and signal characterization
|
|
119
|
+
|
|
120
|
+
[](https://github.com/oscura-re/oscura/actions/workflows/ci.yml)
|
|
121
|
+
[](https://github.com/oscura-re/oscura/actions/workflows/code-quality.yml)
|
|
122
|
+
[](https://codecov.io/gh/oscura-re/oscura)
|
|
123
|
+
[](https://pypi.org/project/oscura/)
|
|
124
|
+
[](https://www.python.org/downloads/)
|
|
125
|
+
[](https://opensource.org/licenses/MIT)
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Vision
|
|
130
|
+
|
|
131
|
+
Hardware systems are obscured through proprietary protocols, undocumented interfaces, cryptographic obfuscation, and black-box designs. Whether imposed by vendors, governments, or time itself—**Oscura illuminates what others obscure.**
|
|
132
|
+
|
|
133
|
+
**Built For:**
|
|
134
|
+
|
|
135
|
+
- **Security researchers** analyzing embedded systems, IoT vulnerabilities, side-channel leakage
|
|
136
|
+
- **Hardware engineers** validating signal integrity, power supply design, EMC compliance
|
|
137
|
+
- **Protocol developers** testing implementations against IEEE standards
|
|
138
|
+
- **Automotive engineers** analyzing CAN/LIN/FlexRay for diagnostics and security research
|
|
139
|
+
- **Right-to-repair advocates** documenting and replicating undocumented interfaces
|
|
140
|
+
- **Academic researchers** studying signal processing, cryptanalysis, and hardware security
|
|
141
|
+
- **Vintage computing enthusiasts** preserving and analyzing retro hardware (1960s–present)
|
|
142
|
+
- **Defense and intelligence analysts** for forensics and threat assessment
|
|
143
|
+
|
|
144
|
+
**What We Enable:**
|
|
145
|
+
|
|
146
|
+
- **Protocol Reverse Engineering**: CRC recovery, message format inference, state machine extraction for security research, protocol development, right-to-repair documentation
|
|
147
|
+
- **Signal Intelligence**: Auto-classify unknown signals (digital/analog, periodicity, SNR) to guide reverse engineering strategy
|
|
148
|
+
- **Cryptographic Analysis**: Side-channel attacks (DPA/CPA, timing, mutual information) for vulnerability assessment and implementation validation
|
|
149
|
+
- **Automotive Reverse Engineering**: CAN/LIN/FlexRay analysis (differential, stimulus-response, hypothesis-driven discovery) for aftermarket, diagnostics, security research (no vendor lock-in)
|
|
150
|
+
- **Debug Interface Analysis**: JTAG/SWD/UART for firmware extraction, bootloader analysis, and development/recovery workflows
|
|
151
|
+
- **Binary Format Recovery**: 100+ magic bytes, structure alignment, auto-parser generation for right-to-repair and vulnerability research
|
|
152
|
+
- **Obsolete System Replication**: Logic family auto-detection (ECL/RTL/DTL/TTL, 1960s-present), IC timing validation, modern replacements for vintage hardware preservation
|
|
153
|
+
- **Evidence-Based Discovery**: Hypothesis tracking, statistical validation, confidence scoring, full audit trails for reproducible reverse engineering
|
|
154
|
+
- **Attack Surface Mapping**: State machine extraction, stimulus-response correlation, differential analysis for vulnerability discovery and exploitation
|
|
155
|
+
- **Intelligence Sharing**: Wireshark dissectors (validated Lua), DBC files, auto-generated parsers, multi-format reports (PDF/HTML/PPTX) for collaboration
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Installation
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
# Production use
|
|
163
|
+
pip install oscura
|
|
164
|
+
|
|
165
|
+
# Development (recommended - includes quality tools)
|
|
166
|
+
git clone https://github.com/oscura-re/oscura.git
|
|
167
|
+
cd oscura
|
|
168
|
+
./scripts/setup.sh
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
**Requirements:** Python 3.12+ | [See pyproject.toml for dependencies](pyproject.toml)
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Quick Start
|
|
176
|
+
|
|
177
|
+
### Decode Unknown Protocol in 5 Lines
|
|
178
|
+
|
|
179
|
+
```python
|
|
180
|
+
import oscura as osc
|
|
181
|
+
|
|
182
|
+
# Load oscilloscope capture
|
|
183
|
+
trace = osc.load("mystery_device.wfm")
|
|
184
|
+
|
|
185
|
+
# Auto-detect and decode
|
|
186
|
+
decoder = osc.auto_detect_protocol(trace)
|
|
187
|
+
messages = decoder.decode(trace)
|
|
188
|
+
print(f"Decoded {len(messages)} {decoder.name} messages")
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Side-Channel Attack on AES
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
from oscura.loaders import load_chipwhisperer
|
|
195
|
+
from oscura.analyzers.side_channel import CPAAnalyzer
|
|
196
|
+
|
|
197
|
+
# Load power traces from ChipWhisperer capture
|
|
198
|
+
traces = load_chipwhisperer("aes_traces.npy")
|
|
199
|
+
|
|
200
|
+
# Correlation Power Analysis
|
|
201
|
+
cpa = CPAAnalyzer(leakage_model="hamming_weight", target_byte=0)
|
|
202
|
+
result = cpa.analyze(traces.traces, traces.plaintexts)
|
|
203
|
+
|
|
204
|
+
print(f"Key byte: 0x{result.key_guess:02X}")
|
|
205
|
+
print(f"Correlation: {result.max_correlation:.4f}")
|
|
206
|
+
print(f"Confidence: {'HIGH' if result.max_correlation > 0.8 else 'LOW'}")
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Black-Box Protocol Reverse Engineering
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
from oscura.sessions import BlackBoxSession
|
|
213
|
+
|
|
214
|
+
# Create analysis session
|
|
215
|
+
session = BlackBoxSession(name="IoT Device RE")
|
|
216
|
+
|
|
217
|
+
# Differential analysis: compare device states
|
|
218
|
+
session.add_recording("idle", "idle.bin")
|
|
219
|
+
session.add_recording("button_press", "button.bin")
|
|
220
|
+
diff = session.compare("idle", "button_press")
|
|
221
|
+
|
|
222
|
+
# Automatic field detection
|
|
223
|
+
spec = session.generate_protocol_spec()
|
|
224
|
+
print(f"Found {len(spec['fields'])} protocol fields")
|
|
225
|
+
|
|
226
|
+
# Export Wireshark dissector
|
|
227
|
+
session.export_results("dissector", "protocol.lua")
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Automotive CAN Bus Analysis
|
|
231
|
+
|
|
232
|
+
```python
|
|
233
|
+
from oscura.automotive.can import CANSession
|
|
234
|
+
|
|
235
|
+
session = CANSession(name="Vehicle RE")
|
|
236
|
+
session.add_recording("idle", "idle.blf")
|
|
237
|
+
session.add_recording("accelerate", "accel.blf")
|
|
238
|
+
|
|
239
|
+
# Identify changed CAN IDs
|
|
240
|
+
diff = session.compare("idle", "accelerate")
|
|
241
|
+
print(f"Changed IDs: {diff.details['changed_ids']}")
|
|
242
|
+
|
|
243
|
+
# Export DBC file for further analysis
|
|
244
|
+
session.export_dbc("vehicle.dbc")
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
**More examples:** [20 demo categories](demonstrations/) with 112 comprehensive demonstrations covering every capability
|
|
248
|
+
|
|
249
|
+
---
|
|
250
|
+
|
|
251
|
+
## Core Capabilities
|
|
252
|
+
|
|
253
|
+
### Protocol Reverse Engineering & Development
|
|
254
|
+
|
|
255
|
+
| Capability | Use Cases (Development / Reverse Engineering) | Location |
|
|
256
|
+
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
|
257
|
+
| **CRC Recovery & Validation** | Checksum development validation / XOR differential technique recovers polynomial, init, xor_out, reflection flags from 4+ message-CRC pairs. Identifies 12+ standard algorithms or brute-forces custom CRCs for proprietary checksum breaking | [`inference/`](src/oscura/inference/) |
|
|
258
|
+
| **Message Format Inference** | Protocol documentation / IPART-style ensemble analysis (entropy, alignment, variance, distribution, n-grams) with confidence-scored field boundaries and automatic checksum/counter/timestamp detection | [`inference/`](src/oscura/inference/) |
|
|
259
|
+
| **State Machine Extraction** | Protocol testing with L\* active learning (systematic querying) and RPNI passive learning / Map authentication flows, command sequences, and hidden states for attack surface analysis with evidence-based hypothesis testing | [`inference/`](src/oscura/inference/) |
|
|
260
|
+
| **Binary Format Recovery** | Firmware documentation / Magic byte detection (100+ formats including executables, images, archives), structure alignment inference (1/2/4/8/16-byte), auto-generate Python parsers and YAML specs for proprietary file format analysis | [`inference/`](src/oscura/inference/) |
|
|
261
|
+
| **Signal Intelligence** | Automatic analysis guidance / Auto-classify digital vs analog signals, detect periodicity (autocorrelation + FFT), estimate SNR, recommend suitable measurement techniques for unknown signal sources | [`inference/`](src/oscura/inference/) |
|
|
262
|
+
| **Pattern Discovery** | Sync marker identification / Find repeating signatures, frame boundaries, magic bytes in raw captures (malware C2, IoT traffic, proprietary protocols) | [`analyzers/patterns/`](src/oscura/analyzers/patterns/) |
|
|
263
|
+
| **Physical Layer Detection** | PCB debugging / Auto-detect baud rates, clock frequencies, logic levels for unknown test points and debug interfaces on embedded devices | [`inference/`](src/oscura/inference/) |
|
|
264
|
+
| **Stream Reassembly** | Protocol validation / TCP/UDP stream reconstruction, framing detection, and packet boundary recovery from fragmented captures | [`inference/`](src/oscura/inference/) |
|
|
265
|
+
| **BlackBox Workflow** | End-to-end RE pipeline / Differential analysis → field hypothesis generation → state machine inference → multi-format export (Wireshark dissectors, DBC, parsers) with full evidence tracking and confidence scoring | [`sessions/`](src/oscura/sessions/) |
|
|
266
|
+
|
|
267
|
+
### Cryptographic & Security Analysis
|
|
268
|
+
|
|
269
|
+
| Capability | Use Cases (Validation / Reverse Engineering) | Location |
|
|
270
|
+
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
|
271
|
+
| **Power Analysis (DPA/CPA)** | Crypto implementation validation / Differential and Correlation Power Analysis for key extraction from smart cards, TPMs, secure enclaves with configurable leakage models (Hamming weight/distance) | [`analyzers/side_channel/`](src/oscura/analyzers/side_channel/) |
|
|
272
|
+
| **Timing Attack Analysis** | Constant-time validation / Statistical timing analysis with mutual information calculation (quantify leakage in bits), effect size measurement (Cohen's d), and outlier detection for vulnerability assessment | [`analyzers/side_channel/`](src/oscura/analyzers/side_channel/) |
|
|
273
|
+
| **ChipWhisperer Integration** | Educational side-channel labs / Direct integration for power/EM trace collection and analysis with standardized formats (.npy, .trs) | [`loaders/`](src/oscura/loaders/) |
|
|
274
|
+
| **Jitter Analysis (IEEE 2414)** | Clock quality validation / TIE, period jitter, RJ/DJ decomposition for detecting clock glitching, fault injection attacks, and timing manipulation | [`analyzers/jitter/`](src/oscura/analyzers/jitter/) |
|
|
275
|
+
| **Power Supply Analysis** | DC-DC converter design / Voltage rail characterization for identifying fault injection targets (brownout thresholds, transient response, ripple analysis) | [`analyzers/power/`](src/oscura/analyzers/power/) |
|
|
276
|
+
|
|
277
|
+
### Protocol Decoding
|
|
278
|
+
|
|
279
|
+
| Category | Use Cases (Development / Reverse Engineering) | Protocols |
|
|
280
|
+
| -------------------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
|
|
281
|
+
| **Serial** | Sensor development, device debugging / Debug console access, flash extraction | UART, SPI, I2C, 1-Wire, I2S, Manchester, HDLC |
|
|
282
|
+
| **Automotive** | Diagnostics, aftermarket dev / ECU security analysis, CAN injection testing | CAN, CAN-FD, LIN, FlexRay, J1939 |
|
|
283
|
+
| **Debug Interfaces** | Firmware development, recovery / Firmware extraction, bootloader analysis | JTAG (TAP state), SWD, USB |
|
|
284
|
+
| **Parallel Bus** | Vintage hardware restoration, instrument control / Industrial system security | IEEE-488 (GPIB), Centronics, ISA |
|
|
285
|
+
|
|
286
|
+
**Location:** [`analyzers/protocols/`](src/oscura/analyzers/protocols/) | [`automotive/`](src/oscura/automotive/)
|
|
287
|
+
|
|
288
|
+
**Auto-detection:** Baud rate recovery, clock extraction, logic level adaptation, confidence scoring
|
|
289
|
+
|
|
290
|
+
### File Format Support
|
|
291
|
+
|
|
292
|
+
| Category | Formats | Location |
|
|
293
|
+
| ------------------- | --------------------------------------------- | ------------------------------------------------------- |
|
|
294
|
+
| **Oscilloscopes** | Tektronix (.wfm), Rigol (.wfm), LeCroy (.trc) | [`loaders/`](src/oscura/loaders/) |
|
|
295
|
+
| **Logic Analyzers** | Sigrok (.sr), VCD (Value Change Dump) | [`loaders/`](src/oscura/loaders/) |
|
|
296
|
+
| **Network** | PCAP, PCAPNG (Wireshark-compatible) | [`loaders/`](src/oscura/loaders/) |
|
|
297
|
+
| **Automotive** | Vector BLF/ASC, ASAM MDF/MF4, DBC, CSV | [`automotive/loaders/`](src/oscura/automotive/loaders/) |
|
|
298
|
+
| **Scientific** | TDMS (LabVIEW), HDF5, NumPy (.npz), WAV, CSV | [`loaders/`](src/oscura/loaders/) |
|
|
299
|
+
| **RF/Network** | Touchstone S-parameters (.s1p-.s8p) | [`loaders/`](src/oscura/loaders/) |
|
|
300
|
+
| **Side-Channel** | ChipWhisperer (.npy, .trs) | [`loaders/`](src/oscura/loaders/) |
|
|
301
|
+
|
|
302
|
+
**Memory-efficient:** Lazy loading, memory-mapped files, chunked processing for TB-scale datasets
|
|
303
|
+
|
|
304
|
+
### Automotive Engineering & Security
|
|
305
|
+
|
|
306
|
+
| Capability | Use Cases (Development / Reverse Engineering) | Location |
|
|
307
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
308
|
+
| **Evidence-Based Discovery** | Protocol documentation / Hypothesis-driven CAN message field detection with statistical validation, confidence scoring, and evidence tracking for reproducible reverse engineering | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
309
|
+
| **Stimulus-Response Mapping** | Input correlation analysis / Correlate user actions (button press, sensor input, vehicle events) to CAN message changes for attack surface identification and control message discovery | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
310
|
+
| **CAN State Machine Extraction** | ECU behavior modeling / Extract protocol state machines from CAN traffic for security analysis and vulnerability discovery | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
311
|
+
| **Pattern Recognition** | Signal validation / Auto-detect counters (rolling, wraparound), checksums (XOR, SUM, CRC), sensor encoding patterns in CAN messages | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
312
|
+
| **Differential Analysis** | Signal validation / Compare CAN captures (idle vs accelerate, locked vs unlocked) to identify control messages and security-critical signals | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
313
|
+
| **Discovery Persistence** | Collaboration / Save/load RE progress in .tkcan format with hypothesis tracking for team collaboration and long-term projects | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
314
|
+
| **DBC Export** | Protocol documentation / Generate Vector DBC files from discoveries for integration with industry tools (CANalyzer, Wireshark, Vehicle Spy) | [`automotive/dbc/`](src/oscura/automotive/dbc/) |
|
|
315
|
+
| **J1939 Protocol** | Heavy vehicle diagnostics / Complete J1939 decoder for truck, construction, agricultural equipment security research (PGN, SPN, suspect/FMI decoding) | [`automotive/j1939/`](src/oscura/automotive/j1939/) |
|
|
316
|
+
| **OBD-II Diagnostics** | Diagnostics development / Complete OBD-II Mode 01-09 support for PIDs, freeze frames, DTCs, VIN extraction | [`automotive/obd/`](src/oscura/automotive/obd/) |
|
|
317
|
+
| **UDS Protocol** | Security testing / Complete Unified Diagnostic Services decoder for ECU programming, security access, routine control, and diagnostic command fuzzing | [`automotive/uds/`](src/oscura/automotive/uds/) |
|
|
318
|
+
|
|
319
|
+
### IEEE-Compliant Measurements
|
|
320
|
+
|
|
321
|
+
| Standard | Measurements | Hardware Hacking Relevance |
|
|
322
|
+
| ---------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
|
|
323
|
+
| **IEEE 181** (Pulse) | Rise/fall time, pulse width, overshoot, duty cycle | Signal integrity validation for protocol analysis |
|
|
324
|
+
| **IEEE 1241** (ADC) | SNR, SINAD, THD, SFDR, ENOB | ADC characterization for side-channel analysis |
|
|
325
|
+
| **IEEE 1459** (Power) | Active/reactive power, harmonics, power factor | Power supply analysis for fault injection targeting |
|
|
326
|
+
| **IEEE 2414** (Jitter) | TIE, period jitter, RJ/DJ decomposition, BER | Clock glitching attack detection, fault injection analysis |
|
|
327
|
+
|
|
328
|
+
**Location:** [`analyzers/waveform/`](src/oscura/analyzers/waveform/) | [`analyzers/spectral/`](src/oscura/analyzers/spectral/) | [`analyzers/power/`](src/oscura/analyzers/power/) | [`analyzers/jitter/`](src/oscura/analyzers/jitter/)
|
|
329
|
+
|
|
330
|
+
### Hardware Acquisition
|
|
331
|
+
|
|
332
|
+
| Source | Description | Status | Location |
|
|
333
|
+
| ---------------- | ----------------------------------------------- | ----------- | ----------------------------------------- |
|
|
334
|
+
| **File-Based** | All supported file formats | ✅ Complete | [`loaders/`](src/oscura/loaders/) |
|
|
335
|
+
| **SocketCAN** | Linux CAN interfaces (vcan, physical CAN) | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
|
|
336
|
+
| **Saleae Logic** | Direct Logic analyzer streaming | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
|
|
337
|
+
| **PyVISA** | Oscilloscopes (Tektronix, Keysight, Rigol, R&S) | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
|
|
338
|
+
| **Synthetic** | Programmable signal generation for testing | ✅ Complete | [`acquisition/`](src/oscura/acquisition/) |
|
|
339
|
+
|
|
340
|
+
### Export & Intelligence Sharing
|
|
341
|
+
|
|
342
|
+
| Format | Hardware Hacking Use Case | Location |
|
|
343
|
+
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
344
|
+
| **Wireshark Dissectors** | Auto-generate validated Lua dissectors with ProtoField type mapping, variable-length field support, TCP/UDP port registration, and checksum validation for live traffic analysis and protocol documentation | [`export/wireshark/`](src/oscura/export/wireshark/) |
|
|
345
|
+
| **Binary Parsers** | Auto-generate Python parsers and YAML specifications from inferred binary formats for firmware analysis, file format documentation, and automated data extraction | [`inference/`](src/oscura/inference/) |
|
|
346
|
+
| **DBC Files** | Export CAN discoveries to Vector DBC format for integration with industry tools (CANalyzer, Vehicle Spy, Wireshark CAN plugins) | [`automotive/dbc/`](src/oscura/automotive/dbc/) |
|
|
347
|
+
| **Multi-Format Reports** | Generate comprehensive evidence reports in PDF, HTML, PPTX, and Markdown with charts, tables, hypothesis tracking, confidence scoring, and full audit trails for reproducible research | [`reporting/`](src/oscura/reporting/) |
|
|
348
|
+
| **Batch Processing** | Generate comparison reports for entire capture directories with statistical analysis, correlation matrices, and trend visualization | [`reporting/`](src/oscura/reporting/) |
|
|
349
|
+
| **Discovery Archives** | Save/load reverse engineering progress in structured .tkcan format (YAML-based) with hypothesis tracking, field candidates, and validation status for team collaboration | [`automotive/can/`](src/oscura/automotive/can/) |
|
|
350
|
+
| **WaveDrom Diagrams** | Generate publication-quality timing diagrams from protocol specifications for documentation, academic papers, and technical communication | [`export/`](src/oscura/export/) |
|
|
351
|
+
| **Vintage Logic Reports** | Specialized reports for retro computing with IC identification, timing validation, modern replacement recommendations, and restoration guidance | [`reporting/`](src/oscura/reporting/) |
|
|
352
|
+
|
|
353
|
+
### Obsolete System Characterization & Replication
|
|
354
|
+
|
|
355
|
+
**For vintage computing restoration, industrial equipment repair, and hardware preservation (1960s-present)**
|
|
356
|
+
|
|
357
|
+
| Feature | Replication Use Case | Location |
|
|
358
|
+
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
359
|
+
| **Logic Family Auto-Detection** | Identify unknown vintage chips by voltage levels: ECL (-1.75V), RTL (3.6V), DTL (5V), PMOS (-12V), NMOS (+12V), TTL variants, HC-CMOS, 4000-series for functional cloning without datasheets | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
|
|
360
|
+
| **IC Timing Database** | Validate against 74xx series, 4000 series specifications (propagation delay, setup/hold times) for functional replication and modern FPGA/CPLD implementations | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
|
|
361
|
+
| **IC Identification** | Match measured timing characteristics to specific ICs (7400, 74LS138, 74HC595, etc.) for part identification when markings are illegible or missing | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
|
|
362
|
+
| **Modern Replacement Mapping** | Recommend current-production substitutes (74HC → 74LS, CD4000 → 74HC) for restoration projects when original parts are unavailable | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
|
|
363
|
+
| **Open-Collector Detection** | Identify open-collector/open-drain outputs requiring pull-up resistors for accurate replication | [`analyzers/digital/`](src/oscura/analyzers/digital/) |
|
|
364
|
+
| **Protocol Preservation** | Extract and document undocumented legacy protocols (parallel buses, proprietary serial) for data recovery and system emulation | [`inference/`](src/oscura/inference/) |
|
|
365
|
+
|
|
366
|
+
---
|
|
367
|
+
|
|
368
|
+
## Learn By Example
|
|
369
|
+
|
|
370
|
+
**Demos are the documentation.** Each category includes working code with validation and comprehensive explanations.
|
|
371
|
+
|
|
372
|
+
### Getting Started (Beginner)
|
|
373
|
+
|
|
374
|
+
| Demo | What You'll Learn |
|
|
375
|
+
| --------------------------------------------------- | ------------------------------------------------- |
|
|
376
|
+
| [01_waveform_analysis](demos/01_waveform_analysis/) | Load Tektronix/Rigol captures, basic measurements |
|
|
377
|
+
| [02_file_format_io](demos/02_file_format_io/) | CSV, HDF5, NumPy, custom binary formats |
|
|
378
|
+
| [04_serial_protocols](demos/04_serial_protocols/) | UART, SPI, I2C decoding with auto-detection |
|
|
379
|
+
| [05_protocol_decoding](demos/05_protocol_decoding/) | Protocol auto-detection pipeline |
|
|
380
|
+
|
|
381
|
+
### Reverse Engineering (Intermediate)
|
|
382
|
+
|
|
383
|
+
| Demo | What You'll Learn |
|
|
384
|
+
| --------------------------------------------------------------------- | ----------------------------------------------------- |
|
|
385
|
+
| [07_protocol_inference](demos/07_protocol_inference/) | State machine learning, CRC recovery, field detection |
|
|
386
|
+
| [08_automotive_protocols](demos/08_automotive_protocols/) | CAN, CAN-FD, LIN, FlexRay analysis |
|
|
387
|
+
| [17_signal_reverse_engineering](demos/17_signal_reverse_engineering/) | Complete unknown signal analysis workflow |
|
|
388
|
+
| [18_advanced_inference](demos/18_advanced_inference/) | Bayesian inference, binary format DSL |
|
|
389
|
+
|
|
390
|
+
### Security & Compliance (Advanced)
|
|
391
|
+
|
|
392
|
+
| Demo | What You'll Learn |
|
|
393
|
+
| ------------------------------------------------------- | -------------------------------------------------- |
|
|
394
|
+
| [12_spectral_compliance](demos/12_spectral_compliance/) | FFT, THD, SNR, SINAD (IEEE 1241) |
|
|
395
|
+
| [13_jitter_analysis](demos/13_jitter_analysis/) | TIE, RJ/DJ decomposition, eye diagrams (IEEE 2414) |
|
|
396
|
+
| [14_power_analysis](demos/14_power_analysis/) | DC-DC converter analysis, efficiency (IEEE 1459) |
|
|
397
|
+
| [15_signal_integrity](demos/15_signal_integrity/) | TDR, S-parameters, setup/hold timing |
|
|
398
|
+
| [16_emc_compliance](demos/16_emc_compliance/) | CISPR, FCC, MIL-STD electromagnetic compatibility |
|
|
399
|
+
|
|
400
|
+
### Complete Workflows (Expert)
|
|
401
|
+
|
|
402
|
+
| Demo | What You'll Learn |
|
|
403
|
+
| ----------------------------------------------------- | ---------------------------------------- |
|
|
404
|
+
| [19_complete_workflows](demos/19_complete_workflows/) | End-to-end reverse engineering pipelines |
|
|
405
|
+
|
|
406
|
+
### Run Your First Demo
|
|
407
|
+
|
|
408
|
+
```bash
|
|
409
|
+
# Generate test data
|
|
410
|
+
python demos/generate_all_demo_data.py
|
|
411
|
+
|
|
412
|
+
# Run waveform analysis demo
|
|
413
|
+
python demos/01_waveform_analysis/comprehensive_wfm_analysis.py
|
|
414
|
+
|
|
415
|
+
# Run protocol inference demo
|
|
416
|
+
python demos/07_protocol_inference/01_state_machine_inference.py
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
**Browse all demos:** [demos/](demos/) | [Demo index with descriptions](demos/README.md)
|
|
420
|
+
|
|
421
|
+
---
|
|
422
|
+
|
|
423
|
+
## Command Line Interface
|
|
424
|
+
|
|
425
|
+
```bash
|
|
426
|
+
# Signal characterization
|
|
427
|
+
oscura characterize capture.wfm
|
|
428
|
+
|
|
429
|
+
# Protocol decoding
|
|
430
|
+
oscura decode uart_capture.wfm --protocol uart --baud 115200
|
|
431
|
+
|
|
432
|
+
# Batch processing
|
|
433
|
+
oscura batch '*.wfm' --analysis characterize
|
|
434
|
+
|
|
435
|
+
# Differential analysis
|
|
436
|
+
oscura compare baseline.wfm modified.wfm
|
|
437
|
+
|
|
438
|
+
# Interactive REPL
|
|
439
|
+
oscura shell
|
|
440
|
+
|
|
441
|
+
# Generate synthetic test signals
|
|
442
|
+
oscura generate --protocol spi --frequency 1MHz --output test.bin
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
**Full reference:** [docs/cli.md](docs/cli.md)
|
|
446
|
+
|
|
447
|
+
---
|
|
448
|
+
|
|
449
|
+
## Quality & Testing
|
|
450
|
+
|
|
451
|
+
Comprehensive test suite with property-based testing, stress tests, and CI enforcement. Current metrics visible in [CI dashboard](https://github.com/oscura-re/oscura/actions) and [code coverage reports](https://codecov.io/gh/oscura-re/oscura).
|
|
452
|
+
|
|
453
|
+
```bash
|
|
454
|
+
# Run test suite (uses pytest in parallel with coverage)
|
|
455
|
+
./scripts/test.sh
|
|
456
|
+
|
|
457
|
+
# Quality checks (linting, type checking, formatting)
|
|
458
|
+
./scripts/check.sh
|
|
459
|
+
|
|
460
|
+
# Auto-fix issues
|
|
461
|
+
./scripts/fix.sh
|
|
462
|
+
|
|
463
|
+
# Full CI validation (pre-push)
|
|
464
|
+
./scripts/pre-push.sh
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
**Quality infrastructure:**
|
|
468
|
+
|
|
469
|
+
- Pre-commit hooks (format, lint, type check)
|
|
470
|
+
- Merge queue CI (prevents untested commits)
|
|
471
|
+
- Property-based testing (Hypothesis)
|
|
472
|
+
- Nightly stress tests
|
|
473
|
+
- Security scanning (Bandit, Safety)
|
|
474
|
+
|
|
475
|
+
**See:** [Testing architecture](docs/testing/) | [Quality gates](.github/workflows/)
|
|
476
|
+
|
|
477
|
+
---
|
|
478
|
+
|
|
479
|
+
## Contributing
|
|
480
|
+
|
|
481
|
+
**We need your expertise.** Whether you're adding a new protocol decoder, improving inference algorithms, or documenting use cases - every contribution illuminates more hardware.
|
|
482
|
+
|
|
483
|
+
### Quick Start
|
|
484
|
+
|
|
485
|
+
```bash
|
|
486
|
+
git clone https://github.com/oscura-re/oscura.git
|
|
487
|
+
cd oscura
|
|
488
|
+
./scripts/setup.sh # Complete setup with hooks
|
|
489
|
+
./scripts/test.sh # Verify environment
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
### What We Need
|
|
493
|
+
|
|
494
|
+
- **Protocol Decoders:** Proprietary protocols you've reverse engineered
|
|
495
|
+
- **File Format Loaders:** Oscilloscope/LA formats we don't support yet
|
|
496
|
+
- **Inference Algorithms:** Better state machine learning, field detection
|
|
497
|
+
- **Hardware Sources:** Integration with more DAQ systems
|
|
498
|
+
- **Documentation:** Real-world case studies and tutorials
|
|
499
|
+
- **Validation:** Test our tools on your captures
|
|
500
|
+
|
|
501
|
+
**Full guide:** [CONTRIBUTING.md](CONTRIBUTING.md) | [Architecture docs](docs/architecture/)
|
|
502
|
+
|
|
503
|
+
---
|
|
504
|
+
|
|
505
|
+
## Documentation
|
|
506
|
+
|
|
507
|
+
### User Guides
|
|
508
|
+
|
|
509
|
+
- [Quick Start Guide](docs/guides/quick-start.md) - Installation and first steps
|
|
510
|
+
- [Black-Box Protocol Analysis](docs/guides/blackbox-analysis.md) - Unknown protocol RE
|
|
511
|
+
- [Side-Channel Analysis](docs/guides/side-channel-analysis.md) - DPA/CPA/timing attacks
|
|
512
|
+
- [Hardware Acquisition](docs/guides/hardware-acquisition.md) - Direct instrument control
|
|
513
|
+
- [Complete Workflows](docs/guides/workflows.md) - End-to-end analysis pipelines
|
|
514
|
+
|
|
515
|
+
### API Reference
|
|
516
|
+
|
|
517
|
+
- [API Documentation](docs/api/) - Complete API reference
|
|
518
|
+
- [Session Management](docs/api/session-management.md) - Interactive analysis sessions
|
|
519
|
+
- [CLI Reference](docs/cli.md) - Command-line interface
|
|
520
|
+
|
|
521
|
+
### Development
|
|
522
|
+
|
|
523
|
+
- [Architecture](docs/architecture/) - Design principles and patterns
|
|
524
|
+
- [Testing Guide](docs/testing/) - Test suite architecture
|
|
525
|
+
- [CHANGELOG](CHANGELOG.md) - Version history and migration guides
|
|
526
|
+
|
|
527
|
+
---
|
|
528
|
+
|
|
529
|
+
## Project Status
|
|
530
|
+
|
|
531
|
+
**Latest Release:** [See current version and release notes](https://github.com/oscura-re/oscura/releases/latest)
|
|
532
|
+
|
|
533
|
+
**Active Development Areas:**
|
|
534
|
+
|
|
535
|
+
- Side-channel analysis and cryptographic attack frameworks
|
|
536
|
+
- Vintage computing support (retro logic families, IC identification)
|
|
537
|
+
- Industrial and automotive protocol decoders
|
|
538
|
+
- Hardware acquisition from diverse sources
|
|
539
|
+
- Inference and machine learning for unknown protocols
|
|
540
|
+
|
|
541
|
+
**See:** [Full changelog](CHANGELOG.md) | [Roadmap discussions](https://github.com/oscura-re/oscura/discussions)
|
|
542
|
+
|
|
543
|
+
---
|
|
544
|
+
|
|
545
|
+
## Support
|
|
546
|
+
|
|
547
|
+
- **Issues:** [GitHub Issues](https://github.com/oscura-re/oscura/issues) - Bug reports and feature requests
|
|
548
|
+
- **Discussions:** [GitHub Discussions](https://github.com/oscura-re/oscura/discussions) - Questions and community
|
|
549
|
+
- **Security:** [SECURITY.md](SECURITY.md) - Responsible disclosure
|
|
550
|
+
|
|
551
|
+
---
|
|
552
|
+
|
|
553
|
+
## Citation
|
|
554
|
+
|
|
555
|
+
If Oscura helps your research, please cite:
|
|
556
|
+
|
|
557
|
+
```bibtex
|
|
558
|
+
@software{oscura2026,
|
|
559
|
+
title = {Oscura: Hardware Reverse Engineering Framework},
|
|
560
|
+
author = {Oscura Contributors},
|
|
561
|
+
year = {2026},
|
|
562
|
+
url = {https://github.com/oscura-re/oscura},
|
|
563
|
+
version = {0.5.0}
|
|
564
|
+
}
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
**Machine-readable:** [CITATION.cff](CITATION.cff)
|
|
568
|
+
|
|
569
|
+
---
|
|
570
|
+
|
|
571
|
+
## License
|
|
572
|
+
|
|
573
|
+
MIT License - [LICENSE](LICENSE)
|
|
574
|
+
|
|
575
|
+
**Built with:** Python, NumPy, SciPy, Hypothesis
|
|
576
|
+
|
|
577
|
+
**Standards:** IEEE 181/1241/1459/2414, ISO/IEC, CISPR
|
|
578
|
+
|
|
579
|
+
**Supported by:** Security researchers, right-to-repair advocates, open source community
|
|
580
|
+
|
|
581
|
+
---
|
|
582
|
+
|
|
583
|
+
**Oscura** - _Illuminate what others obscure_
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
oscura/__init__.py,sha256=
|
|
1
|
+
oscura/__init__.py,sha256=HLrjN-2YU438b35k94HDMDFbOpzj3_2zc9NlcB7ImHM,18313
|
|
2
2
|
oscura/__main__.py,sha256=l1rnaD-tpI1W3cp1VHGhSdq9NDqw6Gxjf_gnqXf-zzE,11786
|
|
3
3
|
oscura/convenience.py,sha256=o8f1Im8WpakGXRz8D4bV-XSNkzpgnVjsyVxnaxZ-dg4,14612
|
|
4
4
|
oscura/exceptions.py,sha256=Ywyi7IhEG9XmbceCxAcLGKAddAOdP9Ph1ZT2NioMQCU,1606
|
|
@@ -110,7 +110,7 @@ oscura/api/fluent.py,sha256=Bvo1yVqqn3nmVWaoPv4C-YtYszBhHmdW8m5NdyhWEEo,15373
|
|
|
110
110
|
oscura/api/operators.py,sha256=To4PZUrwInD43T7i2Sy8YD04eLoRsmrD6XYePuExUX8,13853
|
|
111
111
|
oscura/api/optimization.py,sha256=5R6rPByVsyxla6oq4SjxjxEp9Uplog4owzsIuFcVoR0,11875
|
|
112
112
|
oscura/api/profiling.py,sha256=vkYinleXrznWdd0OT5zIJN_PW289GQE_ODmR9DaCcQ0,10567
|
|
113
|
-
oscura/automotive/__init__.py,sha256=
|
|
113
|
+
oscura/automotive/__init__.py,sha256=MB7wS93P5QUEWv_DjhlcTgGb1bYD9bib0uKBZksnylc,2538
|
|
114
114
|
oscura/automotive/visualization.py,sha256=2ILQjzNwCwj6zZ4MEsBS-QLwYFKMO0_0xDsbv3gEXu0,10692
|
|
115
115
|
oscura/automotive/can/__init__.py,sha256=0WCLgE6juqQF_mTO716tWzfziOcM6cjshdb957G0edw,1283
|
|
116
116
|
oscura/automotive/can/analysis.py,sha256=0z6MycxuJGusqDQhYEpHnGRmDw3OMf5yDbS8zI6GJO0,11251
|
|
@@ -237,7 +237,7 @@ oscura/exploratory/recovery.py,sha256=7nqk5nU6M0nViCvy3JnhgD64YgPDik1mgIyGGVCOj3
|
|
|
237
237
|
oscura/exploratory/sync.py,sha256=6lcLt7GmZoRj9luZkNSjTRIuG7kTnxgONdBp0YSQKns,12610
|
|
238
238
|
oscura/exploratory/unknown.py,sha256=_gByru0b0BvKfZWH0m8DgXNC0dGVW-O_vBo7Jwe6-qE,21614
|
|
239
239
|
oscura/export/__init__.py,sha256=TVVAw5rmbmQSNed3VOD4Fy2mSknwaAzI-oCoLgPKhXI,770
|
|
240
|
-
oscura/export/wireshark/README.md,sha256=
|
|
240
|
+
oscura/export/wireshark/README.md,sha256=3UQGQA3fd0mK-OLOhfjZv1XzE_7bloKzP8toEvTP8GU,7728
|
|
241
241
|
oscura/export/wireshark/__init__.py,sha256=Int_19KSBJP8J78LfdibB0S6aDAfbQZJLMap6HZwWSc,1449
|
|
242
242
|
oscura/export/wireshark/generator.py,sha256=kCYtBxSyYdglriV3lcW2yfNBEYkfYV4K6oaegd3ulG0,10561
|
|
243
243
|
oscura/export/wireshark/lua_builder.py,sha256=8SqRivyzW0lzBY1O_oOhFt3vujL-CSgqBkhpU9kz_58,4533
|
|
@@ -288,7 +288,7 @@ oscura/inference/signal_intelligence.py,sha256=inPsdnq47vxotdJt5PWP8ca_ecFuWFXit
|
|
|
288
288
|
oscura/inference/spectral.py,sha256=r2YTTD9x2vuz44inzr2BCcLrRaQqIRksfz4C0YgwAQY,7100
|
|
289
289
|
oscura/inference/state_machine.py,sha256=wNzjFivXOT_eE7hTCDAVBh8r8v2A4NQGUpYFH0C5vWk,19846
|
|
290
290
|
oscura/inference/stream.py,sha256=pzmbBAx03N9SP9sjtAzfx6iZHiIGsTISSyGhXny4MSs,29448
|
|
291
|
-
oscura/inference/active_learning/README.md,sha256=
|
|
291
|
+
oscura/inference/active_learning/README.md,sha256=h7yvXZNRS1NqL8Jdp0Dy-0M3ciUN9nZqBN11N-4xniw,4834
|
|
292
292
|
oscura/inference/active_learning/__init__.py,sha256=CEay1z0T0VxZnvSM7CM7xJZDdnODq3yU5eIkYFMGN5M,1353
|
|
293
293
|
oscura/inference/active_learning/lstar.py,sha256=fvR0XGnIO3lfZ7ho9ot_qL5OkAgaRIeEKcJZGJbswA4,8590
|
|
294
294
|
oscura/inference/active_learning/observation_table.py,sha256=T0MP5ePONYx_K8L2768zmxOiAtYXVSmizDDKrrJlFVQ,7632
|
|
@@ -333,7 +333,7 @@ oscura/optimization/parallel.py,sha256=30Qy-QDbDt0_cQisBMhbkIQ_adSLaPE8S2BxIo0o2
|
|
|
333
333
|
oscura/optimization/search.py,sha256=-rJQFlMVanCV3oXg35go8tZg5ywUhMYxbhiekEA5rxc,17241
|
|
334
334
|
oscura/pipeline/__init__.py,sha256=W1ObXXo0wn4pGkl8hPfxaElOSLK5b8pjZ-aRxwfksow,964
|
|
335
335
|
oscura/pipeline/base.py,sha256=2-6yXeucDoWf8HJAVXqocLxVcKcPBytyEfonKRarNX4,11353
|
|
336
|
-
oscura/pipeline/composition.py,sha256=
|
|
336
|
+
oscura/pipeline/composition.py,sha256=RF1LGcRMPXmR9TAJqMUO-h6OAl2iywtNFyCVBXv9bdU,7870
|
|
337
337
|
oscura/pipeline/parallel.py,sha256=cTEWq5Ele_EoWQr23OtV1YQVxsWBGM6hchmCwMYvZAk,16984
|
|
338
338
|
oscura/pipeline/pipeline.py,sha256=APEIDaapwVnoeBixkYo5VAtpFOsPh9GaOdMRr_j5ByU,13284
|
|
339
339
|
oscura/pipeline/reverse_engineering.py,sha256=hSPRkaEAnnR84X-ocXwmFRRDnL5iHtl9M_8OGd8kZVw,38590
|
|
@@ -392,7 +392,7 @@ oscura/reporting/renderers/pdf.py,sha256=EYJyXQRPuSFIDl-6M55UvxOG4HKlKAQ-_SypvZp
|
|
|
392
392
|
oscura/reporting/templates/__init__.py,sha256=Snm9Ygw2EIe4DnDAxHcu5NIYLCEVeoZjyw8MDmrcWLM,301
|
|
393
393
|
oscura/reporting/templates/definition.py,sha256=KC--ESq6Ja9OA_hC3uVP3--Y_rhUEIUnm_1QJDIg7nQ,5204
|
|
394
394
|
oscura/reporting/templates/index.html,sha256=V74N-0erqnu8tevVFjPT-zMXi5M-7RSvTfujW9pwQPQ,16007
|
|
395
|
-
oscura/reporting/templates/index.md,sha256=
|
|
395
|
+
oscura/reporting/templates/index.md,sha256=HJANTLpIw7pB6xvTZzAKlM3FWVCpyJtLlA7hjKnMqM0,3754
|
|
396
396
|
oscura/schemas/__init__.py,sha256=0zVM3hatGgl3onywiWNia8ov0TJ-tFqXz_cBzuZW7nU,4317
|
|
397
397
|
oscura/schemas/bus_configuration.json,sha256=gpcDsg04760KCaLeIDuWvP6RzRUcPZuQplJbe7xpc8E,9562
|
|
398
398
|
oscura/schemas/device_mapping.json,sha256=sYOcc2zSe0rmMQN_vtg3Y5XeeDMktAO1ar8vAWl-E1M,5499
|
|
@@ -474,8 +474,8 @@ oscura/workflows/power.py,sha256=fpTzoIfuZi69ldtu2KAHW-Qu6jzA5jBa_9LVy6xqpTI,608
|
|
|
474
474
|
oscura/workflows/protocol.py,sha256=x3T-M81vFVrW3mouaYA8WjxyLLzZyLATVJbiqcMAVFQ,15275
|
|
475
475
|
oscura/workflows/reverse_engineering.py,sha256=K_yrqrQqQNcCoB0jRAG92e2zy8er3oiKJWSF6lU4nGk,19929
|
|
476
476
|
oscura/workflows/signal_integrity.py,sha256=p-DOC-AhzQOkG_jyyBK3EUaIBAGZhAhdmo-Ub_ifC3U,8391
|
|
477
|
-
oscura-0.
|
|
478
|
-
oscura-0.
|
|
479
|
-
oscura-0.
|
|
480
|
-
oscura-0.
|
|
481
|
-
oscura-0.
|
|
477
|
+
oscura-0.5.1.dist-info/METADATA,sha256=hnDRI0G8XD3TZZj6UBcr-f1FSWT_wgMeguPzUuyczvU,38933
|
|
478
|
+
oscura-0.5.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
479
|
+
oscura-0.5.1.dist-info/entry_points.txt,sha256=QLBxd-iTjBQ5HidaVSkLBwvUsqxSG1ZTJ6i-0juu960,48
|
|
480
|
+
oscura-0.5.1.dist-info/licenses/LICENSE,sha256=p1_oEK-oqWDXMFSv5mKbyYkgW-CPbCnFUvdICu490aY,1077
|
|
481
|
+
oscura-0.5.1.dist-info/RECORD,,
|
oscura-0.4.0.dist-info/METADATA
DELETED
|
@@ -1,407 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: oscura
|
|
3
|
-
Version: 0.4.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: click<9.0.0,>=8.1.0
|
|
32
|
-
Requires-Dist: dpkt<2.0.0,>=1.9.0
|
|
33
|
-
Requires-Dist: jinja2<4.0.0,>=3.1
|
|
34
|
-
Requires-Dist: matplotlib<4.0.0,>=3.7.0
|
|
35
|
-
Requires-Dist: numpy<3.0.0,>=1.24.0
|
|
36
|
-
Requires-Dist: pandas<3.0.0,>=2.0.0
|
|
37
|
-
Requires-Dist: psutil<7.0.0,>=5.9.0
|
|
38
|
-
Requires-Dist: pyyaml<7.0.0,>=6.0
|
|
39
|
-
Requires-Dist: scipy<2.0.0,>=1.10.0
|
|
40
|
-
Requires-Dist: tm-data-types<1.0.0,>=0.3.0
|
|
41
|
-
Provides-Extra: all
|
|
42
|
-
Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'all'
|
|
43
|
-
Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'all'
|
|
44
|
-
Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'all'
|
|
45
|
-
Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'all'
|
|
46
|
-
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'all'
|
|
47
|
-
Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'all'
|
|
48
|
-
Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'all'
|
|
49
|
-
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'all'
|
|
50
|
-
Requires-Dist: nbconvert<8.0.0,>=7.0.0; extra == 'all'
|
|
51
|
-
Requires-Dist: networkx<4.0.0,>=3.0; extra == 'all'
|
|
52
|
-
Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'all'
|
|
53
|
-
Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'all'
|
|
54
|
-
Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'all'
|
|
55
|
-
Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'all'
|
|
56
|
-
Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'all'
|
|
57
|
-
Requires-Dist: pytest<10.0.0,>=8.0; extra == 'all'
|
|
58
|
-
Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'all'
|
|
59
|
-
Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'all'
|
|
60
|
-
Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'all'
|
|
61
|
-
Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'all'
|
|
62
|
-
Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'all'
|
|
63
|
-
Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'all'
|
|
64
|
-
Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'all'
|
|
65
|
-
Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'all'
|
|
66
|
-
Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'all'
|
|
67
|
-
Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'all'
|
|
68
|
-
Provides-Extra: analysis
|
|
69
|
-
Requires-Dist: networkx<4.0.0,>=3.0; extra == 'analysis'
|
|
70
|
-
Requires-Dist: openpyxl<4.0.0,>=3.0.0; extra == 'analysis'
|
|
71
|
-
Requires-Dist: pywavelets<2.0.0,>=1.0.0; extra == 'analysis'
|
|
72
|
-
Provides-Extra: automotive
|
|
73
|
-
Requires-Dist: asammdf<9.0.0,>=8.0.0; extra == 'automotive'
|
|
74
|
-
Requires-Dist: cantools<40.0.0,>=39.4.0; extra == 'automotive'
|
|
75
|
-
Requires-Dist: python-can<5.0.0,>=4.4.0; extra == 'automotive'
|
|
76
|
-
Requires-Dist: scapy<3.0.0,>=2.5.0; extra == 'automotive'
|
|
77
|
-
Provides-Extra: dev
|
|
78
|
-
Requires-Dist: check-jsonschema<1.0.0,>=0.29.0; extra == 'dev'
|
|
79
|
-
Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'dev'
|
|
80
|
-
Requires-Dist: interrogate<2.0.0,>=1.7.0; extra == 'dev'
|
|
81
|
-
Requires-Dist: pytest-benchmark<6.0.0,>=4.0.0; extra == 'dev'
|
|
82
|
-
Requires-Dist: pytest-cov<8.0.0,>=6.0; extra == 'dev'
|
|
83
|
-
Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == 'dev'
|
|
84
|
-
Requires-Dist: pytest<10.0.0,>=8.0; extra == 'dev'
|
|
85
|
-
Requires-Dist: types-pyyaml<7.0.0,>=6.0; extra == 'dev'
|
|
86
|
-
Requires-Dist: yamllint<2.0.0,>=1.35; extra == 'dev'
|
|
87
|
-
Provides-Extra: hardware
|
|
88
|
-
Requires-Dist: pyvisa-py<1.0.0,>=0.7.0; extra == 'hardware'
|
|
89
|
-
Requires-Dist: pyvisa<2.0.0,>=1.13.0; extra == 'hardware'
|
|
90
|
-
Provides-Extra: hdf5
|
|
91
|
-
Requires-Dist: h5py<4.0.0,>=3.0.0; extra == 'hdf5'
|
|
92
|
-
Provides-Extra: jupyter
|
|
93
|
-
Requires-Dist: ipython<9.0.0,>=8.0.0; extra == 'jupyter'
|
|
94
|
-
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == 'jupyter'
|
|
95
|
-
Requires-Dist: nbconvert<8.0.0,>=7.0.0; extra == 'jupyter'
|
|
96
|
-
Provides-Extra: oscilloscopes
|
|
97
|
-
Requires-Dist: nptdms<2.0.0,>=1.7.0; extra == 'oscilloscopes'
|
|
98
|
-
Requires-Dist: rigolwfm<2.0.0,>=1.0.0; extra == 'oscilloscopes'
|
|
99
|
-
Provides-Extra: reporting
|
|
100
|
-
Requires-Dist: python-pptx<1.0.0,>=0.6.21; extra == 'reporting'
|
|
101
|
-
Requires-Dist: reportlab<6.0.0,>=4.4.7; extra == 'reporting'
|
|
102
|
-
Description-Content-Type: text/markdown
|
|
103
|
-
|
|
104
|
-
# Oscura
|
|
105
|
-
|
|
106
|
-
**Unified hardware reverse engineering framework. Extract all information from any system through signals and data.**
|
|
107
|
-
|
|
108
|
-
**Build Status:**
|
|
109
|
-
[](https://github.com/oscura-re/oscura/actions/workflows/ci.yml)
|
|
110
|
-
[](https://github.com/oscura-re/oscura/actions/workflows/code-quality.yml)
|
|
111
|
-
[](https://github.com/oscura-re/oscura/actions/workflows/docs.yml)
|
|
112
|
-
[](https://github.com/oscura-re/oscura/actions/workflows/test-quality.yml)
|
|
113
|
-
|
|
114
|
-
**Package:**
|
|
115
|
-
[](https://pypi.org/project/oscura/)
|
|
116
|
-
[](https://www.python.org/downloads/)
|
|
117
|
-
[](https://opensource.org/licenses/MIT)
|
|
118
|
-
[](https://pypi.org/project/oscura/)
|
|
119
|
-
|
|
120
|
-
**Code Quality:**
|
|
121
|
-
[](https://codecov.io/gh/oscura-re/oscura)
|
|
122
|
-
[](https://github.com/astral-sh/ruff)
|
|
123
|
-
[](https://github.com/oscura-re/oscura/tree/main/docs)
|
|
124
|
-
|
|
125
|
-
**Project Status:**
|
|
126
|
-
[](https://github.com/oscura-re/oscura/graphs/commit-activity)
|
|
127
|
-
[](https://github.com/oscura-re/oscura/commits/main)
|
|
128
|
-
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
## What is Oscura?
|
|
132
|
-
|
|
133
|
-
Oscura is a hardware reverse engineering framework for security researchers, right-to-repair advocates, defense analysts, and commercial intelligence teams. From oscilloscope captures to complete system understanding.
|
|
134
|
-
|
|
135
|
-
**Reverse Engineering**: Unknown protocol discovery • State machine extraction • CRC/checksum recovery • Proprietary device replication • Security vulnerability analysis • Black-box protocol analysis
|
|
136
|
-
|
|
137
|
-
**Signal Analysis**: IEEE-compliant measurements (181/1241/1459/2414) • Comprehensive protocol decoding (16+ protocols) • Spectral analysis • Timing characterization • Side-channel analysis (DPA/CPA/timing attacks)
|
|
138
|
-
|
|
139
|
-
**Unified Acquisition**: File-based • Hardware sources (SocketCAN, Saleae, PyVISA - Phase 2) • Synthetic generation • Polymorphic Source protocol
|
|
140
|
-
|
|
141
|
-
**Interactive Sessions**: Domain-specific analysis sessions • BlackBoxSession for protocol RE • Differential analysis • Field hypothesis generation • Protocol specification export
|
|
142
|
-
|
|
143
|
-
**Built For**: Exploitation • Replication • Defense analysis • Commercial intelligence • Right-to-repair • Cryptographic research
|
|
144
|
-
|
|
145
|
-
---
|
|
146
|
-
|
|
147
|
-
## Installation
|
|
148
|
-
|
|
149
|
-
```bash
|
|
150
|
-
# Using uv (recommended)
|
|
151
|
-
uv pip install oscura
|
|
152
|
-
|
|
153
|
-
# Or with pip
|
|
154
|
-
pip install oscura
|
|
155
|
-
|
|
156
|
-
# Development install (RECOMMENDED)
|
|
157
|
-
git clone https://github.com/oscura-re/oscura.git
|
|
158
|
-
cd oscura
|
|
159
|
-
./scripts/setup.sh # Complete setup (dependencies + hooks)
|
|
160
|
-
./scripts/verify-setup.sh # Verify environment is ready
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
---
|
|
164
|
-
|
|
165
|
-
## Quick Start
|
|
166
|
-
|
|
167
|
-
### Signal Analysis
|
|
168
|
-
|
|
169
|
-
```python
|
|
170
|
-
import oscura as osc
|
|
171
|
-
|
|
172
|
-
# Load oscilloscope capture
|
|
173
|
-
trace = osc.load("capture.wfm")
|
|
174
|
-
|
|
175
|
-
# Basic measurements
|
|
176
|
-
print(f"Frequency: {osc.frequency(trace) / 1e6:.3f} MHz")
|
|
177
|
-
print(f"Rise time: {osc.rise_time(trace) * 1e9:.1f} ns")
|
|
178
|
-
|
|
179
|
-
# Decode protocol
|
|
180
|
-
from oscura.protocols import UARTDecoder
|
|
181
|
-
decoder = UARTDecoder(baud_rate=115200)
|
|
182
|
-
messages = decoder.decode(trace)
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
### Black-Box Protocol Reverse Engineering
|
|
186
|
-
|
|
187
|
-
```python
|
|
188
|
-
from oscura.sessions import BlackBoxSession
|
|
189
|
-
from oscura.acquisition import FileSource
|
|
190
|
-
|
|
191
|
-
# Create analysis session
|
|
192
|
-
session = BlackBoxSession(name="IoT Device RE")
|
|
193
|
-
|
|
194
|
-
# Add recordings from different stimuli
|
|
195
|
-
session.add_recording("idle", FileSource("idle.bin"))
|
|
196
|
-
session.add_recording("button_press", FileSource("button.bin"))
|
|
197
|
-
|
|
198
|
-
# Differential analysis
|
|
199
|
-
diff = session.compare("idle", "button_press")
|
|
200
|
-
print(f"Changed bytes: {diff.changed_bytes}")
|
|
201
|
-
|
|
202
|
-
# Generate protocol specification
|
|
203
|
-
spec = session.generate_protocol_spec()
|
|
204
|
-
print(f"Detected {len(spec['fields'])} protocol fields")
|
|
205
|
-
|
|
206
|
-
# Export Wireshark dissector
|
|
207
|
-
session.export_results("dissector", "protocol.lua")
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### CAN Protocol Analysis
|
|
211
|
-
|
|
212
|
-
```python
|
|
213
|
-
from oscura.automotive.can import CANSession
|
|
214
|
-
from oscura.acquisition import FileSource
|
|
215
|
-
|
|
216
|
-
# Create session
|
|
217
|
-
session = CANSession(name="Vehicle Analysis")
|
|
218
|
-
|
|
219
|
-
# Add recordings from CAN bus captures
|
|
220
|
-
session.add_recording("idle", FileSource("idle.blf"))
|
|
221
|
-
session.add_recording("accelerate", FileSource("accelerate.blf"))
|
|
222
|
-
|
|
223
|
-
# Analyze traffic
|
|
224
|
-
analysis = session.analyze()
|
|
225
|
-
print(f"Messages: {analysis['inventory']['total_messages']}")
|
|
226
|
-
print(f"Unique IDs: {len(analysis['inventory']['message_ids'])}")
|
|
227
|
-
|
|
228
|
-
# Compare recordings
|
|
229
|
-
diff = session.compare("idle", "accelerate")
|
|
230
|
-
print(f"Changed IDs: {len(diff.details['changed_ids'])}")
|
|
231
|
-
|
|
232
|
-
# Export DBC file
|
|
233
|
-
session.export_dbc("vehicle.dbc")
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
---
|
|
237
|
-
|
|
238
|
-
## Learn by Example
|
|
239
|
-
|
|
240
|
-
**Demos are the documentation.** Each category includes working code with comprehensive explanations.
|
|
241
|
-
|
|
242
|
-
### Core Capabilities
|
|
243
|
-
|
|
244
|
-
| Demo | Description |
|
|
245
|
-
|------|-------------|
|
|
246
|
-
| [01_waveform_analysis](demos/01_waveform_analysis/) | Load and analyze Tektronix, Rigol, LeCroy captures |
|
|
247
|
-
| [02_file_format_io](demos/02_file_format_io/) | CSV, HDF5, NumPy, custom binary formats |
|
|
248
|
-
| [03_custom_daq](demos/03_custom_daq/) | Streaming loaders for custom DAQ systems |
|
|
249
|
-
| [04_serial_protocols](demos/04_serial_protocols/) | UART, SPI, I2C, 1-Wire decoding |
|
|
250
|
-
| [05_protocol_decoding](demos/05_protocol_decoding/) | Protocol auto-detection and decoding |
|
|
251
|
-
| [06_udp_packet_analysis](demos/06_udp_packet_analysis/) | Network packet capture and analysis |
|
|
252
|
-
|
|
253
|
-
### Advanced Analysis
|
|
254
|
-
|
|
255
|
-
| Demo | Description |
|
|
256
|
-
|------|-------------|
|
|
257
|
-
| [07_protocol_inference](demos/07_protocol_inference/) | State machine learning, CRC reverse engineering |
|
|
258
|
-
| [08_automotive_protocols](demos/08_automotive_protocols/) | CAN, CAN-FD, LIN, FlexRay analysis |
|
|
259
|
-
| [09_automotive](demos/09_automotive/) | OBD-II, UDS, J1939 diagnostics |
|
|
260
|
-
| [10_timing_measurements](demos/10_timing_measurements/) | Rise/fall time, duty cycle (IEEE 181) |
|
|
261
|
-
| [11_mixed_signal](demos/11_mixed_signal/) | Analog + digital combined analysis |
|
|
262
|
-
| [12_spectral_compliance](demos/12_spectral_compliance/) | FFT, THD, SNR, SINAD (IEEE 1241) |
|
|
263
|
-
| [13_jitter_analysis](demos/13_jitter_analysis/) | TIE, RJ/DJ, eye diagrams (IEEE 2414) |
|
|
264
|
-
| [14_power_analysis](demos/14_power_analysis/) | DC-DC, ripple, efficiency (IEEE 1459) |
|
|
265
|
-
| [15_signal_integrity](demos/15_signal_integrity/) | TDR, S-parameters, setup/hold timing |
|
|
266
|
-
| [16_emc_compliance](demos/16_emc_compliance/) | CISPR, FCC, MIL-STD testing |
|
|
267
|
-
| [17_signal_reverse_engineering](demos/17_signal_reverse_engineering/) | Complete unknown signal analysis |
|
|
268
|
-
| [18_advanced_inference](demos/18_advanced_inference/) | Bayesian inference, Protocol DSL |
|
|
269
|
-
| [19_complete_workflows](demos/19_complete_workflows/) | End-to-end reverse engineering |
|
|
270
|
-
|
|
271
|
-
### Run Your First Demo
|
|
272
|
-
|
|
273
|
-
```bash
|
|
274
|
-
# Generate demo data
|
|
275
|
-
python demos/generate_all_demo_data.py
|
|
276
|
-
|
|
277
|
-
# Run a demo
|
|
278
|
-
uv run python demos/01_waveform_analysis/comprehensive_wfm_analysis.py
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
---
|
|
282
|
-
|
|
283
|
-
## Key Features
|
|
284
|
-
|
|
285
|
-
### Protocols (16+)
|
|
286
|
-
|
|
287
|
-
UART • SPI • I2C • 1-Wire • CAN • CAN-FD • LIN • FlexRay • JTAG • SWD • Manchester • Miller • USB • HDLC • I2S • MDIO • DMX512
|
|
288
|
-
|
|
289
|
-
### File Formats (18+)
|
|
290
|
-
|
|
291
|
-
Tektronix WFM • Rigol WFM • LeCroy TRC • Sigrok • VCD • CSV • NumPy • HDF5 • MATLAB • WAV • JSON • BLF • MF4 • PCAP • PCAPNG
|
|
292
|
-
|
|
293
|
-
### Standards Compliance
|
|
294
|
-
|
|
295
|
-
**IEEE 181-2011**: Rise/fall time, pulse width, overshoot
|
|
296
|
-
|
|
297
|
-
**IEEE 1241-2010**: SNR, SINAD, THD, SFDR, ENOB
|
|
298
|
-
|
|
299
|
-
**IEEE 1459-2010**: Power factor, harmonics, efficiency
|
|
300
|
-
|
|
301
|
-
**IEEE 2414-2020**: TIE, period jitter, RJ/DJ
|
|
302
|
-
|
|
303
|
-
---
|
|
304
|
-
|
|
305
|
-
## Command Line Interface
|
|
306
|
-
|
|
307
|
-
```bash
|
|
308
|
-
# Characterize signal measurements
|
|
309
|
-
oscura characterize capture.wfm
|
|
310
|
-
|
|
311
|
-
# Decode protocol
|
|
312
|
-
oscura decode uart.wfm --protocol uart
|
|
313
|
-
|
|
314
|
-
# Batch process multiple files
|
|
315
|
-
oscura batch '*.wfm' --analysis characterize
|
|
316
|
-
|
|
317
|
-
# Compare two signals
|
|
318
|
-
oscura compare before.wfm after.wfm
|
|
319
|
-
|
|
320
|
-
# Interactive shell
|
|
321
|
-
oscura shell
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
See [CLI Reference](docs/cli.md) for complete documentation.
|
|
325
|
-
|
|
326
|
-
---
|
|
327
|
-
|
|
328
|
-
## Contributing
|
|
329
|
-
|
|
330
|
-
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
|
|
331
|
-
|
|
332
|
-
```bash
|
|
333
|
-
# Quick setup
|
|
334
|
-
git clone https://github.com/oscura-re/oscura.git
|
|
335
|
-
cd oscura
|
|
336
|
-
uv sync --all-extras
|
|
337
|
-
./scripts/setup/install-hooks.sh
|
|
338
|
-
|
|
339
|
-
# Run tests
|
|
340
|
-
./scripts/test.sh
|
|
341
|
-
|
|
342
|
-
# Quality checks
|
|
343
|
-
./scripts/check.sh
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
---
|
|
347
|
-
|
|
348
|
-
## Documentation
|
|
349
|
-
|
|
350
|
-
### Getting Started
|
|
351
|
-
|
|
352
|
-
- **[Quick Start Guide](docs/guides/quick-start.md)** - Begin here
|
|
353
|
-
- **[Demos](demos/)** - Working examples for every feature
|
|
354
|
-
- **[Migration Guide](docs/migration/v0-to-v1.md)** - Upgrade from older versions
|
|
355
|
-
|
|
356
|
-
### User Guides
|
|
357
|
-
|
|
358
|
-
- **[Black-Box Protocol Analysis](docs/guides/blackbox-analysis.md)** - Unknown protocol reverse engineering
|
|
359
|
-
- **[Hardware Acquisition](docs/guides/hardware-acquisition.md)** - Direct hardware integration (Phase 2)
|
|
360
|
-
- **[Side-Channel Analysis](docs/guides/side-channel-analysis.md)** - Power/timing/EM attacks
|
|
361
|
-
- **[Workflows](docs/guides/workflows.md)** - Complete analysis workflows
|
|
362
|
-
|
|
363
|
-
### API Reference
|
|
364
|
-
|
|
365
|
-
- **[API Reference](docs/api/)** - Complete API documentation
|
|
366
|
-
- **[Session Management](docs/api/session-management.md)** - Interactive analysis sessions
|
|
367
|
-
- **[CLI Reference](docs/cli.md)** - Command line usage
|
|
368
|
-
|
|
369
|
-
### Development
|
|
370
|
-
|
|
371
|
-
- **[Architecture](docs/architecture/)** - Design principles and patterns
|
|
372
|
-
- **[Testing Guide](docs/testing/)** - Test suite architecture
|
|
373
|
-
- **[CHANGELOG](CHANGELOG.md)** - Version history
|
|
374
|
-
|
|
375
|
-
---
|
|
376
|
-
|
|
377
|
-
## License
|
|
378
|
-
|
|
379
|
-
MIT License - see [LICENSE](LICENSE) for details.
|
|
380
|
-
|
|
381
|
-
---
|
|
382
|
-
|
|
383
|
-
## Citation
|
|
384
|
-
|
|
385
|
-
If you use Oscura in research:
|
|
386
|
-
|
|
387
|
-
```bibtex
|
|
388
|
-
@software{oscura,
|
|
389
|
-
title = {Oscura: Signal Reverse Engineering Toolkit},
|
|
390
|
-
author = {Oscura Contributors},
|
|
391
|
-
year = {2026},
|
|
392
|
-
url = {https://github.com/oscura-re/oscura}
|
|
393
|
-
}
|
|
394
|
-
```
|
|
395
|
-
|
|
396
|
-
Machine-readable: [CITATION.cff](CITATION.cff)
|
|
397
|
-
|
|
398
|
-
---
|
|
399
|
-
|
|
400
|
-
## Support
|
|
401
|
-
|
|
402
|
-
- **[GitHub Issues](https://github.com/oscura-re/oscura/issues)** - Bug reports and feature requests
|
|
403
|
-
- **[Discussions](https://github.com/oscura-re/oscura/discussions)** - Questions and community
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
|
-
**Oscura** • Reverse engineer any system from captured waveforms
|
|
File without changes
|
|
File without changes
|
|
File without changes
|