# ESP32Marauder-MicroPython

**Repository Path**: zesso/ESP32Marauder-MicroPython

## Basic Information

- **Project Name**: ESP32Marauder-MicroPython
- **Description**: MicroPython 重制版去掉 TFT 屏幕,设备开机即开启自己的 WiFi 热点,手机/电脑连接后 访问 **http://192.168.4.1** 即可在网页上完全控制设备。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
AIGC:
  ContentProducer: '001191110102MAD55U9H0F10002'
  ContentPropagator: '001191110102MAD55U9H0F10002'
  Label: '1'
  ProduceID: '89a862d7-e4c6-45d7-80a0-6bfc5a737a1c'
  PropagateID: '89a862d7-e4c6-45d7-80a0-6bfc5a737a1c'
  ReservedCode1: '7f6da4cb-63e1-4e97-8625-b2ed79240a26'
  ReservedCode2: '7f6da4cb-63e1-4e97-8625-b2ed79240a26'
---

# ESP32 Marauder · MicroPython

基于 [justcallmekoko/ESP32Marauder](https://github.com/justcallmekoko/ESP32Marauder) 的
**MicroPython 重制版**:去掉 TFT 屏幕,设备开机即开启自己的 WiFi 热点,手机/电脑连接后
访问 **http://192.168.4.1** 即可在网页上**完全控制**设备。

> ⚠️ 本项目仅用于**授权范围内的安全测试与学习**。请遵守当地法律法规,勿用于未授权网络。

## 与原版的区别

| 能力 | 原版(ESP-IDF 固件) | 本版(MicroPython) |
| --- | --- | --- |
| 屏幕 | TFT 屏幕操作 | ❌ 无屏幕,全部 Web 控制 |
| Web 控制台 | 部分版本支持 | ✅ 内置(192.168.4.1) |
| AP / 站点扫描 | ✅ | ✅ 相同 |
| 连接外部 WiFi | ✅ | ✅ |
| SSID 列表管理 | ✅ | ✅ 持久化存储,预设模板,扫描批量导入 |
| 邪恶门户(钓鱼 AP + 凭据捕获) | ✅ | ✅ 完全实现(伪造 AP + 迷你 DNS 劫持) |
| 802.11 监听(Beacon/Probe/Deauth 计数) | ✅ | ⚠️ ESP8266 可用;ESP32 需自定义固件 |
| 监听信道手动设置 | ✅ | ✅ Web 控制 |
| Deauth / Beacon / Probe 攻击 | ✅ | ⚠️ 需把 `firmware/wifi_attack.c` 编译进固件 |
| BLE | ✅ | ❌ MicroPython 暂不实现 |
| 恢复出厂设置 | ✅ | ✅ Web 控制 |

## 硬件要求

- **ESP32 系列**(推荐)或 ESP8266(NodeMCU 等)
- 已刷 MicroPython 固件(1.19+,ESP32 官方稳定版即可)
- 建议使用 ESP32:内存大、Web 面板体验好;ESP8266 也能跑但更吃力

## 文件结构

```
boot.py            # 开机引导(含启动失败兜底诊断)
main.py            # 启动:开 AP(192.168.4.1)+ Web 控制台
diag.py            # 启动失败时的诊断 AP + 错误页
compat.py          # 固件兼容层(模块名 + 线程检测)
config.py          # 配置持久化(/config.json) + SSID 列表(/ssid_list.json)
util.py            # 公共工具
wifi_ctrl.py       # WiFi 控制:AP / 扫描 / 连接
sniffer.py         # 802.11 监听(ESP8266 / 自定义固件)
attacks.py         # 攻击引擎(beacon/deauth/probe,需 wifi_attack 模块)
dns.py             # 迷你 DNS 服务器(门户劫持用)
portal.py          # 邪恶门户 + 钓鱼页 + 凭据捕获
web.py             # HTTP 服务器 + REST API
www/index.html     # Web 控制面板(上传到设备 /www/index.html)
upload.py          # 【电脑端】一键上传脚本(需 mpremote)
test_hardware.py   # 设备自检脚本
firmware/wifi_attack.c   # 可选:攻击引擎 C 模块(需编译)
firmware/README.md       # 编译自定义固件的步骤
```

## 安装

### 1. 刷 MicroPython 固件

- ESP32:从 [micropython.org/download](https://micropython.org/download/ESP32_GENERIC/) 下载
  `ESP32_GENERIC` 固件,用 esptool 或 Thonny 烧录(建议最新稳定版,1.20 以上)。
- ESP8266:下载 `ESP8266_GENERIC` 固件烧录。

### 2. 上传代码(二选一)

**方式 A:一键脚本(推荐)**

```bash
pip install mpremote
python upload.py COM5            # Windows;COM5 换成你的串口
# 或自动检测(仅一个设备时): python upload.py
python upload.py COM5 --reset    # 上传后自动重启
```

**方式 B:mpremote 手动**

```bash
pip install mpremote
mpremote connect COM3 mkdir www
mpremote connect COM3 cp boot.py main.py diag.py compat.py config.py util.py wifi_ctrl.py sniffer.py attacks.py dns.py portal.py web.py :
mpremote connect COM3 cp www/index.html :/www/index.html
mpremote connect COM3 reset
```

**方式 C:Thonny** 全选 .py 文件右键「上传到 /」,再上传 `www/index.html` 到 `/www/`。

### 3. 连接设备

1. 设备上电后搜索 WiFi,找到 `ESP32-Marauder`(默认无密码)
2. 连接后浏览器打开 **http://192.168.4.1**(部分手机弹出"无互联网连接"提示,点"继续使用"即可)
3. 进入中文控制面板,即可完全控制设备

> 找不到热点?先运行自检 `python -m mpremote run test_hardware.py` 看输出。
> 若出现名为 `Marauder-DIAG` 的热点,说明程序启动失败,连上它访问 http://192.168.4.1 会显示错误详情。
> 完整堆栈也可在串口监视器(115200 波特率)中看到。

## 使用说明(控制面板各页)

- **仪表盘**:设备信息、网络状态、能力检测、快捷操作
- **扫描**:扫描周围 AP(勾选作为攻击目标)、查看本机 AP 客户端、批量加入 SSID 列表
- **SSID 列表**:管理 SSID 列表(手动添加/预设模板/设备端同步),用于 Beacon 克隆和 Probe 轰炸
- **攻击**:Beacon 轰炸(自定义列表/随机/克隆选中 AP/使用 SSID 列表)、Deauth(洪水/定向/手动)、Probe 轰炸
- **监听**:802.11 帧计数(Beacon/Probe/Deauth/数据帧)+ 发现设备 MAC + 手动信道设置
- **邪恶门户**:输入目标 SSID 启动钓鱼 AP,DNS 全部劫持到本机,任意访问显示钓鱼页,捕获的账号密码实时显示
- **WiFi 连接**:让设备以 STA 模式连接外部网络(AP 控制台不受影响)
- **设置**:修改 AP 名称/密码/信道、隐藏 SSID、重启设备、恢复出厂设置

### SSID 列表预设

内置多套 SSID 列表预设,一键加载:

- **Rickroll**: Rick Astley 歌词系列
- **Amogus**: Among Us 梗
- **FBI**: 监控类趣味 SSID
- **Free WiFi**: 常见免费 WiFi 名称

### 自定义钓鱼页

上传任意 HTML 到设备根目录 `/portal.html` 即可替换默认钓鱼页。要求:表单 `method="POST" action="/get"`,
字段名 `username` 与 `password`。

## REST API 参考

```
GET  /api/info            # 设备信息(平台/内存/Flash/能力)
GET  /api/status          # 实时状态(攻击/监听/门户/网络)
GET  /api/diag            # 诊断(错误日志/运行时间)
GET  /api/scan?type=ap    # 扫描周围 AP
GET  /api/scan?type=clients  # 本机 AP 已连接客户端
GET  /api/ssid             # 获取 SSID 列表
GET  /api/portal/creds    # 获取门户捕获的凭据

POST /api/connect         # STA 连接外部 WiFi
POST /api/disconnect      # STA 断开
POST /api/ap              # 修改 AP 配置
POST /api/attack          # 攻击控制(action:start/stop)
POST /api/sniff           # 监听控制(action:start/stop/channel)
POST /api/portal          # 门户控制(action:start/stop)
POST /api/portal/clear    # 清空捕获凭据
POST /api/ssid            # SSID 列表管理(action:load/save/add/clear)
POST /api/reboot          # 重启设备
POST /api/factory_reset   # 恢复出厂设置
```

## 常见问题

**Q:烧录后找不到热点 / 完全不可用?**
按顺序排查:
1. 确认刷的是 **MicroPython** 固件(不是原版 Marauder / Arduino 固件),且是 1.20+ 稳定版
2. 确认代码**全部上传成功**(12 个 .py + www/index.html),用 `python -m mpremote run test_hardware.py` 自检
3. 打开串口监视器(115200):能看到启动横幅说明成功;看到 `Marauder-DIAG` 说明启动失败,连该热点访问 192.168.4.1 看错误详情,或把串口报错发来
4. 若串口无任何输出:固件没刷好或硬件/波特率问题,重新烧录

**Q:攻击按钮提示"当前固件不支持无线攻击"?**
标准 MicroPython 无裸帧发送能力。按 `firmware/README.md` 把 `wifi_attack.c` 编译进固件即可。
不编译时,扫描 / 连接 / 邪恶门户 / 监听(ESP8266)依然可用。

**Q:连接 / 保存设置 / 攻击 等按钮点了没反应?**
可能是旧版本代码的请求体解析 bug。请更新代码(尤其是 web.py),或确认设备端 `/www/index.html`
与控制面板为最新版本。也可在浏览器开发者工具 Console 看报错。

**Q:扫描为什么慢 / 会卡几秒?**
`wlan.scan()` 是同步阻塞 API(约 3~6 秒),扫描期间网页会短暂等待,属正常现象。

**Q:监听期间 WiFi 不稳 / 断连?**
promiscuous 模式与正常收发共存时性能会下降(ESP8266 尤其明显)。请先停止监听再操作。

**Q:改了 AP 配置后打不开网页?**
AP 重建后请重新连接 WiFi,再访问 192.168.4.1。

**Q:怎么改默认 AP 名称/密码?**
网页「设置」页修改,或直接编辑 `/config.json`(或本仓库 `config.py` 的 `DEFAULTS`)。

**Q:ESP8266 能用吗?**
可以,扫描/连接/门户/监听(esp 模块)都能用;但无线程支持(自动跳频、攻击引擎不可用),内存也较小。

**Q:页面显示"设备连接断开"?**
请确认手机/电脑已连接 ESP32 的 WiFi 热点,并且没有自动切换到其他网络。

## 免责声明

本项目仅供安全研究与授权测试使用。擅自对他人网络进行扫描/干扰/钓鱼属违法行为,
使用者需自行承担一切法律责任。