AirmonGUI

A local web interface for the aircrack-ng wireless toolkit.

Screenshots · Quick start · Features · Roadmap · Contributing

[!WARNING] Use this only on networks you own or have written permission to test. Scanning, deauthenticating, or capturing traffic from networks you don't control is illegal in most places. See Legal and responsible use.

What it is

AirmonGUI puts airmon-ng, airodump-ng, aireplay-ng, and aircrack-ng behind one web app that runs on your own machine. You enable monitor mode, scan for networks, capture a WPA handshake, and crack it by clicking through labelled forms instead of remembering flags.

It does not reimplement any of the tools. The backend shells out to the real binaries and parses their output, so what you see is what the suite actually did. The UI binds to 127.0.0.1 and the API never reaches outside your machine.

Why I built it

The aircrack-ng suite is excellent, but the workflow lives across four separate commands and a lot of flags you have to keep in your head: put the card in monitor mode, hop channels to find a target, lock onto a BSSID, fire deauth on the correct channel, wait for the four-way handshake, then feed the capture into a wordlist. Miss the channel and the deauth goes nowhere. Forget --bssid and your capture is full of noise.

I wanted that whole sequence as a set of screens that walk you through it, show you what's on the air, and keep the state straight between steps. That is what this is. It works well for learning how the attacks actually behave, for lab work, and for speeding up an authorized assessment.

Features

How it works

A run moves top to bottom down the sidebar. Here is each screen.

The networks, BSSIDs, and clients in the screenshots below are synthetic demo data, not a real capture.

1. Put the adapter in monitor mode

Pick an interface, check its driver, chipset, and PHY, and switch monitor mode on. Release just that interface when you're done.

2. Scan the air

Start an airodump-ng job and watch access points and clients fill in as they're found. Filter the table, then send any network straight to a deauth or handshake workflow.

3. Pick a target

Signal Analysis scores every access point so the strong, weakly-secured ones with active clients rise to the top. It also shows how busy each channel is and what security the surrounding networks use. Your own devices get flagged so you don't point anything at yourself by mistake.

4. Capture the handshake

This screen locks airodump-ng to the target's BSSID and channel, runs the auto-deauth engine to knock clients off so they reconnect, and turns green the instant a four-way handshake is captured.

5. Crack it

Point aircrack-ng at the capture and a wordlist. The log streams as it runs, and if the passphrase is in your list, it shows up at the top.

More screens: deauth, captures, logs

Standalone deauth with channel locking, run history, and parsed event output:

Capture file management:

Session command history:

Quick start

You need Linux, root, a wireless adapter that supports monitor mode, and the aircrack-ng suite on your $PATH. See Requirements for the full list.

# 0. Install the suite (Debian, Ubuntu, Kali)
sudo apt update && sudo apt install aircrack-ng wireless-tools

# 1. Clone
git clone https://github.com/ELHart05/AirmonGUI.git
cd AirmonGUI

# 2. Backend (terminal 1)
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
sudo -E .venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000

# 3. Frontend (terminal 2)
cd frontend
npm install
npm run dev

Open http://localhost:5173. The UI only talks to 127.0.0.1:8000.

On the first connection the UI asks for an API token. The backend prints one to its console at startup, like this:

======================================================================
AirmonGUI API token (generated for this run):

    Xy3k...long-random-string...

Paste it into the AirmonGUI web UI when prompted.
======================================================================

Paste that token into the unlock screen. To keep a fixed token across restarts, set AIRMON_GUI_AUTH_TOKEN in backend/.env (the backend loads that file on startup). Every API route except the health check requires this token, which is what keeps a stray local process or a web page you happen to be visiting from driving the wireless tools behind your back. You must set the token explicitly before binding the backend to anything other than 127.0.0.1 — otherwise it refuses to start.

If the prompt is just friction on a single-user box, set AIRMON_GUI_AUTH_ENABLED=false to turn auth off entirely; the UI then skips the unlock screen. With auth off the backend refuses to bind anywhere but loopback — point API_HOST at something other than 127.0.0.1 and it won't start.

Root is needed because airmon-ng, airodump-ng, and aireplay-ng use raw sockets. Call .venv/bin/uvicorn directly rather than plain uvicorn, since sudo resets PATH and would otherwise miss the virtualenv; the -E flag keeps any AIRMON_GUI_* variables you set. If you'd rather not run the server as root, set up passwordless sudo for those specific binaries and adjust backend/app/utils.py.

cd frontend
npm run build   # writes static files to frontend/dist/

Tech stack

Architecture

AirmonGUI
├── backend/    FastAPI REST API and WebSocket, one route module per tool
│               app/routes/ (interfaces, airodump, aireplay, aircrack, handshake, captures)
│               app/models.py (validated Pydantic I/O), app/state.py (in-process job registry)
│               app/utils.py (subprocess and sudo logic), app/config.py (env config)
│
├── frontend/   Vue 3 single-page app, the control console
│               views/ (Overview, Monitor, Scan, Signal, Deauth, Handshake, Crack, Captures, Reports, Terminal, Logs)
│               composables/ (reactive job and state logic), api/ (fetch wrappers)
│
└── website/    Standalone React landing site (optional)

The backend serves a REST API at http://127.0.0.1:8000/api and a terminal WebSocket at /ws/terminal (gated by the API token; turn it off with AIRMON_GUI_TERMINAL_ENABLED=0). In development the Vite dev server on :5173 proxies both to the backend.

Requirements

Troubleshooting

"Could not lock wlan0 to channel N" or a scan with no networks. The interface is almost always still in managed mode. Monitor mode is what lets the adapter capture and change channels. Enable it from the Monitor tab first (or airmon-ng start wlan0), then scan on the monitor interface — often wlan0mon, though some drivers keep the original name. The scan refuses a managed interface with this exact hint, and a single-channel scan no longer aborts if the pre-lock cannot be verified, since airodump-ng tunes the channel itself.

Networks show on the first run but not the second. A leftover monitor interface, or NetworkManager re-claiming the adapter between runs, can leave it in a stuck state. Run airmon-ng check kill (the Check Kill button) before scanning, and stop a scan before starting another on the same interface.

Roadmap

Help on any of these is welcome. See Contributing.

• One-command launcher (a Makefile target or Docker Compose) for backend and frontend
• A hashcat hand-off for GPU cracking
• PMKID capture and attack
• Client and AP graphs over time
• The Reports view, finished and exportable
• A packaged release and install script

Have an idea? Open an issue. Feature requests and questions are fine.

Contributing

Pull requests are welcome, and the smaller and more focused the better.

1. Read CONTRIBUTING.md for setup, verification, and the safety rules.
2. Fork, branch, and keep the change scoped to one thing.
3. Check that the backend (uvicorn) and frontend (npm run dev) both start clean.
4. Open a PR that says what changed and why.

Each folder has its own README with notes: backend, frontend, website.

If the project is useful to you, a star helps other people find it and tells me it's worth continuing.

Star history

Legal and responsible use

AirmonGUI is for authorized wireless testing, research, and teaching on networks you own or have written permission to assess.

Intercepting traffic and deauthenticating networks or devices you don't control is illegal in most jurisdictions. The defaults keep both the API and the dev server on loopback for a reason, so don't expose them on a shared or public network. The authors take no responsibility for misuse. By using this software you confirm you have permission for every network and device you touch.

Use it to understand and defend networks, not to attack ones that aren't yours.

License

MIT, see LICENSE. Built on top of the aircrack-ng project, which does the actual work.