10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32


AI free token/AI免费积分

提到无线协议研究和 WiFi 抓包,大多数嵌入式工程师的第一反应是笔记本插一块支持 monitor mode 的 USB 网卡,开 Wireshark 或 Kismet。这很正常。

但如果你最近翻过 GitHub 上 ESP32 方向的 trending,会发现一个不太合常理的项目——一颗 ESP32 加一块小屏幕,就把 WiFi 嗅探、蓝牙嗅探、协议分析全做成了一台掌上设备。这个项目叫 ESP32 Marauder,目前 10.8k Star、1.2k Fork、167 个 Release,是 ESP32 平台上无线安全研究方向被讨论得最多的开源工程之一。

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里

项目是什么

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里 ESP32 Marauder(直译"ESP32 掠夺者")是一套基于 ESP32 平台的 WiFi/蓝牙 协议研究固件,作者是 GitHub 用户 justcallmekoko。项目从 2019 年开源至今,从最初几个 SSID 嗅探 demo,发展到现在覆盖了 2.4 GHz 频段几乎所有常见无线协议的扫描、嗅探和分析能力。

基本信息(数据来源:GitHub 官方仓库,2026 年 5 月):

  • Star:约 10.8k
  • License:GPL v3
  • 语言占比:C++ 77.2%,C 21.4%
  • 支持平台:ESP32 / ESP32-S2 / ESP32-C5
  • 最新版本:v1.12.1(2026-05-05 发布)
  • Wiki 页面:159 篇

它的核心定位写在 README 第一句:"A suite of WiFi/Bluetooth offensive and defensive tools for the ESP32"——既包含主动扫描、抓包、监控这类研究/防御性能力,也有 deauth、beacon spam、evil portal 这类攻击型功能。这种"双刃剑"属性是它被讨论得最多、也最需要在使用前讲清楚边界的原因。


它凭什么能在 ESP32 上做到这些

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里 ESP32 这颗芯片能扛起整套无线协议分析,关键在于 WiFi 子系统对 混杂模式(monitor mode) 提供了底层 API。

普通 WiFi 模块只能收发"发给自己"的数据帧。但 ESP32 通过 esp_wifi_set_promiscuous(true) 可以开启混杂模式,再注册一个 esp_wifi_set_promiscuous_rx_cb() 回调,就能拿到当前信道上所有的 802.11 原始帧——包括 beacon、probe request、deauth 这些管理帧。这就是 Wireshark + USB 网卡所做的事情,只不过 ESP32 把它压缩到了一颗十几块钱的芯片上。

反方向,ESP32 也支持构造任意 802.11 帧并通过 esp_wifi_80211_tx() 发出去。Marauder 用这一点实现 beacon spam、probe flood、deauth flood——本质上就是按 IEEE 802.11 规范在程序里手搓帧头、填字段、丢到射频。

蓝牙这边逻辑类似。ESP32 上挂着 NimBLE 和 ESP-IDF 蓝牙协议栈,可以做 BLE 广播包嗅探、扫描,也可以伪造特定厂商的广播包(Apple Continuity、Samsung Pair 等)。Airtag 嗅探、信用卡 skimmer 检测,都建立在 BLE 广播分析之上。

工程上还有一个聪明的设计:双核 ESP32,一个核处理射频中断和帧捕获,另一个核处理 UI、SD 卡日志、GPS NMEA 解析。这样在持续抓包时,前端显示和落盘不会被射频中断打断——这恰好是单核 MCU 做协议分析的天花板。


核心功能拆解

Wiki 里 159 页内容,按主线归类大致是四块:

1. WiFi 嗅探与分析(研究/防御为主)

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里Scan APs、Scan Stations、Probe Request Sniff、Beacon Sniff、Deauth Sniff、Packet Monitor、Channel Analyzer、EAPOL PMKID Scan……

其中 Packet Monitor 直接在 TFT 屏上画当前信道的 packet rate 曲线,像一个微型频谱仪。Deauth Sniff 注意是"检测他人发起的 deauth 攻击"——只接收解析、不发包,属于纯防御能力。

Wardrive 是另一个挺工程的模块:把 ESP32 装上 GPS,开车扫一圈,固件会把扫到的 AP 和经纬度存到 SD 卡,输出标准 Wigle 格式 CSV,可以直接导入 wigle.net 做无线热力图。

2. 蓝牙嗅探与监控

除了常规 BLE 设备扫描,这里有几个挺现实的功能: 10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里

  • Airtag Sniff / Monitor:发现附近的 Apple AirTag 广播,提示是否被未知 Airtag 跟踪
  • Detect Card Skimmers:识别加油站、ATM 等地被偷装的蓝牙信用卡 skimmer 设备
  • Flock Sniff / Wardrive:检测美国常见的 Flock Safety 车牌识别摄像头(反监控研究方向)
  • Bluetooth Wardrive:和 WiFi Wardrive 一样的玩法,但跑在 BLE 频段

特别提一下 Card Skimmer 检测——这功能在国外社区被反复推荐,因为蓝牙刷卡器越来越多用 HC-05 这类常见模块,特征明显,Marauder 直接列了出来。

3. CLI / Headless 模式(嵌入式工程师最该关注的部分)

整套功能都有命令行版本。在 Marauder Settings 里开启 EnableHeadlessMode,通过 USB 串口就能直接跑:

sniffbeacon                 # 启动 beacon 嗅探
scanap -t 30                # 扫描 AP,30 秒
scansta                     # 扫描 station(已连接客户端)
list -a                     # 列出已发现的 AP
select -a 0 1 2             # 选中第 0/1/2 个 AP
save -a                     # 保存到 SD 卡
sigmon                      # 信号强度监控

这一段是 Marauder 在"正经场景"里最容易落地的方式——你可以把它当成一个无头无线协议探针塞进自己的项目里。比如做一个企业无线环境的合规巡检小盒子,定期扫描自家办公区域有没有未授权 AP、有没有蓝牙 skimmer 异常出现,自动落盘上报。把 GUI 砍掉、留 CLI,整个设备就回到了纯工业用途。

4. 攻击向功能(必须先看下一节再决定要不要碰)

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里

Deauth Flood、Beacon Spam、Probe Flood、Evil Portal(钓鱼热点)、AP Clone Spam、Karma、Sour Apple(Apple BLE 弹窗轰炸)……

这些功能 wiki 里都有完整工作流,但工程上的注意事项稍后会说——简单一句:" 这些功能在中国大陆几乎全部对应法律风险,不要在自己拥有权之外的网络上跑。 "


上手快速入门

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里 入门门槛在 ESP32 项目里算相对低的,官方做了三条路径:

路径 A:现成硬件
 作者卖一款叫 Marauder v8 的官方板,开盒即用,但价格不低(90–150 USD 一台),主要面向国外社区。

路径 B:DIY 通用 ESP32 + TFT
 仓库里一连串 User_Setup_*.h 文件就是给 DIY 玩家用的。常见适配清单:

  • ESP32 + ILI9341 2.8 寸 TFT
  • M5Stick C / C Plus2
  • M5Cardputer(带键盘)
  • CYD(Cheap Yellow Display,国内淘宝 30–50 元那种 ESP32+触屏一体板)
  • ESP32-S2 / ESP32-C5 DevKit
  • Flipper Zero(作为 ESP32 模块插上去)

挑一个手头有的板子,对应的 User_Setup_*.h 改一下 TFT_eSPI 的引脚定义,就能编译。

路径 C:Web Flash(最快)
 打开作者的 MarauderOTA 页面,浏览器直连 ESP32 USB 串口,按板型选 bin 文件,一键烧录。背后用的是 ESP Web Tools——这个方案对没装过 esptool 的新人特别友好。

烧完后第一次开机,TFT 上会出现 Marauder 的骷髅 logo 和主菜单(WiFi / Bluetooth / Device)。如果你接了 SD 卡和 GPS,状态栏会显示对应图标。


选型建议:和谁比,比什么

ESP32 上做无线协议研究,开源选项不止 Marauder 一个:

项目
重点能力
适合谁
ESP32 Marauder
WiFi+BLE 全套,含 UI/CLI/GPS/SD
想要一台便携、独立运行的研究设备
Bruce
多协议(含 NFC、IR、Sub-GHz),UI 更花
喜欢"瑞士军刀"形态、玩多外设
Pwnagotchi
自动化 PMKID 收集,AI 拟态
长期被动收集 WiFi 握手包
Wireshark + USB 网卡
工业级,协议解析完整
桌面环境、做正式取证或排错

一句话区分:如果你是做嵌入式而不是专门做安全,关注点应该落在 Marauder 的 CLI/Headless 模式——把它当成"一个会自己抓包、自己存盘的协议探针",比当成玩具更有价值。


局限性:必须讲清楚的几条

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里

ESP32 Marauder 在国内嵌入式社区不算"普及度高",原因主要在三点:

1. 法律合规边界(最关键)

deauth、beacon spam、evil portal、AP clone、Karma 等功能在中国大陆使用时,几乎全部触及法律红线,对应法规至少有:

  • 《刑法》第 285、286、287 条(非法侵入计算机信息系统罪、破坏计算机信息系统罪、提供侵入工具罪)
  • 《无线电管理条例》(对干扰他人正常无线电业务的处罚)
  • 《网络安全法》《数据安全法》(对未授权扫描、嗅探他人网络的限制)

哪怕在自己家或自己实验室,针对任何不属于你管理权限的设备做 deauth、伪造 AP 钓鱼,都可能构成违法。这里没有"我只是试试"的灰区。

一句话原则:只在你拥有所有权或获得书面授权的网络里玩。家用路由器、自己的实验设备、公司内部安全演练(且有授权文件)——这些是边界以内;其余都不是。

2. 硬件能力局限

  • ESP32 原生只支持 2.4 GHz,不能抓 5 GHz(ESP32-C5 支持双频,但目前仅适配部分功能)
  • 不支持 WPA3 SAE 的完整解析,只能做协议级嗅探
  • 长时间抓包不如 USB 高速网卡完整,偶有掉帧
  • BLE 嗅探只覆盖广播信道(37/38/39),不能跟踪已配对设备的跳频数据

3. 项目维护偏作者驱动

主仓库基本由 justcallmekoko 一人推进,目前 233 个 issue、30 个 PR。社区有 Discord 和 Gitter,但响应速度和长期路线图都依赖作者节奏。


Q&A

Q:我能用它扫描公司 WiFi 排查问题吗?
 A:在公司明确授权下可以,作为内部安全演练或巡检工具是合规用法。无授权时即使只是"看看",被发现也属于越权扫描。

Q:可以做家用 WiFi 设备清单巡检吗?
 A:扫描自己路由器的 SSID 和已连接 station 完全合法。Marauder 的 Wardrive、Scan APs、Scan Stations 这类被动嗅探用于自家网络监控没问题。

Q:ESP32-C5 适配得如何?
 A:官方已经加了 ESP32-C5 DevKitC-1 的适配页(wiki 有专门一节),能跑双频扫描的部分功能,但完整功能集目前仍以 ESP32 原版为主。

Q:和 Flipper Zero 是什么关系?
 A:Marauder 可以作为 ESP32 模块插在 Flipper Zero 上,由 Flipper 提供按键和屏幕、ESP32 跑 Marauder 固件。两者互补,不互斥。


获取方式

10.8k Star,把 WiFi/蓝牙 抓包仪塞进一颗 ESP32 里官方仓库:https://github.com/justcallmekoko/ESP32Marauder

项目 Wiki(含完整命令列表、硬件适配、工作流示例):https://github.com/justcallmekoko/ESP32Marauder/wiki

Web 烧录工具(MarauderOTA):https://justcallmekoko.github.io/MarauderOTA/


结尾

你有没有在 ESP32 上做过类似的无线协议研究?用了什么硬件、跑在什么场景?欢迎在评论区聊聊。如果你身边正好有人在玩 Flipper Zero、M5Stick 或者 CYD,把这篇转给他们——「单片机那点事」,聊的都是这些把"大设备的能力塞进一颗 MCU"的开源项目。


When it comes to wireless protocol research and WiFi packet capture, most embedded engineers' first reaction is to plug a USB network card that supports monitor mode into a laptop and open Wireshark or Kismet. That's normal.

But if you've browsed the trending ESP32 projects on GitHub recently, you'll find one that defies convention—an ESP32 paired with a small screen, turning WiFi sniffing, Bluetooth sniffing, and protocol analysis into a single handheld device. This project is called ESP32 Marauder, currently at 10.8k Stars, 1.2k Forks, 167 Releases—it's one of the most discussed open-source projects for wireless security research on the ESP32 platform.

8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

What is the project

ESP32 Marauder (literally "ESP32 Marauder") is a WiFi/Bluetooth protocol research firmware based on the ESP32 platform, authored by GitHub user justcallmekoko. Open-sourced since 2019, it has evolved from a few initial SSID sniffing demos into comprehensive scanning, sniffing, and analysis capabilities covering nearly all common wireless protocols in the 2.4 GHz band.8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

Basic information (source: GitHub official repository, May 2026):

Stars: ~10.8k

License: GPL v3

Language breakdown: C++ 77.2%, C 21.4%

Supported platforms: ESP32 / ESP32-S2 / ESP32-C5

Latest version: v1.12.1 (released 2026-05-05)

Wiki pages: 159

Its core positioning is stated in the first line of the README: "A suite of WiFi/Bluetooth offensive and defensive tools for the ESP32"—encompassing both proactive scanning, packet capture, and monitoring (research/defensive capabilities) as well as attack-oriented features like deauth, beacon spam, and evil portals. This dual-edged nature is precisely why it generates so much discussion and why clarifying its boundaries before use is essential.

Why can it achieve all this on ESP32

The key to ESP32 handling full wireless protocol analysis lies in the WiFi subsystem's underlying API support for monitor mode.8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

A standard WiFi module can only send and receive frames addressed to itself. But ESP32 can enable promiscuous mode via esp_wifi_set_promiscuous(true), and by registering a callback with esp_wifi_set_promiscuous_rx_cb(), it can capture all 802.11 raw frames on the current channel—including management frames like beacons, probe requests, and deauths. That's exactly what Wireshark + a USB network card does, only compressed onto a chip costing around ten bucks.

On the transmit side, ESP32 also supports constructing arbitrary 802.11 frames and sending them out via esp_wifi_80211_tx(). Marauder uses this to implement beacon spam, probe flood, and deauth flood—essentially manually crafting frame headers and fields per the IEEE 802.11 specification and transmitting them over the radio.

Bluetooth follows a similar logic. ESP32 runs the NimBLE and ESP-IDF Bluetooth stacks, enabling BLE advertising packet sniffing and scanning, as well as spoofing vendor-specific advertisements (Apple Continuity, Samsung Pair, etc.). Airtag sniffing and credit card skimmer detection both rest on BLE broadcast analysis.

There's also a clever engineering design on the hardware side: the dual-core ESP32 dedicates one core to RF interrupts and frame capture, while the other handles the UI, SD card logging, and GPS NMEA parsing. This means during continuous packet capture, the frontend display and disk writes won't be interrupted by RF events—which happens to be the ceiling for single-core MCUs doing protocol analysis.

Core features broken down

The 159 wiki pages can be broadly grouped into four main categories:

1. WiFi Sniffing and Analysis (primarily research/defense)

Scan APs, Scan Stations, Probe Request Sniff, Beacon Sniff, Deauth Sniff, Packet Monitor, Channel Analyzer, EAPOL PMKID Scan ……8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

Among these, Packet Monitor draws the current channel's packet rate curve directly on the TFT screen—like a mini spectrum analyzer. Deauth Sniff, notably, is about "detecting deauth attacks initiated by others"—it only receives and parses, never transmits, making it purely defensive.

Wardrive is another solid engineering module: mount the ESP32 with a GPS, drive around, and the firmware saves all detected APs along with latitude/longitude to the SD card in standard Wigle-format CSV, ready to import into wigle.net for wireless heat maps.

2. Bluetooth Sniffing and Monitoring

Beyond standard BLE device scanning, a few notably practical features stand out:8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

Airtag Sniff / Monitor: detects nearby Apple AirTag broadcasts and alerts you to potential tracking by unknown Airtags

Detect Card Skimmers: identifies illegally installed Bluetooth credit card skimmer devices at gas stations, ATMs, etc.

Flock Sniff / Wardrive: detects Flock Safety license plate recognition cameras (common in the US, for counter-surveillance research)

Bluetooth Wardrive: same concept as WiFi Wardrive, but operating on the BLE frequency band

Card Skimmer detection deserves special mention—this feature is repeatedly recommended in overseas communities because Bluetooth skimmers increasingly use common modules like the HC-05 with distinctive signatures, which Marauder lists directly.

3. CLI / Headless Mode (the part embedded engineers should focus on most)

All features have CLI equivalents. Enable EnableHeadlessMode in Marauder Settings, and you can run everything directly through the USB serial port:

This is the most practical integration path for Marauder in "serious" scenarios—you can treat it as a headless wireless protocol probe and embed it in your own projects. For example, build a compact compliance inspection box for enterprise wireless environments that periodically scans your office area for unauthorized APs or anomalous Bluetooth skimmers, automatically logging and reporting results. Strip away the GUI, keep the CLI, and the whole device becomes a purely industrial-grade tool.

4. Attack-oriented Features (review the next section before deciding whether to touch them)

8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

Deauth Flood, Beacon Spam, Probe Flood, Evil Portal (phishing hotspot), AP Clone Spam, Karma, Sour Apple (Apple BLE popup flooding) ……

The wiki documents complete workflows for each, but engineering precautions will be covered shortly—the key point in short: "nearly all these features carry legal risk in mainland China; do not run them on networks you do not own."

Quick Start Guide

The entry barrier is relatively low among ESP32 projects, with three official paths:8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

Path A: Pre-built hardware. The author sells an official board called Marauder v8, ready out of the box—but it's not cheap ($90–150 USD per unit), and it's primarily aimed at the overseas community.

Path B: DIY with a generic ESP32 + TFT. A series of User_Setup_*.h files in the repository are tailored for DIY builders. Common hardware combinations:

ESP32 + ILI9341 2.8-inch TFT

M5Stick C / C Plus2

M5Cardputer (with keyboard)

CYD (Cheap Yellow Display—the ~30–50 RMB ESP32+touchscreen combo board popular on Taobao)

ESP32-S2 / ESP32-C5 DevKit

Flipper Zero (plugged in as an ESP32 module)

Pick whichever board you have on hand, modify the corresponding User_Setup_*.h to update the TFT_eSPI pin definitions, and compile.

Path C: Web Flashing (fastest). Open the author's MarauderOTA page, connect your ESP32 USB serial directly through the browser, select the bin file for your board, and flash with one click. It runs on ESP Web Tools—this approach is especially beginner-friendly since it requires no esptool installation.

After flashing, the first boot displays Marauder's skull logo and main menu on the TFT (WiFi / Bluetooth / Device). If you've connected an SD card and GPS, their icons appear in the status bar.

Hardware selection guide: what to compare, and against whom

When doing wireless protocol research on ESP32, Marauder isn't the only open-source option:

Project

Key capabilities

Who it's for

ESP32 Marauder

Full WiFi+BLE suite, with UI/CLI/GPS/SD

Anyone wanting a portable, standalone research device

Bruce

Multi-protocol (including NFC, IR, Sub-GHz), more elaborate UI

Users who prefer a "Swiss army knife" form factor and enjoy plugging in multiple peripherals

Pwnagotchi

Automated PMKID collection, AI personality simulation

Those passively collecting WiFi handshake packets over extended periods

Wireshark + USB network card

Industrial-grade, complete protocol analysis

Desktop environments, formal forensics, or troubleshooting

One sentence to distinguish them: if you're an embedded engineer rather than a security specialist, your focus should fall on Marauder's CLI/Headless mode—treating it as "a protocol probe that autonomously captures and stores packets" is far more valuable than treating it as a toy.

Limitations: a few things that must be stated clearly

8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

ESP32 Marauder hasn't achieved high penetration in China's embedded community, primarily due to three factors:

1. Legal compliance boundaries (the most critical factor)

Features like deauth, beacon spam, evil portal, AP clone, and Karma, when used in mainland China, nearly all cross legal red lines. Relevant regulations include at minimum:

Articles 285, 286, and 287 of the Criminal Law (illegal intrusion into computer information systems, destruction of computer information systems, provision of intrusion tools)

The Radio Management Regulations (penalties for interfering with others' legitimate radio operations)

The Cybersecurity Law and Data Security Law (restrictions on unauthorized scanning and sniffing of others' networks)

Even within your own home or lab, performing deauth or setting up rogue APs for phishing against any device outside your management authority may constitute illegal activity. There is no gray area for "I was just testing."

One-sentence principle: only operate on networks you own or have written authorization for. Home routers, your own lab equipment, internal company security drills (with authorization documentation)—these are within bounds; everything else is not.

2. Hardware capability limitations

ESP32 natively supports only 2.4 GHz; it cannot capture 5 GHz (the ESP32-C5 supports dual-band, but currently only partial features are adapted)

Full WPA3 SAE decryption is not supported—only protocol-level sniffing is possible

Long-duration packet capture is less comprehensive than a USB high-speed adapter, with occasional frame drops

BLE sniffing only covers the advertising channels (37/38/39); it cannot track frequency-hopping data from already-paired devices

3. Project maintenance is primarily author-driven

The main repository is essentially advanced by justcallmekoko alone, with 233 open issues and 30 PRs. The community has Discord and Gitter channels, but response speed and the long-term roadmap both depend on the author's pace.

Q&A

Q: Can I use it to scan my company's WiFi for troubleshooting? A: Yes, under explicit company authorization—as an internal security drill or inspection tool, it's compliant usage. Without authorization, even simply "taking a look" constitutes unauthorized scanning if discovered.

Q: Can I use it for home WiFi device inventory checks? A: Scanning your own router's SSID and connected stations is entirely legal. Marauder's passive sniffing features like Wardrive, Scan APs, and Scan Stations are perfectly fine for monitoring your own network.

Q: How well is the ESP32-C5 supported? A: Official adaptation has been added for the ESP32-C5 DevKitC-1 (there's a dedicated wiki section), enabling partial dual-band scanning features—but the complete feature set still primarily targets the original ESP32.

Q: How does it relate to the Flipper Zero? A: Marauder can run as an ESP32 module plugged into a Flipper Zero, with the Flipper providing buttons and display while the ESP32 runs the Marauder firmware. The two complement each other; they are not mutually exclusive.

Where to get it

Official repository: https://github.com/justcallmekoko/ESP32Marauder8k Stars: Fitting a WiFi/Bluetooth Packet Sniffer into an ESP32

Project Wiki (complete command list, hardware compatibility, workflow examples): https://github.com/justcallmekoko/ESP32Marauder/wiki

Web flashing tool (MarauderOTA): https://justcallmekoko.github.io/MarauderOTA/

Closing

Have you done similar wireless protocol research on ESP32? What hardware did you use, and in what scenarios? Feel free to share in the comments. If someone you know is working with a Flipper Zero, M5Stick, or CYD, forward this to them—"单片机那点事" covers exactly these kinds of open-source projects that pack "big device capabilities into a single MCU."

Original article: https://mp.weixin.qq.com/s/XvgGgmU_Q_iF_bVx5kK_AQ

暂无评论,快来发表第一条评论吧!No comments yet. Be the first!

📮 需求咨询📮 Inquiry