Wifiphisher: a rogue AP framework for Wi-Fi red teaming

What Wifiphisher is for, and who should be running it

Wifiphisher is a rogue access point framework written in Python and released under GPL-3.0. The README frames it for red team engagements and Wi-Fi security testing: a tester uses it to reach a man-in-the-middle position against wireless clients, then optionally runs a web phishing scenario against those clients to capture credentials or deliver a payload. The credential targets named in the README are third party login pages and WPA/WPA2 Pre-Shared Keys; the payload target is malware delivered to victim stations.

That framing sets the audience narrowly. This is a tool for penetration testers working under a scope agreement, not a general networking utility. It assumes you already understand wireless association, deauthentication and what a MITM position gives you. The interactive Textual User Interface is described as guiding the tester through the build process of the attack, which lowers the entry barrier for the mechanics but not for the judgement about when to use them.

The modularity claim matters more than it first appears. The README states that users can write Python modules to expand functionality, and the documentation covers custom phishing scenarios. If your engagement needs a lure page that matches a specific corporate portal, the extension path is the reason to pick this over a fixed-purpose tool.

How the association attack and the phishing stage fit together

The README splits operation into two steps. Step one obtains the MITM position through association attacks. Three techniques are listed. Evil Twin creates a fake wireless network that looks similar to a legitimate one. KARMA masquerades as a public network that nearby clients are searching for. Known Beacons broadcasts a dictionary of common ESSIDs that surrounding stations have likely connected to before. While those run, Wifiphisher forges Deauthenticate or Disassociate packets to break existing associations and push victims toward the rogue network.

Step two is optional and depends on step one succeeding. Once the tester holds the MITM position, the README lists data sniffing and vulnerability scanning of victim stations as possibilities. The phishing path is more specific: Wifiphisher gathers information from the target environment and the victim user, then renders a matching page. One documented scenario pulls the broadcasted beacon frames and the HTTP User-Agent header to imitate a Windows network manager and capture the Pre-Shared Key.

That detail is the design centre of the project. The lure is not a static HTML file; it is assembled from what the client leaks before it ever types anything. A tester who wants a fixed captive portal page will find this more machinery than the job needs.

Installing Wifiphisher from source on Linux

The README states the requirement plainly: a working Linux system, with Kali Linux as the officially supported distribution and the platform where new features are primarily tested. You also need one wireless network adapter that supports AP and monitor mode and is capable of injection, with drivers that support netlink. Without that adapter, nothing else in the install matters.

The README gives this install path for the latest development version. It clones the repository, changes into it, and runs setup.py with sudo, which the README describes as installing any dependencies.

 git clone https://github.com/wifiphisher/wifiphisher.git # Download the latest revision
 cd wifiphisher # Switch to tool's directory
 sudo python setup.py install # Install any dependencies

Note what that command does not do: it installs from the master branch, not from a tagged release. The README offers the alternative of downloading the latest stable version from the Releases page. The setup.py file in the repository checks for the netlink and OpenSSL C libraries by compiling small test programs, so a missing development package surfaces at install time rather than at run time.

Once installed, the README says to run the tool as wifiphisher, or as python bin/wifiphisher from inside the tool's directory. Run without options, it finds the right interfaces and interactively asks you to pick the target ESSID from the surrounding networks and then a phishing scenario. The README states that the default behaviour is to perform both Evil Twin and KARMA.

A first run: selecting adapters and a scenario

The README's worked examples are the fastest way to see how the flags combine. This one pins both adapters explicitly, selects the target network manually, runs the Firmware Upgrade scenario, and writes captured handshakes to a file for verification.

wifiphisher -aI wlan0 -jI wlan4 -p firmware-upgrade --handshake-capture handshake.pcap

Here wlan0 spawns the rogue access point and wlan4 handles the DoS side. The README describes the Firmware Upgrade scenario as an easy way to obtain the PSK from a password-protected network, and the handshake file as the way to verify the captured Pre-Shared Key is correct. Two adapters is not a hard requirement in every mode, but the example shows the shape of a real engagement: one radio for the rogue AP, one for disruption.

The second example skips manual selection and targets a named network, protecting the fake AP with a known PSK.

wifiphisher --essid CONFERENCE_WIFI -p plugin_update -pK s3cr3tp4ssw0rd

The README positions this against networks whose PSKs are already disclosed, conferences being the example. The Plugin Update scenario is described as a route to getting victims to download malicious executables. The -pK flag sets the PSK on the Evil Twin itself, which is what makes the fake network look like the real one to a client that already has the key.

The third example spawns an open network and adds Known Beacons.

wifiphisher --essid "FREE WI-FI" -p oauth-login -kB

With -kB, the tool broadcasts the ESSID dictionary in addition to running the named scenario. The README's text on this example is truncated mid-sentence, so treat the flag combination as documented and the surrounding behaviour as not fully described.

Where Wifiphisher stops being the right tool

The single-adapter requirement is the first hard boundary. AP mode, monitor mode and injection are all mandatory per the README. Most laptop wireless chipsets fail at least one of those, and the ones that pass often need specific drivers. If your hardware cannot do injection, Wifiphisher cannot run, and no amount of configuration changes that.

The second boundary is the platform. Linux only, Kali officially supported. The README notes that people have made it work on many distributions, but also that new features are primarily tested on Kali. On anything else you are accepting untested behaviour on a tool that manipulates wireless frames.

Third, the release cadence is worth reading carefully. The most recent tagged release is v1.4, dated 2018-01-12. The last push to the repository was on 2026-05-22, so work continues on master, but there is no tagged release carrying it. Anyone installing via the README's git clone command is running unreleased code. Anyone installing from the Releases page is running a build from 2018. That gap is a real operational decision, not a footnote.

Finally, consider the failure mode of the phishing stage. It depends on clients associating with the rogue AP and then interacting with a rendered page. Clients with certificate pinning, captive portal detection, or users who simply do not connect will walk past it. The README does not document what happens when a victim station refuses the association, and it does not document rollback of network changes made during an engagement.

Alternatives and how their approach differs

The most direct alternative in the same space is hostapd plus a manual DHCP and DNS setup, with dnsmasq and a web server serving the lure. That stack gives you the rogue AP and the captive portal, and it does nothing else. Wifiphisher's difference is the association layer: KARMA and Known Beacons are implemented techniques, not configuration you assemble, and the Deauthenticate forgery is built in. With hostapd you also choose exactly which ESSID to broadcast and stop there, whereas Known Beacons cycles a dictionary of common names to catch clients probing for networks they already know.

A second comparison is a general wireless assessment suite that bundles discovery, capture and cracking alongside the rogue AP. Those tools tend to treat the rogue AP as one module among many, and the phishing page as something you supply. Wifiphisher inverts that: the phishing scenario is a first-class concept with a documented custom scenario format, and the AP exists to serve it. If your engagement is mostly about capturing handshakes and cracking them offline, the phishing machinery is weight you do not need. If the engagement is about what a user will type into a page, the scenario system is the reason to be here.

The third option is writing your own Python on top of the same primitives. The README explicitly supports that path, pointing to documentation for writing modules and creating custom phishing scenarios. Wifiphisher is then less an application and more a framework you extend, which is also the honest description of what GPL-3.0 source distribution means here.

Maintenance, licensing and what to check before deploying

The repository is not archived, and the last push was on 2026-05-22, so the codebase is being touched. The release history tells a different story: v1.4 shipped on 2018-01-12, v1.3 on 2017-04-15, and v1.2 on 2016-12-05. There is no tagged release covering the years of commits after v1.4. Plan your upgrade path around that split. If you install from git, you are tracking master and should expect the interface to move; if you install from the Releases page, you are pinned to a 2018 build and will not receive fixes without moving to git.

The licence is GPL-3.0. The README states that the source may be studied, changed or distributed under those terms. For internal red team use that is generally uncomplicated, but if you intend to redistribute a modified Wifiphisher, or ship it inside a product, the copyleft terms apply to the derivative work. That is a description of the licence, not legal advice; read LICENSE.txt and talk to counsel if redistribution is on the table.

Before deploying, verify three things on your own hardware and your own target environment: that your adapter supports AP and monitor mode with netlink drivers, that setup.py completes without a missing netlink or OpenSSL development library, and that the scenario you intend to run is one you have tested end to end, since the README documents scenarios by name and purpose but not their internal behaviour.

Editorial conclusion

Adopt Wifiphisher if you run authorised wireless assessments on Linux with an injection-capable adapter and want Evil Twin, KARMA and Known Beacons behind one interactive interface. Do not adopt it if you need a cross-platform tool, a maintained release cadence, or anything that works without monitor mode and packet injection. Before your first engagement, verify that your adapter supports AP and monitor mode with netlink drivers, and decide which release you are installing: the README's install path pulls the current master branch, the newest tagged release is v1.4 from 2018-01-12, and the last push to the repository was on 2026-05-22.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. wifiphisher/wifiphisher on GitHub