Introduction & Quick Start

Relevant source files

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

• README.md
• CLAUDE.md
• src/index.ts
• src/cli.ts
• src/oui.ts
• scripts/mac-randomize.sh
• package.json

The spoof project is a Node.js-based CLI utility and library designed to facilitate the spoofing of Media Access Control (MAC) addresses across macOS, Linux, and Windows platforms. It provides a TypeScript rewrite of the original SpoofMAC utilities, offering both a high-level command-line interface and a programmatic API for discovering network interfaces and modifying their hardware addresses.

The tool automates complex platform-specific requirements, such as disassociating Wi-Fi cards on macOS before applying changes, and supports advanced features like OUI (Organizationally Unique Identifier) vendor lookups and vendor-specific MAC randomization.

Sources: README.md:1-15, CLAUDE.md:3-10

System Architecture

The project is structured into three primary layers: the CLI entry point, the core Library API, and the OUI Database module.

• CLI Layer (src/cli.ts): Handles argument parsing via minimist, output formatting (supporting both text and JSON), and execution flow for user commands.
• Library Layer (src/index.ts): Contains the cross-platform logic for interface discovery and MAC manipulation. It abstracts platform differences by branching between darwin, linux, and win32.
• OUI Module (src/oui.ts): Manages the vendor database, providing fuzzy search and vendor-specific prefix generation.

Cross-Platform Execution Flow

The following diagram illustrates how the system branches based on the host operating system to execute hardware commands.

The system utilizes process.platform to determine which system binaries and registries to interact with for network configuration.

Sources: CLAUDE.md:65-75, src/index.ts:79-90

Installation and Quick Start

macOS One-Liner

For macOS users, an interactive shell script is provided to automate the entire installation and randomization process.

curl -fsSL https://raw.githubusercontent.com/TheJACKedViking/spoof/main/scripts/mac-randomize.sh | bash

This script checks for Homebrew and Node.js, installs them if missing, clones the repository, builds the tool, and provides an interactive interface to select and randomize network adapters.

Sources: README.md:20-30, scripts/mac-randomize.sh:1-100

Global Installation

For general use across all platforms, spoof can be installed via standard package managers.

Package Manager	Command
npm	npm install -g spoof
yarn	yarn global add spoof

Sources: README.md:40-50

Command Reference

The spoof CLI supports several primary actions for interface management and address manipulation.

Core Commands

Command	Description	Example
list (or ls)	Lists all network interfaces and current MACs	spoof list --wifi
set	Sets a specific MAC address on a device	sudo spoof set 00:11:22:33:44:55 en0
randomize	Generates and sets a random MAC address	sudo spoof randomize en0 --local
reset	Restores the hardware/burned-in MAC address	sudo spoof reset wi-fi
lookup	Retrieves vendor info for a given MAC	spoof lookup 00:03:93:12:34:56
vendors	Searches the internal OUI database	spoof vendors apple

Sources: README.md:75-155, src/cli.ts:145-165

Global Options

Users can modify command behavior using the following flags:

• --format=json: Returns structured data for automation.
• --dry-run (-n): Simulates the operation without applying changes.
• --vendor=<name>: Used with randomize to use a specific manufacturer's prefix.
• --local: Sets the locally-administered bit on randomized addresses.
• --prefer-ifconfig: Forces Linux systems to use legacy ifconfig instead of ip.

Sources: README.md:166-180, src/cli.ts:25-45

Core API Logic

The project's internal logic for setting a MAC address involves complex state management, particularly for Wi-Fi adapters which require power cycling to accept new addresses on certain platforms.

MAC Set Sequence (macOS/Wi-Fi)

The sequence diagram below demonstrates the library's internal handling of the --wifi flag on macOS.

Hardware Discovery Architecture

Interface discovery is handled by platform-specific parsers. On Windows, the tool merges data from ipconfig /all with the getmac utility to identify "Connection Names" that match the human-readable labels used in the CLI.

Sources: src/index.ts:285-350, src/index.ts:450-515

Development Workflow

The project uses tsup for bundling and vitest for testing.

yarn install    # Install dependencies
yarn build      # Build ESM JS and declarations
yarn test       # Run linting and unit tests
yarn start      # Run the local CLI build

Sources: CLAUDE.md:15-35, package.json:75-85

Summary

The spoof tool provides a unified interface for MAC address management by abstracting the disparate network stacks of macOS, Linux, and Windows. By combining interactive scripts for quick starts with a robust TypeScript API for automation, it serves both end-users looking for privacy and developers requiring programmatic network control.

Sources: README.md:215-225, CLAUDE.md:3-10