AirmonGUI

Un'interfaccia web locale per la suite wireless aircrack-ng.

Screenshot · Avvio rapido · Funzionalità · Roadmap · Contribuire

[!WARNING] Usalo solo su reti di tua proprietà o per le quali hai ricevuto autorizzazione scritta al test. Scansionare, deautenticare o catturare traffico da reti che non controlli è illegale nella maggior parte dei Paesi. Vedi Uso legale e responsabile.

Cos'è

AirmonGUI riunisce airmon-ng, airodump-ng, aireplay-ng e aircrack-ng in un'unica app web che gira sulla tua macchina. Attivi la modalità monitor, scansiona le reti, catturi un handshake WPA e lo crachi cliccando su moduli etichettati invece di ricordare i flag.

Non reimplementa nessuno degli strumenti. Il backend esegue i binari reali e ne analizza l'output, quindi quello che vedi è ciò che la suite ha effettivamente fatto. L'interfaccia si lega a 127.0.0.1 e l'API non esce mai dalla tua macchina.

Perché l'ho creato

La suite aircrack-ng è eccellente, ma il flusso di lavoro si sviluppa su quattro comandi separati e molti flag da tenere a mente: metti la scheda in modalità monitor, salta tra i canali per trovare un target, aggancia un BSSID, lancia la deauth sul canale giusto, aspetta l'handshake a quattro passaggi, poi passa la cattura a una wordlist. Sbaglia canale e la deauth non va da nessuna parte. Dimentica --bssid e la tua cattura è piena di rumore.

Volevo trasformare l'intera sequenza in una serie di schermate che ti guidino, mostrino cosa c'è in onda e mantengano lo stato tra un passaggio e l'altro. Questo è ciò che fa. Funziona bene per imparare come si comportano realmente gli attacchi, per il lavoro in laboratorio e per velocizzare una valutazione autorizzata.

Funzionalità

Come funziona

Un'esecuzione procede dall'alto verso il basso nella barra laterale. Ecco ciascuna schermata.

Le reti, i BSSID e i client negli screenshot seguenti sono dati dimostrativi sintetici, non una cattura reale.

1. Metti l'adattatore in modalità monitor

Scegli un'interfaccia, controlla driver, chipset e PHY e attiva la modalità monitor. Quando hai finito, rilascia solo quell'interfaccia.

2. Scansiona l'etere

Avvia un job airodump-ng e guarda i punti di accesso e i client riempire la tabella mentre vengono trovati. Filtra la tabella, poi invia qualsiasi rete direttamente a un flusso di lavoro deauth o handshake.

3. Scegli un target

L'analisi del segnale valuta ogni punto di accesso, così quelli forti e poco protetti con client attivi salgono in cima. Mostra anche quanto è trafficato ogni canale e quale sicurezza usano le reti circostanti. I tuoi dispositivi vengono segnalati, così non punti nulla per sbaglio verso te stesso.

4. Cattura l'handshake

Questa schermata aggancia airodump-ng al BSSID e al canale del target, esegue il motore di auto-deauth per disconnettere i client così che si riconnettano e diventa verde nell'istante in cui viene catturato un handshake a quattro passaggi.

5. Craccalo

Punta aircrack-ng sulla cattura e su una wordlist. Il log scorre durante l'esecuzione e, se la passphrase è nella tua lista, appare in cima.

Altre schermate: deauth, catture, log

Deauth standalone con blocco del canale, cronologia delle esecuzioni e output degli eventi analizzato:

Gestione dei file di cattura:

Cronologia dei comandi della sessione:

Avvio rapido

Servono Linux, root, un adattatore wireless che supporti la modalità monitor e la suite aircrack-ng nel $PATH. Vedi Requisiti per l'elenco completo.

# 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

Apri http://localhost:5173. L'interfaccia parla solo con 127.0.0.1:8000.

Al primo collegamento l'interfaccia chiede un token API. Il backend lo stampa nella console all'avvio, così:

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

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

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

Incolla quel token nella schermata di sblocco. Per mantenere un token fisso tra i riavvii, imposta AIRMON_GUI_AUTH_TOKEN in backend/.env (il backend carica quel file all'avvio). Tutte le route API, tranne il health check, richiedono questo token, ed è ciò che impedisce a un processo locale o a una pagina web che ti capita di visitare di usare gli strumenti wireless alle tue spalle. Devi impostare esplicitamente il token prima di far ascoltare il backend a qualcosa di diverso da 127.0.0.1, altrimenti si rifiuta di avviarsi.

Se la richiesta è solo un ostacolo su una macchina con un solo utente, imposta AIRMON_GUI_AUTH_ENABLED=false per disattivare del tutto l'autenticazione; l'interfaccia salta la schermata di sblocco. Con l'autenticazione disattivata, il backend si rifiuta di legarsi a qualsiasi indirizzo che non sia il loopback: punta API_HOST su qualcosa di diverso da 127.0.0.1 e non si avvierà.

Root è necessario perché airmon-ng, airodump-ng e aireplay-ng usano i raw socket. Chiama direttamente .venv/bin/uvicorn invece del semplice uvicorn, poiché sudo resetta PATH e non troverebbe il virtualenv; il flag -E preserva tutte le variabili AIRMON_GUI_* che hai impostato. Se preferisci non eseguire il server come root, configura sudo senza password per quei binari specifici e modifica backend/app/utils.py.

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

Stack tecnologico

Architettura

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)

Il backend espone una REST API su http://127.0.0.1:8000/api e un WebSocket per il terminale su /ws/terminal (protetto dal token API; disattivalo con AIRMON_GUI_TERMINAL_ENABLED=0). In sviluppo, il server di sviluppo Vite su :5173 fa da proxy per entrambi verso il backend.

Requisiti

Risoluzione dei problemi

"Could not lock wlan0 to channel N" o una scansione senza reti. L'interfaccia è quasi sempre ancora in modalità managed. La modalità monitor è ciò che permette all'adattatore di catturare e cambiare canale. Abilitala prima dalla scheda Monitor (o con airmon-ng start wlan0), poi scansiona sull'interfaccia monitor, spesso wlan0mon, anche se alcuni driver mantengono il nome originale. La scansione rifiuta un'interfaccia in modalità managed con questo stesso suggerimento, e una scansione su un singolo canale non si interrompe più se il pre-lock non può essere verificato, poiché airodump-ng sintonizza il canale da solo.

Le reti appaiono al primo avvio ma non al secondo. Un'interfaccia monitor rimasta attiva, o NetworkManager che si riprende l'adattatore tra un'esecuzione e l'altra, possono lasciarlo in uno stato bloccato. Esegui airmon-ng check kill (il pulsante Check Kill) prima di scansionare e ferma una scansione prima di avviarne un'altra sulla stessa interfaccia.

Roadmap

Qualsiasi aiuto su questi punti è benvenuto. Vedi Contribuire.

• Avvio con un comando (un target Makefile o Docker Compose) per backend e frontend
• Un passaggio a hashcat per il cracking su GPU
• Cattura e attacco PMKID
• Grafici dei client e degli AP nel tempo
• La vista Reports, completata ed esportabile
• Una release impacchettata e uno script di installazione

Hai un'idea? Apri un issue. Richieste di funzionalità e domande sono benvenute.

Contribuire

Le pull request sono benvenute, e più sono piccole e mirate, meglio è.

1. Leggi CONTRIBUTING.md per setup, verifica e regole di sicurezza.
2. Fai un fork, crea un branch e mantieni la modifica circoscritta a una sola cosa.
3. Verifica che backend (uvicorn) e frontend (npm run dev) si avviino entrambi senza errori.
4. Apri una PR che dica cosa è cambiato e perché.

Ogni cartella ha il proprio README con note: backend, frontend, website.

Se il progetto ti è utile, una stella aiuta altre persone a trovarlo e mi dice che vale la pena continuare.

Storico delle stelle

Uso legale e responsabile

AirmonGUI è pensato per test wireless autorizzati, ricerca e insegnamento su reti di tua proprietà o per le quali hai ricevuto autorizzazione scritta a valutare.

Intercettare il traffico e deautenticare reti o dispositivi che non controlli è illegale nella maggior parte delle giurisdizioni. I valori predefiniti tengono sia l'API sia il server di sviluppo sul loopback per un motivo: non esporli su una rete condivisa o pubblica. Gli autori non si assumono alcuna responsabilità per un uso improprio. Usando questo software confermi di avere il permesso per ogni rete e dispositivo che tocchi.

Usalo per capire e difendere le reti, non per attaccarne di non tue.

Licenza

MIT, vedi LICENSE. Costruito sopra il progetto aircrack-ng, che fa il lavoro vero.