macspoofer 1.0.0__tar.gz

macspoofer-1.0.0/.github/workflows/linux-ci.yml

@@ -0,0 +1,73 @@
+name: MacSpoofer CI
+
+on:
+  push:
+    branches: [dev, master]
+  pull_request:
+    branches: [dev, master]
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff lint
+        run: ruff check .
+
+      - name: Run ruff format check
+        run: ruff format --check .
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Running setup script
+        run: |
+          sudo chmod +x setup.sh
+          sudo ./setup.sh
+
+      - name: Create dummy interface (wlan0)
+        run: |
+          sudo ip link add wlan0 type dummy
+          sudo ip link set wlan0 up
+          echo "Created dummy interface:"
+          ip link show wlan0
+
+      - name: Get initial MAC
+        id: get_mac
+        run: |
+          OLD_MAC=$(ip link show wlan0 | awk '/ether/ {print $2}')
+          echo "old_mac=$OLD_MAC" >> $GITHUB_OUTPUT
+
+      - name: Run MacSpoofer in CI mode
+        run: |
+          echo "Spoofing MAC on dummy wlan0..."
+          sudo python3 ./main.py -i wlan0 --ci
+
+      - name: Verify MAC change
+        run: |
+          OLD_MAC="${{ steps.get_mac.outputs.old_mac }}"
+          NEW_MAC=$(ip link show wlan0 | awk '/ether/ {print $2}')
+          echo "Old MAC: $OLD_MAC"
+          echo "New MAC: $NEW_MAC"
+          if [[ "$NEW_MAC" == "$OLD_MAC" ]]; then
+            echo "MAC was not Spoofed!"
+            exit 1
+          else
+            echo "MAC Spoofed successfully!"
+          fi

macspoofer-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

macspoofer-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__
+manuf
+vendors/
+dist/
+build/
+*.egg-info/

macspoofer-1.0.0/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.

macspoofer-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+# 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/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-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-1.0.0/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-1.0.0/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-1.0.0/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})"