esp-idf-injection-ng

Injeção de quadros 802.11 brutos no ESP-IDF v5.x / v6.x. Um patch reversível de um único comando que reativa o conjunto completo de tipos de quadros 802.11 (Authentication, Deauth, Assoc, Reassoc, Disassoc, RTS/CTS/ACK, …) para transmissão via esp_wifi_80211_tx(), que o libnet80211.a fornecido pela Espressif restringe a uma curta lista de permissões (Beacon, Probe Req/Resp, Action, Data não-QoS).

Inclui:

• O próprio patch (patch/patch_libnet80211.sh) — objcopy --weaken-symbol em um símbolo, com backup e --revert.
• Um firmware de demonstração mínimo (example/) que injeta cinco variantes de quadros e reporta os resultados pela serial.
• Evidências em Pcap, log do Hostapd e log serial de que o patch permite a injeção de SAE Commit (subtipo 11 de Authentication) no ESP32 — o caso de uso motivador deste trabalho.
• O relatório técnico completo como artigo de pesquisa (docs/esp32_raw_tx_report.pdf).

Por que isso existe?

Projetos anteriores da comunidade (wsl_bypasser, esp32-wifi-penetration-tool, Atomic-SAQuery, …) dependiam da sobrescrita de um símbolo C forte sobre a função do blob ieee80211_raw_frame_sanity_check. Essa técnica parou de funcionar silenciosamente por volta do ESP-IDF v5: a ligação do símbolo do blob mudou de WEAK para STRONG, então a sobrescrita agora falha em tempo de link com um erro de múltipla definição.

O fallback óbvio (-Wl,--wrap=ieee80211_raw_frame_sanity_check) também falha silenciosamente: o ld --wrap do GNU só reescreve referências indefinidas entre objetos, mas a chamada que importa — esp_wifi_80211_tx → sanity_check — é intra-objeto dentro de ieee80211_output.o, invisível para --wrap.

Este repositório documenta a mudança quebradora e fornece uma alternativa funcional: reverter o símbolo do blob para WEAK com objcopy --weaken-symbol, e então fornecer a sobrescrita no código da aplicação. A resolução global forte-vence-fraco religa todas as referências, incluindo a intra-objeto.

Consulte docs/esp32_raw_tx_report.pdf para o rastreamento técnico completo, incluindo a desmontagem da lista de permissões de tipos de quadros, três tentativas falhas e evidências de verificação ponta a ponta.

Início rápido

1. Aplicar o patch ao arquivo do IDF

# Assumes IDF is at $IDF_PATH. Override with LIBNET80211=... if needed.
bash patch/patch_libnet80211.sh

# Verify (should print "W" after; "T" means not patched)
xtensa-esp32-elf-nm $IDF_PATH/components/esp_wifi/lib/esp32/libnet80211.a \
    | grep ieee80211_raw_frame_sanity_check
#   0000005c W ieee80211_raw_frame_sanity_check    ← correct

O patch é idempotente; executá-lo novamente não produz alterações. Para reverter:

bash patch/patch_libnet80211.sh --revert

Um backup do arquivo original é salvo como libnet80211.a.bak na primeira execução.

2. Compilar e gravar a demonstração

cd example
idf.py set-target esp32
idf.py build flash monitor

A saída serial deve alternar entre cinco variantes a cada 4 s, cada uma reportando esp_wifi_80211_tx() -> ESP_OK:

I (xxxxx) INJ-DEMO: >>> Sending V0 Deauth (control)            esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V1 Open-Auth (baseline)        esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V2 SAE-Commit bare             esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V3 SAE-Commit full (malformed) esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V4 SAE-Commit valid (scalar=2,E=G)
                                                               esp_wifi_80211_tx() -> ESP_OK

Se, em vez disso, você vir E (xxxxx) wifi:unsupport frame type: 0b0 em cada ciclo, o patch não foi aplicado; execute novamente patch_libnet80211.sh e idf.py fullclean build flash.

3. (Opcional) Captura pelo ar

Aponte outro adaptador Wi-Fi em modo monitor no mesmo canal e execute tcpdump / Wireshark. Consulte evidence/ para um exemplo de captura.

O que está habilitado

Tabela do artigo de pesquisa (Tabela 1):

Tipo de Frame	Subtipos Permitidos no padrão	Subtipos Rejeitados no padrão, Habilitados por este patch
MGMT (0)	4 (ProbeReq), 5 (ProbeResp), 6 (TimingAd), 7, 8 (Beacon), 13 (Action)	0 Assoc, 1 AssocResp, 2 Reassoc, 3 ReassocResp, 9 ATIM, 10 Disassoc, 11 Auth, 12 Deauth
CTRL (1)	(nenhum)	todos (RTS, CTS, ACK, BlockAck, …)
DATA (2)	0–7 (não-QoS)	8–15 (variantes QoS)

Ressalvas

• Restrições a jusante ainda se aplicam. O patch apenas remove a barreira sanity_check. O hardware MAC, a máquina de estados MLME e o agendador de TX ainda aplicam suas próprias restrições. Na prática, isso significa que frames de mgmt são injetados de forma confiável; frames de controle (RTS/CTS/ACK) são enviados mas podem chegar tarde demais do espaço de usuário para o timing adequado do IEEE 802.11 (prazo SIFS). Para fuzzing de conteúdo, o timing não importa; para interações conformes ao protocolo, importa.
• Isto modifica a instalação do ESP-IDF globalmente. Todo projeto que você compilar contra esse IDF será vinculado ao arquivo patcheado. patch_libnet80211.sh --revert restaura o arquivo original a partir do backup.
• Apenas bypass de TX. Isto não afeta o RX — a captura promíscua em modo monitor funciona nativamente no ESP-IDF.
• Testado no ESP-IDF v6.1-dev com ESP32 (clássico). Deve funcionar em v5.x e outros alvos (ESP32-S2/S3/série C) se a vinculação do símbolo for T — verifique com nm primeiro, consulte a etapa "Verify" acima.

Uso ético

As técnicas aqui permitem a transmissão de frames 802.11 brutos, o que tem tanto usos de pesquisa/defensivos (fuzzing, testes de PMF, medição de canal lateral — o caso de uso motivador) quanto usos adversariais (tempestades de deauth contra redes que você não possui). Opere apenas contra redes Wi-Fi e dispositivos que você possui ou tem autorização escrita explícita para testar. A operação não autorizada contra infraestrutura de terceiros é ilegal na maioria das jurisdições.

O autor usa este patch dentro de um ambiente de laboratório isolado na NHSM, Argel, para uma tese de mestrado sobre análise de canal lateral do WPA3-SAE.

Estrutura do repositório

.
├── README.md                            — this file
├── LICENSE                              — MIT
├── patch/
│   └── patch_libnet80211.sh             — the patch script
├── example/                             — minimal demo IDF project
│   ├── CMakeLists.txt
│   └── main/
│       ├── CMakeLists.txt
│       └── main.c
├── docs/
│   └── esp32_raw_tx_report.pdf          — full engineering writeup
└── evidence/
    ├── README.md                        — what each file proves
    ├── sae_injection_first_capture.pcap — monitor-mode OTA capture
    ├── tshark_injected_frames.txt       — decoded frame list
    ├── hostapd_v4_roundtrip.log         — Hostapd parse + response
    └── serial_log_post_bypass.txt       — ESP32 serial, no reject log

Trabalhos relacionados

• risinek/wsl_bypasser — a abordagem original de substituição de mesmo nome. Funciona em IDF ≤ v4.x; quebra silenciosamente em v5+, conforme documentado aqui.
• risinek/esp32-wifi-penetration-tool — depende de wsl_bypasser; mesma limitação.
• Matheus-Garbelini/esp32_esp8266_attacks — PoCs acadêmicos de CVE, limitados à injeção apenas de beacon.
• Vanhoef & Ronen, Dragonblood: Analyzing the Dragonfly Handshake of WPA3 and EAP-pwd, IEEE S&P 2020 — o canal lateral SAE PWE que motiva este projeto.

Citação

Se você usar este patch ou o writeup em trabalho acadêmico, por favor cite:

Mehdi Mansour. "Enabling Raw 802.11 Management Frame Injection on
ESP-IDF v6: A Linker-Level Analysis of ieee80211_raw_frame_sanity_check
and a Reproducible Bypass." Technical report, École Nationale
Supérieure de Mathématiques (NHSM), Algiers, October 2026.

Autor