WifiForge gives pentesters a wireless lab with no radio, and the safety claim rests on mac80211_hwsim

The whole design is that the radio path is software

WifiForge is a tool developed by Black Hills InfoSec to help train pentesters on different WiFi attack vectors and wireless capabilities, and the current release describes itself as a complete WiFi hacking sandbox that is virtual, sandboxed and requires no radio.

The mechanism is mininet-wifi virtual interfaces, using the `mac80211_hwsim` driver, so an entire airspace, access points, client stations and the attacker all run in software with nothing sent over the air.

That is the design decision that makes the tool both safe and useful. A wireless attack lab normally needs hardware: a router to attack, a client to associate with it, and a dongle to inject with, plus a room nobody else is in. The virtual approach replaces all of that with kernel interfaces, which means the lab is reproducible, that several students can run it on one machine, and that the practice carries no risk of interfering with a real network.

The README says it plainly in the overview. Pick a lab from the menu, and WifiForge builds the network, drops you into a per-node terminal, and lets you run the attack hands-on. When you leave, it tears everything down and cleans up.

The safety notes are stated in the same tone. WifiForge creates only virtual networks confined to your machine, and the project asks you to use it only in environments you own or are explicitly authorized to test. The safety section repeats it as a warning: WifiForge is for authorized security research and education only, and the techniques you learn should be used only on networks, devices and clients you own or are explicitly authorized to test. The stronger note is the one about RF, which says WifiForge does not transmit RF, because the entire radio path is mininet-wifi's virtual interfaces running on your machine.

That is a claim you can check yourself, which is the best property a safety claim can have.

The menu is a terminal application, and root is only needed to launch

The usage section is a menu, and the key bindings are documented as a table.

sudo wififorge

The keys are the up and down arrows or `j` and `k` to move the selection, Enter to launch the selected lab, `/` to search with Escape clearing it, and `q` or Escape to quit.

That is a small interface, and it is a deliberate one. A terminal menu is trivially scriptable, works over SSH, and does not need a display server, which matters for a training environment where students may be running it in a container or a remote shell.

The root requirement is scoped carefully, and the scoping is the useful part. Launching a lab needs root, because creating network namespaces and virtual interfaces requires it. But you can browse without it, `wififorge --list` prints every lab, and `wififorge --allow-non-root` opens the menu for a look around. So an instructor can demonstrate the catalogue to a class without root and then hand over the privilege when the practical work starts.

The console entry points in the package metadata are two names for the same function, `wififorge` mapped to `wififorge.cli:main` and `wf` as a short alias. The interface libraries behind the menu are `blessed` for the terminal rendering and `halo` for the spinner, and `libtmux` is the one that explains the architecture.

tmux is how the per-node terminal is created. Each node in the virtual network gets its own tmux session, which is what lets you move between the attacker, the access point and the client as separate shells, and it is also how the teardown can be reliable, because the session boundaries are explicit rather than implied by process trees.

A lab is a Python module, and the harness handles the lifecycle

The Writing Labs section is the most interesting part of the README for anyone who wants to build on it.

A lab is a small Python module, discovered automatically. You declare its metadata and a `run()` entry point, and the shared harness handles the build, then tmux, then teardown lifecycle.

from wififorge.labs._schema import LabMeta, Category, Difficulty
from wififorge.labs._harness import run_lab

LAB = LabMeta(
    title="My Lab",
    category=Category.ATTACK,
    difficulty=Difficulty.INTERMEDIATE,
    tools=("aircrack-ng",),
    summary="One or two sentences describing what the learner will do.",
)

def _topology(net):
    net.addStation("Attacker", wlans=1)
    host1 = net.addStation("host1", passwd="password123", encrypt="wpa2")
    ap1 = net.addAccessPoint("ap1", ssid="MyNet", passwd="password123",
                             encrypt="wpa2", mode="g", channel="1")
    net.configureWifiNodes()
    net.addLink(host1, ap1)
    return [ap1]

def run():
    run_lab("MY_LAB", ["Attacker", "host1"], _topology)

The API is `mininet-wifi`'s, which is why the topology function reads like a script. `addStation` creates a client, `addAccessPoint` creates an access point with an SSID, a password, an encryption mode and a channel, `configureWifiNodes` applies the wireless configuration, and `addLink` associates the two. The returned list is the access point, and the list of node names goes to `run_lab` alongside the topology function.

Two details about the framework make it usable. You drop the file in `src/wififorge/labs/`, or point WifiForge at your own directory with `--labs-dir DIR`, so a course can keep its labs outside the tool. And a lab that fails to import will not crash the menu, it just shows as disabled. That is a small design choice with a large effect on a teaching tool, because a student who writes a broken lab sees a greyed out entry rather than a stack trace, and the rest of the environment keeps working.

The dependency list shows which labs need what

The runtime dependencies are deliberately small, and the comments in the manifest explain exactly why.

The comment above the dependency list notes that mininet-wifi itself is not a pip package, and that it is installed out of band by `./install-system-deps.sh`. Everything the menu and the lab harness need to render and orchestrate lives in the Python dependencies. The script is in the repository root.

The dependencies themselves are `blessed` and `halo` for the terminal, `libtmux` for the sessions, and then three that are commented with the lab that uses them. `tqdm` is for the bundled lab helper scripts in `labs/materials/`, used by eaphammer for the Evil Twin lab. `plotext` is for graph-drones.py in the Drone Hacking lab. And `pwntools` is for control-drones.py, also in the Drone Hacking lab.

So the base install is the menu and the harness, and the tools specific to a lab are declared in the lab's own metadata. The `LabMeta` struct has a `tools` field, a tuple of tool names, and the comment in the manifest says that labs using these tools pull them in explicitly and that the base install should stay lean.

That is a design decision worth copying for any training tool. A learner who only wants the handshake capture lab should not end up with a drone control library installed, and the dependency footprint of the whole environment should reflect the labs you actually run rather than the union of every lab the project has ever written.

The optional dependencies make the same point on the tooling side, with `pytest`, `ruff` and `mypy` plus `types-setuptools` for the development group. The build backend is hatchling, the project requires Python 3.9 or newer, and the classifiers describe a console environment aimed at education and information technology on POSIX and Linux. The README badges say the same, Python 3.9 or newer and Kali Linux as the platform, and the topic list names the tools the labs draw on, aircrack-ng, airgeddon, wifiphisher, wifi-pineapple, arpspoof and john the ripper.

What the lab catalogue actually teaches

The overview names the categories of work the labs cover, and it is a list of the standard wireless attack surface.

It is a safe, legal, sandboxed place to practise real wireless attacks, recon, handshake capture, cracking, evil twins, WPS and more, all without any hardware. The topic list adds the toolchain, with aircrack-ng and a tutorial association, airgeddon, wifiphisher, wifi-pineapple, arpspoof, john the ripper, Kali and Docker.

Reading the topic list as a curriculum is instructive. The labs span the full chain of a wireless engagement, which is the point of a sandbox rather than a single script.

Recon comes first, because you cannot attack what you have not found, and the tool list includes what a wireless scanner and an airgeddon style capture and deauth workflow would use. Then handshake capture, with aircrack-ng and wifiphisher in the list, and the cracking step, which is where john the ripper appears. The evil twin and WPS material is where wifi-pineapple and arpspoof sit. And the artificial-intelligence topic in the list suggests at least one lab leans on a model for some part of the workflow.

The Docker mention in the topics and the Dockerfile-based structure of the project mean the labs can be run without polluting the host with the wireless tooling, which matters when the tooling includes python packages with native builds like pwntools.

For a team that teaches wireless security, the value is that the lab is a fixed, reproducible artefact rather than a set of instructions to be followed. The instructor writes the topology once, and the environment is identical for every student and every run, which is what makes the exercise measurable. The walkthroughs are published separately at wififorge.github.io, and the release history shows the project is still moving, with 4.0.0 published on 2026-10-08, before that 3.4.1 from 2025-09-16 and 3.4.0 from 2025-06-24. The licence is Apache-2.0 and the last push to the repository was on 2026-10-08.

Editorial conclusion

Adopt WifiForge if you teach or learn wireless attacks and want a repeatable lab that needs no router, no dongle and no neighbours, because the whole environment is virtual and it cleans up after itself. Do not adopt it as a way to test a real network, since the point of the tool is that nothing leaves your machine. Verify first that your kernel supports the mac80211_hwsim module and that the mininet-wifi install succeeds on your distribution, since the README is explicit that mininet-wifi is not a pip package and is installed out of band, and that the labs you intend to run are in the list your build provides.

Frequently asked questions

Official sources

1. blackhillsinfosec/WifiForge on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases