macOS Quick-Start Randomizer
Relevant source files
The following files were used as context for generating this wiki page:
The macOS Quick-Start Randomizer is a specialized automation script designed to streamline the process of MAC address spoofing on macOS systems. It serves as an interactive entry point for users, handling the entire lifecycle of environmental preparation, dependency installation, and execution of the core spoof utility.
Sources: scripts/mac-randomize.sh:9-11, README.md:23-33
This component is specifically architected to be executed as a "one-liner" via a piped shell command. It automates the installation of Homebrew and Node.js if they are absent, clones the project repository into a temporary directory, builds the TypeScript source, and provides an interactive TUI (Terminal User Interface) for selecting network interfaces to randomize.
Sources: scripts/mac-randomize.sh:50-80, CLAUDE.md:65-68
Workflow Architecture
The randomizer follows a linear execution path starting from environment validation and ending with the application of new MAC addresses via sudo privileges.
The diagram above illustrates the sequential logic from initial execution to the final cleanup of the temporary build environment.
Sources: scripts/mac-randomize.sh:15-120
Environment Preparation and Dependencies
The script ensures the target system meets all requirements for running the Node.js-based spoof tool. It checks for and optionally installs the following components:
| Component | Purpose | Requirement |
|---|---|---|
| macOS (Darwin) | Target Operating System | Mandatory |
| Xcode CLI Tools | Provides git for cloning | Optional/Installed if missing |
| Homebrew | Package manager for Node.js | Optional/Installed if missing |
| Node.js | Execution runtime | Version >= 18 |
| Yarn | Dependency management | Enabled via Corepack |
Sources: scripts/mac-randomize.sh:16-104, README.md:40-42
Interactive Interface Selection (TUI)
A core feature of the Quick-Start script is the interactive interface picker. It uses a Node.js sub-process to parse interface data into parallel arrays and then renders a selection menu using standard shell input/output.
Data Flow for Discovery
The script invokes the compiled CLI to generate a JSON representation of available hardware ports, which is then parsed by an inline Node.js script.
The diagram shows how the script leverages the core tool's JSON output capability to populate the selection menu.
Sources: scripts/mac-randomize.sh:135-175, src/cli.ts:413-426
Selection Logic
The TUI supports several keyboard interactions for user convenience:
- Arrow Keys (Up/Down): Navigate through the list of discovered interfaces.
- Spacebar: Toggle selection of the highlighted interface.
- Enter: Confirm selections and proceed to randomization.
- 'q' or Escape: Cancel the operation and exit.
Sources: scripts/mac-randomize.sh:225-270, test/mac-randomize-script.test.ts:10-15
MAC Address Randomization Process
Once interfaces are selected, the script utilizes the core spoof randomization logic. For wireless interfaces, it acknowledges the specific macOS requirement of power cycling the Wi-Fi card.
Execution Details
The script executes the command sudo node dist/cli.js randomize <device> for each selected interface. This triggers the underlying setInterfaceMACAsync function, which performs the following on macOS:
- Disassociation: If the port is "Wi-Fi", it runs
networksetup -setairportpower <device> off/on. - Modification: Executes
ifconfig <device> ether <mac>. - Re-association: Power cycles the airport device again to trigger reconnection.
Sources: src/index.ts:503-513, src/index.ts:792-820, scripts/mac-randomize.sh:317-325
Security and Integrity
The Quick-Start Randomizer implements several safeguards to maintain system stability:
- Secure Temp Directory: Clones the repository into a directory created with
mktemp -dand permissions set to700. - Cleanup Trap: Uses a Bash
traponEXITto ensure the cursor is restored, terminal settings are reset, and temporary files/directories are deleted regardless of how the script terminates. - No Eval Injection: Specifically avoids using
evalto parse interface metadata to prevent potential code injection from malicious interface names.
Sources: scripts/mac-randomize.sh:31-43, scripts/mac-randomize.sh:107-115, test/mac-randomize-script.test.ts:13-17
Conclusion
The macOS Quick-Start Randomizer provides a high-level abstraction over the complex manual steps required to spoof MAC addresses on Apple hardware. By combining environment bootstrapping with an interactive TUI and the core spoof API, it offers a robust solution for developers and privacy-conscious users to quickly modify network identity.
Sources: README.md:23-33, CLAUDE.md:65-68