Reset Hardware MAC (spoof reset)

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli.ts
• src/index.ts
• README.md
• CLAUDE.md
• test/setInterfaceMAC.test.ts
• test/cli.test.ts

The reset feature in the spoof utility is designed to restore a network interface's MAC address to its original, "burned-in" hardware value. This is critical for users who have applied temporary spoofed addresses and need to revert to the factory-assigned identifier for network compatibility or troubleshooting.

Within the project architecture, this feature bridges the CLI layer with platform-specific system commands. It relies on the ability to read the permanent hardware MAC address from system logs or registry entries and then apply that specific value back to the active interface.

Sources: README.md:143-149, src/cli.ts:327-333

Architecture and Logic Flow

The reset command follows a specific execution path that involves identifying the hardware address before performing the update. Unlike randomize, which generates new data, reset acts as a restoration process.

Execution Process

1. Device Discovery: The CLI identifies the target interface(s) provided by the user.
2. Hardware Address Retrieval: The system queries the "burned-in" MAC address (recorded in address field of the NetworkInterface object).
3. Validation: It ensures a hardware address was successfully read.
4. Application: It uses the same underlying platform-specific mechanisms as the set command to apply the hardware address.

The following diagram illustrates the logical flow of the reset operation:

Key Components and Functions

The reset functionality is distributed between the CLI entry point and the core library.

CLI Implementation (src/cli.ts)

The reset(devices: string[]) function manages user interaction. It iterates through the provided devices, performs a lookup using spoof.findInterfaceAsync, and checks if the address property (representing the hardware MAC) is populated. If --dry-run is enabled, it logs what would happen without modifying the system state.

Core Library Support (src/index.ts)

The reset logic depends on several internal functions to identify the original MAC:

Function	Role in Reset
findInterfacesAsync	Populates the address field using platform-specific commands (e.g., networksetup on macOS or ipconfig on Windows).
setInterfaceMACAsync	The final actuator that applies the retrieved hardware MAC to the interface.
normalize	Ensures the retrieved hardware MAC is in the canonical format before application.

Sources: src/cli.ts:335-391, src/index.ts:742-763, CLAUDE.md:46-51

Platform-Specific Hardware Detection

The success of a reset operation depends on the project's ability to read the original MAC address, which varies significantly by Operating System.

macOS (Darwin)

The utility parses the output of networksetup -listallhardwareports. This command specifically returns the "Ethernet Address" associated with the hardware port, which remains constant even if the current interface MAC is spoofed.
Sources: src/index.ts:147-156, test/findInterfaces.test.ts:73-85

Windows (Win32)

On Windows, the ipconfig /all command is used to find the "Physical Address". The reset process retrieves this value to write it back into the Windows Registry under the NetworkAddress key for the corresponding adapter.
Sources: src/index.ts:413-435, test/setInterfaceMAC.test.ts:494-515

Linux

The system uses ip link show or ifconfig to identify addresses. It distinguishes between the active address and the permanent address where possible via these system tools.
Sources: src/index.ts:200-220, test/setInterfaceMAC.test.ts:251-275

Usage and Examples

The reset command requires administrative privileges (root/sudo on Unix or Administrator on Windows) because it modifies network configuration.

Command	Description
sudo spoof reset en0	Resets the interface en0 to its hardware MAC on macOS/Linux.
spoof reset Wi-Fi --dry-run	Shows the hardware MAC and the reset command that would be run without applying it.
spoof reset en0 --format=json	Performs the reset and outputs the result in structured JSON format.

Sources: README.md:95-102, src/cli.ts:344-383

JSON Output Example (Dry Run)

When run with --format=json --dry-run, the system returns the current and target (hardware) addresses:

{
  "success": true,
  "dryRun": true,
  "operations": [
    {
      "device": "en0",
      "port": "Ethernet",
      "currentAddress": "00:11:22:33:44:55",
      "newAddress": "AA:BB:CC:DD:EE:FF",
      "success": true
    }
  ]
}

Sources: src/cli.ts:385-390, test/cli.test.ts:340-355

Conclusion

The reset feature is a specialized implementation of the MAC setting logic that uses "read-only" hardware identifiers as the data source. By leveraging platform-specific discovery tools like networksetup and ipconfig, it ensures that users can always return their hardware to its factory state, providing a safety mechanism for the spoofing capabilities of the tool.
Sources: README.md:143-149, CLAUDE.md:65-70