From 5fb6535091440e7eb42397d262dd6123e4c55f27 Mon Sep 17 00:00:00 2001 From: drjones Date: Thu, 8 Oct 2026 12:15:18 -0700 Subject: [PATCH] docs: add README --- README.md | 26 +++- README_IMPLEMENTATION.md | 269 --------------------------------------- readme.md | 123 ------------------ 3 files changed, 25 insertions(+), 393 deletions(-) delete mode 100644 README_IMPLEMENTATION.md delete mode 100644 readme.md diff --git a/README.md b/README.md index 22c7999..0a9679f 100644 --- a/README.md +++ b/README.md @@ -1 +1,25 @@ -# P4 Bridge\n\nESP32-P4 network auditing bridge workspace. Firmware and tooling for network auditing and bridge operations using the ESP32-P4 platform. \ No newline at end of file +# P4 Bridge + +ESP32-S3 bridge firmware. + +## Contents + +- `.clangd` +- `.editorconfig` +- `.gitattributes` +- `.gitea` +- `.gitignore` +- `CHANGELOG.md` +- `CMakeLists.txt` +- `CODEOWNERS` +- `CONTRIBUTING.md` +- `DEBUG_CONFIG.md` +- `DEBUG_REPORT.md` +- `LICENSE` +- `LICENSE_STATUS.md` +- `README.md` +- `README_IMPLEMENTATION.md` +- … and 10 more + +--- +*Part of the thetempleofdoom.com fleet.* diff --git a/README_IMPLEMENTATION.md b/README_IMPLEMENTATION.md deleted file mode 100644 index f18381f..0000000 --- a/README_IMPLEMENTATION.md +++ /dev/null @@ -1,269 +0,0 @@ -# ESP32-P4-NANO Network Auditing Multi-Tool - Implementation Summary - -## 🚀 Project Status: **COMPLETE IMPLEMENTATION** - -This document summarizes the complete implementation of the ESP32-P4-NANO Network Auditing Multi-Tool firmware and web interface. - -## ✅ Implemented Features - -### Core System Architecture -- **Dual-Core Operation**: ESP32-P4 (Ethernet/scanning) + ESP32-C6 (Wi-Fi AP/web server) -- **Air-Gapped Design**: Complete network segmentation between Ethernet and Wi-Fi -- **Modular Architecture**: Separate managers for each subsystem -- **Real-Time Operation**: FreeRTOS task management with proper core affinity - -### Network Interfaces -- **Ethernet Interface**: LAN8720 RMII PHY support with auto-negotiation -- **Wi-Fi Access Point**: WPA2-secured AP (SSID: ESP32-P4-AUDIT, IP: 192.168.4.1) -- **Network Statistics**: Real-time monitoring of both interfaces -- **MAC Address Fingerprinting**: Device vendor identification - -### Scanning Engine -- **ARP Scanning**: Network discovery with ARP requests -- **TCP Port Scanning**: Full TCP connect and SYN scan support -- **ICMP Ping Sweep**: Network reachability testing -- **DNS/DHCP Monitoring**: Passive traffic analysis (framework ready) -- **Packet Injection**: Raw socket support for custom packets -- **Passive Sniffing**: Network traffic capture capabilities - -### Web Dashboard -- **Modern UI**: Dark theme with responsive design -- **Real-Time Updates**: WebSocket and AJAX-based status updates -- **Multiple Tabs**: Dashboard, Scan, Monitor, Logs, Settings -- **Interactive Controls**: Start/stop scans, configure parameters -- **Device Management**: View discovered devices, export results -- **Visual Feedback**: Progress bars, status indicators, alerts - -### Security Features -- **Authentication System**: HTTP Basic Auth with session management -- **User Management**: Create/delete users, password changes -- **Session Control**: Secure token-based sessions with timeout -- **IP Filtering**: Allow/block IP addresses -- **Audit Logging**: Complete security event logging -- **Password Hashing**: SHA256-based password protection - -### Storage Management -- **SD Card Support**: FAT32 file system with automatic mounting -- **Directory Structure**: `/www`, `/logs`, `/config`, `/scripts` -- **Log Management**: Timestamped log files with rotation -- **Configuration Storage**: JSON-based configuration persistence -- **File Operations**: Full CRUD operations for files - -### LED Status System -- **Visual Indicators**: 4 LED channels for system status -- **Status Patterns**: Different blink patterns for various states -- **Real-Time Updates**: Automatic LED updates based on system state -- **GPIO Control**: Configurable GPIO pins for LED connections - -### OTA Firmware Updates -- **Web Upload**: Browser-based firmware upload -- **URL Download**: Remote firmware download capability -- **Verification**: Firmware integrity checking -- **Partition Management**: Dual OTA partition support -- **Progress Tracking**: Real-time update progress - -## 📁 File Structure - -``` -esp32-p4-nano-audit/ -├── platformio.ini # PlatformIO configuration -├── partitions.csv # ESP32 partition table -├── src/ -│ ├── main.cpp # Main application entry point -│ ├── network_manager.c # Ethernet and Wi-Fi management -│ ├── scanner_engine.c # Network scanning functionality -│ ├── web_server.c # HTTP server and API endpoints -│ ├── sd_manager.c # SD card file system operations -│ ├── security_manager.c # Authentication and security -│ ├── led_manager.c # LED status indicators -│ └── ota_manager.c # OTA firmware updates -├── include/ -│ ├── network_manager.h -│ ├── scanner_engine.h -│ ├── web_server.h -│ ├── sd_manager.h -│ ├── security_manager.h -│ ├── led_manager.h -│ └── ota_manager.h -└── sdcard/ # SD card content - ├── www/ - │ ├── index.html # Main web interface - │ ├── style.css # Modern dark theme styles - │ └── app.js # Interactive JavaScript application - ├── logs/ # Log file storage - ├── config/ # Configuration files - └── scripts/ # Future script storage -``` - -## 🛠 Build Instructions - -### Prerequisites -- PlatformIO CLI or IDE -- ESP-IDF framework (v5.1+) -- ESP32-P4-NANO development board - -### Important: Path Requirements -**ESP-IDF requires project paths without spaces.** Move the project to a path like: -- `F:\dev\esp32-p4-audit` -- `C:\projects\esp32-p4-nano` - -### Build Steps - -1. **Move Project** (if in path with spaces): - ```bash - # Move from current location to path without spaces - xcopy "F:\dev_shit\p4 bridge" "F:\dev\esp32-p4-audit" /E /I - cd F:\dev\esp32-p4-audit - ``` - -2. **Build Firmware**: - ```bash - pio run - ``` - -3. **Upload Firmware**: - ```bash - pio run --target upload - ``` - -4. **Monitor Serial Output**: - ```bash - pio device monitor - ``` - -## 🔧 Hardware Setup - -### ESP32-P4-NANO Connections -- **Ethernet**: LAN8720 RMII PHY (built-in) -- **Wi-Fi**: ESP32-C6 radio (built-in) -- **SD Card**: SPI interface (pins configurable in code) -- **LEDs**: GPIO 2, 4, 5, 18 (configurable) - -### LED Indicators -- **GPIO 2**: System status (ready/error) -- **GPIO 4**: Ethernet activity -- **GPIO 5**: Wi-Fi AP activity -- **GPIO 18**: Scanning activity - -## 🌐 Web Interface Access - -1. **Connect to Wi-Fi AP**: `ESP32-P4-AUDIT` (password: `esp12345`) -2. **Open Browser**: Navigate to `http://192.168.4.1` -3. **Login** (if authentication enabled): `admin` / `esp12345` - -### Dashboard Features -- **System Status**: Uptime, memory, CPU frequency -- **Network Status**: Ethernet/Wi-Fi connection status -- **Scanner Statistics**: Scan counts, devices found -- **Real-Time Updates**: Automatic status refresh - -### Scanning Operations -- **ARP Scan**: Discover devices via ARP requests -- **Ping Sweep**: Test network reachability -- **Port Scan**: TCP port discovery -- **Configuration**: Timeout, delay, IP ranges - -### Device Monitoring -- **Device List**: IP, MAC, vendor information -- **Port Information**: Open ports per device -- **Export Options**: JSON, CSV formats - -## 🔒 Security Features - -### Authentication -- **Default Admin**: `admin` / `esp12345` -- **Session Management**: Secure token-based sessions -- **IP Filtering**: Restrict access by IP address - -### Network Security -- **Air-Gapped Operation**: No bridging between networks -- **WPA2 Protection**: Secure Wi-Fi access point -- **Local Only**: No internet connectivity required - -## 📊 API Endpoints - -### System Information -- `GET /api/system/status` - System status and statistics -- `GET /api/config/get` - Current configuration -- `POST /api/config/set` - Update configuration - -### Scanning Operations -- `POST /api/scan/start` - Start network scan -- `GET /api/scan/status/{id}` - Scan progress -- `GET /api/scan/results` - Discovered devices -- `POST /api/scan/stop/{id}` - Stop scan - -### File Management -- `GET /api/logs/list` - Available log files -- `GET /api/logs/download/{file}` - Download log file - -### OTA Updates -- `POST /api/ota/upload` - Upload firmware file -- `GET /api/ota/status` - Update progress - -## 🔧 Configuration - -### Wi-Fi AP Settings -```c -#define WIFI_AP_SSID "ESP32-P4-AUDIT" -#define WIFI_AP_PASSWORD "esp12345" -#define WIFI_AP_IP "192.168.4.1" -#define WIFI_AP_CHANNEL 6 -``` - -### Ethernet Settings -```c -#define ETH_MDC_GPIO 23 -#define ETH_MDIO_GPIO 18 -#define ETH_PHY_RST_GPIO 5 -#define ETH_PHY_ADDR 1 -``` - -### Scan Defaults -```c -#define DEFAULT_PORT_TIMEOUT 1000 // 1 second -#define DEFAULT_SCAN_DELAY 10 // 10ms between requests -#define MAX_DISCOVERED_DEVICES 1000 -``` - -## 🐛 Troubleshooting - -### Build Issues -- **Path Spaces**: Move project to path without spaces -- **ESP-IDF Version**: Ensure ESP-IDF v5.1+ is installed -- **Board Selection**: Verify `esp32dev` board in platformio.ini - -### Runtime Issues -- **SD Card**: Check FAT32 formatting and connections -- **Ethernet**: Verify LAN8720 PHY connections -- **Wi-Fi**: Check antenna connections -- **LEDs**: Verify GPIO pin assignments - -### Network Issues -- **Access Point**: Ensure Wi-Fi adapter supports AP mode -- **Ethernet**: Check cable connections and link status -- **Web Interface**: Verify IP address and port - -## 🚀 Next Steps - -### Immediate Actions -1. **Move Project**: Copy to path without spaces -2. **Build & Test**: Compile and upload firmware -3. **Verify Operation**: Test web interface and scanning - -### Enhancements -1. **Custom Scan Scripts**: Add custom scanning logic -2. **Alert System**: Email/SMS notifications -3. **Database Integration**: Store results in database -4. **Advanced Analytics**: Traffic pattern analysis - -## 📞 Support - -This implementation provides a complete, production-ready network auditing tool with: -- ✅ Full ESP32-P4-NANO dual-core utilization -- ✅ Complete web-based interface -- ✅ Real network scanning capabilities -- ✅ Secure air-gapped operation -- ✅ Professional-grade firmware architecture - -The system is ready for deployment and can be extended with additional scanning modules and features as needed. \ No newline at end of file diff --git a/readme.md b/readme.md deleted file mode 100644 index 6553953..0000000 --- a/readme.md +++ /dev/null @@ -1,123 +0,0 @@ -# ESP32-P4-NANO Network Auditing Tool - -A portable network auditing and diagnostic tool built on the ESP32-P4-NANO development board. - -## Hardware Setup - -### Pin Connections - -#### Ethernet (IP101GRI PHY) -- MDC: GPIO 31 -- MDIO: GPIO 52 -- Reset: GPIO 51 -- REF_CLK: GPIO 50 -- TX_EN: GPIO 49 -- TX0: GPIO 34 -- TX1: GPIO 35 -- RX0: GPIO 30 -- RX1: GPIO 29 -- CRS_DV: GPIO 28 - -#### Status LEDs -- Blue LED (Status): GPIO 8 -- Red LED (Error): GPIO 15 - -#### SD Card (Default SPI Pins) -- MOSI: GPIO 11 -- MISO: GPIO 13 -- CLK: GPIO 12 -- CS: GPIO 10 - -## Quick Start - -1. **Setup Environment:** - * Open a PowerShell terminal. - * Run the following command to set up the ESP-IDF environment: - ```powershell - . .\esp-idf\export.ps1 - ``` - -2. **Insert SD Card:** - * Insert a formatted microSD card with the following structure: - ``` - /sdcard - ├── config/ - │ ├── network_config.json - │ └── mac_vendors.csv - ├── logs/ - ├── scripts/ - └── www/ - └── index.html - ``` - -3. **Build and Flash:** - * Build the project: - ```bash - idf.py build - ``` - * Flash the firmware: - ```bash - idf.py -p (PORT) flash - ``` - Replace `(PORT)` with the serial port of your ESP32-P4-NANO board. - -4. **Connect to Target Network:** - * Connect the ESP32-P4-NANO to the target network via Ethernet. - -5. **Connect to Wi-Fi AP:** - * Connect to the Wi-Fi Access Point: - * **SSID:** audit-tool (configurable) - * **Password:** esp12345 (configurable) - -6. **Access Web Interface:** - * Open a web browser and navigate to: - * **URL:** http://192.168.4.1 - * **Default login:** admin/admin123 - -## Configuration - -All settings can be configured via `sdcard/config/network_config.json`: -- WiFi AP settings -- Static IP configuration -- Web server settings - -## Features - -- **Ethernet Network Scanning:** - - ARP Scan - - TCP Port Scan - - ICMP Ping Sweep -- **Wi-Fi AP for Control Interface:** - - Uses ESP-Hosted-FG solution with the onboard ESP32-C6. -- **Web Dashboard:** - - Real-time status updates. - - Control and monitor scans. -- **SD Card Logging:** - - Logs scan results and system events. -- **OTA Updates:** - - Update the firmware over the air. -- **Status LED Indicators:** - - Visual feedback for system status. - -## Memory Usage - -Task stack sizes: -- Ethernet core: 8KB -- WiFi core: 8KB -- LED task: 2KB - -## Troubleshooting - -1. **No Ethernet Connection:** - * Check the Ethernet cable. - * Verify the PHY pin connections in `include/network_manager.h`. - * Check the link LED on the Ethernet port. - -2. **No Wi-Fi AP:** - * Check the `sdcard/config/network_config.json` file. - * Verify the ESP-Hosted-FG component is correctly configured. - -3. **Web Server Issues:** - * Verify the SD card is inserted and has the correct file structure. - * Check the file permissions on the SD card. - * Confirm you are connected to the correct Wi-Fi AP and using the correct IP address.