Go to file

Kieran Klukas acd1ff0112 fix: switch linux builds to musl for glibc compatibility

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-25 21:45:24 -08:00

.github/workflows

fix: switch linux builds to musl for glibc compatibility

2026-02-25 21:45:24 -08:00

src

feat: add api tools

2026-02-25 21:32:27 -08:00

.gitignore

feat: init

2026-02-25 19:06:11 -05:00

Cargo.lock

chore: bump version to 0.2.0

2026-02-25 21:39:16 -08:00

Cargo.toml

chore: bump version to 0.2.0

2026-02-25 21:39:16 -08:00

demo.tape

docs: add demo gif

2026-02-25 19:55:25 -05:00

LICENSE.md

Add project templates

2026-02-25 19:06:47 -05:00

README.md

feat: add api tools

2026-02-25 21:32:27 -08:00

README.md

rust-ectf-tools

Drop-in replacement for MITRE's uvx ectf CLI, rewritten in Rust with reliable serial I/O. Uses raw termios instead of pyserial to avoid macOS CDC-ACM data corruption bugs.

Install

brew install taciturnaxolotl/tap/ectf-tools

Or build from source:

cargo build --release

Usage

HSM Host Tools

# List files on the HSM
ectf-tools tools /dev/tty.usbmodemXXX list 1a2b3c

# Write a file
ectf-tools tools /dev/tty.usbmodemXXX write 1a2b3c 0 0x4321 myfile.bin

# Read a file
ectf-tools tools /dev/tty.usbmodemXXX read 1a2b3c 1 ./output/

# Interrogate a connected HSM
ectf-tools tools /dev/tty.usbmodemXXX interrogate 1a2b3c

# Listen for another HSM
ectf-tools tools /dev/tty.usbmodemXXX listen

# Receive a file from another HSM
ectf-tools tools /dev/tty.usbmodemXXX receive 1a2b3c 0 1

Hardware Bootloader Tools (MSPM0L2228)

# Check bootloader version and status
ectf-tools hw /dev/tty.usbmodemXXX status

# Erase the current design
ectf-tools hw /dev/tty.usbmodemXXX erase

# Flash an image (name auto-derived from filename for unprotected images)
ectf-tools hw /dev/tty.usbmodemXXX flash design.bin
ectf-tools hw /dev/tty.usbmodemXXX flash design.bin --name mydesign

# Start the flashed design
ectf-tools hw /dev/tty.usbmodemXXX start

# Erase + flash + start in one step (file or directory with hsm.bin)
ectf-tools hw /dev/tty.usbmodemXXX reflash ./build/
ectf-tools hw /dev/tty.usbmodemXXX reflash engineer.hsm/hsm.bin

# Get a file digest from the secure bootloader
ectf-tools hw /dev/tty.usbmodemXXX digest 0

Hardware Bootloader Tools (MAX78000FTHR)

# Flash a design
ectf-tools hw /dev/tty.usbmodemXXX flash-fthr /dev/tty.usbmodemYYY image.bin

# Permanently unlock the secure bootloader (irreversible!)
ectf-tools hw /dev/tty.usbmodemXXX unlock-fthr /dev/tty.usbmodemYYY secrets.json --force --force

Verbosity

-v — protocol-level debug (headers, ACKs, chunk sizes)
-vv — raw byte-level trace with xxd-style hexdump

Why not pyserial?

pyserial has known data corruption issues on macOS with CDC-ACM devices (like the MAX78000). This tool opens the serial port directly with proper termios configuration, flushes the input buffer on open, and uses O_NONBLOCK to avoid blocking on carrier detect.