Windows Implementation

Relevant source files

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

• src/index.ts
• src/cli.ts
• CLAUDE.md
• test/findInterfaces.test.ts
• test/setInterfaceMAC.test.ts
• test/fixtures/windows/ipconfig-all.txt
• test/fixtures/windows/getmac.txt

The Windows implementation of spoof provides the logic necessary to discover network interfaces and modify MAC addresses on the win32 platform. Unlike Unix-based systems that primarily use ifconfig or ip commands, the Windows implementation relies on a combination of CLI tools like ipconfig and getmac, along with direct manipulation of the Windows Registry to persist address changes.

The system is designed to handle the complexities of the Windows networking stack, including the requirement for administrative privileges and the necessity of restarting network adapters (disable/enable cycle) for Registry-based MAC changes to take effect.

Sources: src/index.ts:54, README.md:104-107

Interface Discovery

Interface discovery on Windows is a multi-step process that correlates data from ipconfig /all and getmac.

Discovery Logic

1. Command Execution: The system executes ipconfig /all to list all adapters and their physical addresses.
2. Parsing: It parses the output to extract adapter names (e.g., "Ethernet", "Wi-Fi"), physical addresses, and descriptions.
3. Current MAC Retrieval: Because ipconfig often shows the hardware MAC, the system calls getmac /v /fo csv to identify the "currently set" MAC address, which might differ if the address has been spoofed.
4. Correlation: It matches the connection names from both outputs to build a complete NetworkInterface object.

Sources: src/index.ts:397-458, test/findInterfaces.test.ts:251-279

The diagram above shows the dual-command approach used to gather hardware and software MAC addresses on Windows.

Data Extraction

The implementation uses a custom CSV parser to handle the output of the getmac command, which provides details in a quoted comma-separated format.

Sources: src/index.ts:348-378, test/basic.test.ts:133-157

MAC Address Spoofing

Modifying a MAC address on Windows is performed asynchronously by modifying specific keys in the Windows Registry.

Registry Architecture

Windows stores network adapter configurations in the Registry hive HKEY_LOCAL_MACHINE. Specifically, spoof targets the following path:
\SYSTEM\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002BE10318}

This key contains subkeys (e.g., 0001, 0002) for every network device. The implementation iterates through these subkeys to find the one matching the target device name by checking values such as NetConnectionID, DriverDesc, or AdapterModel.

Sources: src/index.ts:54, src/index.ts:1016-1033, test/setInterfaceMAC.test.ts:446-512

Update Workflow

Once the correct Registry subkey is identified, the following sequence occurs:

1. Write Registry: The NetworkAddress value is set to the new MAC address (without colons).
2. Disable Adapter: The netsh interface set interface <device> disable command is executed.
3. Enable Adapter: The netsh interface set interface <device> enable command is executed to force the driver to reload the configuration.

Sources: src/index.ts:1040-1065, test/setInterfaceMAC.test.ts:505-510

The sequence diagram illustrates the requirement for an adapter restart via netsh following the Registry update.

Implementation Details

Key Functions and Components

Component	Type	Description
WIN_REGISTRY_PATH	Constant	The GUID-based path to network class Registry keys.
setInterfaceMACWin32Async	Function	Orchestrates the Registry search and update for a device.
tryWindowsKeyAsync	Function	Validates if a subkey matches the device and applies the change.
getInterfaceMACWin32	Function	Parses getmac CSV output to find the current active MAC.
winreg	Dependency	External module used to interface with the Windows Registry.

Sources: src/index.ts:54, src/index.ts:316-340, src/index.ts:1016, package.json:23

Constraints and Requirements

• Administrative Privileges: Since the tool modifies HKLM (HKEY_LOCAL_MACHINE) and executes netsh, the CLI must be run from an Administrator shell.
• Async Only: The project deprecates synchronous calls for Windows. setInterfaceMAC throws an error on Windows, requiring the use of setInterfaceMACAsync.
• Registry Format: While the user provides MACs in 00:11:22... format, Windows Registry requires the NetworkAddress string to be stripped of separators (e.g., 001122...).

Sources: src/index.ts:795-797, src/index.ts:1044, README.md:104-107

Conclusion

The Windows implementation of spoof effectively bridges the gap between high-level Node.js code and low-level OS configuration. By utilizing ipconfig for discovery, the Windows Registry for persistence, and netsh for adapter management, it provides a robust spoofing mechanism tailored to the Windows environment while maintaining a consistent API with the macOS and Linux implementations.

Sources: src/index.ts:24-28, src/cli.ts:400-410