pyrmax

Decodificador e codificador para frames do protocolo wire Ubiquiti AirMAX, cobrindo tanto a série AC (firmware WA) quanto a M (firmware XW/XM).

• Decodificação dos cabeçalhos externos em texto claro é conduzida por schemas Kaitai Struct sob ksy/. O payload AC (controlado por versão, alternado em msg_type, com o deauth XOR-unmask) é escrito à mão em ac.py — essa lógica não cabe em Kaitai somente-parse.
• Codificação é escrita à mão para espelhar o caminho de decodificação campo por campo.

Status

Variante	Decode	Encode	iteração de pcap
AC	✅ todos os 5 tipos de msg (beacon, assoc req/resp, probe req, deauth)	✅ inverso byte-exato + builders + seal	✅
M	parcial (9 bytes documentados; resto como unknown_rest)	✅ round-trip da cabeça documentada + unknown_rest	✅
IE Routerboard.com (companheiro de M)	✅ nome do dispositivo + lista de sub-IEs	n/a	✅

O formato wire AC segue docs/ac_wire_format.md (confirmado [P]-contra ubnt_poll_host.ko). Todos os inteiros multi-byte AC são big-endian.

TODO

• pyrmax.ac.encode(AcPacket) -> bytes — inverso byte-exato escrito à mão de decode() (+ seal(), to_ie(), e construtores build_*).
• pyrmax.m.encode(MPacket) -> bytes — o mesmo para M (+ build_m, seal, to_ie).
• Fixar os campos AC [open] — mapa de bits exato de cap_flags, mixed_mode, field_14/field_9c (assoc_req), sta_field_68/ic_6b8 (assoc_resp), e o enc_token do deauth (extraível, mas sua chave ainda não foi reverse-engineered, então não pode ser verificado). Veja docs/ac_wire_format.md §11-§12.
• Verificar os decodificadores AC version < 9 contra capturas reais — o builder TX só emite a versão 9, então os caminhos de versão inferior (nome sem tag, campos de cauda ausentes) são implementados a partir da spec, mas não verificados no wire.
• Fazer reverse-engineer do resto do payload M (bytes 9+ em unknown_rest) — atualmente opaco.
• Expor metadados radiotap em pcap.FrameMeta: canal, RSSI, taxa. Atualmente apenas timestamp/MACs/BSSID são preenchidos.
• Fixtures de captura reais em tests/samples/ — atualmente: airmax_ac_beacon.pcap (1 frame, beacon) e airmax_m_probe_response.pcap (1 frame, probe response). Mais variantes (assoc req/resp, capturas multi-frame) ainda são bem-vindas.
• Envio de pacotes — os comandos scan (force-assoc ativa) e emulate injetam via scapy (os extras [scan] / [emulate]). Veja scan.py / emulate.py.

Ferramenta de linha de comando

O pacote inclui uma CLI dirigida por sub-comandos. Execute-a como 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` aceitam **ou** um arquivo pcap/pcapng (posicional)
**ou** uma interface sem fio ativa via `-i / --iface IFACE`. Os dois são
mutuamente exclusivos. `scan` aceita as mesmas opções de origem (além de um
modo `--active` que só se aplica a uma interface ativa); `emulate` é
apenas para interface ativa.```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

A captura ao vivo pressupõe que a interface já está em modo monitor no canal de interesse — o pyrmax não configura nenhum dos dois. Ela requer o extra opcional [live] (pip install pyrmax[live]), que inclui pcapy-ng. Pressione Ctrl-C para parar: parse informa quantos quadros processou; discover imprime o resumo agregado dos dispositivos ao sair.

Códigos de saída (compartilhados por ambos os comandos e ambos os modos de origem): 0 em caso de sucesso (incluindo "nenhum quadro AirMAX" — um resultado válido), 1 para erros de formato de captura (tipo de enlace incorreto, arquivo malformado, não foi possível abrir a interface), 2 para arquivo ausente ou argumentos de origem inválidos.

parse — dump por quadro```sh

python -m pyrmax parse capture.pcap

Cada quadro de gerenciamento 802.11 que carrega um IE de fornecedor AirMAX produz um bloco: pacote AC, pacote M e qualquer IE companheiro do Routerboard.com encontrado no mesmo quadro.```
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

O mesmo percorredor de passagem única é exposto programaticamente como pyrmax.pcap.iter_airmax(path) — ele gera um AirmaxRecord(meta, ac, m, routerboard) por quadro com AirMAX, então você não precisa correlacionar manualmente os IEs M e Routerboard.

discover — resumo de dispositivos```sh

python -m pyrmax discover capture.pcap

Os frames são agrupados por MAC de origem 802.11, os peers são acumulados, e as
observações de payload AC / payload M / nome de dispositivo Routerboard são consolidadas
em um único bloco por 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

A mesma agregação também é uma função pública:```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)

## Uso

### Decodificar uma única mensagem AirMAX AC

O decodificador espera os bytes da IE Específica do Fornecedor 802.11 **começando na
OUI** — o invólucro da IE (Element ID `0xDD` + Length) já deve ter sido
removido. `src_mac` / `dst_mac` são obtidos do SA / DA do quadro 802.11
externo.```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)