wifikit 0.1.0__tar.gz

wifikit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Test (pytest)
+        run: uv run pytest -q

wifikit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Release
+
+# Cut a PyPI release by pushing a version tag, e.g.:
+#   git tag v0.1.0 && git push origin v0.1.0
+# hatch-vcs turns the tag into the package version, and the package is published
+# to PyPI using an API token stored as the repo secret PYPI_API_TOKEN.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history + tags so hatch-vcs can read the version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      - name: Show built version
+        run: ls -l dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # API token stored as a repo secret (Settings → Secrets → Actions).
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  github-release:
+    name: GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release with artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >
+          gh release create "${GITHUB_REF_NAME}"
+          --repo "${GITHUB_REPOSITORY}"
+          --title "${GITHUB_REF_NAME}"
+          --generate-notes
+          dist/*

wifikit-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+# (uv.lock IS committed for apps; keep it tracked)
+
+# Firmware blobs are fetched at flash time, never vendored
+*.bin
+
+# Session / capture artifacts
+*.pcap
+*.pcapng
+*.hc22000
+.wifikit_history
+
+# Internal session working docs — kept local, not part of the published repo.
+# Public documentation lives in docs/.
+/HANDOFF.md
+/CAPTURE_STREAMING.md
+
+# OS / editor
+.DS_Store
+*.swp
+.idea/
+.vscode/

wifikit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Encouraging or facilitating unlawful use of this project
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer at `ravindra@budgurjar.org`. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

wifikit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to wifikit
+
+Thanks for your interest! Contributions of all kinds are welcome — bug reports,
+features, docs, and board-compatibility notes.
+
+## Ground rules
+
+- **Authorized use only.** This project exists for lawful security testing and
+  education. Do not submit code whose primary purpose is to attack third-party
+  networks, evade detection maliciously, or otherwise facilitate unlawful use.
+- Be respectful — see the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+We use [uv](https://github.com/astral-sh/uv) for environments and packaging.
+
+```bash
+git clone https://github.com/BadRat-in/wifikit
+cd wifikit
+uv sync                 # venv + runtime + dev deps
+```
+
+Before opening a PR, make sure these pass:
+
+```bash
+uv run ruff check .     # lint
+uv run ruff format --check .
+uv run pytest           # unit tests (no hardware required)
+```
+
+## Guidelines
+
+- **Docstrings & comments**: every module and public function should have a
+  docstring explaining *what* and *why*; comment non-obvious logic.
+- **Keep firmware knowledge in `marauder.py`** and transport in `session.py` so
+  the UIs stay firmware-agnostic.
+- **Small, focused commits** with clear messages (Conventional Commits style,
+  e.g. `feat(tui): add station table`).
+- Add or update tests for parsing/logic changes.
+- Do not vendor Marauder firmware binaries into the repo — they are fetched at
+  flash time.
+
+## Reporting bugs
+
+Open an issue with your board model, `wifikit --list-ports` output, the command
+you ran, and what happened. For security-sensitive reports, see
+[SECURITY.md](SECURITY.md).

wifikit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravindra Singh
+
+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.

wifikit-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+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