{"id":26674122,"url":"https://github.com/jamesworldbuilder/macaddress-spoofer","last_synced_at":"2026-04-27T12:05:25.422Z","repository":{"id":284282579,"uuid":"954426164","full_name":"jamesworldbuilder/macaddress-spoofer","owner":"jamesworldbuilder","description":"MAC Address Spoofer Script","archived":false,"fork":false,"pushed_at":"2025-03-25T04:29:34.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T05:24:43.590Z","etag":null,"topics":["bash-script","mac-address-spoofing","shell-script"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesworldbuilder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-25T04:12:06.000Z","updated_at":"2025-03-25T04:29:37.000Z","dependencies_parsed_at":"2025-03-25T05:25:02.947Z","dependency_job_id":"51790380-713b-4f61-afec-9eb4353e58a0","html_url":"https://github.com/jamesworldbuilder/macaddress-spoofer","commit_stats":null,"previous_names":["jamesworldbuilder/macaddress-spoofer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jamesworldbuilder/macaddress-spoofer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesworldbuilder%2Fmacaddress-spoofer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesworldbuilder%2Fmacaddress-spoofer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesworldbuilder%2Fmacaddress-spoofer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesworldbuilder%2Fmacaddress-spoofer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesworldbuilder","download_url":"https://codeload.github.com/jamesworldbuilder/macaddress-spoofer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesworldbuilder%2Fmacaddress-spoofer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32335353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash-script","mac-address-spoofing","shell-script"],"created_at":"2025-03-26T02:17:32.384Z","updated_at":"2026-04-27T12:05:25.405Z","avatar_url":"https://github.com/jamesworldbuilder.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MAC Address Spoofer Script\n\n## Purpose\nThe `MAC Address Spoofer Script` (`mac_address_spoofer.sh`) is a Bash utility designed to spoof (change) the MAC address of a network interface controller (NIC) on most Linux systems and provides an option to revert to the original MAC address. It aims to enhance privacy by allowing users to temporarily mask their device’s hardware MAC address while preserving the ability to restore the original. It’s recommended to run the script before establishing a network connection, though it will still function if the system is already connected.\n\n## What It Does\nThis script performs the following key functions:\n- **Spoofs a MAC Address**: Generates a random MAC address and applies it to a specified or auto-detected network interface (e.g., `eth0`, `wlan0`, `enp1s0`, etc.).\n- **Backs Up the Original MAC Address**: Stores the original MAC address in `~/.config/macaddr_backup/` with a creation date suffix (e.g., `eth0_2025-03-23`), but only if no backup exists yet for the selected network interface. Backup file permissions are isolated to the current user. \n- **Option to Restore Original MAC Address**: Restores the original MAC address of the selected network interface from the backup file when the script is run with the `--revert` flag.\n- **Purpose-Specific Network Handling and MAC Format Validation**: Disconnects the network before changing the MAC address, retries if necessary, checks network connectivity using [Quad9’s public DNS server](https://www.quad9.net/) (`9.9.9.9`), and validates the new MAC address format.\n\n## Requirements\n- **Operating System**: Linux environment.\n- **Bash Shell**: Compatible with Bash 4.0 or later.\n- **Dependencies**:\n  - `ip` (from `iproute2` package, usually pre-installed).\n  - Optional: `nmcli` (from `NetworkManager`, recommended for cleaner network disconnection if available).\n- **Permissions**: Requires `sudo` privileges to modify network interface settings.\n\n## How to Use\n1. **Make it Executable**: \n   ```bash\n   chmod +x mac_address_spoofer.sh\n   ```\n2. **Run the Script**:\n   - **Spoof a MAC Address**:\n     ```bash\n     ./mac_address_spoofer.sh [--interface=\u003cnetwork_interface\u003e]\n     ```\n     - If `--interface` is omitted, the script auto-detects and selects the first non-loopback network interface (e.g., `eth0`, `wlan0`, etc.), excluding the loopback interface (e.g., `lo`).\n     - Example: `./mac_address_spoofer.sh --interface=eth0`\n   - **Revert to Original MAC Address**:\n     ```bash\n     ./mac_address_spoofer.sh --revert [--interface=\u003cnetwork_interface\u003e]\n     ```\n     - If `--interface` is omitted, the script auto-detects and selects the first non-loopback network interface (e.g., `eth0`, `wlan0`, etc.), excluding the loopback interface (e.g., `lo`). The script then looks for a backup file in the `~/.config/macaddr_backup/` directory [matching the pattern](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html) `\u003cnetwork_interface\u003e_*` (e.g., `eth0_2025-03-23`). \n\n        It's recommended that if you spoofed a specific interface, to specify the same one when using the `--revert` flag, because if the auto-detected interface doesn’t match the one you previously spoofed, it fails with a \"`No backup file found`\" error. This is a limitation of the auto-detection logic, not a bug— the script assumes consistency between spoofing and reverting. \n\n        Issues arise if suppose the script previously spoofed the MAC address for the `wlan0` interface and saved the backup file as `wlan0_2025-03-23`, but `eth0` is the first interface detected when running `./mac_address_spoofer.sh --revert` without specifying the `--interface` flag. Then the script will look for a backup filename beginning with \"`eth0_`\" instead of \"`wlan0_`\".\n     - Example: \n\n       (recommended)\n       ```bash\n       ./mac_address_spoofer.sh --revert --interface=eth0 \n       ``` \n       or\n       ```bash\n       ./mac_address_spoofer.sh --revert\n\n## Possible Outputs\n### Successful/Expected Outputs:\n#### Spoofing a MAC Address (First Run)\n```plaintext\nSpoofing MAC address...\nNetwork connection detected - Disconnecting...(attempt 1 of 5)\nSuccessfully disconnected from network\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nGenerated MAC addresses:\n02:AB:CD:EF:12:34\n02:56:78:90:AB:CD\n02:DE:AD:BE:EF:12\n02:34:56:78:90:AB\n02:EF:CD:AB:12:34\nSelected MAC address: 02:AB:CD:EF:12:34\nMAC address for 'eth0' changed to: 02:AB:CD:EF:12:34\nMAC address spoofing completed successfully for 'eth0'\nPrevious MAC: 00:11:22:33:44:55\nNew MAC: 02:AB:CD:EF:12:34\nYou can now connect to a network with the new spoofed MAC address\nTo revert to the original MAC, run: ./mac_address_spoofer.sh --revert [--interface=eth0]\nWARNING: This doesn't affect the 'permaddr' (permanent MAC address),\n         which remains visible to low-level tools (e.g., 'ip link'),\n         but network traffic uses the spoofed active MAC address\n\ndone\n```\n\n#### Spoofing a MAC Address (Subsequent Run - Backup Exists)\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address backup for 'eth0' detected in '/home/user/.config/macaddr_backup' - Proceeding...\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nGenerated MAC addresses:\n02:12:34:56:78:90\n02:AB:CD:EF:12:34\n02:56:78:90:AB:CD\n02:DE:AD:BE:EF:12\n02:EF:CD:AB:12:34\nSelected MAC address: 02:12:34:56:78:90\nMAC address for 'eth0' changed to: 02:12:34:56:78:90\nMAC address spoofing completed successfully for 'eth0'\nPrevious MAC: 00:11:22:33:44:55\nNew MAC: 02:12:34:56:78:90\nYou can now connect to a network with the new spoofed MAC address\nTo revert to the original MAC, run: ./mac_address_spoofer.sh --revert [--interface=eth0]\nWARNING: This doesn't affect the 'permaddr' (permanent MAC address),\n         which remains visible to low-level tools (e.g., 'ip link'),\n         but network traffic uses the spoofed active MAC address\n\ndone\n```\n\n#### Reverting to Original MAC Address\n```plaintext\nSelected network interface: eth0\nMAC address successfully reverted to original for 'eth0'\nRestored from: /home/user/.config/macaddr_backup/eth0_2025-03-23\nCurrent MAC: 00:11:22:33:44:55\n\ndone\n```\n\n### Error Outputs:\n\n#### No Suitable Network Interface Found (Auto-Detection)\n```plaintext\nSpoofing MAC address...\nERROR: No suitable network interface found\n```\n- **Cause**: No non-loopback network interfaces (e.g., `eth0`, `wlan0`, etc.) were detected.\n- **Fix**: Specify an interface with `--interface=\u003cname\u003e` or ensure a network interface exists (check with `ip link show`).\n\n#### Specified Network Interface Not Found (Manual)\n```plaintext\nSpoofing MAC address...\nERROR: Specified network interface 'eth99' not found\n```\n- **Cause**: The network interface '`eth99`', specified with the `--interface=eth99` flag, doesn’t exist.\n- **Fix**: Use a valid interface name (check with `ip link show`).\n\n#### No Network Interface Specified (Manual)\n```plaintext\nERROR: No network interface specified with '--interface='\n```\n- **Cause**: The `--interface` flag was used without a value (e.g., `--interface=`).\n- **Fix**: Provide a value (e.g., `--interface=eth0`).\n\n#### Unknown Flag\n```plaintext\nERROR: Unknown flag: --foo\nUsage: ./mac_address_spoofer.sh [--interface=\u003cnetwork_interface\u003e] [--revert]\n```\n- **Cause**: An invalid flag was used (e.g., `--foo`).\n- **Fix**: Use only supported flags `--interface` or `--revert`.\n\n#### Failed to Disable Network Interface\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nList of generated MAC addresses saved to temporary file: /tmp/tmp.XYZ789\n02:AB:CD:EF:12:34\nSelected MAC address: 02:AB:CD:EF:12:34\nERROR: Failed to disable network interface 'eth0'\n```\n- **Cause**: The script tried to disable the selected network interface (with `sudo ip link set eth0 down`) and it failed (e.g., due to insufficient permissions or other interface issues).\n- **Fix**: Try running the script with `sudo` or check interface status (with `ip link show`) for other possible issues.\n\n#### Failed to Bring Network Interface Back Up\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nList of generated MAC addresses saved to temporary file: /tmp/tmp.XYZ789\n02:AB:CD:EF:12:34\nSelected MAC address: 02:AB:CD:EF:12:34\nERROR: Failed to bring network interface 'eth0' back up\n```\n- **Cause**: The script tried to enable the selected network interface (with `sudo ip link set eth0 up`) and failed (e.g., due to NIC hardware or driver issues).\n- **Fix**: Check interface status (with `ip link show`) and system logs (with `dmesg`). \n\n#### Failed to Set New MAC Address (Verification)\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nGenerated MAC addresses:\n02:AB:CD:EF:12:34\n02:56:78:90:AB:CD\n02:DE:AD:BE:EF:12\n02:34:56:78:90:AB\n02:EF:CD:AB:12:34\nSelected MAC address: 02:AB:CD:EF:12:34\nERROR: Failed to set new MAC address\n```\n- **Cause**: The script tried running `sudo ip link set eth0 address ...` and it failed (e.g., due to NIC hardware not supporting MAC address spoofing or driver ignored the change).\n- **Fix**: Verify NIC hardware support for MAC spoofing. Try running the script with `sudo`.\n\n#### MAC Address Change Failed (Verification)\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nGenerated MAC addresses:\n02:AB:CD:EF:12:34\n02:56:78:90:AB:CD\n02:DE:AD:BE:EF:12\n02:34:56:78:90:AB\n02:EF:CD:AB:12:34\nSelected MAC address: 02:AB:CD:EF:12:34\nMAC address for 'eth0' changed to: 02:AB:CD:EF:12:34\nERROR: MAC address change failed\nPrevious MAC: 00:11:22:33:44:55\nCurrent MAC: 00:11:22:33:44:55\nExpected MAC: 02:AB:CD:EF:12:34\n```\n- **Cause**: The new MAC address didn’t apply correctly (e.g., due to NIC hardware not supporting MAC address spoofing or driver ignored the change).\n- **Fix**: Verify NIC hardware support for MAC spoofing. Try running the script with `sudo`.\n\n#### Failed to Revert MAC Address (Revert)\n```plaintext\nSelected network interface: eth0\nMAC address for 'eth0' changed to: 00:11:22:33:44:55\nERROR: Failed to revert MAC address\nCurrent MAC: 02:AB:CD:EF:12:34\nExpected MAC: 00:11:22:33:44:55\n```\n- **Cause**: The original MAC address didn’t apply correctly (e.g., due to NIC hardware not supporting MAC address spoofing or driver ignored the change).\n- **Fix**: Verify NIC hardware support for MAC spoofing. Try running the script with `sudo`.\n\n#### No Backup File Found (Revert)\n```plaintext\nSelected network interface: eth0\nERROR: No backup file found for 'eth0' in '/home/user/.config/macaddr_backup' - Cannot revert\n```\n- **Cause**: No `eth0_*` backup file exists in the `~/.config/macaddr_backup/` directory.\n- **Fix**: Refer to the \"**Revert to Original MAC Address**\" bullet-point in the [How to Use](#how-to-use) section.\n\n\n#### The `ip` Command Not Installed (Dependencies)\n```plaintext\nSpoofing MAC address...\nERROR: 'ip' is required but not installed\n```\n- **Cause**: The `ip` command (from `iproute2`) is missing.\n- **Fix**: Install `iproute2` (e.g., `sudo apt install iproute2` on Debian/Ubuntu).\n\n#### Invalid MAC Address Format in Backup File (Revert)\n(Rare, but theoretically possible)\n```plaintext\nSelected network interface: eth0\nERROR: Invalid MAC address format in backup file '/home/user/.config/macaddr_backup/eth0_2025-03-23'\n```\n- **Cause**: The backup file contains an invalid MAC address (e.g., manually edited to `invalid`).\n- **Fix**: Remove the backup file (with `sudo rm ~/.config/macaddr_backup/*`) and recreate the backup file by running the script again.\n\n#### MAC Address List Empty\n(Rare, but theoretically possible)\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nGenerated MAC addresses:\nERROR: MAC address list is empty\nGenerating a list of random MAC addresses to select from...(attempt 2 of 3)\nGenerated MAC addresses:\nERROR: MAC address list is empty\nGenerating a list of random MAC addresses to select from...(attempt 3 of 3)\nGenerated MAC addresses:\nERROR: MAC address list is empty\nERROR: Failed to generate a valid MAC address list after 3 attempts\n```\n- **Cause**: The list of generated MAC addresses was empty (e.g., due to a failure in the generation process, though unlikely with current logic unless modified).\n- **Fix**: Debug the `generate_mac_list()` function output to ensure MAC addresses are being generated correctly. If you're seeing this error, you probably manually edited the script.\n\n#### Failed to Generate Valid MAC After Max Attempts (Verification)\n```plaintext\nSpoofing MAC address...\nSelected network interface: eth0\nOriginal MAC address: 00:11:22:33:44:55\nOriginal MAC address saved to '/home/user/.config/macaddr_backup/eth0_2025-03-23' for future restoration\nGenerating a list of random MAC addresses to select from...(attempt 1 of 3)\nGenerated MAC addresses:\n[malformed output]\nSelected MAC address: [invalid]\nInvalid MAC address format detected - Retrying...\n[... repeats for 3 attempts ...]\nERROR: Failed to generate valid MAC address after 3 attempts\n```\n- **Cause**: The generated MACs were invalid (unlikely with current `printf`, but possible if modified).\n- **Fix**: Debug the `generate_mac_list()` function output to ensure MAC addresses are being generated correctly. If you're seeing this error, you probably manually edited the script.\n\n---\n## Author Details\n- **Name:** James Logan Forsyth\n- **Email:** james3895@duck.com\n- **Date Created:** March 2025\n- **License:** MIT License\n\n      Copyright (c) 2025 - James Logan Forsyth\n      \n      Permission is hereby granted, free of charge, to any person obtaining a copy\n      of this software and associated documentation files (the \"Software\"), to deal\n      in the Software without restriction, including without limitation the rights\n      to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n      copies of the Software, and to permit persons to whom the Software is\n      furnished to do so, subject to the following conditions:\n\n      The above copyright notice and this permission notice shall be included in all\n      copies or substantial portions of the Software.\n\n      THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n      OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n      THE SOFTWARE.\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesworldbuilder%2Fmacaddress-spoofer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesworldbuilder%2Fmacaddress-spoofer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesworldbuilder%2Fmacaddress-spoofer/lists"}