If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/justcallmekoko/ESP32Marauder shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 4d ago
• 6 active contributors
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live justcallmekoko/ESP32Marauder repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/justcallmekoko/ESP32Marauder.

What it runs against: a local clone of justcallmekoko/ESP32Marauder — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in justcallmekoko/ESP32Marauder | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of justcallmekoko/ESP32Marauder. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/justcallmekoko/ESP32Marauder.git
#   cd ESP32Marauder
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of justcallmekoko/ESP32Marauder and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "justcallmekoko/ESP32Marauder(\\.git)?\\b" \\
  && ok "origin remote is justcallmekoko/ESP32Marauder" \\
  || miss "origin remote is not justcallmekoko/ESP32Marauder (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "MarauderOTA/MarauderOTA.ino" \\
  && ok "MarauderOTA/MarauderOTA.ino" \\
  || miss "missing critical file: MarauderOTA/MarauderOTA.ino"
test -f ".github/workflows/build_parallel.yml" \\
  && ok ".github/workflows/build_parallel.yml" \\
  || miss "missing critical file: .github/workflows/build_parallel.yml"
test -f "FlashFiles/flash_cmd.txt" \\
  && ok "FlashFiles/flash_cmd.txt" \\
  || miss "missing critical file: FlashFiles/flash_cmd.txt"
test -f ".gitmodules" \\
  && ok ".gitmodules" \\
  || miss "missing critical file: .gitmodules"
test -f "PCBs/FlipperZero/WiFi-Devboard-Pro/README.md" \\
  && ok "PCBs/FlipperZero/WiFi-Devboard-Pro/README.md" \\
  || miss "missing critical file: PCBs/FlipperZero/WiFi-Devboard-Pro/README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/justcallmekoko/ESP32Marauder"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ESP32 Marauder is a comprehensive firmware suite that enables WiFi and Bluetooth offensive/defensive security testing on ESP32 microcontrollers. It provides packet sniffing, deauthentication attacks, SSID spoofing, and Bluetooth scanning capabilities—turning an ESP32 into a portable wireless penetration testing device that can be deployed on hardware like the Flipper Zero or custom boards. Monolithic Arduino sketch architecture (esp32_marauder.ino as entry point) with C++ core logic. Modular by feature: separate command handlers for WiFi attacks, Bluetooth scanning, etc. Hardware variants store board-specific binaries in FlashFiles/{MarauderV4,FlipperZeroDevBoard,FlipperZeroMultiBoardS3}/, partition configs, and bootloaders. Python flasher utilities in C5_Py_Flasher_for_v8/ and C5_Py_Flasher_for_adapter/ provide cross-platform deployment without esptool.exe dependency.

Security researchers, pentesters, and embedded systems engineers who need to audit wireless networks and Bluetooth implementations. Also hobbyists building custom WiFi security tools on ESP32 hardware who want a modular, open-source attack framework rather than writing firmware from scratch.

Active and established: the project has multiple hardware variants (MarauderV4, FlipperZero integration, ESP32-C5 support), pre-built binaries in FlashFiles/, and CI/CD pipelines (GitHub Actions workflows in .github/workflows/). Last visible activity includes nightly builds and parallel build workflows, indicating ongoing maintenance. However, single-maintainer risk is present (justcallmekoko as primary author).

Moderate risk: this is security-focused research code without visible public test suite in the file list, so correctness of attack implementations is hard to verify externally. Hardware variants require matching driver versions (e.g., CH34x drivers in Drivers/ for specific boards), and binary flashing (esp32_marauder_v1_12_0_v8.bin) requires correct board selection—wrong selection can brick devices. WiFi/Bluetooth legal compliance varies by jurisdiction, so users must verify legality of testing in their region.

Active support for multiple ESP32 variants: recent additions include ESP32-C5 board support (C5_Py_Flasher_for_adapter/ and C5_Py_Flasher_for_v8/ with v1.8.5 and v1.12.0 binaries) and Flipper Zero multi-board S3 variant. CI pipelines run nightly builds and parallel builds. MarauderOTA/ suggests over-the-air update capability in development. Open issue tracking via GitHub Issues with templates for bug reports and feature requests.

Clone and build: git clone https://github.com/justcallmekoko/ESP32Marauder.git && cd ESP32Marauder. For flashing on v8 hardware: python3 C5_Py_Flasher_for_v8/c5_flasher.py (requires the prebuilt .bin files in C5_Py_Flasher_for_v8/bins/). For Arduino IDE development: open esp32_marauder.ino in Arduino IDE, select your ESP32 board type, and compile. Prebuilt binaries in FlashFiles/ can be flashed directly with esptool or the provided flasher scripts.

Daily commands: For Arduino IDE: File > Open > esp32_marauder.ino, select Tools > Board > 'Your ESP32 Variant', set Tools > Partition Scheme, then Sketch > Upload. For automated flashing on v8: python3 C5_Py_Flasher_for_v8/c5_flasher.py (interactive, guides board selection and COM port). Device exposes a serial terminal interface after boot for interactive command entry. Web interface or mobile app may exist (check wiki).

• MarauderOTA/MarauderOTA.ino — Primary Arduino sketch entry point for the ESP32 Marauder firmware; essential for understanding the main application flow and hardware initialization
• .github/workflows/build_parallel.yml — CI/CD build pipeline that compiles firmware for multiple ESP32 variants; critical for understanding supported hardware targets and build process
• FlashFiles/flash_cmd.txt — Flashing instructions and commands for deploying firmware to ESP32 devices; required reference for development and testing workflows
• .gitmodules — Defines external dependencies and libraries used by the project; essential for setting up the build environment correctly
• PCBs/FlipperZero/WiFi-Devboard-Pro/README.md — Documents the custom hardware board design specifications; critical for understanding supported ESP32 module configurations
• C5_Py_Flasher_for_v8/c5_flasher.py — Python utility for flashing ESP32 firmware; demonstrates the flash tool architecture and binary handling patterns

Add Support for a New ESP32 Hardware Variant

1. Create a new board configuration directory under FlashFiles/ following the naming convention (e.g., FlashFiles/YourNewBoard/) (FlashFiles/)
2. Place compiled binaries: bootloader.bin, partitions.bin, and the application .bin file in the new directory (FlashFiles/YourNewBoard/esp32_marauder.ino.bootloader.bin)
3. Add a new build target to .github/workflows/build_parallel.yml under the matrix strategy for the CI to compile for your variant (.github/workflows/build_parallel.yml)
4. Create a flashing script in the C5_Py_Flasher_for_v8/ directory by copying and modifying c5_flasher.py with your board's offset addresses (C5_Py_Flasher_for_v8/c5_flasher.py)
5. Document the hardware requirements and flash procedure in a README.md file in your board directory (FlashFiles/YourNewBoard/README.md)

Update Firmware and Release a New Version

1. Modify the primary firmware in MarauderOTA/MarauderOTA.ino with your changes (MarauderOTA/MarauderOTA.ino)
2. Push changes to the master branch; the build_parallel.yml workflow will automatically compile binaries for all registered variants (.github/workflows/build_parallel.yml)
3. Download the compiled .bin artifacts from the GitHub Actions workflow run (.github/workflows/build_parallel.yml)
4. Place the new binaries in FlashFiles and C5_Py_Flasher directories, updating filenames to reflect the new version number (FlashFiles/MarauderV4/esp32_marauder.ino.bootloader.bin)
5. Commit and tag the release in git with version information for GitHub Releases (LICENSE)

Customize the PCB Design for a Variant

1. Copy the WiFi-Devboard-Pro directory structure under PCBs/FlipperZero/ to create your variant (PCBs/FlipperZero/WiFi-Devboard-Pro/)
2. Open the KiCAD project files and modify schematic and layout; update component libraries as needed from the Libraries/ subdirectory (PCBs/FlipperZero/WiFi-Devboard-Pro/Libraries/)
3. Update the BOM.ods and Manufacturing/ CSV files with any component changes (PCBs/FlipperZero/WiFi-Devboard-Pro/Manufacturing/WiFi-Devboard-Pro-BOM.csv)
4. Generate Gerber files and export manufacturing data; save updated BOM and position files to Manufacturing/ (PCBs/FlipperZero/WiFi-Devboard-Pro/Manufacturing/Gerber and Drill/)
5. Update the README.md with new board specifications, pin mappings, and assembly instructions (PCBs/FlipperZero/WiFi-Devboard-Pro/README.md)

• ESP32 microcontroller — Provides dual-core processor, integrated WiFi/Bluetooth, sufficient SRAM/Flash, and extensive Arduino IDE support for embedded offensive/defensive security tools
• Arduino IDE / sketches (.ino files) — Industry-standard abstraction for microcontroller development; enables rapid prototyping and broad hardware compatibility across ESP32 boards
• GitHub Actions CI/CD — Enables automated parallel compilation for multiple ESP32 variants; reduces manual build steps and ensures consistency across hardware targets
• KiCAD PCB design tools — Open-source hardware design enables community contributions; Gerber/manufacturing files allow custom board production and variants
• Python flashing utilities — esptool.py provides cross-platform binary flashing with minimal overhead; custom wrappers (c5_flasher.py) handle variant-specific offset/partition logic

• Multiple hardware variants (V4, FlipperZero, S3, C5) with separate pre-compiled binaries

  • Why: Different ESP32 modules have different memory layouts, pin configurations, and feature sets (PSRAM, JTAG, etc.); unified binary would waste flash or exclude functionality
  • Consequence: Increased maintenance burden: each variant requires separate compilation, testing, and flashing scripts; larger repository footprint

• Pre-compiled binary distribution rather than source-only

  • Why: Users can flash devices immediately without setting up full Arduino IDE build environment; reduces support friction
  • Consequence: Security risk: binaries are harder to audit than source; updates require manual re-release rather than auto-compilation; trust must be placed in pre-built artifacts

• OTA firmware update support via MarauderOTA.ino

  • Why: Allows remote/wireless firmware updates after initial flash; improves user experience for feature rollouts
  • Consequence: Adds firmware complexity; requires partition scheme with dedicated OTA slots; potential for bricked devices if update process fails mid-flash

• Parallel CI builds for all variants in GitHub Actions

  • Why: Reduces total build time; automatically catches variant-specific compilation errors early
  • Consequence: Increased GitHub Actions resource usage; requires careful matrix configuration maintenance as new variants are added

Board variant mismatch: selecting wrong partition/bootloader .bin file for your hardware (ESP32 vs S3 vs C5) will cause boot loops—always verify board type before flashing. Serial port permissions on Linux/Mac: may need sudo or udev rules for CH34x USB chips (see Drivers/CH34x_Install_Windows_v3_4.EXE comment). Arduino IDE must have ESP32 board package installed (Tools > Board Manager > search 'esp32'). Binary blobs (.bin files) in FlashFiles/ are pre-compiled; source code for bootloader/partition generator not visible in file list. Python flasher scripts require pyserial (pip install pyserial). WiFi/BT attack legality varies by country—operating on networks without permission is illegal in most jurisdictions.

• WiFi Deauthentication Attack (802.11 Management Frames) — Core Marauder capability that disconnects clients by spoofing deauth management frames; requires understanding raw 802.11 frame construction and station state machines
• Bluetooth Low Energy (BLE) Advertising & GATT — Marauder Bluetooth features scan and enumerate BLE devices via GAP advertising and GATT service discovery; essential for understanding BLE attack surface
• ESP32 Partition Scheme & Flash Memory Layout — Marauder requires correct partitions.bin matching hardware variant; bootloader, OTA app, and SPIFFS storage are defined in partition table and determine memory layout
• FreeRTOS Task Scheduling — ESP32 runs FreeRTOS; Marauder likely uses multiple tasks for packet capture, command parsing, and WiFi/BT scanning simultaneously without blocking
• Promiscuous Mode WiFi Packet Capture — Marauder sniffing features use esp_wifi_set_promiscuous() to see all nearby frames regardless of SSID/encryption; underpins reconnaissance attacks
• SSID Spoofing & Beacon Frame Injection — Marauder can create fake WiFi networks by crafting and transmitting 802.11 Beacon frames with arbitrary SSIDs; requires raw frame API access
• Over-the-Air (OTA) Firmware Updates — MarauderOTA/ suggests remote update capability; requires secure partition management and rollback protection to prevent bricking across devices

• espressif/esp-idf — Official ESP32 SDK underlying Arduino framework; source for WiFi/Bluetooth hardware APIs that Marauder calls
• arduino/Arduino — Arduino IDE and core libraries providing the sketch compilation framework and serial upload toolchain
• espressif/esptool — Low-level ESP32 flasher tool that Python flasher scripts wrap; handles bootloader and partition flashing
• morrissimo/esp32-wifi-penetration-tool — Alternative ESP32 WiFi attack toolkit; similar attack surface but different UI/architecture
• flipperdevices/flipperzero-firmware — Flipper Zero main firmware; Marauder integrates as WiFi module for Flipper hardware variants

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create automated CI workflow for binary artifact validation

The repo contains multiple pre-built binary files across FlashFiles/, C5_Py_Flasher_for_v8/, and C5_Py_Flasher_for_adapter/ directories (bootloader.bin, partitions.bin, firmware.bin). These binaries lack automated validation in CI/CD. A GitHub Actions workflow should verify binary checksums, validate ESP32 firmware structure, and ensure consistency across board variants (V4, S3, C5). This prevents accidental corrupted builds from being committed and improves release integrity.

• [ ] Create .github/workflows/validate_binaries.yml that runs on pull requests modifying FlashFiles/* or C5_Py_Flasher*/ directories
• [ ] Add esptool.py validation step to check ESP32 firmware headers and partition tables for each .bin file
• [ ] Generate and commit .sha256 checksum files for all binaries, then validate them in CI
• [ ] Add build matrix for different board variants (MarauderV4, FlipperZeroDevBoard, FlipperZeroMultiBoardS3, ESP32C5) to ensure all variants are tested

Add Python flasher integration tests

Two Python flasher scripts exist (C5_Py_Flasher_for_v8/c5_flasher.py and C5_Py_Flasher_for_adapter/c5_flasher.py) but have no test coverage. These tools are critical for end-users flashing firmware. Tests should validate argument parsing, binary file existence checks, esptool command generation, and error handling for common failure scenarios (missing files, invalid ports, corrupted binaries).

• [ ] Create tests/test_c5_flasher.py with pytest fixtures for mocking esptool.py subprocess calls
• [ ] Add test cases for: valid flash parameters, missing binary files, invalid serial ports, corrupted binary detection
• [ ] Create tests/test_flasher_compatibility.py to verify both c5_flasher.py variants handle the same command-line interface correctly
• [ ] Add GitHub Actions workflow (.github/workflows/test_python_flashers.yml) to run pytest on Python 3.8+ and report coverage

Document PCB board variants and firmware selection guide

The repo supports multiple hardware variants (MarauderV4, FlipperZero, FlipperZeroMultiBoardS3, ESP32C5) with corresponding firmware binaries and PCB files in PCBs/ and FlashFiles/. However, there's no guide explaining which firmware to use for which board, PCB assembly instructions, or pin mapping documentation. This creates friction for new contributors and users trying to understand hardware differences.

• [ ] Create docs/HARDWARE_VARIANTS.md documenting each board variant (V4, S3, C5, FlipperZero) with specifications, pin mappings, and use cases
• [ ] Create docs/FIRMWARE_SELECTION.md explaining which binary from FlashFiles/* to use based on hardware version
• [ ] Add README files to PCBs/FlipperZero/WiFi-Devboard-Pro/ and PCBs/FlipperZero/ explaining BOM assembly, KiCad schematic generation, and component sourcing
• [ ] Add a comparison table in docs/ showing RAM/Flash differences, supported features (WiFi/BLE versions), and antenna configurations across variants

• Add missing unit tests for WiFi packet sniffing logic: create a test file that mocks esp_wifi.h calls and validates packet filtering against known test vectors—currently no visible test suite in repo
• Document hardware variant selection guide: create a wiki page or README section explaining when to use MarauderV4 vs FlipperZero vs ESP32-C5 binaries, with device ID detection instructions (currently only in file names)
• Implement automated board detection in Python flasher: modify C5_Py_Flasher_for_v8/c5_flasher.py to query connected ESP32 via serial for chip ID and auto-select correct partition/bootloader, reducing user error on variant selection

• High · Precompiled Binaries Without Integrity Verification — FlashFiles/, C5_Py_Flasher_for_v8/bins/, C5_Py_Flasher_for_adapter/bins/. The repository contains multiple precompiled binary files (.bin files) in FlashFiles and C5_Py_Flasher directories without any checksums, signatures, or integrity verification mechanisms. This poses a significant supply chain risk as users cannot verify the authenticity or integrity of the firmware being flashed. Fix: Implement cryptographic checksums (SHA256) or digital signatures for all binary releases. Provide a checksums.txt or similar file signed with a GPG key. Document the verification process in README.
• High · Executable Files in Repository — Drivers/CH34x_Install_Windows_v3_4.EXE, FlashFiles/esptool.exe. The repository contains executable files (.EXE for CH34x driver and FlashFiles/esptool.exe) which pose a malware distribution risk. These should not be stored in source control. Fix: Remove executables from the repository. Instead, provide download links and verification instructions in documentation. Use package managers or official distribution channels for dependencies like esptool and drivers.
• High · Python Flasher Scripts Without Input Validation — C5_Py_Flasher_for_adapter/c5_flasher.py, C5_Py_Flasher_for_v8/c5_flasher.py. The c5_flasher.py scripts (C5_Py_Flasher_for_adapter/c5_flasher.py and C5_Py_Flasher_for_v8/c5_flasher.py) are flasher utilities that likely interact with user input and device I/O. Without source code review, there's potential for command injection or unsafe file handling. Fix: Review Python scripts for input validation. Use subprocess module with proper argument parsing. Validate all file paths and user inputs. Consider using established tools like esptool.py with pinned versions.
• Medium · Missing Security Documentation — Repository root. The repository lacks security-related documentation such as SECURITY.md, responsible disclosure policy, or security guidelines. There is no evidence of security best practices documentation for users. Fix: Create a SECURITY.md file documenting: responsible disclosure process, security contacts, known limitations of the tool, and warnings about legal use. Add security warnings to README about lawful use.
• Medium · Offensive Security Tool Without Adequate Warnings — README.md. This project implements WiFi/Bluetooth offensive tools. The README lacks prominent warnings about legal implications and responsible use. This could facilitate misuse by unauthorized individuals. Fix: Add prominent legal disclaimers and responsible use warnings in README. Include information about applicable laws (CFAA, GDPR, etc.). Recommend educational and authorized testing contexts only.
• Medium · Compressed Archive Files with Unknown Contents — FlashFiles/flash_download_tool_3.9.5.zip. The repository contains FlashFiles/flash_download_tool_3.9.5.zip with no integrity verification or extraction security controls. Unknown archive contents could pose security risks. Fix: Document the exact contents and purpose of all archives. Provide checksums. Consider removing third-party tool archives and instead providing links to official sources with integrity verification.
• Low · No .gitignore Protection for Secrets — .gitignore. While a .gitignore exists, there's no evidence of patterns protecting common secret types (.env, config files with credentials, API keys). The presence of binary files suggests potential for accidental secret commits. Fix: Enhance .gitignore with patterns for: *.env, *.key, *.pem, credentials, *.config. Add pre-commit hooks to scan for secrets using tools like git-secrets or Detect Secrets.
• Low · No Software Composition Analysis — Repository root. No dependency file (requirements.txt, package.json, Cargo.toml, etc.) provided in the analysis. This makes it impossible to assess third-party dependency vulnerabilities. Fix: Maintain explicit dependency files for all languages used (Python, C++/Arduino). Pin to specific versions. Use tools like

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.