Metadata-Version: 2.4
Name: wifikit
Version: 0.1.0
Summary: Terminal UI + CLI to drive an ESP32 running the Marauder firmware for authorized WiFi security testing.
Project-URL: Homepage, https://github.com/BadRat-in/wifikit
Project-URL: Repository, https://github.com/BadRat-in/wifikit
Project-URL: Issues, https://github.com/BadRat-in/wifikit/issues
Author-email: Ravindra Singh <ravindra@budgurjar.org>
License-Expression: MIT
License-File: LICENSE
Keywords: 802.11,deauth,esp32,hardware,marauder,pentest,security,textual,tui,wardriving,wifi
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Requires-Dist: esptool>=4.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyserial>=3.5
Requires-Dist: textual>=0.80
Description-Content-Type: text/markdown

# wifikit

**A terminal UI + CLI for driving an ESP32 running the [ESP32 Marauder][marauder] firmware — for authorized WiFi security testing and learning.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/BadRat-in/wifikit/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![CI](https://github.com/BadRat-in/wifikit/actions/workflows/ci.yml/badge.svg)](https://github.com/BadRat-in/wifikit/actions/workflows/ci.yml)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Built with Textual](https://img.shields.io/badge/built%20with-Textual-5a2ca0.svg)](https://github.com/Textualize/textual)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/BadRat-in/wifikit/blob/main/CONTRIBUTING.md)

`wifikit` turns the raw Marauder serial command line into a single-screen,
target-oriented dashboard. Instead of memorising commands or juggling the
multi-terminal aircrack-ng workflow (airodump here, aireplay there, aircrack in
a third window), you **scan**, **pick a target from a live table**, and act on
it from a menu or with hotkeys — then run the host-side crack from the same UI.

<p align="center">
  <img src="https://raw.githubusercontent.com/BadRat-in/wifikit/main/docs/assets/wifikit.gif" width="820"
       alt="wifikit TUI cycling through the Targets, Stations, Console and Crack tabs">
</p>

> The demo above runs with `wifikit --demo` (sample data, no board required).

---

## ⚠️ Legal & authorized-use notice

This is a tool for **authorized security testing and education only**. Attacking
networks you do not own or lack **explicit written permission** to test is
illegal in most jurisdictions.

- Only use `wifikit` against **your own** networks/devices or those you are
  contractually authorized to assess.
- Deauthentication and handshake capture affect real users on a network — never
  run them against third parties.
- The authors accept **no liability** for misuse. By using this software you
  agree you are solely responsible for complying with all applicable laws.

`wifikit` is a *front-end*: it drives the already-open-source ESP32 Marauder
firmware and standard tools like `hashcat`/`aircrack-ng`. It contains no novel
attack code.

---

## Features

- 🖥️ **Textual TUI** (default): live AP table, tabbed layout, mouse + keyboard.
- 🎯 **Target-oriented**: select an AP, then Deauth / Capture PMKID / Capture
  handshake / set channel — via an Actions menu (Enter or right-click) or hotkeys.
- 👥 **Stations tab**: clients grouped by AP (via Marauder's `list -c`), populated
  live during a scan; select a station to deauth it directly.
- 📥 **SD-free capture**: `wifikit --capture --channel N` streams the pcap over
  USB (Marauder's `-serial`) into `captures/` — no microSD card needed.
- 🔌 **Auto-detects** the ESP32's serial port (by USB-UART chip), ignoring
  Bluetooth/debug ports.
- ⌨️ **Nice REPL** (`--cli`): local echo, history and tab-completion — a painless
  replacement for `screen`, which Marauder's non-echoing CLI makes miserable.
- 🤖 **Scriptable** one-shot mode (`--exec "scanall"`).
- 🧨 **Integrated cracking**: run `hashcat`/`aircrack-ng` in a Crack tab with live
  streaming output — scan → deauth → capture → crack in one place.
- ⚡ **One-command flashing** of the correct classic-ESP32 build (`wifikit-flash`).

```
 ● /dev/cu.usbserial-….   |   SCANNING   |   APs: 4   | [s]can [x]stop [r]efresh
┌ Targets ─┬ Console ─┬ Crack ─────────────────────────────────────────────────┐
│ Idx  CH   ESSID / BSSID          RSSI                                          │
│  0    3   rb_alderson            -72   ← cursor; press Enter for Actions       │
│  1    3   8e:86:dd:a0:8b:68      -73                                           │
│  2    3   rb_alderson            -84                                           │
└──────────────────────────────────────────────────────────────────────────────┘
 s Scan  x Stop  r Refresh  a Actions  d Deauth  p PMKID  ^r Reconnect  q Quit
```

## Documentation

Full guides live in [`docs/`](https://github.com/BadRat-in/wifikit/tree/main/docs):

- [Overview & mental model](https://github.com/BadRat-in/wifikit/blob/main/docs/index.md) — what wifikit is and how to navigate.
- [Architecture](https://github.com/BadRat-in/wifikit/blob/main/docs/architecture.md) — modules, data flow, threading.
- [Usage](https://github.com/BadRat-in/wifikit/blob/main/docs/usage.md) — flashing, the TUI, the CLI/REPL, hotkeys.
- [Capture → crack](https://github.com/BadRat-in/wifikit/blob/main/docs/capture-to-crack.md) — the SD-free `-serial` workflow.
- [Performance & GPU](https://github.com/BadRat-in/wifikit/blob/main/docs/performance.md) — measured crack rates, `--benchmark`.
- [Firmware](https://github.com/BadRat-in/wifikit/blob/main/docs/firmware.md) — the Marauder build, `-serial`, future plans.
- [Troubleshooting](https://github.com/BadRat-in/wifikit/blob/main/docs/troubleshooting.md) — ports, baud, captures, and more.

## Hardware

- An **ESP32** board (developed and tested on a classic **ESP32-WROOM-32**
  DevKit) flashed with **ESP32 Marauder**.
- A **microSD module** (SPI) is **optional** — capture streams over USB via
  Marauder's `-serial`, so an SD card is only needed for *untethered* capture
  (running the board off the host).

## Install

Requires Python 3.10+. Using [uv][uv] (recommended):

```bash
uv tool install wifikit          # once published to PyPI
# or run from a clone:
uv venv && uv pip install -e .
```

With pipx:

```bash
pipx install wifikit
```

Installing wifikit pulls its **Python** dependencies automatically (including
`esptool` for flashing). Nothing else is needed to **scan, deauth, or capture**.

## Requirements: external tools (for cracking)

The **cracking** half of the workflow shells out to native CLI tools that pip
**cannot** install — grab them from your OS package manager. They're optional:
everything except cracking works without them.

```bash
wifikit --setup     # auto-install the missing tools (brew/apt/dnf/pacman)
wifikit --doctor    # just report what's present + how to install the rest
```

`--setup` detects your package manager, shows the exact command, and installs the
missing tools; the underlying commands are:

| Tool | Needed for | macOS | Debian/Ubuntu |
| :-- | :-- | :-- | :-- |
| `hashcat` | crack WPA (Crack tab, `--benchmark`) | `brew install hashcat` | `sudo apt install hashcat` |
| `hcxtools` (`hcxpcapngtool`) | convert `.pcap` → `.hc22000` | `brew install hcxtools` | `sudo apt install hcxtools` |
| `aircrack-ng` | alternative cracker (optional) | `brew install aircrack-ng` | `sudo apt install aircrack-ng` |

The **ESP32 firmware** is not a manual dependency — `wifikit-flash` downloads the
correct Marauder build on demand from the official release.

## Flash the ESP32

`wifikit-flash` downloads the **correct classic-ESP32 build** (the `old_hardware`
app plus the matching bootloader/partition table) and writes it. It does **not**
vendor Marauder's binaries — they are fetched from the official release.

```bash
wifikit-flash            # auto-detect port, flash at a safe 115200 baud
wifikit-flash --erase    # wipe flash first
```

> Note: the Marauder `flipper` build is for the ESP32-**S2** and will **not** run
> on a classic WROOM-32 (`Unexpected chip ID`). `wifikit-flash` picks the right
> one for you.

## Usage

```bash
wifikit                       # launch the TUI (auto-detect the board)
wifikit --cli                 # line-based REPL instead of the TUI
wifikit --exec "scanall" --timeout 15   # one-shot, print output, exit
wifikit --capture --channel 3 # stream a pcap over USB into captures/ (no SD)
wifikit --list-ports          # show candidate serial ports
wifikit --demo                # try the TUI with sample data (no board needed)
wifikit --benchmark           # measure this GPU's WPA crack rate + time table
wifikit --doctor              # check external tools (hashcat, hcxtools) + hints
wifikit --setup               # auto-install missing external tools (--yes to skip prompt)
```

`--capture` also accepts `--seconds S`, `--mode pmkid|handshake`, and `--out
PATH`. It enables Marauder's `SavePCAP`, sniffs with `-serial`, and reassembles
the streamed `.pcap` on the host.

**TUI hotkeys:** `s` scan · `x` stop · `r` refresh list · `a`/Enter actions ·
`d` deauth selected · `p` PMKID selected · `Ctrl-R` reconnect · `q` quit. The
**Stations** tab lists clients grouped by AP and fills live during a scan.

### The capture → crack loop (on *your own* network)

No SD card required — the capture streams over USB straight to your Mac.

1. `s` to scan, `x` to stop — the table fills live from Marauder's `list -a`.
2. Highlight your AP, press **Enter** → **Capture (stream to Mac)**, or from the
   CLI run `wifikit --capture --channel N` (add `--seconds S`, `--mode
   pmkid|handshake`, `--out PATH`).
3. **Deauth** briefly to force a client to reconnect (generates a handshake).
4. `wifikit` enables Marauder's `SavePCAP`, runs the sniff with `-serial`, and
   **reassembles the streamed `.pcap` into `captures/`** — then converts it via
   `hcxpcapngtool` to an `hc22000` line.
5. In the **Crack** tab, run e.g.
   `hashcat -m 22000 capture.hc22000 wordlist.txt` — output streams live.

## How it works

```
              ┌────────────── wifikit (Python) ──────────────┐
  ESP32  <──USB serial──>  session.py  ──>  tui.py / cli.py
  Marauder                 (threaded I/O)     (UI + parsing)
                                   │
                              marauder.py  (command set + `list` parser)
                                   │
                              flash.py  (esptool + firmware fetch)
```

- `session.py` — port auto-detect + a threaded serial reader/writer.
- `marauder.py` — the firmware's command set and `list` parser (APs + stations).
- `capture.py` — demuxes Marauder's `-serial` pcap stream into a `.pcap` and
  (optionally) converts it to `hc22000` via `hcxpcapngtool`.
- `cli.py` / `tui.py` — the two front-ends (REPL and Textual dashboard).
- `flash.py` — one-command flashing via `esptool`.

## Development

```bash
uv sync                       # create venv + install deps (incl. dev group)
uv run ruff check .           # lint
uv run ruff format .          # format
uv run pytest                 # tests (parser/port logic run without hardware)
```

Please read [CONTRIBUTING.md](https://github.com/BadRat-in/wifikit/blob/main/CONTRIBUTING.md) and the
[Code of Conduct](https://github.com/BadRat-in/wifikit/blob/main/CODE_OF_CONDUCT.md). Security reports: see [SECURITY.md](https://github.com/BadRat-in/wifikit/blob/main/SECURITY.md).

## Acknowledgements & credits

`wifikit` stands entirely on the shoulders of these projects — please star and
support them:

- **[ESP32 Marauder][marauder]** by **[justcallmekoko][jcmk]** — the firmware
  that does all the actual WiFi/BLE work. `wifikit` is only a host-side driver
  for it; the firmware binaries it flashes are built and distributed by that
  project.
- **[Textual][textual]** & **Rich** by Textualize — the TUI framework.
- **[pyserial][pyserial]** — serial transport.
- **[esptool][esptool]** by Espressif — flashing.
- **[prompt_toolkit][ptk]** — the REPL experience.
- **[hashcat][hashcat]** and **[aircrack-ng][aircrack]** — the cracking tools the
  Crack tab drives.

## License

[MIT](https://github.com/BadRat-in/wifikit/blob/main/LICENSE) © 2026 Ravindra Singh. The ESP32 Marauder firmware is the property
of its respective authors under its own license.

[marauder]: https://github.com/justcallmekoko/ESP32Marauder
[jcmk]: https://github.com/justcallmekoko
[textual]: https://github.com/Textualize/textual
[pyserial]: https://github.com/pyserial/pyserial
[esptool]: https://github.com/espressif/esptool
[ptk]: https://github.com/prompt-toolkit/python-prompt-toolkit
[hashcat]: https://hashcat.net/hashcat/
[aircrack]: https://www.aircrack-ng.org/
[uv]: https://github.com/astral-sh/uv
