GitNexus Code Intelligence
Relevant source files
The following files were used as context for generating this wiki page:
GitNexus Code Intelligence for the spoof project provides a structured framework for understanding, navigating, and safely modifying the codebase. It indexes symbols, relationships, and execution flows to assist developers in impact analysis and debugging. The project itself is a Node.js CLI tool designed to change MAC addresses across macOS, Linux, and Windows platforms.
Within this ecosystem, "Code Intelligence" refers to the semantic understanding of the TypeScript rewrite, which utilizes a library-first architecture with a separate CLI entry point. This system ensures that cross-platform hardware interactions (via ifconfig, ip, networksetup, and Windows Registry) are mapped and analyzed for risk before any changes are committed.
Sources: CLAUDE.md:1-12, CLAUDE.md:110-125, README.md:1-15
Core Architecture and Modules
The project is structured into three primary functional areas: the core library API, the OUI (Organizationally Unique Identifier) database module, and the CLI interface.
Library API (src/index.ts)
The core library exposes both asynchronous (primary) and synchronous (deprecated) APIs for hardware interaction. It handles platform detection and executes system-specific commands to query or modify network interfaces.
- Primary Functions:
findInterfacesAsync(),findInterfaceAsync(),setInterfaceMACAsync(),getInterfaceMACAsync(). - Platform Branching: Uses
process.platformto select betweendarwin(macOS),linux, andwin32.
Sources: CLAUDE.md:65-71, src/index.ts:133-145, src/index.ts:474-486
OUI Database Module (src/oui.ts)
This module manages the Organizationally Unique Identifier database, allowing for vendor lookups and randomized MAC generation based on specific manufacturers.
- Key Functions:
lookup(mac),searchVendors(query),randomizeAsVendor(vendorQuery). - Data Source: Loaded from
src/data/oui.json.
Sources: CLAUDE.md:79-85, src/oui.ts:1-15
CLI Interface (src/cli.ts)
The command-line interface parses user arguments using minimist and maps them to library functions. It supports structured JSON output and dry-run modes.
Sources: CLAUDE.md:73-77, src/cli.ts:1-50
System Execution Flows
The following diagram illustrates the high-level flow of a MAC spoofing request from the CLI to the underlying system hardware commands.
The flow shows how spoof abstracts platform-specific complexities, such as the requirement to disassociate Wi-Fi on macOS before changing addresses.
Sources: src/index.ts:405-466, src/index.ts:748-775, src/index.ts:861-875
Data Structures and Configuration
The project utilizes specific TypeScript interfaces to maintain type safety across the library and CLI.
| Type | Description | File Reference |
|---|---|---|
NetworkInterface | Represents a hardware port, device name, and MAC addresses (hardware/current). | src/types.ts |
AsyncOptions | Configuration for timeouts and abort signals. | src/types.ts |
VendorInfo | Contains vendor name and OUI prefix. | src/oui.ts |
OperationResult | Structure used for CLI output reporting success or error of an operation. | src/cli.ts |
Sources: CLAUDE.md:87-88, src/oui.ts:17-23, src/cli.ts:42-49
Hardware Detection Logic
The system performs a multi-step sequence to identify interfaces, particularly on Linux where it attempts to use modern iproute2 tools before falling back to legacy net-tools.
GitNexus Operational Guidelines
GitNexus enforces strict "Always Do" and "Never Do" rules for maintaining the integrity of the spoof codebase.
- Impact Analysis: Developers MUST run
gitnexus_impactbefore editing any symbol. This is critical for functions likenormalize()which are used extensively across both the core library and the OUI module. - Change Detection: Running
gitnexus_detect_changes()is required before committing to verify the blast radius of changes to execution flows. - Refactoring: Symbols should never be renamed with find-and-replace;
gitnexus_renamemust be used to preserve the call graph.
Sources: CLAUDE.md:113-134
Summary
GitNexus Code Intelligence for spoof ensures that the transition between high-level CLI commands and low-level system operations is transparent and safe. By mapping the cross-platform branching logic and OUI database interactions, the system provides a robust environment for extending MAC spoofing capabilities while minimizing the risk of breaking hardware interface abstractions.
Sources: CLAUDE.md:110-112, README.md:143-145