pyrmax

Decoder ed encoder per i frame wire-protocol Ubiquiti AirMAX, che coprono sia la serie AC (firmware WA) che la serie M (firmware XW/XM).

• Decodifica degli header esterni in chiaro è guidata da Kaitai Struct schemi in ksy/. Il payload AC (condizionato dalla versione, selezionato in base a msg_type, con l'unmask XOR del deauth) è scritto a mano in ac.py — quella logica non si adatta a un Kaitai di solo parsing.
• Codifica è scritta a mano per rispecchiare il percorso di decodifica campo per campo.

Stato

Variante	Decodifica	Codifica	iterazione su pcap
AC	✅ tutti e 5 i tipi di msg (beacon, assoc req/resp, probe req, deauth)	✅ inverso byte-esatto + builder + seal	✅
M	parziale (9 byte documentati; il resto come unknown_rest)	✅ fa il round-trip della testa documentata + unknown_rest	✅
Routerboard.com IE (complementare a M)	✅ nome dispositivo + elenco sub-IE	n/a	✅

AC wire format segue docs/ac_wire_format.md (confermato [P] contro ubnt_poll_host.ko). Tutti gli interi multi-byte AC sono big-endian.

TODO

• pyrmax.ac.encode(AcPacket) -> bytes — inverso byte-esatto scritto a mano di decode() (+ seal(), to_ie() e costruttori build_*).
• pyrmax.m.encode(MPacket) -> bytes — lo stesso per M (+ build_m, seal, to_ie).
• Definire con precisione i campi AC [open] — mappa di bit esatta di cap_flags, mixed_mode, field_14/field_9c (assoc_req), sta_field_68/ic_6b8 (assoc_resp) e l'enc_token del deauth (estraibile ma la sua chiave non è ancora stata ricavata tramite reverse engineering, quindi non può essere verificato). Vedi docs/ac_wire_format.md §11-§12.
• Verificare i decoder AC version < 9 contro catture reali — il TX builder emette solo versione 9, quindi i percorsi delle versioni inferiori (nome non taggato, campi di coda mancanti) sono implementati dalla spec ma non verificati sul wire.
• Fare reverse engineering del resto del payload M (byte 9+ in unknown_rest) — attualmente opaco.
• Esporre i metadati radiotap su pcap.FrameMeta: channel, RSSI, rate. Attualmente sono popolati solo timestamp/MAC/BSSID.
• Fixture di cattura reali in tests/samples/ — attualmente: airmax_ac_beacon.pcap (1 frame, beacon) e airmax_m_probe_response.pcap (1 frame, probe response). Altre varianti (assoc req/resp, catture multi-frame) ancora benvenute.
• Invio di pacchetti — i comandi scan (force-assoc attivo) ed emulate iniettano tramite scapy (gli extra [scan] / [emulate]). Vedi scan.py / emulate.py.

Strumento a riga di comando

Il pacchetto include una CLI basata su sottocomandi. Eseguilo come python -m pyrmax COMMAND ....``` usage: python -m pyrmax [-h] [--version] COMMAND ...

COMMAND parse Print each AirMAX frame in detail. discover Summarize devices observed in the capture. scan Live-scan for AirMAX devices and flag vulnerable firmware. emulate Emulate AirMAX AC/M devices (fake targets for scanners).

`parse` e `discover` accettano **o** un file pcap/pcapng (posizionale) **o** un'interfaccia wireless attiva tramite `-i / --iface IFACE`. Le due modalità si escludono a vicenda. `scan` accetta le stesse opzioni di origine (più una modalità `--active` che si applica solo a un'interfaccia attiva); `emulate` funziona solo su interfaccia attiva.```sh
python -m pyrmax parse     capture.pcap          # offline
python -m pyrmax discover  capture.pcap

sudo python -m pyrmax parse     -i wlan0mon      # live (needs root)
sudo python -m pyrmax discover  -i wlan0mon

La cattura live presuppone che l'interfaccia sia già in modalità monitor sul canale di interesse — pyrmax non configura nessuno dei due. Richiede l'extra opzionale [live] (pip install pyrmax[live]) che include pcapy-ng. Premere Ctrl-C per fermarsi: parse riporta quanti frame ha elaborato; discover stampa il riepilogo aggregato dei dispositivi al termine.

Codici di uscita (condivisi da entrambi i comandi e da entrambe le modalità di sorgente): 0 in caso di successo (incluso "no AirMAX frames" — un risultato valido), 1 per errori di formato della cattura (tipo di link errato, file malformato, impossibilità di aprire l'interfaccia), 2 per file mancante o argomenti di sorgente non validi.

parse — dump per frame```sh

python -m pyrmax parse capture.pcap

Ogni frame di gestione 802.11 che trasporta un vendor IE AirMAX produce un
blocco: pacchetto AC, pacchetto M e qualsiasi IE companion Routerboard.com trovato
nello stesso frame.```
Found 1 AirMAX frame(s) in capture.pcap: 0 AC, 1 M (1 with Routerboard companion).

=== Frame #0  [M]  ts=1765494974.955358 ===
  802.11   src=04:18:d6:0e:0c:42  dst=24:a4:3c:88:d8:22  bssid=04:18:d6:0e:0c:42
  AirMAX M
    version      15
    msg_type     BEACON  (raw=1)
    src_mac      04:18:d6:0e:0c:42
    enable       1
    unknown_rest b700000000000000000000040418d60e0c420000000000  (23B)
  Routerboard.com IE
    oui_type     0
    unknown      0000
    device_name  'AP Sur HY1315'
    sub_ie       subtype=1  (30B) 040000001f660902ff0f4150205375722048593133313500000000000000

Lo stesso walker a passaggio singolo è esposto programmaticamente come pyrmax.pcap.iter_airmax(path) — produce un AirmaxRecord(meta, ac, m, routerboard) per ogni frame che contiene AirMAX, così non devi correlare manualmente gli IE M e Routerboard.

discover — riepilogo dispositivo```sh

python -m pyrmax discover capture.pcap

I frame sono raggruppati per MAC sorgente 802.11, i peer accumulati e
le osservazioni AC payload / M payload / nome dispositivo Routerboard confluiscono in
un singolo blocco per dispositivo.```
2 device(s) observed in capture.pcap across 12 AirMAX frame(s).

  24:5a:4c:44:57:fd  (AC)
    radioname    'LB1'
    ssid         'labalUBI2'
    ac_msg_types BEACON
    ac_version   9
    cap_flags    0x0000003e
    mixed_mode   0
    frames       8
    first seen   1767046123.708745
    last seen    1767046129.012448
    peers        (broadcast only)

  04:18:d6:0e:0c:42  (M)
    device_name  'AP Sur HY1315'
    msg_types    BEACON
    m_version    15
    m_enable     1
    frames       4
    first seen   1765494974.955358
    last seen    1765494980.341110
    peers        24:a4:3c:88:d8:22

La stessa aggregazione è anche una funzione pubblica:```python from pyrmax.devices import summarize from pyrmax.pcap import iter_airmax

devices = summarize(iter_airmax("capture.pcap")) for mac, dev in devices.items(): print(mac.hex(":"), dev.device_name or dev.radioname, dev.peers)

## Utilizzo

### Decodificare un singolo messaggio AirMAX AC

Il decoder si aspetta i byte dell'IE 802.11 Vendor Specific **a partire dall'OUI** — il wrapper dell'IE (Element ID `0xDD` + Length) deve essere già stato rimosso. `src_mac` / `dst_mac` sono ricavati dai campi SA / DA del frame 802.11 esterno.```python
from pyrmax import ac

packet = ac.decode(
    data,                              # bytes starting at b"\x00\x27\x22"
    src_mac="aa:bb:cc:dd:ee:ff",       # accepts str ("aa:bb:..." or "aa-bb-..."
                                       # or "aabbcc...") and raw 6-byte bytes
    dst_mac="ff:ff:ff:ff:ff:ff",       # optional — defaults to broadcast
)

packet.msg_type          # <MsgType.BEACON: 1>
packet.version           # 9 (the wire-format epoch / version gate)
packet.src_mac           # b'\xaa\xbb\xcc\xdd\xee\xff'  (integrity-checked)
packet.radioname         # "lab-rx-1"   (convenience prop, delegates to body)
packet.ssid              # "NetA"
packet.cap_flags         # 0x3e  (None for msg types that have no cap_flags)