High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The spoof project is a cross-platform Node.js utility designed to simplify the process of viewing and modifying Media Access Control (MAC) addresses on macOS, Linux, and Windows systems. It is written in TypeScript and targetting Node.js version 24 or higher, utilizing a modular architecture that separates command-line processing, core library logic, and vendor database management.
Sources: package.json:2-6, CLAUDE.md:7-9
System Overview
The architecture is divided into three primary layers: the Command Line Interface (CLI), the Core API Library, and the OUI (Organizationally Unique Identifier) Module. The CLI handles user input and output formatting, the Core API interacts with the underlying operating system to query and modify network interfaces, and the OUI module provides fuzzy-search capabilities and random MAC generation based on a bundled vendor database.
The diagram above illustrates the hierarchical relationship between the system components and their interaction with platform-specific OS tools.
Sources: CLAUDE.md:46-72, src/index.ts:79-84
Core API Component
The Core API, located in src/index.ts, acts as the engine of the project. It provides both synchronous (deprecated) and asynchronous methods for interacting with network hardware. The library detects the current operating system via process.platform and executes specific command sequences to manipulate interfaces.
Platform-Specific Implementations
| Platform | Tools Used | Method of MAC Modification |
|---|---|---|
| macOS (darwin) | networksetup, ifconfig, airport | Power cycles hardware via networksetup before applying ifconfig ether. |
| Linux | ip (iproute2), ifconfig | Brings interface down, sets address, and brings interface up. |
| Windows (win32) | winreg, netsh, getmac | Modifies the NetworkAddress registry key and restarts the adapter via netsh. |
Sources: src/index.ts:40-42, src/index.ts:168-185, src/index.ts:608-620, CLAUDE.md:79-84
Data Models
The system uses standardized TypeScript interfaces to ensure consistency across different operating system outputs.
export interface NetworkInterface {
port: string
device: string
address: string | null
currentAddress: string | null
description?: string
}
Sources: src/index.ts:7-14, src/types.ts
OUI Module & Vendor Database
The OUI module (src/oui.ts) manages a database of MAC address prefixes assigned by the IEEE. This module allows the CLI to provide human-readable vendor names (e.g., "Apple, Inc.") from a MAC address and supports generating random addresses that appear to belong to specific manufacturers.
Logic Flow: Vendor Randomization
When a user requests a random MAC for a specific vendor, the system performs a fuzzy search using Levenshtein distance to find the best matching OUI prefix.
The sequence diagram demonstrates the flow from a user query to the final application of a vendor-specific MAC address.
Sources: src/oui.ts:109-158, src/cli.ts:250-275
CLI Entry Point
The CLI (src/cli.ts) uses minimist for argument parsing and chalk for colorized terminal output. It supports a structured JSON output mode via the --format=json flag, allowing the tool to be integrated into larger automation pipelines.
Primary Commands
list(aliasls): Discovers and displays network interfaces.set <mac> <devices...>: Manually assigns a MAC address.randomize <devices...>: Assigns a random MAC, optionally filtered by--vendoror--local.reset <devices...>: Reverts an interface to its burned-in hardware MAC address.lookup <mac>: Queries the vendor database for a specific address.
Sources: src/cli.ts:121-144, CLAUDE.md:58-64, README.md:120-195
Build and Deployment Architecture
The project employs a modern TypeScript build pipeline. Source code in src/ is bundled into ECMAScript Modules (ESM) using tsup, targeting the dist/ directory.
Build Workflow
- Transpilation:
tsupcompiles TypeScript to ESM. - Type Generation:
tsc --emitDeclarationOnlycreates.d.tsfiles. - Data Sync: The
oui.jsondatabase is copied to thedist/data/directory during the build. - Installer: A standalone shell script (
scripts/mac-randomize.sh) provides an interactive wrapper for macOS users to clone, build, and run the utility in one step.
Sources: package.json:69, CLAUDE.md:74-77, scripts/mac-randomize.sh:90-115
Conclusion
The spoof architecture is designed for extensibility and platform independence. By isolating OS-specific execution commands within a dedicated library layer and providing a rich OUI vendor database, it offers a robust toolset for network hardware management while maintaining a simplified interface for the end-user.