TL;DR

Bad Kitty is a compact ESP32-based research device that automates wireless scanning and session capture for offline analysis. It’s built as a field-friendly, portable box that logs session captures to a micro-SD for later review in standard tools.

What it does (high level) Runs on an ESP32-WROOM module with a small SPI TFT UI. Automatically scans local RF/802.11 environments and records session captures to the SD card for offline analysis. Local UI shows status and saved sessions. Portable and battery ready — designed for quick field use in controlled/test environments.

[!] This project is for research and authorized testing only. Do not use this device on networks you do not own or do not have express permission to test.

Hardware (overview)

Core: ESP32-WROOM-32D (or compatible ESP32 module)
Display: SPI TFT (small, ~1.8”–2.8”)
Storage: micro-SD card module (HSPI) for .cap session files and logs
Other: basic wiring, optional enclosure and battery pack

Flashing & hardware notes

Use your normal ESP32 toolchain/flash workflow (platformio, esptool, etc.). See docs/ for detailed build scripts if you want to compile locally.
SD module quirk: Some micro-SD modules behave differently between vendors. In our build we observed a signal conflict on some modules;
the fix we used on the prototype was a small hardware adjustment to the SD module we had on hand.
Behavior varies by vendor — treat this as a module-specific hardware note rather than a required step. If you try a different SD adapter it may work without modification.
Suggested repo entry: a short troubleshooting section that documents which SD modules worked for us and which behaved oddly.
If you contribute hardware notes, please describe the module/vendor and symptoms rather than instructions that could be misapplied.

Output

Capture files written to the SD card in standard .cap format for offline analysis.
Local log files and session metadata saved alongside captures.

Responsible use & legal

Bad Kitty is a research tool. By using or contributing to this project you agree to:
Use the device only on networks you own or where you have explicit, written permission to test.
Follow applicable laws and responsible disclosure practices.
Not use the project to interfere with others' networks or services.
Include a clear “Responsible Use” block in your project page and require contributors
to acknowledge the policy (see CONTRIBUTING.md).

Credits

libnet80211.a — used in this build for packet functionality.
Credits to the original author for their work.
Thanks to community testers and hardware contributors.

Contributing

Contributions, bug reports, and hardware notes are welcome. When reporting an issue, include:
Your test environment (hardware revisions, SD module vendor, ESP32 module variant).
Confirmation you tested only on authorized targets.
Please follow the repo’s CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT License

Copyright (c) 2025 Miscreant

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Bad Kitty