Photo in, attack surface out. The first open-source toolkit that identifies PCB components, extracts traces, maps trust chains, and tells you where to probe.
$ pip install git+https://github.com/ericrihm/retrace.git
click to copy
Works from a photograph alone. No Gerbers, no schematics, no vendor cooperation needed. Point your phone at a board.
Every output is threat-informed. CVSS scoring, MITRE ATT&CK mapping, attack path visualization, debug interface enumeration.
YOLO and EasyOCR are optional. Core pipeline runs on pure Python with OpenCV. Works air-gapped on classified networks.
Nine stages. One command. No design files required.
One SVG. Nine layers. Ten view presets. Three rendering styles. Like switching between Satellite and Terrain on Google Maps.
Board image with translucent overlays. Default mode — like Google Maps satellite view.
Vector-only, no photo. Opaque component outlines, thick traces, bold labels. Like Google Maps roadmap.
Dimmed photo with high-contrast overlays. Everything visible at once. Hybrid satellite + roadmap.
Board photo only. Clean view for orientation.
Components + traces + BOM. Default RE view.
Vector-only with net labels and grid.
All layers with dimmed photo. Full visibility.
Security findings + attack path arrows.
Pentester first look: security + power rails.
VRMs, LDOs, rails, decoupling caps.
Functional zone overlay: CPU, memory, power.
Debug interfaces + net classification.
Everything visible. Full analysis mode.
retrace scan board.jpg --format svg — self-contained SVG with JavaScript layer controls. Open in any browser.
Two targets. Both analyzed from photos alone.
Automatically detected debug interfaces with CVSS 3.1 scoring and MITRE ATT&CK mapping.
| Severity | CVSS | Interface | Target | Component | CWE | ATT&CK |
|---|---|---|---|---|---|---|
| HIGH | 7.6 | JTAG | Cisco ASA 5506-X | J15 | CWE-1191 | T1200, T0839 |
| MEDIUM | 6.8 | UART | Cisco ASA 5506-X | J10 | CWE-1299 | T1200 |
| HIGH | 7.6 | JTAG | Xbox One 1540 | J5 | CWE-1191 | T1200, T0839 |
Every identified IC is enriched with security-relevant datasheet specs. Debug interfaces, boot mode pins, readout protection, JEDEC IDs, flashrom commands — actionable intel for hardware hackers.
42 microcontrollers with JTAG/SWD interfaces, BOOT mode pins, readout protection levels (RDP, APPROTECT, lock bits). STM32, ESP32, nRF52, AVR, PIC, RP2040.
9 SPI NOR flash chips with JEDEC IDs, read commands, write-protect pin locations, and exact flashrom command lines. Winbond, Macronix, GigaDevice, ISSI, Infineon.
4 FPGAs with configuration interfaces, JTAG chain info, bitstream formats, and toolchains. Xilinx Artix-7 and Spartan-6, Lattice iCE40 (open-source reversible), Intel MAX 10.
8 crypto/trust chips with I2C/SPI addresses, FIPS/CC certifications, key storage capabilities, and attestation protocols. ATECC608, SE050, SLB9670, STSAFE.
26 voltage regulators with output voltages, enable pins, input ranges, and topology. LDO, buck, boost, buck-boost. Know which rail to glitch.
Schematic-style package diagrams for SOIC-8, TQFP-48, QFN-24, and TSOP-48 packages. Quad-sided rendering with function-group colors and security intel panels. Flash chips include extraction cheat sheets.
Standalone schematic-style power delivery topology. Shows power flow from input sources through VRMs/LDOs to load ICs with voltage rail labels and decoupling cap counts.
Circular graph showing component interconnections via inferred protocol buses. Auto-detects SPI, I2C, UART, JTAG, USB, SDIO, PCIe, and DDR from trace context and component markings.
119 of 128 components enriched with security intel · CSV/JSON exports include flattened intel columns
Not just detection — inference, optimization, and learning across boards.
Stop guessing where to put your multimeter. The probe advisor maintains a Dirichlet belief distribution per unresolved node and ranks every point by expected Shannon entropy reduction.
Trace extraction from photos is inherently partial — expect 40–70% recovery. The constraint solver infers the rest using pinout rules, proximity heuristics, and arc consistency propagation.
Every scan builds a persistent knowledge base. The more boards you analyze, the faster the next one goes. 15 subcircuit patterns transfer automatically between targets.
Cisco's Trust Anchor module is a Xilinx Spartan-6 FPGA that verifies boot image integrity on ASA, IOS-XE, and NX-OS. The FPGA loads its bitstream from an external SPI flash (W25Q128JV) at power-on — and that bitstream is not authenticated or encrypted. re:trace maps this entire attack path automatically from a board photo: identifies the FPGA, traces the SPI flash connection, flags the unencrypted bitstream, and marks the JTAG header that provides initial access.
Same attack surface exploited by the ArcaneDoor state-sponsored campaign (2024) — CISA Emergency Directive ED 25-03
Engineering techniques under the hood — not wrappers around existing tools.
Multi-stage pipeline: adaptive thresholding, morphological filtering (dilate/erode), contour hierarchy analysis, HSV+LAB dual-colorspace copper trace extraction. No ML dependency for core detection.
Trace connectivity via proximity-based endpoint matching builds a component adjacency graph. Bus topology extraction, net grouping, and attack-path traversal from debug ports to high-value targets.
Pin assignment solving under electrical rules: pin count vs. package geometry, protocol-specific signal ordering (UART TX/RX, SPI MOSI/MISO/CLK/CS), voltage level constraints from datasheet cross-reference.
Shannon entropy profiling over configurable block sizes classifies firmware regions as null/padding, code, text, compressed, or encrypted. Drives automated encrypted-firmware detection at 80% high-entropy threshold.
CVSS 3.1 base score computation with physical access vectors. CWE mapping (1191, 1247, 1299) and MITRE ATT&CK technique references (T1200, T0839). Severity-ranked findings with remediation guidance.
Automated UART baud-rate inference, SPI/I2C bus parameter extraction, JTAG/SWD chain detection. Generates Sigrok/PulseView session files with pre-labeled channels and decoder configuration.
Self-contained HTML deliverables. Sortable BOM, datasheet hyperlinks, print-friendly. What a consultancy ships to clients.
Enterprise firewall assessment. Intel Atom C2508, Xilinx Spartan-6 Trust Anchor, Thrangrycat attack path mapped. 5 findings, 177 components, 88 traces.
Gaming console assessment. AMD Liverpool APU, 8x DDR3 banks, Southbridge X861949, SK Hynix eMMC. 1 finding, 150 components, 68 traces.
Every artifact from a single scan.
Reconstructed schematic netlist and positional PCB layout. retrace export-kicad writes a netlist; retrace export-kicad-pcb places footprints at detected board coordinates for a fully-positioned .kicad_pcb file.
Machine-readable bill of materials. Part numbers, markings, confidence scores, datasheet URLs.
Raw pipeline output. Component bounding boxes, trace polylines, pattern matches, timing metadata.
Annotated debug header close-ups with pin labels and probe wiring guides for J-Link, Bus Pirate, FTDI, and ST-Link.
Self-contained SVG with 9 layers, 10 presets, and 3 rendering styles. Switch views like Google Maps Satellite/Terrain/Roadmap.
Power delivery topology from input through VRMs to loads. Bus topology graph with auto-detected SPI, I2C, UART, JTAG, USB, PCIe, DDR connections.
Bayesian probe advisor output and AC-3 constraint solver results. Machine-readable for automated test rigs or field assessment notes.
Auto-generates JTAGulator scan configs and OpenOCD .cfg files from detected JTAG headers. Drop the output straight into your toolchain — no manual pin mapping.
Detects fault-injection attack surfaces: voltage regulators near security ICs (VFI candidates), external clocks feeding crypto logic (clock glitch), and thin-die packages vulnerable to EMFI. Each finding includes CVSS score and remediation guidance.
Identifies SPI flash, eMMC, and EEPROM storage chips and generates ready-to-run flashrom commands, wiring diagrams, and JEDEC ID verification steps. Includes verify-by-double-read and write-protect bypass guidance.
Binary-level first-pass analysis of firmware dumps: Shannon entropy profiling detects encrypted/compressed regions, magic byte scanner identifies 17 embedded formats (ELF, U-Boot, SquashFS, JFFS2, gzip, xz), and regex-based string extraction surfaces credentials, SSH keys, API tokens, and hardcoded IPs. Completes the kill chain: board photo → probe → dump → triage.
