v1.4.0

BomberCat Tools v1.4.0

Executive Summary

This release brings full first-class support for the EMVyBomberCat firmware to
the BomberCat CLI. A new bombercat emvy … command group lets you read
contactless/EMV cards, tunnel raw APDUs to a live card, read tag UIDs, emulate
magstripe swipes, and emulate NDEF tags or EMV cards — all while streaming each
reader/terminal exchange live. Under the hood, the EMVyBomberCat firmware is now
a recognized member of the device discovery contract, so device, status, and
the auto-flash workflow treat it like every other supported board instead of
reporting it as unknown.

Alongside the new capability, v1.4.0 hardens the safety model around driving
hardware: emvy auto-flashes a board running the wrong firmware under the usual
policy, and then double-checks the firmware's identity over the handshake before
sending any operative command. All of these commands are intended for authorized
security testing and research only.

New Features

• New bombercat emvy command group for boards flashed with EMVyBomberCat:
  • emvy info — confirm the firmware, version, live state, and the operations
    the board exposes.
  • emvy read — read an EMV/contactless card (PAN, expiry, label, AID, Track 2
    equivalent), with a human-readable analysis block plus --json / --raw
    output.
  • emvy apdu — tunnel a raw APDU to a live card, driving the full engage →
    release session automatically (release always fires on exit, even on Ctrl-C).
  • emvy tag — read any nearby tag's protocol, technology, and UID.
  • emvy mag — emulate a one- or two-track magstripe swipe.
  • emvy cardscan + emvy emu card --from-ram — scan a card into device RAM
    and reemulate it to a terminal.
  • emvy emu ndef / emvy emu card — emulate an NDEF tag or an EMV card while
    streaming every reader/terminal APDU live.
  • emvy nfcinfo — PN7150 I2C diagnostic.
  • emvy reboot — reset the MCU (re-enumerates over USB).
• EMVyBomberCat firmware recognition. The firmware now implements the BomberCat
  discovery contract (verified on hardware), so device list / status
  identify it by name and report its capabilities instead of falling back to
  UNKNOWN (PR #4).
• Auto-flashable image. EMVyBomberCat.uf2 ships with the firmware releases, so
  bombercat flash EMVyBomberCat installs it and emvy auto-flashes a board
  running the wrong firmware, like every other group.

Improvements

• Firmware-identity gate for emvy. Because auto-flash may clear a board on a
  boot-banner match (likely, but not certain), emvy additionally verifies
  info.fw_name == emvybombercat over the handshake before driving hardware, and
  refuses a board that identifies as anything else — with a clear message
  pointing to bombercat flash EMVyBomberCat.
• Shared Track 2 parsing. The track2 and track_parser modules moved from
  magspoof into core, so both magspoof and emvy decode Track 2 (service
  code, standard, security verdict) through one shared parser.
• Deliberately lax magstripe validation in emvy mag, matching what the firmware
  actually accepts (ISO sentinels optional, either track allowed empty),
  documented so it isn't accidentally unified with magspoof's stricter rules.
• Documentation: new emvy command reference, an implementation plan, updated
  README, usage, reference, limitations, and release docs; expanded test coverage
  (EMVy CLI, link, parser, firmware registry, and auto-flash wiring).

Bugfixes

• Simplified an internal detection_cli docstring that referenced a planning
  document not shipped with the tool.

Breaking Changes

None. All existing command groups (relay, tags, readers, magspoof,
flash, device, status, …) are unchanged; emvy is purely additive.

Installation / Migration Notes

• Upgrade as usual for your platform; no configuration or workflow changes are
  required for existing commands.
• To use the new group, flash a board with bombercat flash EMVyBomberCat (or
  let emvy auto-flash it), then run bombercat emvy info to confirm.

Warning

⚠ The emvy commands read and emulate payment cards. Use them only on cards and
terminals you own or are explicitly authorized to test.

V1.3.0

Summary

This release turns BomberCat Tools from a repository you clone into a program you install. Native packages are now published for Debian/Ubuntu, Arch Linux, macOS (Intel and Apple Silicon) and Windows — download one file, install it, and bombercat is on your PATH with the USB permissions already configured. No virtual environment, no pip, no manual dialout group editing.

It also removes the two biggest sources of friction once the tool is running. Commands that need a particular firmware no longer just fail when the board is running something else — they say exactly what's flashed, what's needed, and offer to flash it for you. And every NFC-A tag you scan now reports its chip model (MIFARE Classic 1K, NTAG, DESFire, …) alongside the UID, with no firmware update required on your board.

---

New features

Installable packages for every platform

Grab the file for your system from the latest release:

Platform	Package	Install
Debian / Ubuntu	bombercat-<version>.deb	sudo apt install ./bombercat-<version>.deb
Arch Linux	bombercat-<version>-1-any.pkg.tar.zst	sudo pacman -U bombercat-<version>-1-any.pkg.tar.zst
macOS (Intel)	bombercat-<version>-x86_64.pkg	double-click, or sudo installer -pkg … -target /
macOS (Apple Silicon)	bombercat-<version>-arm64.pkg	double-click, or sudo installer -pkg … -target /
Windows	bombercat-<version>.exe	run the installer

The Linux packages depend only on python3 and set the machine up for you at install time: udev rules for the serial port and the BOOTSEL volume, dialout/plugdev group membership, and a desktop entry. The macOS and Windows builds are self-contained — no Python needed at all.

bombercat setup-env — one command to grant USB access (Linux)

If you install from source instead of a package, sudo bombercat setup-env does the same machine setup the packages do: writes the udev rules, creates and joins the dialout and plugdev groups, and reloads udev. Safe to re-run; log out and back in for the groups to take effect.

Firmware auto-flash

Commands that need a specific firmware (tags, readers, magspoof, relay, config, capture) now check the board before connecting, and can fix a mismatch instead of failing:

✗ `tags` needs DetectTags; this board is running magspoof.
    bombercat flash DetectTags

On an interactive terminal it offers to flash the right image and then continues with your original command. Three things control it, first one set wins:

1. --auto-flash / --no-auto-flash on the command line
2. BOMBERCAT_AUTO_FLASH=always|ask|never
3. Unset — ask on a terminal, never in a script or pipe

A few deliberate details: the check is capability-based, so a board running a compatible variant (for example MagspoofCVSAttack for a magspoof command) is not reflashed needlessly; a board whose firmware can't be identified always prompts, even under always; and reflashing over NFCGate warns you first that its saved WiFi/relay configuration will be erased.

Chip model identification for NFC tags

tags read, watch and scan now report three extra fields on every NFC-A detection — atqa, sak and model:

  uid           04:1A:2B:3C
  technology    NFC-A
  protocol      T2T
  atqa          0004
  sak           08
  model         MIFARE Classic 1K

The fields appear in the scan table and in the --json / --csv exports. No firmware update is needed — the bytes were already being printed by the board, and this works on every published .uf2 today. Identification follows NXP AN10833, the same table proxmark3 and libnfc use, and is deliberately conservative: chips that are indistinguishable at this layer are reported as a family ("MIFARE Ultralight / NTAG"), and anything unrecognized is left blank rather than guessed.

bombercat --version

Reports the installed version, whether you're running from a source checkout, a frozen macOS/Windows build, or a system package.

---

Improvements

• Clearer firmware errors. A wrong-firmware board now gets a message naming what's flashed and what's needed, distinct from the older "nothing responded on this port" — which is a connection problem, not a firmware one.
• Scriptable failures. A firmware mismatch exits with code 3 instead of the generic 1, so scripts can branch on why a command failed without parsing stderr.
• Real help when the BOOTSEL drive doesn't appear. flash now detects when udisks2 is missing (common on headless and minimal systems) and prints the exact mount command instead of timing out silently. The Debian package recommends udisks2 for this reason.
• Continuous package builds. Every push to main builds all four packages in CI, and the Debian/Arch builds are gated on actually installing the artifact in a clean container and running it.
• Smaller installers. Test directories are stripped from vendored dependencies in the packaged builds.
• New documentation: step-by-step install and uninstall per platform, building the packages, cutting a release, and the setup-env reference, plus new troubleshooting entries for auto-flash and the missing bootloader drive.

---

Bugfixes

• NFC-A tags were reported before their own SAK arrived. The firmware prints SEL RES one line after the UID, so a detection used to close too early. It's now finalized one line later — no detection is lost, and the chip data is always complete.
• Flashing failed on Windows when the bootloader drive had a letter instead of a label. The UF2 drive is now located by asking Windows for the real volume label.
• The CLI crashed on import on Windows and macOS in the system commands, which unconditionally imported the Unix-only grp module.
• Downloading firmware failed in the frozen macOS/Windows builds because CA certificates weren't bundled. certifi data is now collected into both.

---

Breaking changes

• New exit code 3. A command that fails because the board is running the wrong firmware now exits with 3 rather than 1. Scripts that check != 0 are unaffected; scripts that test specifically for 1 should be updated.
• A command may now reflash your board. On an interactive terminal, a firmware mismatch prompts before flashing — it never flashes without a yes, and never prompts at all when stdin isn't a TTY. To disable it permanently, set BOMBERCAT_AUTO_FLASH=never.
• tags JSON output gained fields. NFC-A detections now carry atqa, sak and model. Consumers that iterate over keys, or that read a SAK key emitted by a structured-mode firmware event, should note the fields are now lowercase. Existing uid/tech/protocol/ts_ms fields are unchanged.

---

Installation and migration notes

Coming from a source/virtualenv install? You don't have to migrate — the source workflow still works exactly as before. If you switch to a package, you can delete the old checkout and virtualenv afterwards; user data lives in ~/.bombercat/.

On Linux from source, run sudo bombercat setup-env once and then log out and back in. The .deb and Arch packages already do this for you.

macOS and Windows packages are unsigned — there's no Apple Developer ID or Authenticode certificate yet, so expect a Gatekeeper or SmartScreen warning on first run. The full click-through for each is in docs/installation.md.

On minimal or headless Linux, install udisks2 (sudo apt install udisks2 / sudo pacman -S udisks2) so the BOOTSEL volume mounts automatically when flashing.

Shell completion is not installed automatically — run bombercat completion install if you want it.

V1.2.0

BomberCat Tools v1.2.0.0

Highlights

This release adds full MIFARE Classic support to the BomberCat CLI —
key recovery, sector/block reading and writing, dumping, restoring, and
text encoding — plus a broad internal cleanup of the CLI and detection
layer.

New Features

• MIFARE Classic command suite (bombercat mifare ...):
  • mifare check — per-sector authentication with Key A/B, including
    Key B recovery via trailer read, detailed failure diagnostics, and
    real-time progress/timing summary
  • mifare dump — bulk sector reading with JSON, raw binary, hex, and
    human-readable (decoded ASCII) output options
  • mifare restore — write JSON dumps back to magic cards, with
    trailer-writing options and validation
  • mifare write-text — encode and write text to specific sectors,
    with authentication and block-writing support
  • mifare code — encode text as block hex for MIFARE Classic sectors
• Block 0 and access-bit dissection, including support for
  Infineon MIFARE Classic 1K tags
• Key management: bundled default MIFARE key list plus a keyfile
  loader for custom key files, with per-sector key configuration and
  display
• Detection commands (read/watch/scan/info) unified under a
  shared detection group for NFC tags

Improvements & Refactors

• Enforced consistent bombercat relay command structure
• Simplified Wireshark process handling (removed threading and
  redundant methods)
• Consolidated firmware description enrichment and version-retrieval
  logic
• Streamlined track-standard detection and removed unused detectors
• Errors now reported directly via logger.error instead of a
  generic error wrapper

Removed

• Deprecated CLI command aliases
• Unused output helpers (print_empty_line, print_title, and
  related quiet-mode test scaffolding)
• Unused Aggregator order tracking and harden_track2 function
• Unused MIFARE_TRAILER_KEY_LEN constant

Documentation

• Added MIFARE Classic commands to the status and reference docs
• Clarified example command in device.md

Other

• .gitignore updated to exclude MIFARE key files and card dumps
• Version bumped to 1.2.0.0

Notes for Upgraders

• Default MIFARE keys ship in the repo (mifare_default_keys.keys) for
  offline key recovery — no action needed, but be aware they're bundled.
• Deprecated relay/detection command aliases have been removed; update
  any scripts still referencing the old command names.

Full Changelog: v1.0.0...v1.2.0

V1.0.0

bombercat CLI v1.1.0.0

First release of the bombercat control CLI: a click/rich command-line tool for BomberCat firmwares, talking to the board over USB-serial to configure it, relay NFCGate over WiFi, capture APDUs, read/emit NFC tags, detect readers, and drive magstripe emulation.

Highlights

• Device & firmware management — device list/status to discover boards and detect the flashed firmware; flash to download and write published UF2 images (NFCGate, DetectTags, DetectReaders, magspoof) with tab completion for firmware names.
• NFCGate relay — relay config/run/status/monitor/stop to configure WiFi + server/session and drive the relay. Control-plane only: no APDUs travel over serial, only over WiFi/TCP to nfcgate-server.
• Wireshark capture — capture start -ws streams relayed APDUs live to Wireshark over a FIFO/named pipe (Unix and Windows).
• DetectTags — tags read/watch/scan/info to read NFC tag UIDs directly with the board's PN7150, plus aggregated scan summaries and CSV/JSON export.
• DetectReaders — readers read/watch/scan/info to fingerprint the readers/terminals that probe the board's emulated card.
• magspoof — magspoof show/play, a flash-resident multi-card store (card add/list/delete/set/select/get/info), Track 2 service-code normalization/hardening (card require-sc), and NFC EMV card read/emulation (nfc read, visa) — several card/nfc subcommands are for authorized security testing only, see the per-command docs.
• testserver — scripts and a Dockerfile to fetch, patch, and run a local nfcgate-server for end-to-end relay testing, with a relay smoke test.
• Shell completion — tab completion for firmware and card names.

Hardening & security

• Verified checksums and signature checks on downloaded firmware release assets, with explicit warnings for unverified assets.
• Robust error handling around subprocess calls, Unix FIFOs and Windows named pipes, malformed device payloads, and unanticipated write errors.
• CSV export output neutralized against formula injection.
• Strict-mode option for capture, with clearer error routing (stdout vs stderr) throughout the CLI.

Breaking changes / deprecations

• Relay commands moved under bombercat relay … (previously at the root).
• bombercat status now reports the flashed firmware; relay state moved to bombercat relay status.
• The old root spellings (config, run, stop, monitor) still work for one release as hidden aliases that print a deprecation notice and forward to relay … — they will be removed afterward.

Docs

• New docs/ tree: usage, command reference, deployment, troubleshooting, glossary, protocol, and per-command guides (flash, relay, capture, tags, readers, magspoof, device, status, completion, proto, testserver).
• Android/NFCGate rooting guides (EN/ES) for card/HCE mode.
• Legal-use disclaimer for the security-testing–oriented magspoof subcommands.

CI

• GitHub Actions workflow for the host test suite, plus pre-commit hooks.

What's Changed

• feat: add bombercat CLI for BomberCat device control by @Darcko123 in #1

New Contributors

• @Darcko123 made their first contribution in #1

Full Changelog: https://github.com/ElectronicCats/bombercat-tools/commits/v1.0.0