pyrmax

Ubiquiti AirMAX ワイヤープロトコルフレーム用のデコーダおよびエンコーダで、AC（WA ファームウェア）シリーズと M（XW/XM ファームウェア）シリーズの両方に対応しています。

• クリアテキストの外部ヘッダーのデコード は、ksy/ 配下の Kaitai Struct スキーマによって駆動されます。AC ペイロード （msg_type で切り替わるバージョンゲート付き、deauth XOR アンマスクを含む）は ac.py に手書きで実装されています — このロジックはパース専用の Kaitai には適合しません。
• エンコード は、デコードパスをフィールド単位で忠実に再現するように手書きされています。

ステータス

AC ワイヤーフォーマットは docs/ac_wire_format.md に従います（[P] は ubnt_poll_host.ko に対して確認済み）。AC の多バイト整数はすべて ビッグエンディアンです。

TODO

• pyrmax.ac.encode(AcPacket) -> bytes — decode() の手書きによるバイト単位完全 逆変換（+ seal()、to_ie()、および build_* コンストラクタ）。
• pyrmax.m.encode(MPacket) -> bytes — M についても同様（+ build_m、 seal、to_ie）。
• [open] AC フィールドの特定 — cap_flags の正確なビットマップ、 mixed_mode、/（assoc_req）、/ （assoc_resp）、および deauth の （抽出は可能だが、その鍵はまだ リバースエンジニアリングされていないため検証不能）。詳細は §11-§12 を参照。

コマンドラインツール

このパッケージにはサブコマンド駆動型の CLI が同梱されています。次のように実行します： 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` と `discover` は、pcap/pcapng ファイル（位置引数）**または**
`-i / --iface IFACE` によるライブ無線インターフェースの**いずれか**を受け取ります。この2つは
相互排他的です。`scan` は同じソースオプションを受け付けます（さらに、
ライブインターフェースにのみ適用される `--active` モードも指定できます）。`emulate` は
ライブのみです。```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

ライブキャプチャは、インターフェースが対象チャンネルですでにモニターモードになっていることを前提としています — pyrmax はどちらも設定しません。任意の [live] エクストラ (pip install pyrmax[live]) が必要で、これにより pcapy-ng がインストールされます。Ctrl-C で停止します: parse はストリームしたフレーム数を報告し、discover は終了時に集約されたデバイスサマリーを出力します。

終了コード (両コマンドと両ソースモードで共通): 成功時 (「AirMAXフレームなし」を含む — これは有効な結果) は 0、キャプチャ形式エラー (リンクタイプの誤り、ファイルの破損、インターフェースを開けない) は 1、ファイルが見つからないかソース引数が無効な場合は 2。

parse — フレーム単位のダンプ```sh

python -m pyrmax parse capture.pcap

AirMAX ベンダー IE を保持する各 802.11 管理フレームは、同じフレーム内で見つかった AC パケット、M パケット、および Routerboard.com コンパニオン IE を含む 1 つのブロックを生成します。```
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

同じシングルパスウォーカーは、プログラム上では次のように公開されています。 pyrmax.pcap.iter_airmax(path) — AirMAXを含むフレームごとに1つの AirmaxRecord(meta, ac, m, routerboard)を生成するため、 M IEとRouterboard IEを手動で関連付ける必要はありません。

discover — デバイス概要```sh

python -m pyrmax discover capture.pcap

フレームは802.11送信元MACごとにグループ化され、ピアが蓄積され、ACペイロード / Mペイロード / Routerboardデバイス名の観測結果は、デバイスごとに1つのブロックにまとめられます。```
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

同じ集約は公開関数でもあります:```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)

## 使い方

### 単一のAirMAX ACメッセージをデコードする

デコーダは、802.11 Vendor Specific IEのバイト列が**OUI
から始まる**ことを想定しています — IEラッパー（Element ID `0xDD` + 長さ）はすでに
取り除かれている必要があります。`src_mac` / `dst_mac` は、外部の802.11フレームの
SA / DA から取得されます。```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)

# The per-message-type fields live on packet.body, one of:
#   BeaconBody | AssocReqBody | AssocRespBody | ProbeReqBody | DeauthBody
body = packet.body
if isinstance(body, ac.BeaconBody):
    body.mac_0c          # the radio's own MAC / BSSID
    body.cap_flags       # u32 capability bitfield (§11)
    body.mixed_mode      # u32 [open]

msg_type は BEACON / ASSOC_REQ / ASSOC_RESP / PROBE_REQ / DEAUTH のいずれかです。バージョンゲートされた末尾フィールド (field_9c, rssi, fwname, txpower, …) は、フレームの version がしきい値未満の場合は None になります。Deauth は、整合性チェックの前に src_mac を jiffies nonce で XOR 解除し、 16 バイトの enc_token を不透明なバイト列として表面化します (そのキーは まだ逆算されていないため、検証できません)。

AC TLV リストを走査する

ネーム TLV を運ぶボディ（beacon、assoc_req）は、ストリームを — 末尾の Padding エントリも含めて — body.tlvs にそのまま保持します。radioname、 ssid、fwname はパケット上の便利なプロパティとして表面化され、 それ以外はすべて生のまま残ります。```python body = packet.body for tlv in getattr(body, "tlvs", ()): if tlv.tag == ac.TlvTag.PADDING: continue print(f"{tlv.tag.name:<10} ({len(tlv.data)} bytes): {tlv.data!r}")

### 単一のAirMAX Mメッセージをデコードする

形状は同じで、表面はより小さい — Mペイロードのうち文書化されているのはわずか9バイトのみ。残りは `unknown_rest` にそのまま保持される。**注記:** Mペイロード自体にはSSIDフィールドがない — SSIDを確認するには、それを含むビーコンまたはプローブレスポンス内の標準802.11 SSID IEを参照してください（`pyrmax.pcap` を介して反復処理する際に `FrameMeta.ssid` として公開されます）。```python
from pyrmax import m

packet = m.decode(data, src_mac="aa:bb:cc:dd:ee:ff")

packet.version           # 1
packet.msg_type          # <MsgType.BEACON: 1>
packet.src_mac           # b'\xaa\xbb\xcc\xdd\xee\xff'
packet.enable            # 1
packet.unknown_rest      # b'\xde\xad\xbe\xef...'   # opaque, RE pending

メッセージの作成 (encode)

encode(packet, dst_mac=…) は、decode のバイト完全一致の逆関数です — 整形式フレームでは encode(decode(x)) == x です。これはボディをシリアライズし、 （バージョンゲートを再適用し、deauth の場合は src_mac XORマスクも再適用）、 AESブロックにパディングし、packet.src_mac から導出されたキーで暗号化し、 OUI 以降のバイトを出力します。to_ie() でラップすると、完全な 0xDD ベンダー IE になります。

build_* コンストラクタは、入れ子のボディを手作業で組み立てる手間を省きます：```python from pyrmax import ac

A beacon (mac_0c defaults to src_mac; broadcast key, as beacons use)

pkt = ac.build_beacon(src_mac="24:5a:4c:44:57:fd", radioname="LB1", ssid="labalUBI2", cap_flags=0x3e) ie = ac.to_ie(ac.encode(pkt)) # full 802.11 vendor IE, ready to embed

An authenticated deauth — the encoder XOR-masks the src with the jiffies nonce

deauth = ac.build_deauth(src_mac="24:5a:4c:44:57:fd", jiffies_nonce=0xdeadbeef) raw = ac.encode(deauth, dst_mac="24:a4:3c:88:d8:22")

Others: ac.build_assoc_req / build_assoc_resp / build_probe_req, and m.build_m

ファジング / PoC 向けに、`seal()` は **任意の** 平文を暗号化し、外部ヘッダーを構築します。これにより、構造化エンコーダーが決して生成しない、意図的に不正な形式のペイロード（偽の `msg_type`、誤った長さ、サブブロック本体など）を作成できます：```python
frame = ac.seal(b"\xde\xad\xbe\xef", src_mac="aa:bb:cc:dd:ee:ff",
                dst_mac="ff:ff:ff:ff:ff:ff", msg_type=0xEE)  # zero-padded to 16

構造化された encode は、ワイヤ上に載せられないもの （TLV 値 > 255 バイト、暗号文 ≥ 0x101）に対して EncodeError を発生させます。seal は設計上寛容です。

pcap または pcapng からのパケットストリーム

pyrmax.pcap は、802.11 管理フレーム内の AirMAX ベンダー IE を検出し、 外側の 802.11 ヘッダーから MAC アドレスを抽出して、すべてを 適切なデコーダーに渡します。.pcap と .pcapng は両方とも自動検出されます。 デコードに失敗したフレーム（キー誤り、破損、無関係なベンダー IE）は黙ってスキップされ、 イテレーションは EOF でのみ停止します。```python from pyrmax import pcap

for meta, packet in pcap.iter_ac("capture.pcap"): print( f"{meta.timestamp:.3f} " f"{meta.src_mac.hex(':')} → {meta.dst_mac.hex(':')} " f"{packet.msg_type.name:<10} " f"radio={packet.radioname!r} ssid={packet.ssid!r}" )

for meta, packet in pcap.iter_m("capture.pcapng"): print( f"{meta.timestamp:.3f} " f"{packet.msg_type.name:<10} " f"src={packet.src_mac.hex(':')} enable={packet.enable}" )

`meta` は `FrameMeta(timestamp, src_mac, dst_mac, bssid)` です。radiotap からのチャネル/RSSI 抽出は TODO リストにあります。

### Routerboard.com IE からデバイス名を復元する

AirMAX M フレームは、ほぼ常に同じ 802.11 管理フレーム内に Mikrotik / Routerboard.com ベンダー IE（OUI `00:0C:42`）を伴います。その subtype-1 サブ IE はデバイス名を保持します。```python
from pyrmax import pcap

for meta, packet in pcap.iter_routerboard("capture.pcap"):
    print(f"{meta.src_mac.hex(':')}  →  {packet.device_name!r}")
    # "AP Sur HY1315"

Routerboard デコーダーは単体でも利用できます — OUI から始まる IE データを渡します:```python from pyrmax import routerboard

packet = routerboard.decode(ie_data) packet.device_name # "AP Sur HY1315" packet.sub_ies # tuple of SubIe(subtype, data)

`meta.timestamp` と `meta.src_mac` を照合して、同じキャプチャ内のRouterboardパケットをMパケットと関連付けます。

### `scan` — 脆弱なデバイスを検出する

モニターモードのインターフェース（またはpcap）でAirMAXデバイスをスニッフィングし、脆弱なものをフラグ付けします。`[scan]` エクストラ（`scapy`）と、ライブキャプチャの場合はroot権限が必要です。```sh
# offline — scan a capture (no root)
python -m pyrmax scan capture.pcap

# live, passive — read versions only from traffic that happens to fly
sudo python -m pyrmax scan -i wlan0mon --channel 36

# live, active — force AirMAX AC APs to disclose their firmware
sudo python -m pyrmax scan -i wlan0mon --channel 36 --active

バージョンは、変種ごとに脆弱性の判定方法が異なります。関与するバージョン番号は2つあります：ワイヤーフォーマットのプロトコルバージョン（すべての AirMAX IE（ビーコンを含む）に含まれる）と、ACファームウェアバージョン（fwname）（関連付け交換にのみ含まれる）。``` AirMAX AC ──> proto < 9 ? ──yes──────────────┐ │no ├──> VULNERABLE ▼ │ fw <= 8.7.20 ? ──yes───────────┘ ├──no───────> PATCHED └──unknown──> UNDETERMINED

AirMAX M ───> proto < 15 ? ──yes──> VULNERABLE └──no───────────> UNDETERMINED

`proto` がビーコン内にあるため、**古い**デバイス（AC epoch < 9、M
version < 15）は **受動的に** 検出されます。`PATCHED` の判定には、
AC のファームウェアバージョンが必要なので、キャプチャされたアソシエーションか、
または `--active`（アクティブなハンドシェイク — auth → assoc → assoc-resp
`fwname` を読み取る — は、完全でバイトレベルの忠実な Ubiquiti ステーション交換です）。

フラグ: `--channel N`（1つのチャンネルに固定、それ以外はホッピング）、`--seconds N`、
`--cutoff X.Y.Z`（`fw <= cutoff` なら AC に脆弱、デフォルト `8.7.20`）、
`--src MAC`（アクティブプローブの送信元、例: PTP ピア）、`--vuln-only`、
`--no-set-channel`。終了コードは、脆弱なデバイスが1つでも見つかった場合は **3**
（スクリプトに便利）、それ以外は `0` です。```
AirMAX: 5 device(s) (3 AC, 2 M), 2 vulnerable (AC fw <= 8.7.20 or protocol version below the fixed epoch).

  1c:6a:1b:00:00:01  AC  VulnAC            ch36   v8.7.19    VULNERABLE     rssi=-40dBm  peers=0
  1c:6a:1b:00:00:04  M   VulnM             ch36   v14        VULNERABLE     rssi=-42dBm  peers=0
  1c:6a:1b:00:00:03  AC  PatchedAC         ch36   v8.7.24    patched        rssi=-41dBm  peers=0
  1c:6a:1b:00:00:02  AC  UndetAC           ch36   epoch9     undetermined   rssi=-41dBm  peers=0
  1c:6a:1b:00:00:05  M   UndetM            ch36   v15        undetermined   rssi=-43dBm  peers=0

emulate — 偽のAirMAXターゲット

1つ以上の偽のAirMAX AC/Mデバイスとしてビーコンを送信し、ACの場合は、 ディスカバリーハンドシェイクに応答して、アクティブスキャナーがエミュレートされたファームウェア バージョンを読み取れるようにします。[emulate] エクストラ（scapy）、モニターモードインターフェース、 およびroot権限が必要です。実際のハードウェアなしで scan をテストするのに便利です。```sh sudo python -m pyrmax emulate -i wlan1mon --channel 36
-d ac/8.7.19/VulnAC -d ac/9/UndetAC -d ac/8.7.24/PatchedAC
-d m/14/VulnM -d m/15/UndetM

各 `-d`（繰り返し指定可）は `TYPE/VERSION[/SSID[/MAC]]` で、`/` 区切りのため MAC のコロンは安全です:

- `ac/8.7.19` — モダン AC、ファームウェア `8.7.19`（epoch 9、`fwname` を開示）
- `ac/9` — モダン AC epoch、ファームウェア文字列**なし** → スキャナは `undetermined` と認識
- `ac/7` — **旧** AC、ワイヤーフォーマット epoch 7（< 9）→ 脆弱、ビーコンから検出
- `m/14` — AirMAX M、バージョン 14（< 15）→ 脆弱
- `m/15` — 修正済み epoch の AirMAX M → undetermined

`-d` なしの場合、デモ用フリートがエミュレートされます。`--no-respond` はビーコンのみ（AC ファームウェアはその場合開示されません）。AC ファームウェアバージョンは assoc-resp にのみ存在するため、レスポンダが必要なのです。

### 1台のマシンで両方を一緒にテストする

`scripts/hwsim_testbed.sh` は `mac80211_hwsim` 経由で2つの仮想無線機を作成するため、ハードウェアなしで一方で `emulate`、もう一方で `scan` を実行できます:```sh
sudo ./scripts/hwsim_testbed.sh up 36    # prints EMU_IFACE / SCAN_IFACE
# ...run emulate on EMU_IFACE and scan on SCAN_IFACE (two terminals)...
sudo ./scripts/hwsim_testbed.sh down

scripts/demo_5_devices.sh は全体をエンドツーエンドで実行します — ラジオを起動し、 上記の5デバイス群をエミュレートし、scan --active を実行して、後片付けを 行います:```sh sudo ./scripts/demo_5_devices.sh 36

### エラーハンドリング

スキーマの不一致や整合性の失敗は `pyrmax.DecodeError` を発生させます。
最も一般的な原因は、キーの誤りです（対象のフレームに対して `src_mac` / `dst_mac` を
`decode()` に誤って渡した場合）。```python
from pyrmax import ac, DecodeError

try:
    packet = ac.decode(data, src_mac=src, dst_mac=dst)
except DecodeError as exc:
    print(f"skipping frame: {exc}")

追加オプション

• pip install pyrmax[pcap] (または uv sync --extra pcap) — dpkt を取り込みます これにより pyrmax.pcap.iter_ac(path) / iter_m(path) は、.pcap または .pcapng キャプチャ (リンクタイプ DLT_IEEE802_11_RADIO) からパケットをストリーム出力できます。 形式はファイルのマジックナンバーから自動検出されます。
• pip install pyrmax[live] — モニターモードの無線インターフェースからの ライブキャプチャ用に pcapy-ng を追加します。CLI の -i / --iface フラグと、 プログラムによる pyrmax.pcap.iter_airmax_live(iface) ジェネレータで使用されます。
• pip install pyrmax[scan] — scan コマンド用に scapy を追加します (ライブスニッフィング/デコード + アクティブな強制アソシエーションハンドシェイク)。
• pip install pyrmax[emulate] — コマンド用に を追加します (ビーコンの注入 + 偽デバイスとしてディスカバリーハンドシェイクに応答)。

複数を一度にインストールするには、例: uv sync --extra scan --extra emulate。

レイアウト```

pyrmax/ ├── ksy/ # Kaitai Struct source schemas │ ├── airmax_ac.ksy # AC cleartext outer header (payload decode is hand-written in ac.py) │ ├── airmax_m.ksy # M outer (OUI marker + encrypted blob) │ ├── airmax_m_payload.ksy # M decrypted payload (9 documented bytes) │ └── routerboard.ksy # Mikrotik / Routerboard.com vendor IE ├── src/pyrmax/ │ ├── init.py │ ├── ac.py # AC decode/encode API + AcPacket dataclass │ ├── m.py # M decode/encode API + MPacket dataclass │ ├── routerboard.py # Routerboard IE decoder + RouterboardPacket │ ├── pcap.py # iter_ac / iter_m / iter_routerboard / iter_airmax / iter_airmax_live │ ├── devices.py # summarize() — per-device aggregation │ ├── vuln.py # firmware-version parse + is_vulnerable() │ ├── scan.py # Scanner — live/pcap discovery + active handshake + vuln verdict │ ├── emulate.py # Emulator — fake AC/M targets (scapy) │ ├── main.py # python -m pyrmax CLI │ ├── exceptions.py │ ├── _crypto.py # AES-128-ECB + HMAC-SHA1 KDF (internal) │ └── _generated/ # kaitai-struct-compiler output (committed) ├── scripts/ │ ├── hwsim_testbed.sh # two virtual radios (mac80211_hwsim) for scan<->emulate │ └── demo_5_devices.sh # end-to-end 5-device emulate + scan demo └── tests/ ├── samples/ # raw frame captures (currently empty) ├── test_ac.py ├── test_m.py ├── test_crypto.py ├── test_pcap.py ├── test_routerboard.py ├── test_devices.py ├── test_cli.py └── test_integration.py # real-capture round-trips

## 開発```sh
uv sync                    # create .venv and install runtime + dev deps
uv run pytest              # run tests
uv run ruff check          # lint
uv run pyright             # static type check

設定は pyproject.toml（[tool.pyright]）にあります：

• typeCheckingMode = "basic" — dpkt / kaitaistruct / pycryptodome の境界と戦わずに構造上の問題を検出します（これらのパッケージは型スタブを提供していません）。
• src/pyrmax/_generated/ は除外されます — Kaitai が生成したファイルにはすでに # type: ignore が含まれており、kaitai-struct-compiler を実行するたびに上書きされます。
• dpkt との境界で動的属性（例：MGMT_Frame.src）に触れる場合は、散在する ignore コメントではなく、ローカルバインディングの Any アノテーションで対応します。

Kaitai パーサーの再生成

src/pyrmax/_generated/ 以下の生成された Python ファイルはコミットされているため、Kaitai ツールチェーンなしでパッケージをインストールできます。.ksy を編集した後に再生成するには：```sh kaitai-struct-compiler -t python --outdir src/pyrmax/_generated/ ksy/*.ksy