Set MAC Address (spoof set)

Relevant source files

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

• src/cli.ts
• src/index.ts
• test/setInterfaceMAC.test.ts
• scripts/mac-randomize.sh
• README.md

Introduction

The spoof set feature provides the capability to manually assign a specific Media Access Control (MAC) address to one or more network interfaces across macOS, Linux, and Windows platforms. This module acts as the core manual configuration interface within the spoof utility, allowing users to override hardware-burned addresses with user-defined hex strings.

Sources: README.md:95-99, src/cli.ts:162-166

The system handles platform-specific complexities, such as disassociating Wi-Fi cards on macOS before applying changes or managing Windows Registry keys and adapter restarts. It supports validation of MAC formats and ensures that operations are performed with necessary administrative privileges (root/sudo on Unix-like systems, Administrator on Windows).

Sources: README.md:20-24, src/index.ts:401-403

Architecture and Logic Flow

The "set" operation follows a tiered execution model starting from the CLI argument parser, moving through a platform-agnostic library layer, and finally executing platform-specific system commands.

Execution Sequence

When a user executes spoof set <mac> <devices...>, the following flow occurs:

1. CLI Parsing: minimist extracts the target MAC and device list.
2. Interface Lookup: The system searches for the specified device name (e.g., en0) to confirm existence and identify the port type (e.g., Wi-Fi).
3. Privilege Check: The system verifies if the process has root/UID 0 permissions (for non-Windows platforms).
4. Platform Dispatch: The setInterfaceMACAsync function executes logic specific to the detected OS.

Sources: src/cli.ts:162-205, src/index.ts:803-855

The diagram shows the coordination between the CLI entry point, the core library, and the underlying OS commands.
Sources: src/cli.ts:405-416, src/index.ts:803-855

Validation and Normalization

Before any system command is executed, the input MAC address undergoes strict validation and normalization to ensure compatibility with hardware drivers.

Input Constraints

• Device Names: Validated against DEVICE_NAME_RE (/^[a-zA-Z0-9._-]+$/).
• MAC Format: Validated against MAC_VALIDATION_RE. Supported formats include colon-separated (00:11:22...), dash-separated (00-11-22...), and Cisco-style (0000.0000.0000).
• Normalization: All valid inputs are converted to uppercase, colon-separated strings (e.g., 00:11:22:33:44:55).

Sources: src/index.ts:44-53, src/index.ts:515-540, test/setInterfaceMAC.test.ts:79-100

Format Type	Example Input	Normalized Output
Standard	00:11:22:33:44:55	00:11:22:33:44:55
Dashed	00-11-22-33-44-55	00:11:22:33:44:55
Cisco	0123.4567.89ab	01:23:45:67:89:AB

Sources: src/index.ts:515-540, README.md:126-133

Platform-Specific Implementations

macOS (Darwin)

On macOS, standard ethernet changes use ifconfig <device> ether <mac>. However, Wi-Fi interfaces require a power cycle using networksetup -setairportpower to disassociate from existing networks before and after the change.

Sources: src/index.ts:816-836, test/setInterfaceMAC.test.ts:153-176

Linux

Linux supports two toolsets. By default, it uses iproute2 (ip command), but can fall back to net-tools (ifconfig) if ip is unavailable or if the --prefer-ifconfig flag is used. The interface is brought down before the address change and up immediately after.

Sources: src/index.ts:837-852, test/setInterfaceMAC.test.ts:205-234

Windows (Win32)

Windows does not support a direct CLI command to change the MAC. Instead, the utility:

1. Locates the correct registry key under HKLM\SYSTEM\CurrentControlSet\Control\Class\{4D36E972-E325-11CE-BFC1-08002BE10318} by matching NetConnectionID or DriverDesc.
2. Sets the NetworkAddress value.
3. Restarts the adapter using netsh interface set interface <name> disable/enable.

Sources: src/index.ts:887-954, test/setInterfaceMAC.test.ts:373-435

This flow illustrates the divergent technical paths required to achieve a MAC change across supported operating systems.
Sources: src/index.ts:814-954

Summary

The "Set MAC Address" feature is a robust wrapper around low-level OS utilities. It abstracts the complexity of registry editing on Windows, tool-switching on Linux, and Wi-Fi state management on macOS into a unified API and CLI command. By enforcing strict validation and requiring elevated privileges, it provides a safe and predictable method for manual hardware address spoofing.