wifit3: Cross-platform USB Wi-Fi auditing in pure Python
A cross-platform USB Wi-Fi auditor for security teams, using pure Python drivers instead of aircrack-ng.
GitHub derv82/wifit3 Updated 2026-09-26 Branch master Stars 922 Forks 87
Python Shell USB Wi-Fi auditing PyUSB Textual Linux/macOS/Windows WPA/WPA2/WPA3 GNU GPL v2.0

🧭 Decision Guide

Try it if you

  • You have a USB adapter listed by the README and need one audit workflow across Linux, macOS, or Windows.
    The README's “Supported Hardware” requires at least one supported USB wireless adapter; “Why?” states identical operation on all three platforms.
  • You need simultaneous capture across multiple adapters and want to designate one adapter for injection.
    The README's “Multi-Card Aggregation” explicitly supports capture across multiple adapters and a dedicated injection card.
  • Your testing covers WPA/WPA2 handshakes, PMKID, WPS, or WEP artifact export.
    The README's “Attacks & Captures” lists handshakes, PMKID, WPS Recovery Suite, and WEP Suite, with .pcap and .hc22000 export.

Skip it if you

  • You do not have a USB wireless adapter from the Supported Hardware list.
    The README states twice that “At least one supported USB wireless adapter is required.”
  • You require a stable release and cannot accept the BETA status of v0.3.3.
    Project metadata labels the latest version “v0.3.3 (BETA).”
  • Your environment forbids direct USB register access or installation of WinUSB and udev rules.
    The README's “License & Disclaimer” describes direct USB register access; “One-Time Driver Setup” describes installing WinUSB or writing udev rules.
  • You need to audit networks or equipment that you do not own or lack explicit authorization to test.
    The README disclaimer limits use to networks and equipment owned or explicitly authorized for auditing.

Requirements

  • At least one supported USB wireless adapter is required.
  • Runs identically on Linux, macOS, and Windows.
  • Source execution uses Astral's uv with uv sync and uv run wifit3.
  • Linux setup involves pkexec/sudo, udev, and modprobe; Windows setup involves UAC and WinUSB; macOS requires selecting Allow in the authorization dialog.

First step (verbatim from README)

uv sync

Watch out

  • Uninstalling on Linux also removes the udev and modprobe rules written by wifit3.
    The README's “Uninstalling” section explicitly says Linux removes these rules.
  • Windows uninstall removes the WinUSB binding and triggers a PnP rescan.
    The README's “Uninstalling” section explicitly describes this Windows behavior.
  • The macOS prebuilt binary requires quarantine handling before execution.
    The README's “Installation & Running” section provides the xattr -d com.apple.quarantine command.
  • Capabilities and limitations vary by USB model and require checking SUPPORTED-HARDWARE.md.
    The README's “Supported Hardware” section links to docs/SUPPORTED-HARDWARE.md for details.

Alternatives

  • wifite2:When you want the wifite2 ecosystem mentioned in the README credits instead of wifit3's built-in USB mini-drivers.
    README section “Thank you, Linux!”
  • aircrack-ng:When an existing workflow depends on the aircrack-ng tool explicitly named by the README rather than wifit3's Zero Runtime Dependencies approach.
    README sections “Why?” and “Thank you, Linux!”

Not stated in the README

  • Minimum supported versions for Linux, macOS, and Windows are not specified.
  • Actual throughput, scan speed, and multi-card limits are not specified.
  • Known defects, test coverage, and regression practices for v0.3.3 BETA are not specified.
  • Compatibility of WPA3 EvilTwin across chipsets and operating systems is not specified.
  • Exact version requirements for PyUSB, Textual, and firmware are not specified.
  • The minimum privilege scope required for first-time driver setup is not quantified.

💡 Deep Analysis

6
No I use a TP-Link TL-WN722N on Windows, but it may be V1, V2, or V3; when I need monitor mode and frame injection, can I treat these revisions as the same hardware?
For: A Windows security researcher using a TP-Link TL-WN722N or a visually identical adapter with a different hardware revision

No, you should not treat them as the same hardware, because the README distinguishes capability by chipset and hardware revision, and V1 versus V2/V3 appear under different support entries.

  • The Supported Hardware table lists TP-Link TL-WN722N V1 under Atheros AR9271, marked as 2.4 GHz.
  • It lists TL-WN722N v2/v3 under Realtek RTL8188EUS, showing that visually similar revisions use different chipsets.
  • Project insights explicitly warn that adapters with the same appearance but different hardware revisions may have completely different capabilities; monitor mode, injection, bands, and stability cannot be inferred from the product name alone.
  • On Windows, first-time setup also installs WinUSB through UAC, changing the device binding used by normal Wi-Fi.

Therefore, verifying the label, USB enumeration information, and Supported Hardware documentation is a hard prerequisite; the shared TL-WN722N name is not enough.

  • README, “Supported Hardware”: “Atheros AR9271 ... TP-Link TL-WN722N V1”
  • README, “Supported Hardware”: “Realtek RTL8188EUS ... TP-Link TL-WN722N v2/v3”
  • Project insights, user_experience.common_pitfalls: visually similar devices with different chipset versions may have completely different capabilities
  • README, “One-Time Driver Setup”: “Windows: Prompts once via UAC to install WinUSB for the device”
Not stated in the README:The README provides no Windows comparison of monitor mode, injection, or stability for each TL-WN722N revision.;It does not explain how to confirm the actual chipset using only operating-system tools.
Yes I need the same wireless auditing workflow across Linux, Windows, and macOS, and I own a USB adapter listed in the README; is wifit3 a better fit than a toolchain based on aircrack-ng and reaver?
For: A wireless security auditor who needs the same workflow on Linux, Windows, and macOS and already owns a supported USB adapter

Yes, provided that your adapter is on the supported list and you accept the fact that wifit3 takes direct control of the USB device.

  • The README defines it as a standalone USB Wi-Fi auditor for Linux, Windows, and macOS, with an identical cross-platform workflow as a goal.
  • Its Mini-Drivers control devices directly through USB bulk/control transfers, bypassing the native Wi-Fi stack and removing the runtime need for aircrack-ng or reaver.
  • Scanning, AP/client identification, WPA/WPA2 handshakes, PMKID, WPS, WEP, and pcap/hc22000 export are integrated in one application.
  • The trade-off is system integration: first run may change Linux udev/modprobe settings, while Windows installs WinUSB. The README provides an Uninstall flow to restore the device binding.

It is therefore a good fit for a cross-platform, USB-based auditing workflow, not for ordinary Wi-Fi connectivity.

  • README, “Why?”: “Runs identically on Linux, macOS, and Windows”
  • README, “Why?”: “No aircrack-ng or reaver, just pure Python with PyUSB & Textual libraries”
  • README, “How it Works: Mini-Drivers”: “directly control wireless devices over USB bulk and control transfers”
  • README, “One-Time Driver Setup” and “Uninstalling”
uv sync
Not stated in the README:The README does not state whether every supported chipset exposes identical capabilities on Linux, Windows, and macOS.;It provides no stability or performance benchmarks for specific OS-and-adapter combinations.
It depends I need to switch adapters between audit mode and normal Wi-Fi on Windows and Linux lab hosts, and must restore the native driver afterward; is wifit3's device-recovery workflow sufficiently clear?
For: A lab administrator who must switch a USB adapter between auditing and normal Wi-Fi use and restore Windows or Linux driver binding afterward

It depends: the README documents a clear recovery procedure, but it requires running Uninstall before unplugging and carries additional risk because the project directly operates hardware registers.

  • First run may write Linux udev permissions and /etc/modprobe.d/ blocklists; Windows installs a WinUSB binding.
  • The Uninstall procedure requires selecting the card on the splash screen, clicking Uninstall, accepting elevation, then unplugging and reconnecting the adapter.
  • The README says Linux rules are deleted, while Windows removes the WinUSB binding and triggers a PnP rescan so the old driver reattaches.
  • Project insights warn that unplugging or returning to normal use without uninstalling may temporarily disable system Wi-Fi; the disclaimer also notes that kernel guardrails are bypassed.

The procedure is operationally clear, but the project documentation does not support a zero-risk or unattended switching guarantee.

  • README, “One-Time Driver Setup”: Linux writes udev/modprobe configuration; Windows installs WinUSB
  • README, “Uninstalling”: “Click the `Uninstall` button” before unplugging and reconnecting
  • README, “Uninstalling”: “triggers a PnP device rescan (old driver reattaches)”
  • README, “License & Disclaimer”: “operates directly on USB hardware registers without kernel guardrails”
Not stated in the README:The README does not provide manual rollback commands or an automatic repair tool if restoration fails.;It does not state the recovery rate after an unsafe unplug, application crash, or system reboot.
Yes I test WPA3/SAE transition mode only in an authorized lab and need WPA/WPA2 handshake and PMKID file exports; does wifit3 cover this validation path?
For: A penetration tester in an authorized lab assessing WPA3/SAE transition mode and exporting WPA/WPA2 handshake or PMKID evidence

Yes, it fits this authorized lab workflow, but the presence of a feature does not mean every AP and client will yield a successful capture.

  • The scanner tracks encryption suites and WPA3/SAE transition modes, which supports identifying transition-mode targets.
  • WPA/WPA2 support includes passive sniffing, targeted deauthentication, crackable-pair validation, and export to .pcap and .hc22000.
  • PMKID support includes both active association harvesting and passive sniffing, with .hc22000 output.
  • The EvilTwin WPA3 Downgrade flow evicts clients through CSA, BTM, and deauthentication to capture handshakes, and the README says it works with single and multiple cards.

The feature set and output formats match your requirement. However, project insights say success depends on AP configuration, client behavior, signal quality, and vendor implementation; active flows may also interrupt service or trigger detection.

  • README, “Real-time Scanner”: “tracks signal strength, encryption suites, WPA3/SAE transition modes”
  • README, “WPA/WPA2 Handshakes”: “exports `.pcap` and `.hc22000` files”
  • README, “PMKID Harvesting”: “Active association harvest and passive sniffing”
  • README, “EvilTwin WPA3 Downgrade”: “via CSA, BTM, and de-auths”
uv run wifit3
Not stated in the README:The README does not list the validated range of AP, client, or vendor models.;It provides no success-rate data for WPA3 downgrade, handshake capture, or PMKID collection.
Yes I maintain Python projects, want to use uv for dependency management, review the mostly Python codebase, and build a PyInstaller binary myself; is wifit3's source-build path suitable?
For: A security-tool developer maintaining Python code who wants to build an auditable binary from source

Yes, particularly if you are willing to review USB driver ports and firmware licensing rather than treating it as an ordinary Python CLI.

  • The project is primarily Python with a small amount of Shell, and the README identifies PyUSB and Textual as its main runtime libraries.
  • The source path uses Astral’s uv, with documented commands for dependency synchronization, execution, and PyInstaller packaging; the output is placed in dist/.
  • Mini-Drivers live under src/wifit3/chips/* and operate through USB bulk/control transfers. This improves inspectability but means defects can affect device state.
  • The code is GPLv2, while firmware blobs are redistributed under vendor licenses. A release process requiring license-by-license verification must review both areas.

It fits maintainers comfortable with Python, uv, and USB debugging; the README does not establish the maturity expected of a broadly validated commercial binary.

  • Project data: main_language is Python; the language distribution includes Python and Shell
  • README, “Why?”: “just pure Python with PyUSB & Textual libraries”
  • README, “Option 2: Run from Source” and “Option 3: Build your own binary”
  • README, “How it Works: Mini-Drivers” and “License & Disclaimer”
uv sync
Not stated in the README:The README does not say whether source builds automatically pin or verify firmware blob integrity.;Project data provides no test coverage, reproducible-build, or per-chip automated-test results.
It depends In a lab I use multiple USB adapters, want channels split across adapters, and need to designate a dedicated injection card; can wifit3 meet this multi-card constraint?
For: A lab auditor using two or more USB adapters who needs simultaneous 2.4GHz/5GHz coverage and separate scanning and injection roles

It depends: the software explicitly supports multi-card aggregation, but results depend on chipset, band support, and USB/RF conditions.

  • The Features section provides Multi-Card Aggregation, allowing simultaneous capture across adapters and selection of a dedicated injection card.
  • The Real-time Scanner supports 2.4GHz and 5GHz channel hopping and splits channels across multiple cards.
  • The support table includes 2.4GHz-only devices such as Atheros AR9271 and Realtek RTL8187L, alongside dual-band MT7610U, MT7612U, MT7921AU, and several Realtek chipsets. Mixed adapters therefore do not have identical capabilities.
  • Project insights identify USB bandwidth, power, antenna placement, channel planning, and device conflicts as factors affecting collection; adding adapters does not inherently improve results.

The architecture matches your requirement, but each adapter must be checked against the Supported Hardware limitations rather than planned by device count alone.

  • README, “Features”: “Multi-Card Aggregation” and “pick a dedicated card to inject”
  • README, “Features”: “2.4GHz & 5GHz channel-hopping (split for multi-cards)”
  • README, “Supported Hardware”: Atheros AR9271 is 2.4 GHz; MediaTek MT7610U is 2.4 / 5 GHz
  • Project insights, user_experience.common_pitfalls: USB bandwidth, power, antennas, channel splitting, and conflicts
Not stated in the README:The README gives no maximum stable adapter count or throughput benchmarks for specific multi-card combinations.;It does not describe OS-specific USB bandwidth or scheduling differences during simultaneous multi-card use.

✨ Highlights

  • Runs identically on Linux, macOS, and Windows
  • Uses pure Python with PyUSB and Textual
  • Supports multi-card capture and dedicated-card injection
  • Scans 2.4GHz, 5GHz, and WPA3 transition modes
  • Requires at least one supported USB adapter
  • Directly operates USB registers without kernel guardrails

🔧 Engineering

  • Uses built-in Python mini-drivers to bypass Linux kernel drivers and Windows NDIS.
  • The Textual dashboard displays beacon, data, injection, and deauthentication rates.
  • Supports WPA/WPA2 handshakes, PMKID, WPS, and WEP capture.
  • Prebuilt binaries cover Windows, Linux, and macOS execution.

⚠️ Risks

  • The README warns that USB hardware registers are operated without kernel guardrails.
  • The first Linux run writes udev and modprobe rules.
  • The first Windows run installs a WinUSB binding through UAC.
  • Functionality depends on USB chipsets and models in the supported list.
  • The latest release is still labeled v0.3.3 BETA.

👥 For who?

  • Engineers auditing USB Wi-Fi across Linux, macOS, and Windows.
  • Security teams owning AR9271, MT7612U, or RTL8812AU adapters.
  • Testers needing PyUSB capture, WPA handshakes, and PMKID export.
  • Users wanting to avoid runtime dependencies on aircrack-ng and reaver.