Skip to content

Home

Jump to bottom
poli0981 edited this page Aug 25, 2025 · 1 revision

MAC Address Spoofer User Guide

Introduction

MAC Address Spoofer is a Windows desktop application for temporarily changing the MAC address of network adapters. It enhances user privacy during network connections and supports testing scenarios. Always use responsibly and in compliance with laws.

Getting Started

Prerequisites

  • Windows 10/11.
  • Python 3.12+ installed.
  • Admin access for MAC changes.

Installation

  1. Clone the repo from GitHub.
  2. Install requirements: pip install -r requirements.txt.
  3. Run: python main.py (as admin).

Building Standalone Executable

For distribution:

  • Install PyInstaller: pip install pyinstaller.
  • Build: pyinstaller --onefile --windowed --hidden-import=customtkinter --name="MAC_Spoofer" main.py.
  • The .exe will be in the dist/ folder. Run as administrator.

Interface Overview

  • Select Adapter: Dropdown to choose network interface (e.g., Wi-Fi, Ethernet).
  • Current MAC: Displays the active MAC address.
  • MAC Entry: Field for manual input or randomized MAC.
  • Buttons:
    • Randomize: Generates a new valid MAC and clears/fills the entry.
    • Spoof: Applies the MAC (confirms first; may disconnect network briefly).
    • Revert: Restores original MAC.
    • Toggle Theme: Switches Dark/Light mode.
    • Save Log: Exports log file.
  • Checkboxes:
    • Enable Logging: Turns on/off event logging.
    • Auto-start on boot: Adds/removes from Windows startup.
  • Menu Bar: "About" menu with software info, license, third-party credits, and author details.

Advanced Usage

  • Manual MAC Input: Format: XX:XX:XX:XX:XX:XX (validated automatically).
  • Logging: Logs are saved to mac_spoofer.log. View/save via button.
  • Error Handling: App checks for admin rights and adapter support. If spoof fails, check driver compatibility.
  • Auto-Revert: On app exit/crash, reverts any pending changes.

Troubleshooting

  • No Adapters Listed: Ensure network connections are active; run as admin.
  • Spoof Fails: Some drivers don't support MAC spoofing (e.g., older hardware). Check Windows Device Manager > Network Adapter > Advanced > Network Address.
  • Registry Issues: App uses Windows registry; if errors, verify permissions.
  • Build Errors: Ensure all hidden-imports in PyInstaller command; test in virtual env.

Security and Privacy

  • Run only on trusted machines.
  • Spoofing may violate network policies; use ethically.
  • No data collection; all operations local.

Contributing

Fork the repo, submit PRs for improvements (e.g., macOS/Linux support).

Credits

  • User (35%): Prompts, ideas, bug fixes, verification.
  • Grok 4 by xAI (65%): Code generation, fixes, docs, features, research.

For questions, open an issue on GitHub.

Clone this wiki locally