Skip to content
Back to search

esp32_nat_router

An AI-enabled NAT Router/Firewall for the ESP32

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/martin-ger/esp32_nat_router with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/martin-ger/esp32_nat_router'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/martin-ger--esp32-nat-router/badge.svg)](/listings/martin-ger--esp32-nat-router)

HTML

<a href="/listings/martin-ger--esp32-nat-router"><img src="/api/listings/martin-ger--esp32-nat-router/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ESP32 NAT Router
  2. This is a firmware to use the ESP32 as WiFi NAT router. It routes between the network of the AP interface and the STA or ETH interface as uplink network. It can also work as a VPN router using WireGuard as uplink.
  3. ## Other WiFi Router/Repeater Projects
  4. Starting from this code base I started several spin-off projects with slightly differrent scope. These are all (ab)using the ESP as a minimal network device.
  5. - **Layer 2 WiFi Repeater**: Finally we have it - the **WiFi Repeater**, a layer 2 network bridge between STA and AP (no NAT, no DHCP, just plain frame forwarding in one broadcast domain, i.e. one IP network segment). You currently find it's sources in the [esp32_wifi_repeater](https://github.com/martin-ger/esp32_nat_router/tree/esp32_wifi_repeater) branch of this repo, that is still under development, but it works generally with good performance and makes it a >2$ WiFi extender.
  6. - **WiFi Access Point**: If you have a **W32-ET01 board** and you are looking for a plain ESP32 **Ethernet AP**, or correctly for an **Ethernet to WiFi Layer 2 Bridge**, check out [esp32_eth_wifi_bridge](https://github.com/martin-ger/esp32_eth_wifi_bridge).
  7. - **Ethernet Router**: If you are looking for an ESP32 NAT router with reverse direction, i.e. **WiFi STA as uplink** (Internet) and **Ethernet as downlink** (LAN), check out [esp32_ethernet_router](https://github.com/martin-ger/esp32_ethernet_router). Here I also experiment with support for the common WIZnet W5500 SPI Ethernet NIC.
  8. - **PPPoE Router**: If you ever consider using the ESP32 as an open-source ISP router, have a look at the [esp32_PPPoE_router](https://github.com/martin-ger/esp32_PPPoE_router). It adds PPPoE as additional Ethernet uplink option. So it could be used directly on an ISP modem.
  9. - **VPN Gateway**: If you need more than a WireGuard uplink, check out the [esp32_vpn_gateway](https://github.com/martin-ger/esp32_vpn_gateway). It adds a **WireGuard server** for up to 8 clients (keys, configs and QR codes generated on the device), so phones and laptops can dial *in* and reach the AP network, and a **LAN gateway** that lets machines on your VPN reach hosts on the uplink network. It runs on the dual-core ESP32 and ESP32-S3 (incl. WT32-ETH01 and ESP32-POE-ISO) and is meant for remote access to IoT networks with low traffic demands.
  10. - **ESP8266 NAT Router/Repeater**: The *grandfather* of all these projects, a feature monster once build on the NONOS-SDK for the [ESP8266](https://github.com/martin-ger/esp_wifi_repeater).
  11. ## Use cases for the NAT Router:
  12. - Simple range extender for an existing WiFi network
  13. - An additional WiFi network with different SSID/password and restricted access for guests or IoT devices
  14. - VPN-Router using WireGuard
  15. - Converter from a corporate (WPA2-Enterprise) network to a regular (WPA-PSK) network for simple devices
  16. - Classic WiFi router with Ethernet uplink
  17. - MCP-server to control your network using agentic AI
  18. - Presence detection and network monitoring in a Home Assistant IoT network
  19. - Debugging and monitoring of WiFi devices
  20. ## Key Features
  21. - **NAT Routing**: Full WiFi NAT router with IP forwarding (15+ Mbps throughput)
  22. - **WireGuard VPN**: Optional VPN tunnel for upstream traffic with automatic MSS clamping and Path MTU
  23. - **DHCP Reservations**: Assign fixed IPs to specific MAC addresses
  24. - **Port Forwarding**: Map external ports to internal devices
  25. - **Firewall**: Define ACL to restrict or monitor traffic
  26. - **PCAP Capture**: Live packet capture can be streamed to Wireshark or other network tools
  27. - **WPA2-Enterprise Support**: Connect to corporate networks (PEAP, TTLS, TLS) and convert them to WPA2-PSK
  28. - **5 GHz WiFi**: Dual-band support on ESP32-C5 with configurable band preference (auto/2.4 GHz/5 GHz)
  29. - **Ethernet Support**: Use a W32-ET01 board with LAN8720 PHY to get Ethernet uplink
  30. - **Web Interface**: Web UI with password protection for easy configuration
  31. - **Serial Console**: Full CLI for advanced configuration
  32. - **Remote Console**: Network-accessible CLI via TCP (password protected, per-interface binding)
  33. - **LED Status Indicator**: Visual feedback via plain GPIO LED or addressable LED strip (WS2812/SK6812) with color-coded status
  34. - **OLED Display**: Status display on 72x40 I2C SSD1306 OLEDs (as found on some ESP32-C3 mini boards)
  35. - **MQTT Home Assistant**: Publish telemetry and per-client stats to MQTT with HA auto-discovery
  36. - **MCP Bridge (AI-Ready)**: BETA - Control the router from AI assistants (Claude, etc.) via the Model Context Protocol
  37. - **mDNS**: The router is reachable as `esp32-nat-router.local` via mDNS/Bonjour — no need to look up the IP address.
  38. - **OTA Updates**: Flash new firmware directly from the Web UI
  39. The maximum number of simultaniously connected WiFi clients is 8 (5 on the ESP32c3) due to RAM limitations (uses about 5KB per client). Each of the features: Web Interface, PCAP Capture, Wireguard VPN, Remote Console, WPA Enterprise and MQTT Home Assistant require several KB of additional RAM. So using all of them at once will probably burst the ESP32's ressources. Unused/disabled features are optimized for minimal to no RAM usage. Have a look at remaining heap size if in doubt.
  40. ## First Boot
  41. After first boot the ESP32 NAT Router will offer a WiFi network with an open AP and the ssid "ESP32_NAT_Router". Configuration can either be done via a web interface or via the serial console.
  42. 1. Connect to the **ESP32_NAT_Router** WiFi network
  43. 2. Open **http://esp32-nat-router.local** (or http://192.168.4.1) in your browser
  44. 3. Configure your upstream WiFi and AP settings on the Getting Started page
  45. 4. Click **Save & Reboot**
  46. <img src="https://raw.githubusercontent.com/martin-ger/esp32_nat_router/master/UI_Index.png">
  47. ## Flashing Pre-built Binaries
  48. ### Web Installer (Easiest)
  49. Flash directly from your browser — no tools or command line required:
  50. **[Open Web Installer](https://martin-ger.github.io/esp32_nat_router/)**
  51. Requires a browser with Web Serial API. Select your firmware variant (WiFi or Ethernet) and click "Connect & Install".
  52. ### esptool (Command Line)
  53. Install [esptool](https://github.com/espressif/esptool) and flash using the pre-built binaries from the `firmware_*` directories. Example for ESP32:
  54. ```bash
  55. esptool.py --chip esp32 \
  56. --before default_reset --after hard_reset write_flash \
  57. -z --flash_mode dio --flash_freq 40m --flash_size detect \
  58. 0x1000 firmware_esp32/bootloader.bin \
  59. 0x8000 firmware_esp32/partition-table.bin \
  60. 0xf000 firmware_esp32/ota_data_initial.bin \
  61. 0x20000 firmware_esp32/esp32_nat_router.bin
  62. ```
  63. Pre-built binaries are available for: **ESP32**, **ESP32-C3**, **ESP32-C5**, **ESP32-C6**, **ESP32-S3**, and **WT32-ETH01** (Ethernet).
  64. See the [Installation](https://github.com/martin-ger/esp32_nat_router/wiki/Installation) wiki page for all chip-specific commands.
  65. ## Documentation
  66. Full documentation is available in the [Wiki](https://github.com/martin-ger/esp32_nat_router/wiki):
  67. | Page | Description |
  68. |------|-------------|
  69. | [Web Interface](https://github.com/martin-ger/esp32_nat_router/wiki/Web-Interface) | Web UI pages, security, backup/restore |
  70. | [WiFi and Network](https://github.com/martin-ger/esp32_nat_router/wiki/WiFi-and-Network) | DHCP reservations, port forwarding, WPA2-Enterprise, TTL, DNS |
  71. | [Firewall](https://github.com/martin-ger/esp32_nat_router/wiki/Firewall) | ACL packet filtering rules and configuration |
  72. | [Packet Capture](https://github.com/martin-ger/esp32_nat_router/wiki/Packet-Capture) | PCAP streaming to Wireshark |
  73. | [WireGuard VPN](https://github.com/martin-ger/esp32_nat_router/wiki/WireGuard-VPN) | VPN tunnel configuration and server setup |
  74. | [Remote Console](https://github.com/martin-ger/esp32_nat_router/wiki/Remote-Console) | Network-accessible CLI via TCP |
  75. | [Security](https://github.com/martin-ger/esp32_nat_router/wiki/Security) | Hardening guide: interface binding, VPN, ACL, credential handling |
  76. | [MQTT Home Assistant](https://github.com/martin-ger/esp32_nat_router/wiki/MQTT-Home-Assistant) | MQTT telemetry with HA auto-discovery |
  77. | [MCP Bridge](https://github.com/martin-ger/esp32_nat_router/wiki/MCP-Bridge) | AI assistant integration via Model Context Protocol |
  78. | [CLI Reference](https://github.com/martin-ger/esp32_nat_router/wiki/CLI-Reference) | Full command listing for the serial/remote console |
  79. | [NVS Storage](https://github.com/martin-ger/esp32_nat_router/wiki/NVS-Storage) | Reference of all persisted configuration keys |
  80. | [Hardware](https://github.com/martin-ger/esp32_nat_router/wiki/Hardware) | LED status, OLED display, antenna switch, factory reset |
  81. | [WT32-ETH01](https://github.com/martin-ger/esp32_nat_router/wiki/WT32-ETH01) | Ethernet uplink variant (LAN8720 PHY) |
  82. | [Installation](https://github.com/martin-ger/esp32_nat_router/wiki/Installation) | Flashing pre-built binaries |
  83. | [Building](https://github.com/martin-ger/esp32_nat_router/wiki/Building) | Compiling from source with ESP-IDF or PlatformIO |
  84. ## Building from Source
  85. ```bash
  86. idf.py menuconfig # Enable LWIP IP forwarding, NAT, and L2-to-L3 copy
  87. idf.py build
  88. idf.py flash monitor
  89. ```
  90. See the [Building](https://github.com/martin-ger/esp32_nat_router/wiki/Building) wiki page for PlatformIO, WT32-ETH01, and multi-target build instructions.
  91. ## Performance
  92. The performance of the Router depends on several factors, of course including WiFi signal strength and congestion of the used frequencies. Expect something in the range from 5 - 15 mbps under reasonable conditions. Single video streams should be possible, but it is not intended as a 2$ full replacement for a professional home router.
  93. Internally the speed depends on the processing power of the used ESP32 chip (single core vs. dual core, clock speed) and available RAM for buffering. All "hot pathes", i.e. the direct routing of packets are optimized, any additional features, especially VPN, ACL processing, per client statistics, and packet capturing, introduce some delays. If you need maximum speed, dynamically disable all unused features in the configuration. However in default config everything is already disabled, the only major feature, that is running, is the web interface. Especially on the C3 and C5 with small RAM (and combined DRAM and IRAM) disabling it can result in an additional performance boost, due to the additional buffer space. If required, you can re-enable it via the remote console at any time (with a reboot).
  94. ## Licence
  95. The WireGuard submodul has the following licence_
  96. ```
  97. Copyright (c) 2021 Kenta Ida (fuga@fugafuga.org)
  98. The original license is below:
  99. Copyright (c) 2021 Daniel Hope (www.floorsense.nz)
  100. All rights reserved.
  101. Redistribution and use in source and binary forms, with or without modification,
  102. are permitted provided that the following conditions are met:
  103. * Redistributions of source code must retain the above copyright notice, this
  104. list of conditions and the following disclaimer.
  105. * Redistributions in binary form must reproduce the above copyright notice, this
  106. list of conditions and the following disclaimer in the documentation and/or
  107. other materials provided with the distribution.
  108. * Neither the name of "Floorsense Ltd", "Agile Workspace Ltd" nor the names of
  109. its contributors may be used to endorse or promote products derived from this
  110. software without specific prior written permission.
  111. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  112. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  113. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  114. DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  115. ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  116. (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  117. LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  118. ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  119. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  120. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  121. Author: Daniel Hope <daniel.hope@smartalock.com>
  122. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.