Here you will find all the tools supported by Electronic Cats associated to Bombercat you can find more information in the Bombercat Wiki about ussage.
A click/rich command-line tool for BomberCat firmwares. It talks to a
BomberCat over USB-serial to configure it, start/stop the NFCGate relay,
watch it live, capture the relayed APDUs to Wireshark; on the
DetectTags firmware — read NFC tags directly with the board's PN7150; on
MifareClassic — authenticate, read, write, dump and restore Mifare Classic
cards; on DetectReaders — detect the readers/terminals that probe it; and on
magspoof — control magstripe emulation: play/inspect the active card,
manage a flash-resident multi-card store, and emulate/read EMV cards over NFC;
and on EMVyBomberCat — read EMV cards, tunnel raw APDUs to a live card, and
emulate tags/magstripe/NDEF/EMV cards while watching each APDU live.
Control plane only. No APDUs travel over serial — those go over WiFi/TCP to
the nfcgate-server. The USB link is a text, line-based control channel: it
configures, arms, starts, monitors and captures the device, nothing more
(docs/NFCGATE_PLAN.md Fase 6). Keep this in mind everywhere below — see the
architecture diagram for how the pieces connect.
Grab the package for your platform 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 it (Inno Setup installer) |
.deb/.pkg.tar.zst only depend on python3 — no venv to manage. The
.pkg/.exe are unsigned (no Apple Developer ID / Authenticode cert yet):
expect a Gatekeeper/SmartScreen warning on first run. Building any of them
locally, or wiring them into CI, is covered in
docs/packaging.md; the step-by-step install (and
uninstall) instructions per platform live in
docs/installation.md.
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activatepython3 -m pip install -r requirements.txt # click, rich, pyserial (+ a few extras)
python3 bombercat.py --helpA virtualenv is recommended. On Linux, serial access usually needs your user in
the dialout group; sudo bombercat setup-env installs the udev rules and adds
you to it (the packages below already do that) — see
setup-env and
Troubleshooting.
The tool is developed and tested on Linux; read
Current limitations before running it elsewhere.
Throughout the docs the command is written as bombercat; if you installed a
package above, that's it — the launcher's on PATH. From a source checkout,
if you have not set up the
bombercat alias or
shell completion, run it as
python3 bombercat.py … instead.
# 1. Discover the board(s)
bombercat device list # IDs + serial ports; ✓ = answered the handshake
bombercat status # which firmware is flashed + what it can do
# 2. Put the relay firmware on it (skip if `status` already says NFCGate)
bombercat flash --list # the published images, with descriptions
bombercat flash NFCGate # download and write it over UF2
# 3. Configure the NFCGate relay (persisted to flash unless --no-save)
bombercat relay config wifi --ssid MyNet --pass 's3cret'
bombercat relay config nfcgate --server 192.168.1.5:5566 --session 42 --role reader
bombercat relay config show
# 4. Run & watch
bombercat relay run # associate WiFi, connect server, start relay
bombercat relay status # state / link / peer / relayed count
bombercat relay monitor # live serial stream (relay logs + APDU hex)
bombercat relay stop
# 5. Capture the relayed APDUs to Wireshark
bombercat capture start -ws # live Wireshark on a FIFO (Ctrl-C to stop)Not doing a relay? bombercat flash DetectTags and read NFC tags directly —
no server, no second board:
bombercat tags read # wait for one tag, print its UID
bombercat tags watch # stream detections until Ctrl-C
bombercat tags scan -t 20 # sample for 20s, aggregated summarySee Detecting NFC tags.
Working with Mifare Classic cards? bombercat flash MifareClassic — authenticate,
read/write blocks, and dump or restore a whole card:
bombercat tags mifare keys # list built-in default keys
bombercat tags mifare check -o card.keys # recover each sector's keys to a keyfile
bombercat tags mifare dump --keys-file card.keys --out card.json # read the whole card to file
bombercat tags mifare restore --dump card.json # write a dump back (magic card)See tags mifare. Reading/writing another
party's cards is for authorized security testing only.
Or flip it around: bombercat flash DetectReaders and detect the
readers/terminals that probe the board's emulated card — no server, no
second board:
bombercat readers read # wait for one reader, print its fingerprint
bombercat readers watch # stream detections until Ctrl-C
bombercat readers scan -t 20 # sample for 20s, aggregated summaryOr bombercat flash magspoof for magstripe emulation — play/inspect the
active card, manage a flash-resident multi-card store, or emulate an EMV
card over NFC:
bombercat magspoof show # inspect what's loaded
bombercat magspoof play # emulate a swipe
bombercat magspoof card add visa --t2 ';4111111111111111=25121010000000000000?'See magspoof. Several card/nfc subcommands
are for authorized security testing only — see the doc's per-command notes.
Or, on a board flashed with the EMVyBomberCat firmware, bombercat emvy …
reads EMV cards, tunnels raw APDUs to a live card, and emulates
tags/magstripe/NDEF/EMV cards while streaming each APDU:
bombercat emvy info # confirm the firmware and see what it exposes
bombercat emvy read # read a contactless card (PAN/expiry/AID/track2)
bombercat emvy apdu 00A404000E325041592E5359532E444446303100 # SELECT PPSE
bombercat emvy emu card # emulate an EMV card, watch the terminal's APDUsSee emvy. 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 — then confirms the
firmware's identity over the handshake before driving the hardware. The commands
are for authorized testing only.
Command layout changed. The relay commands now live under
bombercat relay …, andbombercat statusreports the flashed firmware instead of the relay state (that moved tobombercat 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 torelay ….
A relay needs two peers on the same --server and --session: one
--role reader (reads a physical card), the other --role card (emulates one to
a terminal). Both boards are usually plugged into the same host — address each
one by its ID with -d/--device. See the
end-to-end guide.
| Page | What's in it |
|---|---|
| Command reference | Every command and subcommand: purpose, flags, examples, expected output. device, status (flashed firmware), flash, relay … (config/run/stop/status/monitor), identify, capture, tags … (read/watch/scan/info, mifare *), readers … (read/watch/scan/info), magspoof … (play/show/watch/info, nfc *, card *), emvy … (info/read/apdu/tag/mag/cardscan/emu */nfcinfo/reboot), proto, testserver, completion, and device selection with -d/-p. |
| End-to-end usage | The real workflow on hardware — two BomberCats via nfcgate-server (Path A) and against the NFCGate Android app (Path B) — config → run → monitor → capture — plus the standalone tags/readers workflows on DetectTags/DetectReaders. |
| Control protocol | The line-based SerialControl protocol (:key value, +OK, -ERR), the DeviceLink client, and how ports are discovered and numbered. For developers. |
| Capture / Wireshark | How capture taps a copy of every relayed APDU, the classic-pcap vs pcapng distinction, and the DLT_ISO_14443 encapsulation. |
| Troubleshooting | Serial permissions, board not detected, old firmware without identify/capture, run timeouts. |
| Glossary | Terms used across these docs — REPL, SEL_RES, APDU, Service Code, UF2, VID/PID, and more. |
| Current limitations | Platform support matrix, host requirements, device/serial and relay-scope constraints — known, not bugs. |
| Deploy a dedicated server | Run nfcgate-server permanently on a VPS (Docker or systemd), verify the latency patch, day-2 ops. |
| Install / uninstall the packages | Step-by-step install of the release assets on Windows, macOS (Intel/Apple Silicon), Debian/Ubuntu and Arch — plus post-install (setup-env, groups, completion) and how to remove each one. |
| Building the packages | Build the .deb/.pkg.tar.zst/.pkg/.exe locally: prerequisites per OS, make targets, where the output lands. |
| Cutting a release | The release procedure: bump VERSION, tag, gh release create, verify the 5 assets, re-run a single failed build. |
| Rooting an Android phone for NFCGate (es) | Required only for Path B card/HCE mode: rooting with Magisk and installing NFCGate's native module (Zygisk + LSPosed), with the associated risks. |
These wrap the reproducible build/test scripts (see docs/NFCGATE_PLAN.md Fases 1–5);
full details in proto and testserver:
bombercat proto gen # regenerate firmware/core/src/proto/*.pb.{c,h}
bombercat testserver run [-p 5566] # local nfcgate-server in Docker
bombercat testserver smoke [host port]# relay smoke test (no RF)See testserver/README.md for the local server fixture.
Unit tests — the CLI surface (every command, its output and its exit code) with the serial, Docker and Wireshark layers faked, so they run anywhere:
pytest # the whole suite (tools/tests/test_*.py)
pytest -k capture # one area
pytest --cov=modules # with coverageEnd-to-end host tests — standalone scripts that exercise the real protocol against a fake device or a live server:
python3 tools/tests/serialctl_hosttest.py # DeviceLink protocol parser (pty)
python3 tools/tests/capture_hosttest.py # pcap writer + ISO 14443 vs tshark
tools/testserver/codec_hosttest/build_and_run.sh # firmware codec vs live serverBoth suites run on every push — see .github/workflows/tests.yml.
Developed and validated on Linux (VERSION 1.1.0.0); most commands should
work on macOS/Windows but are untested there. Known constraints around
platform support, host requirements (Wireshark, Docker), device/serial
behavior and relay scope — see Current limitations.
bombercat testserver run is for a local, ephemeral server. To keep a
relay up permanently on a VPS or LAN box (Docker or systemd), verify the
latency patch, and do day-2 ops — see Deployment.
All Bombercat Firmware has been moved to a different repository, to have a better version control, and issue tracking you will find it here:
https://github.com/ElectronicCats/bombercat-firmware
All Bombercat versions are supported in this repository, you will need to check what version you own and select the proper branch to develop or release for just program your board.
All Bombercat Hardware has been moved to a different repository, to have a better version control, and issue tracking you will find it here:
https://github.com/ElectronicCats/Bombercat
Important
BomberCat is a wireless penetration testing tool intended solely for use in authorized security audits, where such usage is permitted by applicable laws and regulations. Before utilizing this tool, it is crucial to ensure compliance with all relevant legal requirements and obtain appropriate permissions from the relevant authorities.
The board does not provide any means or authorization to utilize credit cards or engage in any financial transactions that are not legally authorized. Electronic Cats holds no responsibility for any unauthorized use of the tool or any resulting damages.
Contributions are welcome!
Please read the document Contribution Manual which will show you how to contribute your changes to the project.
✨ Thanks to all our contributors! ✨
See Electronic Cats CLA for more information.
See the community code of conduct for a vision of the community we want to build and what we expect from it.