{"id":50443910,"url":"https://github.com/ericrihm/retrace","last_synced_at":"2026-05-31T20:02:57.451Z","repository":{"id":354903325,"uuid":"1225898530","full_name":"ericrihm/retrace","owner":"ericrihm","description":"AI-powered PCB reverse engineering toolkit — the FCC won't let me be, so let me see what's on this PCB","archived":false,"fork":false,"pushed_at":"2026-05-11T14:37:13.000Z","size":90513,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T15:28:34.065Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericrihm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T19:01:47.000Z","updated_at":"2026-05-11T14:46:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ericrihm/retrace","commit_stats":null,"previous_names":["ericrihm/retrace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ericrihm/retrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericrihm%2Fretrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericrihm%2Fretrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericrihm%2Fretrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericrihm%2Fretrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericrihm","download_url":"https://codeload.github.com/ericrihm/retrace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericrihm%2Fretrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33746528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T20:02:57.364Z","updated_at":"2026-05-31T20:02:57.443Z","avatar_url":"https://github.com/ericrihm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# re:trace\n\n**PCB reverse engineering toolkit -- board photo in, attack surface out**\n\n*Automated component detection, trace extraction, constraint inference, and security assessment from PCB photographs. No schematics. No design files. No NDA.*\n\n[![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)](https://github.com/ericrihm/retrace/releases)\n[![CI](https://img.shields.io/github/actions/workflow/status/ericrihm/retrace/ci.yml?label=CI\u0026logo=github)](https://github.com/ericrihm/retrace/actions)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?logo=python\u0026logoColor=white)](https://github.com/ericrihm/retrace)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen.svg)](https://github.com/ericrihm/retrace)\n\n**\u003c!-- STATS:tests --\u003e1905\u003c!-- /STATS --\u003e tests** · **\u003c!-- STATS:modules --\u003e33\u003c!-- /STATS --\u003e modules** · **\u003c!-- STATS:loc --\u003e16465\u003c!-- /STATS --\u003e LOC** · **Zero required ML deps**\n\n[Technical Highlights](#technical-highlights) · [Architecture](#architecture) · [Design Decisions](#design-decisions) · [Quick Start](#quick-start) · [For Security Researchers](#for-security-researchers) · [API Examples](#api-examples) · [Live Demo](https://ericrihm.github.io/retrace/)\n\n\u003c/div\u003e\n\n---\n\nFeed it a board photo. Get back identified components, traced connections, debug interfaces, and Bayesian-optimal probe points -- no microscope, no schematic, no prior knowledge of the board required.\n\n```bash\npip install git+https://github.com/ericrihm/retrace.git\nretrace scan board_photo.jpg\n```\n\n```\n  re:trace v0.3.0 — PCB Reverse Engineering Toolkit\n  ──────────────────────────────────────────────────\n\n  [detect]   Found 177 components (20 ICs, 8 connectors, 56 caps, 29 resistors...)\n  [ocr]      Read 18 IC markings — 16 matched (89%)\n  [trace]    Extracted 88 traces, 269 nodes\n  [identify] Matched: Intel Atom C2508, Xilinx Spartan-6 XC6SLX9, W25Q128JV...\n  [infer]    AC-3: 88 iterations, 3 inferred connections\n  [advise]   Top probe: U1.DDR3_DQ0 (EIG: 4.807 bits)\n  [security] 2 findings: JTAG (HIGH, CVSS 7.6), UART (MEDIUM, CVSS 6.8)\n  [export]   Wrote: annotated.svg, attack_surface.svg, zones.svg, bom.json\n```\n\n## Technical Highlights\n\nThe analysis pipeline combines techniques from computer vision, probabilistic inference, graph theory, and security assessment:\n\n- **Bayesian inference for probe optimization** -- Dirichlet belief distributions over net-label hypotheses, ranked by expected Shannon entropy reduction. Pin-name priors encode domain knowledge (proximity to power planes, silk markings). Converges on unknown pin functions in 6-10 measurements on typical boards. No equivalent exists in any public PCB RE tool.\n\n- **Constraint satisfaction for connection inference** -- AC-3 arc consistency propagation resolves missing connections from pinout rules, proximity constraints, and differential pair detection. O(ed^3) complexity scales to 200+ node boards in real time. Union-find equality groups merge high-confidence trace segments before propagation.\n\n- **Computer vision pipeline** -- Dual-space color segmentation (HSV + LAB) isolates copper traces across green, blue, red, and black soldermask. Morphological open/close removes noise and bridges gaps. Zhang-Suen skeletonization extracts trace centerlines. BFS graph construction maps pad-to-pad connectivity. Distance transform estimates trace width at each point.\n\n- **Graph algorithms for topology extraction** -- BFS-based trace connectivity builds a full board graph. Bus topology extraction identifies SPI, I2C, JTAG, and UART buses as protocol-aware subgraphs. Power tree analysis maps voltage rail topology from input sources through regulators to load paths. Cross-board subcircuit pattern matching recognizes 15 canonical circuits (LDO, buck converter, I2C pull-up pair, SPI flash circuit, etc.).\n\n- **Information-theoretic probe selection** -- Shannon entropy quantifies uncertainty at each unresolved node. Expected information gain (EIG) ranks all candidate probe points. Measurements collapse belief at the probed node and propagate through union-find groups, updating the entire belief network per measurement.\n\n- **Security assessment with standards mapping** -- CVSS 3.1 vector scoring for each finding. CWE mapping (CWE-1191 for exposed JTAG, CWE-1299 for debug ports). MITRE ATT\u0026CK technique references (T1200 hardware additions, T0839 firmware modification). Automated trust chain analysis (e.g., Thrangrycat: JTAG header to CPU to FPGA to unencrypted SPI flash bitstream).\n\n- **Protocol interface detection and parameter extraction** -- Pattern-based detection of JTAG (20/14/10-pin), SWD (10/4/2-pin), UART (4/3/6-pin), SPI (8/6/4-pin), and I2C (4/2-pin) interfaces. Pin function labeling (data, clock, power, ground, control, debug). Probe wiring guides for J-Link, Bus Pirate, FTDI FT232H, ST-Link V2, flashrom, and OpenOCD.\n\n- **Fault injection surface mapping** -- Identifies voltage glitch targets (VRM/LDO output decoupling capacitors on processor core rails), clock glitch targets (crystal oscillators and clock distribution ICs with frequency data), and EMFI proximity candidates. Constraint solver classifies power nets and maps which components share rails, enabling pre-bench glitch planning.\n\n## Architecture\n\nThe pipeline processes a single board photograph through seven stages, each feeding the next:\n\n```\n  PCB Photo\n      |\n      v\n  Component Detection ---- YOLO v8 (6,260-image training set, 25 classes)\n      |                     OpenCV contour fallback (adaptive threshold,\n      |                     morphological filtering, contour hierarchy)\n      v\n  Chip OCR + Matching ----- EasyOCR marking extraction\n      |                     Fuzzy match against 128-part local DB\n      |                     Datasheet URL resolution\n      v\n  Trace Extraction -------- HSV/LAB dual-space segmentation\n      |                     Zhang-Suen skeletonization\n      |                     BFS 8-connected graph construction\n      v\n  Constraint Inference ---- AC-3 arc consistency propagation\n      |                     Pinout rules, proximity constraints,\n      |                     differential pair detection, union-find merge\n      v\n  Net Analysis ------------ Power tree topology\n      |                     Bus topology (SPI/I2C/JTAG/UART subgraphs)\n      |                     Cross-board pattern recognition (15 patterns)\n      v\n  Security Assessment ----- Debug interface detection (JTAG/SWD/UART/SPI/I2C)\n      |                     Trust chain mapping (chip-to-chip attack paths)\n      |                     Fault injection surface identification\n      |                     CVSS 3.1 scoring, CWE mapping, ATT\u0026CK references\n      v\n  Report Generation ------- Self-contained HTML report\n                            KiCad netlist (.net) for schematic reconstruction\n                            Interactive layered SVG (9 layers, 3 styles)\n                            BOM (JSON/CSV/SVG), pinout diagrams, attack surface maps\n```\n\n```\nsrc/retrace/                             # \u003c!-- STATS:src_loc --\u003e16465\u003c!-- /STATS --\u003e lines across \u003c!-- STATS:modules --\u003e33\u003c!-- /STATS --\u003e modules\n├── cli.py                               # Click CLI: 27 commands\n├── web.py                               # Gradio web interface\n├── core/\n│   ├── pipeline.py                      # Orchestrator: photo → AnalysisResult\n│   └── config.py                        # TOML config, model paths, cache dirs\n├── detection/\n│   ├── detector.py                      # YOLO v8 + OpenCV contour fallback\n│   ├── trace_extractor.py               # HSV/LAB → skeleton → BFS connectivity\n│   └── ocr.py                           # EasyOCR chip marking extraction\n├── identification/\n│   └── matcher.py                       # Fuzzy part number → datasheet lookup\n├── analysis/\n│   ├── attack_path.py                   # Chip-to-chip attack path ranking\n│   ├── probe_advisor.py                 # Bayesian optimal probe selection (Shannon entropy)\n│   ├── constraint_solver.py             # AC-3 arc-consistency propagation\n│   ├── cross_board.py                   # Cross-board subcircuit pattern matching\n│   ├── firmware_triage.py               # Entropy profiling, magic bytes, credential extraction\n│   └── protocol_topology.py             # Bus topology inference (I2C/SPI/UART/CAN/1-Wire)\n├── sources/\n│   ├── fcc.py                           # FCC filing scraper (47 CFR § 0.457)\n│   ├── ifixit.py                        # iFixit API v2.0 client\n│   ├── device_registry.py               # 48 revisions across 10 product families\n│   └── board_sourcer.py                 # Multi-source image acquisition\n├── learning/\n│   └── engine.py                        # Persistent component knowledge base\n├── plugins/\n│   ├── base.py                          # Plugin protocol + entry-point discovery\n│   └── builtin/\n│       ├── debug_interfaces.py          # JTAG/UART/SWD/SPI/I2C detection\n│       ├── glitch_surface.py            # Voltage/clock/EMFI fault injection surfaces\n│       └── boot_mode.py                 # MCU boot mode pin detection (9 families)\n└── export/\n    ├── bom.py                           # BOM generator (JSON, CSV, SVG table)\n    ├── html_report.py                   # Self-contained HTML assessment report\n    ├── kicad.py                         # KiCad netlist + PCB placement exporter\n    ├── pinout_diagram.py                # Debug header pinout diagrams\n    ├── sigrok.py                        # Sigrok/PulseView session export\n    ├── firmware_extract.py              # Flashrom command + SPI wiring generator\n    ├── entropy_svg.py                   # Entropy heatmap SVG visualizer\n    ├── sbom.py                          # SPDX 2.3 + CycloneDX 1.5 SBOM export\n    └── svg.py                           # Dark-theme SVG: zones, traces, security, topology\n```\n\n## Design Decisions\n\nEvery design choice reflects a real constraint encountered during hardware assessments.\n\n**Dual-space color segmentation (HSV + LAB) over single-space.** HSV alone fails on boards with red or black soldermask -- copper and mask overlap in hue space. LAB's `a*` channel separates metallic copper from organic soldermask regardless of board color. Running both and intersecting costs ~15ms per frame but eliminates an entire class of false negatives on production boards.\n\n**AC-3 arc consistency over SAT/SMT solvers.** Z3 can encode PCB constraints but the encoding itself becomes the bottleneck above 200 nodes. AC-3 propagates in O(ed^3) and is fast enough for real-time probe feedback. The trade-off: no backtracking search. In practice, PCB constraints are sparse enough that AC-3 resolves 85-95% of inferable connections without it.\n\n**Shannon entropy over brute-force pin scanning.** JTAGulator-style exhaustive scanning requires O(n^2) measurements. Bayesian information gain converges in 6-10 measurements on typical boards. The Dirichlet prior incorporates domain knowledge (pin names, proximity to power planes) without hard-coded rules.\n\n**OpenCV contour fallback over requiring YOLO.** Many assessments happen on air-gapped systems without CUDA. The contour-based detector (adaptive threshold, morphological filtering, contour hierarchy) is less accurate but runs anywhere Python runs. The pipeline falls back transparently.\n\n**Local fuzzy matching over cloud APIs (Octopart, Digi-Key).** Cloud lookups need API keys, rate limits, and network access -- none of which are available in a SCIF or during a field assessment. The built-in 128-part DB covers parts most commonly found in consumer and enterprise hardware. Unknown markings are queued for later identification rather than blocking the pipeline.\n\n**Zhang-Suen skeletonization over medial axis transform.** Medial axis produces cleaner centerlines but is 3-5x slower and sensitive to boundary noise from real PCB photos. Zhang-Suen is a lookup-table thinning pass -- fast, deterministic, and robust to jagged edges. Width estimation uses distance transform on the pre-skeleton mask, so skeleton quality does not affect width accuracy.\n\n---\n\n## Quick Start\n\n```bash\n# Install -- works immediately, no model downloads\npip install git+https://github.com/ericrihm/retrace.git\n\n# Full analysis: detect + OCR + trace + identify + advise\nretrace scan board_photo.jpg\n\n# Interactive layered SVG output\nretrace scan board_photo.jpg --format svg --output ./analysis\n\n# Bayesian probe advisor -- where to measure next\nretrace advise board_photo.jpg\n\n# HTML assessment report -- datasheet links, CWE references, sortable BOM\nretrace report-html board_photo.jpg --output assessment.html\n\n# KiCad netlist -- import into EDA for schematic reconstruction\nretrace export-kicad board_photo.jpg --output board.net\n\n# Pinout diagrams -- annotated debug header close-ups with probe wiring guides\nretrace pinout board_photo.jpg --output ./pinouts\n\n# AC-3 constraint solver -- infer missing connections\nretrace solve board_photo.jpg --output solver_result.txt\n\n# Compare two board revisions\nretrace compare board_v04.jpg board_v05.jpg\n\n# Search FCC filings + iFixit teardowns\nretrace search \"cisco asa\"\n\n# Machine-readable output for pipeline integration\nretrace identify STM32F030 --json\nretrace debug board_photo.jpg --json\n```\n\n### Optional ML Dependencies\n\n```bash\npip install \"retrace-pcb[detection] @ git+https://github.com/ericrihm/retrace.git\"  # YOLO v8 + ONNX Runtime\npip install \"retrace-pcb[ocr] @ git+https://github.com/ericrihm/retrace.git\"        # EasyOCR\npip install \"retrace-pcb[web] @ git+https://github.com/ericrihm/retrace.git\"        # Gradio web UI\npip install \"retrace-pcb[all] @ git+https://github.com/ericrihm/retrace.git\"        # Everything\n```\n\n---\n\n## Built For\n\n- **Hardware penetration testing** -- map debug interfaces, trust chains, and glitch surfaces during IoT/embedded security assessments\n- **Supply chain verification** -- cross-reference component markings against known BOMs to flag counterfeit, remarked, or substituted parts\n- **Incident response** -- rapid board triage in the field when you have a device but no documentation\n- **Research and training** -- reproducible PCB RE methodology for academic labs, CTF challenges, and security training courses\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/examples/terminal_demo.svg\" width=\"700\" alt=\"retrace terminal demo — scan a PCB photo, get components, traces, debug interfaces, and probe recommendations\"/\u003e\n\u003c/div\u003e\n\n### Demo: Dual-Board Analysis\n\nTwo boards. Two worlds. Both analyzed from photos alone. Demo uses synthetic PCB renders with verified real-world component data (BOM, pinouts, debug interfaces, attack paths are all real). Synthetic images are used because iFixit photos are [CC BY-NC-SA](https://www.ifixit.com/Info/Licensing) (incompatible with MIT) and neither device has FCC internal photos available. Run `retrace scan your_board.jpg` on a real photo for the full experience -- see [Known Limitations](#known-limitations) for photo requirements.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Xbox One Model 1540 (Durango) -- Gaming Console RE**\n\n\u003cimg src=\"docs/examples/xbox_annotated.svg\" width=\"100%\" alt=\"Xbox One Model 1540 Durango — AMD Liverpool APU, 155 components, functional zones\"/\u003e\n\nAMD Liverpool APU (BGA-1170), 8x SK Hynix DDR3, Southbridge X861949, SK Hynix eMMC -- 150 components, 12 functional zones (CPU, memory, power, I/O, debug, storage, network)\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n**Cisco ASA 5506-X V05 (Rangeley) -- Enterprise Firewall RE**\n\n\u003cimg src=\"docs/examples/cisco_annotated.svg\" width=\"100%\" alt=\"Cisco ASA 5506-X V05 — Intel Atom C2508, Xilinx Spartan-6 Trust Anchor, 177 components, 88 traces, 16 functional zones\"/\u003e\n\nIntel Atom C2508 (Rangeley), Xilinx Spartan-6 Trust Anchor FPGA, 4x DDR3 ECC -- 177 components, 88 traces, 16 functional zones, full Thrangrycat attack path mapped\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Visualization Modes\n\nNine output modes per board -- static overlays, component inventories, debug pinouts, circuit topology diagrams, and interactive layered SVGs with Google Maps-style layer toggles:\n\n---\n\n#### Board Analysis\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/cisco_annotated.svg\" width=\"100%\" alt=\"Cisco ASA 5506-X annotated board\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco ASA -- Annotated\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e177 components, BOM overlay, trace routing, security findings\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/cisco_attack_surface.svg\" width=\"100%\" alt=\"Cisco ASA 5506-X attack surface\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco ASA -- Attack Surface\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eThrangrycat: JTAG to CPU to FPGA from unencrypted SPI flash\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/cisco_zones.svg\" width=\"100%\" alt=\"Cisco ASA 5506-X zone map\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco ASA -- Zones\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e16 functional zones -- CPU, memory, VRM, Trust Anchor FPGA\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/xbox_annotated.svg\" width=\"100%\" alt=\"Xbox One 1540 annotated board\"/\u003e\u003cbr/\u003e\u003cb\u003eXbox One -- Annotated\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e150 components -- APU, DDR3, Southbridge, eMMC, debug headers\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/xbox_attack_surface.svg\" width=\"100%\" alt=\"Xbox One 1540 attack surface\"/\u003e\u003cbr/\u003e\u003cb\u003eXbox One -- Attack Surface\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eJTAG to AMD Liverpool APU to eMMC, Southbridge\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/xbox_zones.svg\" width=\"100%\" alt=\"Xbox One 1540 zone map\"/\u003e\u003cbr/\u003e\u003cb\u003eXbox One -- Zones\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e12 functional zones -- CPU, memory, power, I/O, debug, storage\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n#### Bill of Materials\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/examples/cisco_bom_table.svg\" width=\"100%\" alt=\"Cisco ASA 5506-X BOM table\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco ASA 5506-X -- 177 Components\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eGrouped by type (IC, connector, passive) with color-coded badges, part numbers, OCR markings, packages, and per-component confidence bars. 24.3% identification rate.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/examples/xbox_bom_table.svg\" width=\"100%\" alt=\"Xbox One 1540 BOM table\"/\u003e\u003cbr/\u003e\u003cb\u003eXbox One Model 1540 -- 150 Components\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eFull inventory with confidence scoring. AMD Liverpool APU, SK Hynix DDR3 banks, eMMC storage, voltage regulators identified by OCR + database matching.\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n#### Debug Interface Pinouts\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/cisco_jtag_pinout.svg\" width=\"100%\" alt=\"Cisco JTAG 20-pin pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco JTAG -- J15\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e20-pin ARM standard. TDI/TDO/TCK/TMS/TRST. Wiring for J-Link, Bus Pirate, FTDI.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/cisco_uart_pinout.svg\" width=\"100%\" alt=\"Cisco UART console pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco UART -- J10\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eSerial console. TX/RX/GND labeled. Bus Pirate + FTDI FT232 wiring. Baud rates.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\u003cimg src=\"docs/examples/xbox_jtag_pinout.svg\" width=\"100%\" alt=\"Xbox JTAG pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eXbox JTAG -- J5\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eDebug header. Pin labels, J-Link / Bus Pirate / FTDI / OpenOCD wiring tables.\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n#### IC Package Pinouts\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"25%\"\u003e\u003cimg src=\"docs/examples/W25Q128_IC_pinout.svg\" width=\"100%\" alt=\"W25Q128 SOIC-8 SPI flash pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eW25Q128 -- SOIC-8\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eSPI flash. CS#/MISO/MOSI/CLK/VCC/GND. Flashrom extraction guide.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"25%\"\u003e\u003cimg src=\"docs/examples/AT24C256_IC_pinout.svg\" width=\"100%\" alt=\"AT24C256 SOIC-8 EEPROM pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eAT24C256 -- SOIC-8\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eI2C EEPROM. SDA/SCL/A0-A2/WP/VCC/GND.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"25%\"\u003e\u003cimg src=\"docs/examples/STM32F103_IC_pinout.svg\" width=\"100%\" alt=\"STM32F103 TQFP-48 MCU pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eSTM32F103 -- TQFP-48\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eARM Cortex-M3 MCU. 48-pin quad layout with SWD/JTAG debug.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"25%\"\u003e\u003cimg src=\"docs/examples/iCE40UP5K_IC_pinout.svg\" width=\"100%\" alt=\"iCE40UP5K QFN-24 FPGA pinout\"/\u003e\u003cbr/\u003e\u003cb\u003eiCE40UP5K -- QFN-24\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eLattice FPGA. 24-pin quad layout with configuration pins.\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n#### Circuit Topology\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/examples/power_tree.svg\" width=\"100%\" alt=\"Power tree voltage rail topology\"/\u003e\u003cbr/\u003e\u003cb\u003ePower Tree\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eSchematic-style voltage rail topology -- input sources, regulators, and load paths. Auto-generated from component detection.\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/examples/bus_topology.svg\" width=\"100%\" alt=\"Bus topology protocol interconnection graph\"/\u003e\u003cbr/\u003e\u003cb\u003eBus Topology\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eProtocol-aware component interconnection graph -- SPI, I2C, JTAG, UART buses with color-coded nodes by component type.\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n#### Interactive Layered SVG\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/examples/cisco_interactive.svg\" width=\"100%\" alt=\"Cisco ASA interactive SVG\"/\u003e\u003cbr/\u003e\u003cb\u003eCisco ASA 5506-X\u003c/b\u003e\u003cbr/\u003e\u003csub\u003e9 layers, 10 presets, 3 styles (Photo / Schematic / X-Ray). JavaScript-powered -- open in any browser. \u003ca href=\"https://ericrihm.github.io/retrace/examples/cisco_interactive.svg\"\u003eOpen in browser\u003c/a\u003e\u003c/sub\u003e\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\u003cimg src=\"docs/examples/xbox_interactive.svg\" width=\"100%\" alt=\"Xbox One interactive SVG\"/\u003e\u003cbr/\u003e\u003cb\u003eXbox One Model 1540\u003c/b\u003e\u003cbr/\u003e\u003csub\u003eSame layer system. Toggle components, traces, zones, security findings, power rails, BOM panel, net labels, grid. \u003ca href=\"https://ericrihm.github.io/retrace/examples/xbox_interactive.svg\"\u003eOpen in browser\u003c/a\u003e\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e **Interactive layered SVG**: `retrace scan board.jpg --format svg` generates a single self-contained SVG with **9 toggleable layers**, **10 view presets**, and **3 rendering styles** -- like switching between Satellite, Terrain, and Roadmap on Google Maps. **Layers:** Board Image, Components, Traces, Zones, Security, Power Rails, BOM Panel, Net Labels, Grid Reference. **Styles:** Photo (board image with overlays), Schematic (vector-only, no photo), X-Ray (dimmed photo, high-contrast overlays). **Presets:** Satellite (photo only), Analysis (default), Schematic, X-Ray, Attack Surface, Recon, Power Map, Zones, Debug, All Layers. JavaScript-powered floating control panel -- open in any browser, no server needed.\n\n\u003e **Pinout diagrams**: `retrace pinout board.jpg` crops the board image around each detected debug interface, labels every pin by function (data, clock, power, ground, control, debug), and includes probe wiring guides for J-Link, Bus Pirate, FTDI FT232H, ST-Link V2, flashrom, and OpenOCD. Supports JTAG (20/14/10-pin), SWD (10/4/2-pin), UART (4/3/6-pin), SPI (8/6/4-pin), and I2C (4/2-pin) layouts. Voltage warnings and common baud rate references included.\n\n\u003e **Assessment reports**: `retrace report-html board.jpg` generates a self-contained HTML deliverable with executive summary, security findings (CWE hyperlinks, CVSS 3.1 scores, MITRE ATT\u0026CK technique IDs), sortable component inventory (datasheet links), and print-friendly styling. Live previews: [Cisco ASA 5506-X report](https://ericrihm.github.io/retrace/examples/cisco_report.html) / [Xbox One report](https://ericrihm.github.io/retrace/examples/xbox_report.html)\n\n\u003e **How Thrangrycat works (CVE-2019-1649):** Cisco's Trust Anchor module (TAm) is a Xilinx Spartan-6 FPGA that verifies boot image integrity on ASA, IOS-XE, and NX-OS platforms. The FPGA loads its bitstream from an external SPI flash chip (W25Q128JV on the 5506-X) at power-on -- and that bitstream is **not authenticated or encrypted**. An attacker with root access (or physical access to the SPI flash) can modify the bitstream to disable secure boot verification entirely, creating a persistent backdoor that survives firmware updates. re:trace maps this path automatically: it identifies the FPGA, traces the SPI flash connection, flags the unencrypted bitstream interface, and marks the JTAG header that provides the initial access vector. This is the same attack surface exploited by the **ArcaneDoor** state-sponsored campaign (2024), which prompted CISA Emergency Directive ED 25-03.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCisco ASA 5506-X -- Debug Interface Detection\u003c/b\u003e\u003c/summary\u003e\n\n```\nTotal findings: 2  (HIGH=1  MEDIUM=1)\n\n  [HIGH] CVSS 7.6  JTAG\n         Component : J15  (connector)\n         Marking   : JTAG\n         Detail    : JTAG debug interface — full CPU debug/program access\n         CWE       : CWE-1191\n         ATT\u0026CK    : T1200, T0839\n         CVSS      : CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H\n\n  [MEDIUM] CVSS 6.8  UART\n         Component : J10  (connector)\n         Marking   : CONSOLE\n         Detail    : UART/serial console — may expose bootloader or root shell\n         CWE       : CWE-1299\n         ATT\u0026CK    : T1200\n         CVSS      : CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCisco ASA 5506-X -- Constraint Solver\u003c/b\u003e -- 269 nodes, 88 AC-3 iterations\u003c/summary\u003e\n\n```\nAC-3 iterations: 88  |  269 nodes  |  3 inferred connections\n\n  [POWER]   U1.VCC, U2-U5.VDD/VDDQ, U6.VCC, U10-U12.VIN, J14.VCC_12V\n  [GROUND]  U1.GND, J1-J9.GND, J10-J15.GND, U10-U12.GND (36 nodes)\n\n  Inferred: U1.VCC  ↔  U11.SW         (VRM output to CPU core rail)\n  Inferred: U6.TRUST_VERIFY ↔ U11.SW  (FPGA Trust Anchor verification via power rail)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCisco ASA 5506-X -- Probe Advisor\u003c/b\u003e -- Bayesian information-gain ranking\u003c/summary\u003e\n\n```\nTop 5 Probe Recommendations (269 nodes, Dirichlet belief):\n\n  #1  U1.DDR3_DQ0   EIG: 4.807 bits    most likely net: VCC_CORE (3.6%)\n  #2  U1.DDR3_A0    EIG: 4.807 bits    most likely net: VCC_CORE (3.6%)\n  #3  U1.PCIE_TX0   EIG: 4.807 bits    most likely net: VCC_CORE (3.6%)\n  #4  U1.PCIE_RX0   EIG: 4.807 bits    most likely net: VCC_CORE (3.6%)\n  #5  U1.SATA_TX    EIG: 4.807 bits    most likely net: VCC_CORE (3.6%)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eXbox One Model 1540 -- Debug Interface Detection\u003c/b\u003e\u003c/summary\u003e\n\n```\nTotal findings: 1  (HIGH=1)\n\n  [HIGH] CVSS 7.6  JTAG\n         Component : J5  (connector)\n         Marking   : JTAG\n         Detail    : JTAG debug interface — full CPU debug/program access\n         CWE       : CWE-1191\n         ATT\u0026CK    : T1200, T0839\n         CVSS      : CVSS:3.1/AV:P/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H\n```\n\n\u003c/details\u003e\n\n## Prior Work\n\nEvery existing tool either requires design files, only handles one stage, or needs manual annotation:\n\n| Capability | [pcbre](https://github.com/pcbre/pcbre) | [OpenBoardView](https://github.com/OpenBoardView/OpenBoardView) | KiCad | [tracespace](https://github.com/tracespace/tracespace) | [JTAGulator](https://github.com/grandideastudio/jtagulator) | **re:trace** |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|\n| **Input** | Photo | `.brd` files | Schematic | Gerber | Physical pins | **Photo** |\n| Auto-detect components | Manual | - | - | - | - | **YOLO v8** |\n| OCR markings to datasheet | - | - | - | - | - | **EasyOCR** |\n| Trace extraction | Manual | - | - | Render only | - | **Automated** |\n| Infer missing connections | - | - | - | - | - | **AC-3** |\n| Optimal probe selection | - | - | - | - | Brute-force | **Bayesian** |\n| Cross-board learning | - | - | - | - | - | **Persistent** |\n| BOM from photo | - | - | Schematic only | - | - | **Yes** |\n| KiCad netlist export | - | - | Native | - | - | **From photo** |\n| FCC image search | - | - | - | - | - | **Built-in** |\n| Debug interface detection | - | - | - | - | Pin scan | **Pattern match** |\n| Plugin system | - | - | Yes | - | - | **Entry-point** |\n| Zero ML deps option | N/A | N/A | N/A | N/A | N/A | **Yes** |\n\nThe closest academic precedents are [Kleber et al. (USENIX WOOT 2017)](https://www.usenix.org/system/files/conference/woot17/woot17-paper-kleber.pdf) -- automated PCB RE from photos -- which is now 8 years old with no public follow-on tool, and [Kleber et al. (Scientific Reports 2024)](https://www.nature.com/articles/s41598-024-84635-2) on automated 3D PCB X-ray CT netlist extraction. Recent YOLO PCB papers ([EC-YOLO 2024](https://www.mdpi.com/1424-8220/24/13/4363), [FPIC-Component 2023](https://www.mdpi.com/2079-9292/12/11/2450)) target manufacturing defect detection, not reverse engineering. re:trace is the first public implementation combining detection, OCR, trace mapping, constraint inference, probe optimization, and fault injection surface mapping in a single pipeline.\n\n## For Security Researchers\n\nre:trace maps to the standard hardware assessment workflow -- recon through reporting:\n\n| Assessment Phase | What You Need | re:trace Feature |\n|---|---|---|\n| **Recon** | Board photos without opening the case | FCC filing search (47 CFR 0.457, public domain) + iFixit teardown API |\n| **Attack surface mapping** | Identify MCUs, flash, FPGAs, crypto ICs | YOLO v8 detection + OCR + 128-part fuzzy matcher with datasheet links |\n| **Trust chain analysis** | Map FPGA to SPI flash to CPU paths | Automated trace extraction + constraint solver (see Thrangrycat path above) |\n| **Debug interface discovery** | Find JTAG, SWD, UART, SPI headers | Pattern-match detection with CWE references (CWE-1191, CWE-1299) |\n| **Optimal probing** | Where to put the multimeter next | Bayesian advisor: 6-10 measurements to convergence |\n| **Partial trace recovery** | Board has 60% visible traces | AC-3 constraint propagation infers the rest |\n| **Cross-board analysis** | Transfer knowledge between targets | 15 subcircuit patterns auto-recognized across boards |\n| **Fault injection recon** | Map glitch surfaces before bringing equipment | Power rail tracing, VRM/LDO/clock identification, decoupling cap mapping |\n| **Reporting** | Deliverable for the client | Self-contained HTML report (datasheet links, CWE references, sortable BOM), KiCad netlist, SVG overlays, attack surface visualization |\n\nre:trace complements firmware analysis tools (Ghidra, Binary Ninja) and hardware debug tools (OpenOCD, JTAGulator) -- it bridges the gap between having a board in your hands and knowing where to probe.\n\n### Assessment Deliverables\n\nOne command generates the full artifact set that a hardware security engagement delivers:\n\n```bash\nretrace scan board.jpg --bom --format svg --output ./analysis\nretrace report-html board.jpg --output ./analysis/report.html\nretrace export-kicad board.jpg --output ./analysis/board.net\nretrace pinout board.jpg --output ./analysis/pinouts\n```\n\n| Artifact | Format | What It Contains |\n|---|---|---|\n| **Assessment Report** | `.html` | Executive summary, security findings (CWE-linked), sortable BOM with datasheet hyperlinks, component confidence scores -- self-contained, no external dependencies |\n| **KiCad Netlist** | `.net` | Reconstructed schematic netlist importable into KiCad 5/6/7/8 -- components mapped to footprint libraries, nets derived from trace extraction |\n| **Attack Surface Map** | `.svg` | Dimmed board overlay highlighting security-critical ICs, attack path arrows with labels (e.g. JTAG to CPU to FPGA from SPI flash) |\n| **Functional Zone Map** | `.svg` | Color-coded functional zone overlay -- CPU, memory, power, I/O, debug, storage, network, Trust Anchor |\n| **BOM Table** | `.svg` / `.json` / `.csv` | Grouped components with type badges, confidence bars, part numbers, values, packages |\n| **Annotated Board** | `.svg` | Full component overlay with BOM callouts, trace routing, and security findings |\n| **Pinout Diagrams** | `.svg` | Cropped debug header close-ups with pin labels, color-coded function groups, probe wiring guides (J-Link, Bus Pirate, FTDI, ST-Link), voltage warnings |\n| **Debug Report** | `.txt` | JTAG/SWD/UART/SPI detection with severity ratings and CWE references |\n| **Probe Plan** | `.txt` | Bayesian-ranked probe recommendations with expected information gain in bits |\n| **Constraint Solution** | `.txt` | AC-3 inferred connections -- power nets, ground nets, signal paths |\n\n## API Examples\n\n```python\nfrom retrace.core.pipeline import Pipeline\n\n# Full pipeline: photo → analysis result\npipeline = Pipeline()\nresult = pipeline.run(\"board_photo.jpg\")\n\nprint(f\"Found {len(result.components)} components, {len(result.traces)} traces\")\nfor c in result.components:\n    print(f\"  {c.label}: {c.marking or 'unknown'} ({c.confidence:.0%})\")\n```\n\n```python\nfrom retrace.analysis.probe_advisor import ProbeAdvisor, Measurement\n\nadvisor = ProbeAdvisor()\nadvisor.add_components(result.components)\n\n# Top 5 probe recommendations ranked by information gain\nfor rec in advisor.recommend(top_k=5):\n    print(f\"Probe {rec.node_id}: expected gain = {rec.score:.3f} bits\")\n\n# Feed back a measurement — beliefs update + propagate\nadvisor.update(Measurement(node_id=\"J1:3\", kind=\"voltage\", value=3.3))\n```\n\n```python\nfrom retrace.analysis.constraint_solver import ConstraintSolver\n\nsolver = ConstraintSolver()\nresult = solver.solve(components, traces)\nprint(f\"Resolved {len(result.assignments)} pins, inferred {len(result.inferred_traces)} traces\")\n```\n\n```python\nfrom retrace.sources.fcc import search_fcc, download_fcc_photos\n\n# Search + download FCC internal photos for any product\nresults = search_fcc(\"xbox one\")\nphotos = download_fcc_photos(results[0][\"fcc_id\"], dest_dir=\"./fcc_photos\")\n```\n\n```python\nfrom retrace.learning.engine import KnowledgeBase\n\n# Cross-board component knowledge — grows with every scan\nkb = KnowledgeBase()\nprint(f\"{kb.total_sightings} sightings across {kb.board_count} boards\")\nfor comp in kb.top_components(5):\n    print(f\"  {comp.part_number}: seen {comp.frequency}x\")\n```\n\n```python\nfrom retrace.export.kicad import export_kicad_netlist\n\n# Convert analysis result to KiCad schematic for EDA import\nnetlist = export_kicad_netlist(result, title=\"Board Rev A\")\nPath(\"board.net\").write_text(netlist)\n```\n\n## Deep Dive\n\n### Functional Zone Segmentation\n\nThe SVG overlay renders semi-transparent color-coded regions that segment the board into logical subsystems:\n\n| Zone | Color | What It Groups |\n|---|---|---|\n| **CPU** | Cyan | Main processor / SoC / APU |\n| **Memory** | Purple | DDR/SRAM banks, memory controllers |\n| **Power** | Amber | VRMs, inductors, bulk caps, DC input |\n| **I/O** | Green | USB, HDMI, connectors, level shifters |\n| **Debug** | Red | JTAG headers, test points, SWD |\n| **Network** | Blue | Ethernet PHYs, NICs, RJ45 ports |\n| **Storage** | Teal | eMMC, SPI flash, mSATA, eUSB |\n\nZones use dashed borders at 6% fill opacity -- visible enough to orient a researcher, subtle enough not to obscure trace routing. Each zone is an SVG `\u003cg\u003e` element with `data-zone` attributes for programmatic access.\n\n### Bayesian Probe Advisor\n\nGiven partial board knowledge, the advisor recommends where to place your multimeter probes for maximum information gain:\n\n1. Maintains a Dirichlet belief distribution per unresolved node over net-label hypotheses (VCC, GND, SDA, SCL, TX, RX, etc.)\n2. Pin-name priors give 10x weight to likely labels (a pin near \"VCC\" silk gets a power prior)\n3. Ranks all unresolved nodes by expected Shannon entropy reduction\n4. After each measurement, collapses belief at the probed node and propagates through union-find groups\n5. Voltage/resistance/continuity readings are automatically classified to net labels\n\nConverges on unknown pin functions in 6-10 measurements on typical boards.\n\n### Constraint Solver (AC-3)\n\nWhen trace extraction is partial (it always is on real boards), the solver infers missing connections:\n\n- **Pinout rules** -- MCU VDD must connect to power, GND to ground plane\n- **Proximity rules** -- 2-pin cap near IC power pin implies decoupling implies pins are POWER + GND\n- **Differential pair detection** -- IN+/IN- pairs get \"different\" arc constraints\n- **Union-find equality** -- traces with confidence \u003e= 0.5 merge their connected nodes\n- **AC-3 propagation** -- iteratively prunes impossible values until the domain is stable\n\n### Fault Injection Surface Mapping\n\nre:trace maps the power delivery topology to flag glitch surfaces before you bring equipment to the bench:\n\n- **Voltage glitching targets** -- identifies VRMs, LDOs, and their output decoupling capacitors. Tapping or momentarily shorting a decoupling cap on a processor's core rail (VCC_CORE) is the standard voltage fault injection setup for bypassing secure boot checks\n- **Clock glitching targets** -- crystal oscillators and clock distribution ICs are flagged with package and frequency data, identifying where to inject a clock glitch to skip instruction cycles\n- **Power rail mapping** -- the constraint solver classifies power nets and traces which components share rails, so you know which glitch point affects which IC before powering anything on\n\nThis maps directly to the methodology in [Synacktiv's voltage fault injection research](https://www.synacktiv.com/en/publications/how-to-voltage-fault-injection) and IOActive's [HARRIS 2024 chip RE workshop](https://www.ioactive.com/ioactive-presents-at-harris-2024-chip-reverse-engineering-andrew-zonenberg/).\n\n### Component Detection\n\n[YOLO v8](https://docs.ultralytics.com/) fine-tuned on the [FPIC-Component dataset](https://www.mdpi.com/2079-9292/12/11/2450) -- 6,260 images, 29,639 labeled objects, 25 component classes. Detects ICs, capacitors, resistors, connectors, inductors, crystals, test points, debug headers, diodes, and transistors.\n\nFalls back to OpenCV contour detection (adaptive threshold, morphological filtering, contour hierarchy) when YOLO isn't installed. The entire pipeline works with `pip install git+https://github.com/ericrihm/retrace.git` -- zero GPU, zero model downloads.\n\n### Copper Trace Extraction\n\n1. **Dual-space color segmentation** -- HSV + LAB filtering isolates copper, robust across green/blue/red/black soldermask\n2. **Morphological cleanup** -- open/close removes noise, bridges small gaps\n3. **Skeletonization** -- Zhang-Suen thinning extracts trace centerlines\n4. **BFS graph construction** -- 8-connected traversal maps pad-to-pad connectivity\n5. **Width estimation** -- distance transform measures trace width at each point\n\n### Debug Interface Detection\n\nAutomatically flags security-relevant interfaces:\n\n| Interface | Detection Method | Severity |\n|---|---|---|\n| **JTAG** | Header pattern + TDI/TDO/TCK/TMS marking | High |\n| **SWD** | SWDIO/SWCLK near MCU | High |\n| **UART** | TX/RX marking + 3-4 pin header | Medium |\n| **SPI** | MOSI/MISO/SCK/CS near flash/EEPROM | Medium |\n| **I2C** | SDA/SCL marking + pull-up resistors | Low |\n\nEach finding includes the interface type, matched component, and CWE reference.\n\n### Persistent Component Knowledge Base\n\nEvery `retrace scan` builds your component knowledge automatically:\n\n- **Component frequency** -- tracks which parts appear most across boards. After 10+ scans, `retrace report` shows your most-seen ICs, connectors, and passives\n- **Cross-board sightings** -- maps which parts appear on which boards, enabling pattern transfer between targets\n- **Unmatched marking queue** -- OCR'd markings that didn't match the built-in DB are flagged for review. Run `retrace report` to see what needs identifying\n- **Zero config** -- enabled by default, grows silently in the background\n\n### Cross-Board Pattern Recognition\n\n15 subcircuit patterns that transfer between boards -- the more you scan, the faster identification gets:\n\n| Pattern | Components | Identifies |\n|---|---|---|\n| `ldo_supply` | IC + 2 capacitors | Linear voltage regulator |\n| `buck_converter` | IC + inductor + cap | Switching regulator |\n| `rc_lowpass` | Resistor + capacitor | RC low-pass filter |\n| `decoupling_pair` | 2 capacitors near IC | Bulk + bypass decoupling |\n| `pull_up_resistor` | Resistor near IC | I2C/SPI pull-up |\n| `i2c_pullup_pair` | 2 resistors near IC | I2C bus pull-ups |\n| `crystal_oscillator` | Crystal + 2 capacitors | Clock oscillator circuit |\n| `spi_flash_circuit` | Flash IC + resistors + cap | SPI flash with pull-ups |\n| `uart_level_shifter` | IC + connectors | UART voltage translator |\n| `usb_esd_protection` | Diode + USB connector | USB ESD clamping |\n| `usb_connector_circuit` | USB-A/B/C + passives | USB port subsystem |\n| `h_bridge` | 4 FETs + driver IC | Motor driver |\n| `reset_circuit` | Resistor + cap + IC | Power-on reset |\n| `differential_pair_termination` | 2 resistors matched | LVDS/USB/Ethernet termination |\n| `power_indicator_led` | LED + resistor | Power status indicator |\n\n\u003c!-- STATS:patterns --\u003e15\u003c!-- /STATS --\u003e built-in patterns. Extensible via plugins.\n\n### FCC Filing Pipeline\n\nThe FCC won't let any device be sold without filing internal board photos -- and those photos are **public domain** under [47 CFR 0.457](https://www.law.cornell.edu/cfr/text/47/0.457):\n\n```bash\nretrace search \"cisco asa\"\n#\n#   Cisco ASA (Cisco)\n#   ──────────────────────────────────────────────────\n#     1. ASA 5505 Base  (2006)               FCC: N/A-wired\n#     2. ASA 5506-X  (2015)                  FCC: N/A-wired   [Thrangrycat, ArcaneDoor]\n#     3. ASA 5506W-X  (2015)                 FCC: LDKASA-AP702\n#     4. ASA 5508-X  (2015)                  FCC: N/A-wired\n#     5. ASA 5515-X  (2012)                  FCC: N/A-wired\n#     ...\n#\nretrace search \"xbox one\"\n#\n#   Xbox One (Microsoft)\n#   ──────────────────────────────────────────────────\n#     1. Xbox One (Original)  (2013)      FCC: C3K1520   iFixit #19718  [Durango]\n#     2. Xbox One S  (2016)               FCC: C3K1681   iFixit #65572\n#     3. Xbox One S All-Digital  (2019)   FCC: C3K1832\n#     4. Xbox One X  (2017)               FCC: C3K1698   iFixit #99609  [Scorpio]\n```\n\nAlso searches [iFixit](https://www.ifixit.com/) teardowns via API v2.0 for high-resolution step-by-step board photos.\n\n**Built-in device registry** covers 10 product families and 48 hardware revisions -- Xbox One (7), Xbox Series (3), PlayStation 5 (9), Nintendo Switch (4), Steam Deck (2), Raspberry Pi (5), Ubiquiti UniFi (4), Ring Doorbell (3), **Cisco ASA** (8: 5505, 5506-X, 5506W-X, 5508-X, 5510, 5515-X, 5516-X), and **Cisco Catalyst** (3: 2960-X, 3560-X) -- with FCC IDs, SoC specs, RAM, storage, security notes (Thrangrycat, AVR54, ArcaneDoor), and iFixit guide IDs. Search by product name, codename, model number, or FCC ID.\n\n### Probing Guide -- Budget Equipment for PCB RE\n\nre:trace tells you *where* to probe. Here's *what* to probe with -- optimized for maximum RE capability per dollar.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eEquipment tiers: $63 starter to $500 full lab\u003c/b\u003e\u003c/summary\u003e\n\n**Starter Kit (~$63) -- covers UART/SPI/JTAG on most targets:**\n\n| Item | Price | What It Does |\n|---|---|---|\n| Spring pogo pins (P75-B1, 0.68mm tip) | ~$5/50pc | Probe test points and breakout vias without soldering |\n| Saleae Logic clone (24MHz/8ch) | ~$10 | Capture UART, I2C, SPI, JTAG with PulseView/Sigrok |\n| MG Chemicals flux pen (no-clean) | ~$8 | Essential for bodge wire attachment |\n| Bus Pirate v4 clone | ~$15 | Interactive UART/SPI/I2C/JTAG -- slow but universal |\n| PCB holder/clamp (Panavise style) | ~$15 | Hands-free board access |\n| Black Magic Probe clone | ~$25 | ARM JTAG/SWD with built-in GDB server, no drivers |\n\n**Mid-tier additions (~$200 total):**\n\n| Item | Price | What It Does |\n|---|---|---|\n| DSLogic Plus (400MHz/16ch) | ~$149 | High-speed logic capture -- SPI at 50MHz+, protocol decode |\n| Andonstar USB microscope (AD407) | ~$70 | Read 0402 markings, guide pogo placement, inspect solder joints |\n| 0.3mm solder + 30AWG magnet wire | ~$12 | Solder to 0402 pads and BGA breakout vias under scope |\n\n**Full lab (~$500 total):**\n\n| Item | Price | What It Does |\n|---|---|---|\n| Rigol DS1054Z oscilloscope | ~$350 | Signal integrity, analog capture, 4ch decode. Hackable to 100MHz |\n| Yihua 858D hot air station | ~$65 | Remove QFP/SOIC for flash dump, BGA inspection |\n\n**Trace width to probe tip guide:**\n\n| Pad / Trace | Minimum Probe |\n|---|---|\n| \u003e 0.5mm (0603+) | IC hook clip or 0.5mm pogo |\n| 0.3-0.5mm (0402) | P50-Q sharp pogo (0.5mm tip) |\n| \u003c 0.3mm (0201, BGA breakout) | 30AWG magnet wire soldered under microscope |\n\n**Workflow: re:trace to probe to capture:**\n\n1. `retrace scan board.jpg` -- identify components and debug interfaces\n2. `retrace advise board.jpg` -- get probe priority list ranked by information gain\n3. Solder 30AWG wire to highest-EIG test point under microscope, strain-relief with kapton tape\n4. Connect logic analyzer, auto-detect baud in PulseView\n5. Feed measurement back into the model, re-run `retrace advise` for updated rankings\n6. Repeat until convergence (typically 6-10 measurements)\n\n\u003c/details\u003e\n\n### Plugin System\n\n```python\nfrom retrace.plugins.base import AnalyzerPlugin\n\nclass MyAnalyzer(AnalyzerPlugin):\n    name = \"my-analyzer\"\n\n    def analyze(self, components, traces):\n        return {\"findings\": [...]}\n```\n\n```toml\n# pyproject.toml — register via entry points\n[project.entry-points.\"retrace.plugins\"]\nmy_analyzer = \"my_package:MyAnalyzer\"\n```\n\n## Stats\n\n| Metric | Value |\n|--------|-------|\n| Tests | \u003c!-- STATS:tests --\u003e1905\u003c!-- /STATS --\u003e |\n| Coverage | \u003c!-- STATS:coverage --\u003e99%\u003c!-- /STATS --\u003e |\n| Modules | \u003c!-- STATS:modules --\u003e33\u003c!-- /STATS --\u003e |\n| Lines of code | \u003c!-- STATS:loc --\u003e16465\u003c!-- /STATS --\u003e |\n| Component DB | \u003c!-- STATS:components --\u003e196\u003c!-- /STATS --\u003e parts |\n| Circuit patterns | \u003c!-- STATS:patterns --\u003e15\u003c!-- /STATS --\u003e built-in |\n\n\u003csub\u003eAuto-updated by \u003ccode\u003etools/readme_stats.py\u003c/code\u003e\u003c/sub\u003e\n\n## Development\n\n```bash\ngit clone https://github.com/ericrihm/retrace.git\ncd retrace\npip install -e \".[dev]\"\npytest                         # \u003c!-- STATS:tests --\u003e1905\u003c!-- /STATS --\u003e tests, \u003c1s\nruff check src/ tests/         # lint\nretrace --help                 # CLI reference\n```\n\nCI runs on Python 3.10, 3.11, and 3.12 with coverage uploaded to Codecov.\n\n## Responsible Use\n\nre:trace is a **read-only analysis tool**. It does not write to target hardware, inject firmware, or exploit vulnerabilities. No exploit code is included or referenced. If you discover a vulnerability using re:trace, please follow [coordinated disclosure](https://www.cisa.gov/coordinated-vulnerability-disclosure-process) practices.\n\n## Known Limitations\n\n**Photo requirements.** re:trace works best with high-resolution top-down photos (\u003e=8MP, even lighting, minimal glare). Angled shots, blurry images, and photos with heavy shadowing degrade detection accuracy. For best results, use a scanner or a phone camera mounted directly above the board.\n\n**Synthetic demo images.** The demo boards (Cisco ASA, Xbox One) use synthetic PCB images with verified real-world component data. The component list, trace routing, and debug interfaces are accurate to the real hardware, but the images are rendered rather than photographed. This means the demo represents the analysis output accurately while avoiding IP/NDA issues with real board photos.\n\n**Trace extraction fidelity.** Copper trace extraction from photos is inherently noisy. Expect 40-70% trace recovery on typical boards -- the constraint solver exists specifically to fill the gaps. Multi-layer boards have traces on inner layers that are physically invisible from surface photos.\n\n**Component DB coverage.** The built-in database covers 128 parts. Uncommon or new parts will be OCR'd but not identified. Use `retrace learn` to add parts, or file a PR to expand the DB.\n\n**No inner-layer analysis.** re:trace analyzes the visible surface only. Via stitching, buried traces, and internal planes require X-ray CT imaging (see [Kleber et al. 2024](https://www.nature.com/articles/s41598-024-84635-2)).\n\n## Tested Hardware\n\nThe pipeline has been tested against:\n\n| Board | Components | Traces | Zones | Security Findings |\n|---|---|---|---|---|\n| **Xbox One (Model 1540)** | 150 (34 ICs, 10 connectors, 56 caps, 29 resistors, 15 test points, 5 inductors, 1 crystal) | 68 | 12 | JTAG header (HIGH) |\n| **Cisco ASA 5506-X** | 177 (20 ICs, 8 RJ45, 20 CPU caps, 10 FPGA caps, 8 DDR3 caps, 16 VRMs, 16 network magnetics, 10 test points) | 88 | 16 | JTAG + UART console + Thrangrycat SPI path (HIGH/MED) |\n\nThe device registry covers **10 product families** with 48 hardware revisions: Xbox One/Series, PlayStation 5, Nintendo Switch, Steam Deck, Raspberry Pi, Ubiquiti UniFi, Ring Doorbell, Cisco ASA, and Cisco Catalyst -- including SoC specs, FCC IDs, iFixit guide IDs, and security advisories (Thrangrycat, AVR54, ArcaneDoor).\n\n## Legal\n\n- **FCC internal photos** -- public domain under [47 CFR 0.457](https://www.law.cornell.edu/cfr/text/47/0.457)\n- **iFixit images** -- used under [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/) (Xbox One teardown photos by [iFixit](https://www.ifixit.com/Teardown/Xbox+One+Teardown/19718))\n- **No firmware files** or exploit code included or referenced\n- **Component datasheets** -- linked via URL, never redistributed\n- **Detection models** -- trained exclusively on public datasets ([FPIC-Component](https://www.mdpi.com/2079-9292/12/11/2450), CC-licensed images)\n\n## License\n\nMIT -- use it for research, pentests, product teardowns, education, whatever.\n\n## Author\n\nBuilt by [Eric Rihm](https://github.com/ericrihm) -- [hello@cobaltsystems.io](mailto:hello@cobaltsystems.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericrihm%2Fretrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericrihm%2Fretrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericrihm%2Fretrace/lists"}