macOS (Darwin) Implementation

Relevant source files

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

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

The macOS (Darwin) implementation of the spoof utility provides a specialized workflow for discovering network interfaces and modifying Media Access Control (MAC) addresses. On macOS, this process is uniquely constrained by the requirement to disassociate Wi-Fi interfaces from active networks before a MAC address change can be successfully applied.

The system utilizes native Darwin command-line tools, primarily networksetup, ifconfig, and the airport binary functionality, to interface with the hardware. The implementation includes both a core library API and a standalone interactive shell script designed specifically for macOS quick-start scenarios.

Sources: src/index.ts:121-124, README.md:23-28, README.md:100-101

Interface Discovery Logic

Discovery on macOS involves parsing structured output from the networksetup utility. Unlike Linux or Windows, macOS provides a clear distinction between the "Hardware Port" (e.g., Wi-Fi, Ethernet) and the logical "Device" name (e.g., en0, en1).

The Discovery Pipeline

The discovery process follows a specific sequence of command executions to build a complete NetworkInterface object:

1. Enumerate Ports: Execute networksetup -listallhardwareports to obtain a list of hardware ports, their associated device names, and their hardware MAC addresses.
2. Filter Targets: If specific targets are provided, the system matches them against both the Port name and the Device name (case-insensitive).
3. Retrieve Current State: For each identified device, the system executes ifconfig <device> to fetch the currently assigned MAC address, which may differ from the burned-in hardware address if previously spoofed.

Sources: src/index.ts:121-175, src/index.ts:601-645

MAC Address Modification

Changing a MAC address on macOS requires administrative privileges (sudo) and involves different logic depending on whether the target interface is a Wi-Fi (wireless) port.

Wi-Fi Power Cycling

For Wi-Fi interfaces, the system must disassociate from the network. This is achieved by power-cycling the "airport" hardware using networksetup -setairportpower <device> off followed by on. This sequence is performed both before and after the address change to ensure the new MAC is registered and the device attempts to re-associate.

Sources: src/index.ts:466-475, src/index.ts:747-756, test/setInterfaceMAC.test.ts:151-174

Core Modification Sequence

The actual modification of the address is performed using the ifconfig utility with the ether directive.

Technical Reference

Native Commands Used

The implementation relies on specific Darwin system binaries:

Command	Usage in Project	Source
networksetup -listallhardwareports	Primary discovery of ports, devices, and hardware MACs.	src/index.ts:128
networksetup -setairportpower	Power cycles Wi-Fi to force disassociation/re-association.	src/index.ts:472
ifconfig <device>	Reads the current operational MAC address.	src/index.ts:446
ifconfig <device> ether <mac>	Sets the new link-layer address (requires root).	src/index.ts:483

Data Structures

The macOS implementation populates the NetworkInterface type as follows:

• port: The human-readable name (e.g., "Wi-Fi").
• device: The BSD device name (e.g., "en0").
• address: The burned-in hardware MAC address from networksetup.
• currentAddress: The active MAC address parsed from ifconfig.

Sources: src/index.ts:149-154, src/types.ts

Interactive macOS Helper (mac-randomize.sh)

A specialized Bash script is provided for macOS users to simplify the process. It automates the environment setup and provides a GUI-like interactive CLI for selecting interfaces.

Script Workflow

1. Environment Check: Verifies the OS is Darwin and checks for git, brew, and node (installing them if necessary).
2. Build Phase: Clones the repository to a temporary directory and runs yarn build.
3. Interactive Selection: Executes spoof list --format=json and presents a selectable list of interfaces using an interactive picker.
4. Execution: Invokes the built cli.js with sudo to apply the randomized MAC to selected interfaces.

Sources: scripts/mac-randomize.sh:13-17, scripts/mac-randomize.sh:91-94, scripts/mac-randomize.sh:317-320

Conclusion

The macOS implementation of spoof provides a robust wrapper around Darwin-specific networking utilities. By handling the complex Wi-Fi disassociation requirements through networksetup power-cycling and providing an interactive helper script, the system abstracts the manual difficulties of MAC spoofing on macOS into a single, automated workflow.

Sources: README.md:23-28, src/index.ts:466-493