macspoofer 1.0.0__py3-none-any.whl

macspoofer/__init__.py

@@ -0,0 +1,3 @@
+"""MAC Address Spoofer - A CLI tool to spoof network interface MAC addresses on Linux."""
+
+__version__ = "1.0.0"

macspoofer/cli.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""MAC Address Spoofer - CLI entry point."""
+
+import asyncio
+
+from rich import print
+
+from macspoofer.modules.args_parser import ArgumentParser
+from macspoofer.modules.error_config import configure_pretty_errors
+from macspoofer.spoofer import run_spoofer_logic
+from macspoofer.utils.exceptions import CustomException
+
+
+async def _async_main() -> None:
+    """Async application entry point."""
+    try:
+        configure_pretty_errors()
+        args = ArgumentParser().parse_args()
+        await run_spoofer_logic(args)
+    except KeyboardInterrupt:
+        print("\n[-] [bold red]Stopped.")
+    except CustomException as e:
+        print(f"\n[-] [bold red]{e}")
+    except ModuleNotFoundError:
+        print("\n[-] [bold red]Missing one of the pip packages.")
+    except Exception as e:
+        print(f"\n[-] [bold red]Error occurred: {e}")
+
+
+def main() -> None:
+    """Synchronous wrapper for the CLI entry point (used by pyproject.toml scripts)."""
+    asyncio.run(_async_main())
+
+
+if __name__ == "__main__":
+    main()

macspoofer/modules/args_parser.py

@@ -0,0 +1,71 @@
+"""Command-line argument parsing for MAC Address Spoofer."""
+
+import argparse
+from dataclasses import dataclass
+
+VERSION = "0.0.0"
+
+
+@dataclass
+class SpooferArgs:
+    """Parsed command-line arguments for the spoofer."""
+
+    interface: str
+    auto: bool = False
+    ci: bool = False
+
+
+class ArgumentParser:
+    """Handles command-line argument parsing."""
+
+    def __init__(self) -> None:
+        self._parser = self._create_parser()
+
+    def _create_parser(self) -> argparse.ArgumentParser:
+        """Create and configure the argument parser."""
+        parser = argparse.ArgumentParser(
+            description="MAC Address Spoofer - Change your network interface MAC address",
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        self._add_arguments(parser)
+        return parser
+
+    def _add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add all command-line arguments to the parser."""
+        parser.add_argument(
+            "-i",
+            dest="interface",
+            required=True,
+            help="Network interface name (e.g., wlan0, eth0)",
+        )
+
+        parser.add_argument(
+            "--auto",
+            action="store_true",
+            help="Non-interactive mode: generate and apply a safe random unicast MAC",
+        )
+
+        parser.add_argument(
+            "--ci",
+            action="store_true",
+            help="CI mode: for automated testing (similar to --auto)",
+        )
+
+        parser.add_argument(
+            "--version",
+            action="version",
+            version=f"MAC Address Spoofer v{VERSION}",
+        )
+
+    def parse_args(self) -> SpooferArgs:
+        """Parse command-line arguments.
+
+        Returns:
+            SpooferArgs dataclass with parsed values
+        """
+        args = self._parser.parse_args()
+        return SpooferArgs(
+            interface=args.interface,
+            auto=args.auto,
+            ci=args.ci,
+        )

macspoofer/modules/error_config.py

@@ -0,0 +1,18 @@
+"""Pretty error output configuration."""
+
+import pretty_errors
+
+
+def configure_pretty_errors() -> None:
+    """Configure pretty_errors for enhanced error display.
+
+    Sets up formatting options for better error readability including
+    separator characters, full filename display, and context lines.
+    """
+    pretty_errors.configure(
+        separator_character="*",
+        filename_display=pretty_errors.FILENAME_FULL,
+        line_color=pretty_errors.RED + "> " + pretty_errors.default_config.line_color,
+        lines_before=3,
+        lines_after=3,
+    )

macspoofer/modules/interface.py

@@ -0,0 +1,100 @@
+"""Network interface management for MAC spoofing."""
+
+import contextlib
+from collections.abc import AsyncIterator
+from enum import StrEnum
+
+from macspoofer.utils import shell_utils
+from macspoofer.utils.exceptions import CustomException, ErrorCode
+
+
+class InterfaceState(StrEnum):
+    """Network interface state values."""
+
+    UP = "up"
+    DOWN = "down"
+
+
+class NetworkInterface:
+    """Represents a network interface for MAC address manipulation.
+
+    This class encapsulates operations on a network interface,
+    including state management and MAC address spoofing.
+
+    Attributes:
+        name: The interface name (e.g., 'eth0', 'wlan0')
+    """
+
+    def __init__(self, name: str) -> None:
+        """Initialize a NetworkInterface.
+
+        Args:
+            name: The interface name (e.g., 'eth0', 'wlan0')
+        """
+        self.name = name
+
+    async def set_state(self, state: InterfaceState) -> None:
+        """Set the interface to the specified state.
+
+        Args:
+            state: Desired interface state (UP or DOWN)
+
+        Raises:
+            CustomException: If the state change fails
+        """
+        try:
+            await shell_utils.execute_command(["ip", "link", "set", "dev", self.name, state])
+        except CustomException as err:
+            raise CustomException(
+                message=f"Failed to set interface {self.name} to {state}",
+                error_code=ErrorCode.INTERFACE_STATE_FAILED,
+            ) from err
+
+    async def up(self) -> None:
+        """Bring the interface up."""
+        await self.set_state(InterfaceState.UP)
+
+    async def down(self) -> None:
+        """Bring the interface down."""
+        await self.set_state(InterfaceState.DOWN)
+
+    async def set_mac_address(self, mac: str) -> None:
+        """Set the MAC address of the interface.
+
+        Note: The interface should be down before changing the MAC address.
+
+        Args:
+            mac: New MAC address (format: 'xx:xx:xx:xx:xx:xx')
+
+        Raises:
+            CustomException: If setting the MAC address fails
+        """
+        try:
+            await shell_utils.execute_command(
+                ["ip", "link", "set", "dev", self.name, "address", mac]
+            )
+        except CustomException as err:
+            raise CustomException(
+                message=f"Failed to set MAC address {mac} on {self.name}",
+                error_code=ErrorCode.MAC_SPOOF_FAILED,
+            ) from err
+
+    @contextlib.asynccontextmanager
+    async def disable_temporarily(self) -> AsyncIterator[None]:
+        """Async context manager to temporarily bring the interface down and back up.
+
+        Usage:
+            async with interface.disable_temporarily():
+                await interface.set_mac_address(new_mac)
+        """
+        try:
+            await self.down()
+            yield
+        finally:
+            await self.up()
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return f"NetworkInterface({self.name!r})"

macspoofer/spoofer.py

@@ -0,0 +1,140 @@
+"""MAC Address Spoofer - Core spoofing logic and TUI."""
+
+import asyncio
+
+import art
+from rich import print
+
+from macspoofer.modules.args_parser import SpooferArgs
+from macspoofer.modules.interface import NetworkInterface
+from macspoofer.utils import shell_utils
+from macspoofer.utils.exceptions import CustomException, ErrorCode
+from macspoofer.utils.random_utils import (
+    HexValuesLength,
+    generate_hex_values_delimited_by_dotted,
+    generate_safe_unicast_mac,
+    get_random_vendor_from_list,
+)
+from macspoofer.utils.vendors import VendorRegistry
+
+
+async def spoof_mac_address(
+    interface: NetworkInterface,
+    mac: str,
+    require_confirmation: bool = True,
+) -> None:
+    """Spoof the MAC address of a network interface.
+
+    Temporarily brings the interface down via an async context manager,
+    changes its MAC address, then brings it back up.
+
+    Args:
+        interface: NetworkInterface instance to spoof
+        mac: New MAC address to assign (format: 'xx:xx:xx:xx:xx:xx')
+        require_confirmation: If True, wait for user confirmation before proceeding
+
+    Raises:
+        CustomException: If any step of the spoofing process fails
+    """
+    print(f"[+] [bold yellow]We need to temporarily turn OFF interface: {interface}")
+
+    if require_confirmation:
+        input("Press Enter to continue or Ctrl+C to terminate -> ")
+
+    async with interface.disable_temporarily():
+        print(f"\n[+] [bold green]Turning {interface} OFF...")
+        await asyncio.sleep(1)
+
+        print(f"\n[+] [bold green]Spoofing {interface} mac...")
+        await asyncio.sleep(1)
+        await interface.set_mac_address(mac)
+
+    print(f"\n[+] [bold green]Turning {interface} back ON...")
+    await asyncio.sleep(1)
+
+
+def choose_vendor() -> str:
+    """Display vendor options and get user selection.
+
+    Returns:
+        The selected vendor name
+    """
+    vendors = VendorRegistry.NAMES
+    options = "\n".join(f"[bold green][{i}] [cyan]{vendor}" for i, vendor in enumerate(vendors))
+    print(f"[bold magenta]Enter your choice:\n\n{options}\n")
+
+    user_input = input("-> ").strip()
+
+    while not user_input.isdigit() or int(user_input) >= len(vendors):
+        user_input = input("Invalid choice, try again-> ").strip()
+
+    return vendors[int(user_input)]
+
+
+def generate_mac_for_vendor(vendor: str) -> str:
+    """Generate a MAC address for the specified vendor.
+
+    Args:
+        vendor: Vendor name (must be in VendorRegistry.NAMES)
+
+    Returns:
+        A valid MAC address string
+    """
+    if vendor == VendorRegistry.NAMES[0]:
+        return generate_safe_unicast_mac()
+
+    vendor_oui_list = VendorRegistry.get_ouis_for_vendor(vendor)
+    if vendor_oui_list is None:
+        return generate_safe_unicast_mac()
+
+    oui = get_random_vendor_from_list(vendor_oui_list)
+    nic = generate_hex_values_delimited_by_dotted(HexValuesLength.NIC)
+    return f"{oui}:{nic}"
+
+
+async def run_tui(interface: NetworkInterface) -> None:
+    """Run the text-based user interface for MAC spoofing.
+
+    Args:
+        interface: NetworkInterface instance to spoof
+    """
+    art.tprint("Spoofer")
+
+    vendor = choose_vendor()
+    print("[+] [bold green]Generating random mac according to your request...\n")
+    await asyncio.sleep(1)
+
+    mac = generate_mac_for_vendor(vendor)
+
+    print(f"[+] [bold green]Spoofing your interface {interface} mac to {mac}\n")
+    await asyncio.sleep(1)
+
+    await spoof_mac_address(interface, mac)
+    print("\n[+] [bold green]Done.")
+
+
+async def run_spoofer_logic(args: SpooferArgs) -> None:
+    """Main entry point for the spoofer logic.
+
+    Args:
+        args: Parsed command-line arguments
+
+    Raises:
+        CustomException: If not running as root
+    """
+    if not shell_utils.check_for_admin():
+        raise CustomException(
+            message="This tool must be run as root (sudo)",
+            error_code=ErrorCode.COMMAND_EXECUTION_FAILED,
+        )
+
+    interface = NetworkInterface(args.interface)
+
+    if args.ci or args.auto:
+        mode = "CI" if args.ci else "AUTO"
+        print(f"\n[{mode}] Generating safe random unicast MAC address...")
+        mac = generate_safe_unicast_mac()
+        print(f"\n[{mode}] Spoofing {interface} to {mac}")
+        await spoof_mac_address(interface, mac, require_confirmation=False)
+    else:
+        await run_tui(interface)

macspoofer/utils/exceptions.py

@@ -0,0 +1,34 @@
+"""Custom exceptions and error codes for MacSpoofer."""
+
+from enum import IntEnum
+
+
+class ErrorCode(IntEnum):
+    FAILED_TO_CREATE_LOGGER_FOLDER = 1000
+    FAILED_TO_SETUP_LOGGER = 1001
+    COMMAND_EXECUTION_FAILED = 1002
+    INTERFACE_STATE_FAILED = 1003
+    MAC_SPOOF_FAILED = 1004
+
+
+class CustomException(Exception):
+    """Base exception for MacSpoofer with an associated error code."""
+
+    def __init__(self, message: str, error_code: ErrorCode):
+        self._message = message
+        self._error_code = error_code
+        super().__init__(self._message)
+
+    @property
+    def error_code(self) -> ErrorCode:
+        return self._error_code
+
+    @property
+    def message(self) -> str:
+        return self._message
+
+    def __str__(self) -> str:
+        return f"[Error {self._error_code}] {self._message}"
+
+    def __repr__(self) -> str:
+        return f"CustomException(message='{self._message}', error_code={self._error_code})"

macspoofer/utils/random_utils.py

@@ -0,0 +1,66 @@
+"""Random MAC address generation utilities."""
+
+import random
+from enum import Enum
+
+
+class HexValuesLength(Enum):
+    """Defines the length of different MAC address components."""
+
+    MAC_ADDRESS = 12  # Full MAC address (6 bytes = 12 hex chars)
+    OUI = 6  # Organizationally Unique Identifier (3 bytes)
+    NIC = 6  # Network Interface Controller specific (3 bytes)
+
+
+def generate_hex_values_delimited_by_dotted(hex_values_to_generate: HexValuesLength) -> str:
+    """Generate a random hex string formatted as MAC address octets.
+
+    Args:
+        hex_values_to_generate: Number of hex characters to generate
+
+    Returns:
+        Random hex string delimited by colons (e.g., "01:bf:e2")
+    """
+    hex_chars = [format(random.randint(0, 15), "x") for _ in range(hex_values_to_generate.value)]
+
+    # Join every 2 hex chars with colons
+    octets = ["".join(hex_chars[i : i + 2]) for i in range(0, len(hex_chars), 2)]
+    return ":".join(octets)
+
+
+def get_random_vendor_from_list(vendors: list[str]) -> str:
+    """Select a random vendor OUI from a list.
+
+    Args:
+        vendors: List of vendor OUI strings
+
+    Returns:
+        A randomly selected vendor OUI
+    """
+    return random.choice(vendors)
+
+
+def _random_byte() -> int:
+    """Generate a random byte value (0-255)."""
+    return random.randint(0x00, 0xFF)
+
+
+def generate_safe_unicast_mac() -> str:
+    """Generate a valid, locally administered unicast MAC address.
+
+    The returned MAC address has:
+    - Bit 1 of first byte set to 1 (locally administered)
+    - Bit 0 of first byte set to 0 (unicast)
+
+    These settings ensure compatibility with virtual and dummy network
+    interfaces where global or multicast MACs may be rejected by the kernel.
+
+    Returns:
+        MAC address string in format 'xx:xx:xx:xx:xx:xx'
+    """
+    first_byte = _random_byte()
+    # Set locally administered bit (bit 1) and clear multicast bit (bit 0)
+    first_byte = (first_byte & 0b11111100) | 0b00000010
+
+    mac_bytes = [first_byte] + [_random_byte() for _ in range(5)]
+    return ":".join(f"{byte:02x}" for byte in mac_bytes)

macspoofer/utils/shell_utils.py

@@ -0,0 +1,46 @@
+"""Shell command utilities for system-level operations."""
+
+import asyncio
+import getpass
+
+from macspoofer.utils.exceptions import CustomException, ErrorCode
+
+
+def check_for_admin() -> bool:
+    """Check if the current user has root/admin privileges.
+
+    Returns:
+        True if running as root, False otherwise
+    """
+    return getpass.getuser() == "root"
+
+
+async def execute_command(command_args: list[str]) -> None:
+    """Execute a shell command asynchronously.
+
+    Args:
+        command_args: List of command arguments to execute
+
+    Raises:
+        CustomException: If command_args is empty or the command exits non-zero
+    """
+    if not command_args:
+        raise CustomException(
+            message="execute_command called with no arguments",
+            error_code=ErrorCode.COMMAND_EXECUTION_FAILED,
+        )
+
+    process = await asyncio.create_subprocess_exec(
+        *command_args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await process.communicate()
+
+    if process.returncode != 0:
+        error_output = stderr.decode().strip() if stderr else ""
+        raise CustomException(
+            message=f"Command failed (exit {process.returncode}): {' '.join(command_args)}"
+            + (f"\n{error_output}" if error_output else ""),
+            error_code=ErrorCode.COMMAND_EXECUTION_FAILED,
+        )

macspoofer/utils/vendors.py

@@ -0,0 +1,408 @@
+"""Vendor OUI (Organizationally Unique Identifier) definitions.
+
+This module contains MAC address prefixes for various hardware vendors,
+used for generating vendor-specific MAC addresses.
+"""
+
+
+class VendorRegistry:
+    """Registry of vendor OUI prefixes for MAC address generation."""
+
+    # Vendor display names for menu selection
+    NAMES: list[str] = [
+        "Total Random",
+        "Samsung",
+        "Apple",
+        "Intel",
+        "Microsoft",
+        "Huawei",
+        "Google",
+        "Cisco",
+    ]
+
+    # OUI prefixes by vendor
+    SAMSUNG: list[str] = [
+        "00:21:19",
+        "00:02:78",
+        "00:07:ab",
+        "00:09:18",
+        "00:0d:ae",
+        "00:0d:e5",
+        "00:12:47",
+        "00:12:fb",
+        "00:13:77",
+        "00:15:99",
+        "e8:50:8b",
+        "e8:6d:cb",
+        "e8:7f:6b",
+        "e8:93:09",
+        "e8:b4:c8",
+        "e8:e5:d6",
+        "ec:10:7b",
+        "ec:1f:72",
+        "ec:7c:b6",
+        "ec:9b:f3",
+        "ec:aa:25",
+        "ec:e0:9b",
+        "f0:08:f1",
+        "f0:25:b7",
+        "f0:39:65",
+        "f0:5a:09",
+        "f0:5b:7b",
+        "f0:65:ae",
+        "f0:6b:ca",
+        "f0:70:4f",
+        "f0:72:8c",
+        "dc:89:83",
+        "dc:cc:e6",
+        "dc:cf:96",
+        "dc:dc:e2",
+        "dc:f7:56",
+        "e0:03:6b",
+        "e0:99:71",
+        "e0:9d:13",
+        "e0:aa:96",
+        "78:00:9e",
+        "78:1f:db",
+        "78:23:27",
+        "78:25:ad",
+        "78:37:16",
+        "78:40:e4",
+        "78:46:d4",
+        "78:47:1d",
+    ]
+
+    APPLE: list[str] = [
+        "f8:10:93",
+        "f8:1e:df",
+        "f8:27:93",
+        "f8:2d:7c",
+        "f8:38:80",
+        "f8:4d:89",
+        "f8:4e:73",
+        "f8:62:14",
+        "f8:66:5a",
+        "f8:6f:c1",
+        "e4:b2:fb",
+        "e4:c6:3d",
+        "e4:ce:8f",
+        "e4:e0:a6",
+        "e4:e4:ab",
+        "e8:04:0b",
+        "e8:06:88",
+        "e8:1c:d8",
+        "e8:36:17",
+        "e8:5f:02",
+        "e8:78:65",
+        "e8:7f:95",
+        "e8:80:2e",
+        "e8:81:52",
+        "d8:cf:9c",
+        "d8:d1:cb",
+        "d8:dc:40",
+        "d8:de:3a",
+        "dc:08:0f",
+        "dc:0c:5c",
+        "dc:2b:2a",
+        "dc:2b:61",
+        "dc:37:14",
+        "dc:41:5f",
+        "dc:52:85",
+        "dc:53:92",
+        "dc:56:e7",
+        "dc:80:84",
+        "dc:86:d8",
+        "dc:9b:9c",
+        "5c:97:f3",
+        "5c:ad:cf",
+        "5c:e9:1e",
+        "5c:f5:da",
+        "5c:f7:e6",
+        "5c:f9:38",
+        "60:03:08",
+        "60:06:e3",
+    ]
+
+    INTEL: list[str] = [
+        "00:d7:6d",
+        "00:db:df",
+        "00:e1:8c",
+        "04:33:c2",
+        "04:56:e5",
+        "04:6c:59",
+        "04:cf:4b",
+        "04:d3:b0",
+        "04:e8:b9",
+        "04:ea:56",
+        "04:ec:d8",
+        "04:ed:33",
+        "08:11:96",
+        "08:5b:d6",
+        "08:6a:c5",
+        "08:71:90",
+        "08:8e:90",
+        "08:9d:f4",
+        "08:d2:3e",
+        "08:d4:0c",
+        "0c:54:15",
+        "0c:7a:15",
+        "0c:8b:fd",
+        "0c:91:92",
+        "0c:9a:3c",
+        "0c:d2:92",
+        "0c:dd:24",
+        "48:45:20",
+        "48:51:b7",
+        "48:51:c5",
+        "48:68:4a",
+        "48:89:e7",
+        "48:a4:72",
+        "48:ad:9a",
+        "48:f1:7f",
+        "4c:03:4f",
+        "4c:1d:96",
+        "4c:34:88",
+        "4c:44:5b",
+        "4c:77:cb",
+        "4c:79:6e",
+        "cc:d9:ac",
+        "cc:f9:e4",
+        "d0:3c:1f",
+        "d0:57:7b",
+        "d0:7e:35",
+        "d0:ab:d5",
+        "d0:c6:37",
+    ]
+
+    MICROSOFT: list[str] = [
+        "00:03:ff",
+        "00:22:48",
+        "04:27:28",
+        "00:25:ae",
+        "00:12:5a",
+        "00:15:5d",
+        "00:17:fa",
+        "00:1d:d8",
+        "0c:41:3e",
+        "0c:e7:25",
+        "10:2f:6b",
+        "14:9a:10",
+        "14:cb:65",
+        "1c:1a:df",
+        "20:62:74",
+        "20:a9:9b",
+        "3c:83:75",
+        "44:16:22",
+        "48:50:73",
+        "48:86:e8",
+        "4c:3b:df",
+        "5c:ba:37",
+        "6c:5d:3a",
+        "70:bc:10",
+        "84:57:33",
+        "84:63:d6",
+        "90:6a:eb",
+        "94:9a:a9",
+        "98:5f:d3",
+        "98:7a:14",
+        "9c:6c:15",
+        "9c:aa:1b",
+        "a8:8c:3e",
+        "b8:31:b5",
+        "b8:4f:d5",
+        "bc:83:85",
+        "c4:9d:ed",
+        "c8:3f:26",
+        "c8:96:65",
+        "ca:12:5c",
+        "d4:8f:33",
+        "d8:e2:df",
+        "dc:98:40",
+        "e4:2a:ac",
+        "e8:a7:2f",
+        "ec:59:e7",
+        "ec:83:50",
+        "f0:1d:bc",
+    ]
+
+    HUAWEI: list[str] = [
+        "00:18:82",
+        "00:34:fe",
+        "00:66:4b",
+        "00:e0:fc",
+        "04:25:c5",
+        "04:75:03",
+        "04:b0:e7",
+        "04:e7:95",
+        "08:19:a6",
+        "08:63:61",
+        "08:c0:21",
+        "0c:31:dc",
+        "0c:70:4a",
+        "0c:c6:cc",
+        "10:32:1d",
+        "10:a4:da",
+        "14:09:dc",
+        "14:46:58",
+        "14:89:cb",
+        "14:ab:02",
+        "18:02:2d",
+        "18:cf:24",
+        "1c:1d:67",
+        "1c:59:9b",
+        "1c:a6:81",
+        "20:08:ed",
+        "20:53:83",
+        "20:a6:80",
+        "20:f3:a3",
+        "24:26:d6",
+        "24:4c:07",
+        "24:9e:ab",
+        "24:df:6a",
+        "28:17:09",
+        "28:53:4e",
+        "28:a6:db",
+        "28:fb:ae",
+        "2c:55:d3",
+        "2c:ab:00",
+        "30:74:96",
+        "30:e9:8e",
+        "34:0a:98",
+        "34:58:40",
+        "34:b3:54",
+        "38:4c:4f",
+        "38:f8:89",
+        "3c:54:47",
+        "3c:9d:56",
+    ]
+
+    GOOGLE: list[str] = [
+        "00:1a:11",
+        "00:f6:20",
+        "08:9e:08",
+        "14:22:3b",
+        "08:b4:b1",
+        "1c:f2:9a",
+        "20:1f:3b",
+        "20:df:b9",
+        "24:05:88",
+        "24:29:34",
+        "28:bd:89",
+        "30:fd:38",
+        "38:86:f7",
+        "38:8b:59",
+        "3c:28:6d",
+        "3c:5a:b4",
+        "3c:8d:20",
+        "44:07:0b",
+        "44:bb:3b",
+        "48:d6:d5",
+        "54:60:09",
+        "58:24:29",
+        "58:cb:52",
+        "60:b7:6e",
+        "70:3a:cb",
+        "74:74:46",
+        "7c:2e:bd",
+        "7c:d9:5c",
+        "88:3d:24",
+        "88:54:1f",
+        "90:0c:c8",
+        "90:ca:fa",
+        "94:eb:2c",
+        "98:d2:93",
+        "9c:4f:5f",
+        "a4:77:33",
+        "ac:67:84",
+        "b0:2a:43",
+        "b0:6a:41",
+        "b0:e4:d5",
+        "d8:eb:46",
+        "da:a1:19",
+        "dc:e5:5b",
+        "e4:5e:1b",
+        "e4:f0:42",
+        "f0:5c:77",
+        "f0:72:ea",
+        "f0:ef:86",
+    ]
+
+    CISCO: list[str] = [
+        "08:ec:f5",
+        "08:f3:fb",
+        "0c:11:67",
+        "0c:27:24",
+        "0c:68:03",
+        "0c:75:bd",
+        "0c:85:25",
+        "0c:d0:f8",
+        "10:06:ed",
+        "10:8c:cf",
+        "10:b3:c6",
+        "10:b3:d5",
+        "10:b3:d6",
+        "10:bd:18",
+        "10:f3:11",
+        "10:f9:20",
+        "14:16:9d",
+        "14:a2:a0",
+        "18:33:9d",
+        "18:59:f5",
+        "18:80:90",
+        "18:8b:45",
+        "18:8b:9d",
+        "18:9c:5d",
+        "18:e7:28",
+        "18:ef:63",
+        "1c:17:d3",
+        "1c:1d:86",
+        "1c:6a:7a",
+        "1c:aa:07",
+        "1c:d1:e0",
+        "1c:de:a7",
+        "1c:e8:5d",
+        "20:37:06",
+        "20:3a:07",
+        "20:4c:9e",
+        "20:bb:c0",
+        "20:cf:ae",
+        "24:01:c7",
+        "24:16:9d",
+        "24:7e:12",
+        "24:81:3b",
+        "24:b6:57",
+        "24:e9:b3",
+        "24:36:da",
+        "28:34:a2",
+        "28:52:61",
+        "28:6f:7f",
+    ]
+
+    @classmethod
+    def get_oui_map(cls) -> dict[str, list[str]]:
+        """Get mapping of vendor names to their OUI lists.
+
+        Returns:
+            Dictionary mapping vendor display names to OUI lists
+        """
+        return {
+            "Samsung": cls.SAMSUNG,
+            "Apple": cls.APPLE,
+            "Intel": cls.INTEL,
+            "Microsoft": cls.MICROSOFT,
+            "Huawei": cls.HUAWEI,
+            "Google": cls.GOOGLE,
+            "Cisco": cls.CISCO,
+        }
+
+    @classmethod
+    def get_ouis_for_vendor(cls, vendor_name: str) -> list[str] | None:
+        """Get OUI list for a specific vendor.
+
+        Args:
+            vendor_name: Name of the vendor
+
+        Returns:
+            List of OUI strings, or None if vendor not found
+        """
+        return cls.get_oui_map().get(vendor_name)

macspoofer-1.0.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: macspoofer
+Version: 1.0.0
+Summary: A command-line tool to spoof your network interface's MAC address on Linux systems.
+Project-URL: Homepage, https://github.com/DanielKirshner/MacSpoofer
+Project-URL: Repository, https://github.com/DanielKirshner/MacSpoofer
+Project-URL: Issues, https://github.com/DanielKirshner/MacSpoofer/issues
+Author: Daniel Kirshner
+License-Expression: MIT
+License-File: LICENSE
+Keywords: linux,mac,mac-address,network,security,spoofer
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.11
+Requires-Dist: art>=6.0
+Requires-Dist: pretty-errors>=1.2.25
+Requires-Dist: rich>=14.0.0
+Description-Content-Type: text/markdown
+
+# MAC Address Spoofer
+
+![CI (master)](https://github.com/DanielKirshner/MacSpoofer/actions/workflows/linux-ci.yml/badge.svg?branch=master)
+
+A command-line tool to spoof your network interface's MAC address on Linux systems.
+
+![MacSpoofer Demo](demo/demo.gif)
+
+## What is a MAC Address?
+
+A **Media Access Control (MAC) address** is a unique identifier assigned to a network interface controller (NIC) for use as a network address in communications within a network segment. This identifier is used in most IEEE 802 networking technologies, including Ethernet, Wi-Fi, and Bluetooth.
+
+Changing your MAC address can be useful for:
+- **Privacy** - Prevent tracking across networks
+- **Testing** - Simulate different network devices
+- **Bypassing restrictions** - Some networks filter by MAC address
+
+## MAC Address Structure
+
+A MAC address is a **12-digit hexadecimal number** (6 bytes), typically represented in colon-hexadecimal notation (e.g., `00:1A:2B:3C:4D:5E`).
+
+| Bytes | Name | Description |
+|-------|------|-------------|
+| First 3 bytes | **OUI** (Organizationally Unique Identifier) | Identifies the manufacturer |
+| Last 3 bytes | **NIC** (Network Interface Controller) | Device-specific identifier |
+
+## Features
+
+- 🎲 **Random MAC generation** - Generate safe, locally-administered unicast addresses
+- 🏭 **Vendor spoofing** - Mimic devices from Samsung, Apple, Intel, Microsoft, Huawei, Google, or Cisco
+- 🖥️ **Interactive TUI** - Easy to use text interface
+- ⚡ **Auto mode** - Non-interactive operation for scripts
+- 🔧 **CI mode** - Designed for automated testing pipelines
+
+## Compatibility
+
+The tool is compatible with **Linux distributions only**.
+
+Tested on:
+- **Ubuntu** - 16.04.7, 18.04.6, 20.04.6, 22.04.5, 24.04.2
+- **Debian** - 8, 9, 10, 11, 12
+- **Kali** - 2021.4a, 2022.4, 2023.4, 2024.4, 2025.1
+- **Raspbian** - 8, 9, 10, 11, 12
+
+## Installation
+
+### Via pip (recommended)
+
+```bash
+pip install macspoofer
+```
+
+### From source
+
+```bash
+chmod +x setup.sh
+sudo ./setup.sh
+```
+
+## Usage
+
+### Find Your Interface Name
+
+```bash
+ifconfig -a
+# or
+ip link show
+```
+
+### Interactive Mode (TUI)
+
+```bash
+sudo macspoofer -i <interface>
+# or
+sudo python3 main.py -i <interface>
+```
+
+### Auto Mode (Non-Interactive)
+
+```bash
+sudo macspoofer -i <interface> --auto
+# or
+sudo python3 main.py -i <interface> --auto
+```
+
+### Command Line Options
+
+| Option | Description |
+|--------|-------------|
+| `-i <interface>` | Network interface name (e.g., `wlan0`, `eth0`) **[Required]** |
+| `--auto` | Non-interactive mode: generate and apply a random unicast MAC |
+| `--ci` | CI mode: for automated testing |
+| `--help` | Show help message and usage examples |
+| `--version` | Show version information |
+
+
+## Resources
+
+- [MAC Vendor Lookup API](https://macvendors.com/) - Look up manufacturer by MAC address
+- [Wireshark Vendor Database](https://github.com/wireshark/wireshark/blob/master/manuf) - Comprehensive list of known manufacturers
+
+> 💡 Want more vendors? Feel free to open a PR to add more vendor OUIs!
+
+## License
+
+[MIT License](LICENSE)
+
+---
+
+**© 2022-2026 Daniel Kirshner. All rights reserved.**

macspoofer-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+macspoofer/__init__.py,sha256=G-Om7V7zAuN7j2q6x0sLwnAyr2DNZA3QZK5AEQUhAcs,113
+macspoofer/cli.py,sha256=Y9BfAz27t4mVaVSmsAxnsHHYk-3bodbYeHYKkQqEruI,1045
+macspoofer/spoofer.py,sha256=wUdECzW8YZ84LAokgev7GlY6WUxqis5l7KIOxmUUNmQ,4332
+macspoofer/modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+macspoofer/modules/args_parser.py,sha256=290hHeJGVCwgfZDhurOJj3BTQ5v6Q6M0qyCY8YEhBuc,1956
+macspoofer/modules/error_config.py,sha256=jxRbSlW9WjK96TIn10ghcVPJ0e2FCcpM7p0t53orLdw,566
+macspoofer/modules/interface.py,sha256=4QGMlE4cMjR-QzqQwgpn6enTkvwOEhiMBuFjsnjji80,3003
+macspoofer/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+macspoofer/utils/exceptions.py,sha256=4gaR_4I5NvM5q-VVDrJuoftZCLnTCs8B56_LAZ-cUig,939
+macspoofer/utils/random_utils.py,sha256=06oA6S520f39et1CSMrh-2UR_yi0npbumXAA8AqLqSw,2088
+macspoofer/utils/shell_utils.py,sha256=n_Gis_k3cfgEa_mq2vSorL_d064p2reddXG8x4tMmek,1392
+macspoofer/utils/vendors.py,sha256=mBWpcI3gz6oV_zyjDOPmDKUm4GWobGGUHeY8Ldai39E,8322
+macspoofer-1.0.0.dist-info/METADATA,sha256=hYNeprgg0fcx65OsBZYBs9zBulzImoLMSgjK7VO918s,4312
+macspoofer-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+macspoofer-1.0.0.dist-info/entry_points.txt,sha256=KZ6WXXxXhFi1S_881Ew6IsJj0_YHZH1JQwqfQuNPpCg,51
+macspoofer-1.0.0.dist-info/licenses/LICENSE,sha256=Bm-Ku6lugPyBn5w36W9Z221mdwA6kcmbq_3mT3lMWQM,1076
+macspoofer-1.0.0.dist-info/RECORD,,

macspoofer-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

macspoofer-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+macspoofer = macspoofer.cli:main

macspoofer-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2026 Daniel Kirshner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.