Randomize MAC Address (spoof randomize)
Relevant source files
The following files were used as context for generating this wiki page:
The randomize feature is a core component of the spoof utility, designed to generate and apply cryptographically secure, randomized Media Access Control (MAC) addresses to network interfaces across macOS, Linux, and Windows. This system provides a high degree of privacy and testing flexibility by allowing users to obfuscate their hardware's original identity.
The system supports two primary modes of randomization: a default mode that uses common Virtual Machine (VM) vendor prefixes and an advanced mode that leverages the Organizationally Unique Identifier (OUI) database to mimic specific hardware manufacturers. It integrates deeply with platform-specific networking commands to ensure that changes take effect immediately, including handling hardware-specific requirements such as Wi-Fi disassociation on macOS.
Sources: src/cli.ts:187, src/index.ts:409, README.md
Architecture and Data Flow
The randomization process flows from the CLI entry point through a library layer that handles logic and vendor lookups, eventually reaching platform-specific execution modules.
The diagram above illustrates how the randomize command traverses from user input to hardware application.
Sources: src/cli.ts:187-251, src/index.ts:634-712
MAC Generation Logic
The generation of a new MAC address relies on the node:crypto module to ensure high entropy. The system uses two distinct strategies for generating the first three bytes (the OUI).
Default Randomization
By default, the system selects from a list of known Virtual Machine vendor prefixes to minimize the risk of collision with local physical hardware. On Windows, it uses specific prefixes (0xD2, 0xD6, 0xDA, 0xDE) recommended for compatibility.
Sources: src/index.ts:409-436
Vendor-Specific Randomization
When the --vendor flag is provided, the system performs a fuzzy search against the internal OUI database. It selects a random prefix from the matching results and generates the remaining three bytes.
Sources: src/oui.ts:211-253, src/cli.ts:215-223
Locally Administered Bit
If the --local flag is used, the system sets the second least significant bit of the most significant byte to 1. This marks the address as a "Locally Administered" address.
Sources: src/index.ts:446-456, src/oui.ts:245-247
Platform-Specific Implementation
The randomize feature uses setInterfaceMACAsync to apply the generated address. The implementation varies significantly by operating system:
| Platform | Tools Used | Specific Logic |
|---|---|---|
| macOS (Darwin) | networksetup, ifconfig | Disassociates Wi-Fi by power cycling the Airport device before and after the change. |
| Linux | ip link, ifconfig | Brings the interface down, applies the address, and brings it back up. Supports legacy ifconfig via --prefer-ifconfig. |
| Windows | Winreg, netsh | Modifies the Windows Registry (NetworkAddress key) and restarts the adapter via netsh interface set interface. |
Sources: src/index.ts:366-407, src/index.ts:634-712, src/index.ts:762-817
Interactive Randomization (macOS Script)
A standalone Bash script provides an interactive wrapper for the randomization feature on macOS. It handles dependency installation and provides a UI for selecting multiple interfaces.
The sequence above shows the interaction between the standalone helper script and the core CLI utility.
Sources: scripts/mac-randomize.sh:135-267
Configuration and Flags
The following flags directly modify the behavior of the randomize command:
| Flag | Type | Description |
|---|---|---|
--local | Boolean | Sets the locally administered bit on the generated MAC. |
--vendor=<name> | String | Performs fuzzy lookup and generates a MAC with the vendor's OUI. |
--dry-run | Boolean | Shows the generated MAC without applying it to the system. |
--format=json | String | Outputs the result (newAddress, vendor, success) as a JSON object. |
Sources: src/cli.ts:23-40, src/cli.ts:133-152
Technical Summary
The spoof randomize system provides a robust mechanism for hardware identity obfuscation. By combining a cryptographically secure random number generator with an extensive OUI database, it ensures that generated addresses are both valid and diverse. The platform-specific drivers handle the low-level complexities of the operating system's networking stack, allowing for a unified CLI experience.
Sources: src/index.ts:409, src/oui.ts:211, src/cli.ts:187