Persisting MAC Changes
Relevant source files
The following files were used as context for generating this wiki page:
The spoof project provides mechanisms to modify Media Access Control (MAC) addresses across different operating systems. However, the persistence of these changes varies significantly depending on the platform's architecture and how the operating system manages network hardware. While the tool focuses on the immediate application of new MAC addresses, it also provides guidance and hooks for achieving long-term persistence.
Sources: README.md:13-17, src/index.ts:543-550
Platform-Specific Persistence Behavior
The ability for a MAC address change to survive a system reboot is largely determined by the underlying operating system and the method used by spoof to apply the change.
macOS (Darwin)
On macOS, changes are inherently volatile. The spoof tool utilizes ifconfig and networksetup to modify the address in memory. Upon a system restart, the hardware defaults are restored by the kernel.
Sources: README.md:154-156, src/index.ts:553-575
Windows (Win32)
Windows persistence is achieved by modifying the Windows Registry. The spoof tool targets specific registry keys to store the NetworkAddress value. Because this is a registry-level change, it persists across reboots, although the adapter must be cycled (disabled and enabled) for the change to take effect initially.
Sources: README.md:82-85, src/index.ts:792-805
Linux
Linux persistence depends on the network management stack (e.g., NetworkManager, systemd-networkd). spoof applies changes using ip link or ifconfig, which are generally temporary unless integrated into system startup scripts.
Sources: README.md:80-81, src/index.ts:580-594
Windows Registry Architecture
The Windows implementation is the only one within the core codebase that natively implements a persistent change by writing to the system hive.
The diagram shows the logic flow for Windows where the MAC address is written to a persistent registry key before cycling the hardware.
Sources: src/index.ts:829-842, src/index.ts:875-897
Registry Configuration Details
| Key/Attribute | Value/Path | Description |
|---|---|---|
| Registry Path | \SYSTEM\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002BE10318} | The base path for network adapter configurations in Windows. |
| Value Name | NetworkAddress | The registry string value used to override the hardware MAC address. |
| Data Type | REG_SZ | The required registry format for the MAC address string. |
| Format | 001122334455 | Windows registry expects the MAC without colon or dash separators. |
Sources: src/index.ts:39-40, src/index.ts:887-891, test/setInterfaceMAC.test.ts:476-480
Automating Persistence on macOS
Since macOS does not natively persist ifconfig changes, the project recommends external automation via the system's initialization daemon, launchd.
Launchd Integration
Users seeking persistence on macOS must create a launchd property list (plist) that executes spoof during the boot sequence or upon network interface detection. This effectively "spoofs" the address every time the system starts, simulating persistence.
Sources: README.md:195-200
Implementation Logic for Persistent Selection
The scripts/mac-randomize.sh script provides an interactive way to select interfaces for randomization on macOS. While the script itself is a one-time execution, the logic it uses to identify and target interfaces is the foundation for any persistent automation script.
The sequence shows how the interactive script identifies hardware ports to apply changes that would need to be automated for persistence.
Sources: scripts/mac-randomize.sh:137-147, scripts/mac-randomize.sh:260-265
Key Functions and Components
setInterfaceMACWin32Async(device, mac): The core function for Windows persistence via registry modification.
Sources: src/index.ts:829-842tryWindowsKeyAsync(key, device, mac): Matches specific registry keys to network devices usingNetConnectionIDorDriverDesc.
Sources: src/index.ts:875-890mac-randomize.sh: A shell utility that automates the installation and execution environment for randomization on macOS.
Sources: scripts/mac-randomize.sh:1-40
Summary
Persistence of MAC changes in spoof is platform-dependent. Windows changes are persistent by design through registry modification. In contrast, macOS and Linux changes are volatile. For these platforms, persistence must be achieved through system-level automation such as launchd or startup scripts that re-apply the spoof command during the boot process.
Sources: README.md:195-200, src/index.ts:543-550