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, field_14/field_9c (assoc_req), sta_field_68/ic_6b8 (assoc_resp), 그리고 deauth enc_token (추출은 가능하지만 키가 아직 역분석되지 않아 검증할 수 없음). docs/ac_wire_format.md §11-§12 참조.
• 실제 캡처로 version < 9 AC 디코더 검증 — TX 빌더는 항상 버전 9만 생성하므로 하위 버전(태그 없는 이름, 누락된 꼬리 필드) 경로는 사양에 따라 구현되었지만 실제 와이어에서는 검증되지 않았습니다.
• M 페이로드의 나머지 역분석 (unknown_rest의 9바이트 이후) — 현재 불투명함.
• pcap.FrameMeta에 radiotap 메타데이터 노출: channel, RSSI, rate. 현재는 타임스탬프/MAC/BSSID만 채워집니다.
• tests/samples/의 실제 캡처 픽스처 — 현재: airmax_ac_beacon.pcap (1프레임, beacon) 및 airmax_m_probe_response.pcap (1프레임, probe response). 추가 변형 (assoc req/resp, 다중 프레임 캡처)은 언제든 환영합니다.
• 패킷 전송 — scan(능동 강제 assoc) 및 emulate 명령은 scapy를 통해 주입합니다 ([scan] / [emulate] 엑스트라). scan.py / emulate.py 참조.

명령줄 도구

이 패키지는 하위 명령 기반 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).

라이브 캡처는 관심 채널의 인터페이스가 이미 모니터 모드라고 가정합니다. pyrmax는 어느 것도 구성하지 않습니다. 선택적 [live] 엑스트라(pip install pyrmax[live])가 필요하며, 이를 통해 pcapy-ng가 함께 설치됩니다. Ctrl-C를 눌러 중지합니다. parse는 스트리밍한 프레임 수를 보고하고, discover는 종료 시 집계된 장치 요약을 출력합니다.

종료 코드(두 명령과 두 소스 모드 모두 공통): 성공 시 0("no AirMAX frames" 포함 — 유효한 결과), 캡처 형식 오류 시 1(잘못된 링크 타입, 손상된 파일, 인터페이스를 열 수 없음), 파일 누락 또는 잘못된 소스 인수 시 2.

parse — 프레임별 덤프```sh

python -m pyrmax parse capture.pcap

동일한 단일 패스 워커는 프로그래밍 방식으로 pyrmax.pcap.iter_airmax(path)로 노출됩니다. 이는 AirMAX를 포함하는 프레임마다 AirmaxRecord(meta, ac, m, routerboard)를 하나씩 생성하므로 M 및 Routerboard IE를 수동으로 연관시킬 필요가 없습니다.

discover — 장치 요약```sh

python -m pyrmax discover capture.pcap

동일한 집계는 또한 공용 함수입니다:```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)

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}")

메시지 제작 (encode)

encode(packet, dst_mac=…)는 decode의 바이트 단위 정확한 역함수입니다 —
잘 구성된 프레임의 경우 encode(decode(x)) == x입니다. 본문을 직렬화하고(버전 게이트를 다시 적용하고, deauth의 경우 src_mac XOR 마스크를 다시 적용), AES 블록으로 패딩한 다음 packet.src_mac에서 파생된 키로 암호화하고 OUI 이후 바이트를 내보냅니다. 전체 0xDD 벤더 IE를 얻으려면 to_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

구조화된 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}" )

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)

버전이 취약성을 결정하는 방식은 변형(variant)마다 다릅니다. 두 개의 버전 번호가 관련됩니다: 와이어 형식 프로토콜 버전은 모든 AirMAX IE(비콘 포함)에 포함되고, AC 펌웨어 버전 (fwname)은 연결(association) 교환에서 만 전달됩니다.``` AirMAX AC ──> proto < 9 ? ──yes──────────────┐ │no ├──> VULNERABLE ▼ │ fw <= 8.7.20 ? ──yes───────────┘ ├──no───────> PATCHED └──unknown──> UNDETERMINED

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

emulate — 가짜 AirMAX 대상

하나 이상의 가짜 AirMAX AC/M 장치로 비콘을 보내고, AC의 경우 활성 스캐너가 에뮬레이션된 펌웨어 버전을 읽을 수 있도록 디스커버리 핸드셰이크에 응답합니다. [emulate] 추가 기능(scapy), 모니터 모드 인터페이스 및 루트 권한이 필요합니다. 실제 하드웨어 없이 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

scripts/demo_5_devices.sh는 전체 작업을 처음부터 끝까지 수행합니다 — 라디오를 시작하고, 위의 5개 장치 플릿을 에뮬레이션하고, scan --active를 실행한 다음, 정리합니다:```sh sudo ./scripts/demo_5_devices.sh 36

선택적 추가 기능

• 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를 추가합니다 (라이브 스니핑/디코딩 + 능동적인 force-assoc 핸드셰이크).
• pip install pyrmax[emulate] — emulate 명령을 위한 scapy를 추가합니다 (비콘 주입 + 가짜 장치로 디스커버리 핸드셰이크에 응답).

한 번에 여러 개를 설치할 수 있습니다(예: 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

설정은 pyproject.toml ([tool.pyright])에 있습니다:

• typeCheckingMode = "basic" — 구조적 문제를 잡아내면서 dpkt / kaitaistruct / pycryptodome 경계와 씨름하지 않습니다(이 패키지들은 타입 스텁을 제공하지 않습니다).
• src/pyrmax/_generated/는 제외됩니다 — Kaitai 생성 파일에는 이미 # type: ignore가 포함되어 있으며 kaitai-struct-compiler가 실행될 때마다 덮어쓰여집니다.
• dpkt 경계에서 동적 속성을 다루는 부분(예: MGMT_Frame.src)은 로컬 바인딩의 Any 애너테이션으로 처리하고, 여기저기 흩어진 ignore 주석은 사용하지 않습니다.

Kaitai 파서 재생성

src/pyrmax/_generated/ 아래의 생성된 Python 파일은 커밋되어 있으므로 패키지는 Kaitai 툴체인 없이도 설치할 수 있습니다. .ksy를 편집한 후 다시 생성하려면:```sh kaitai-struct-compiler -t python --outdir src/pyrmax/_generated/ ksy/*.ksy