List Network Interfaces (spoof list)

Relevant source files

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

• src/cli.ts
• src/index.ts
• src/types.ts
• test/findInterfaces.test.ts
• README.md

Introduction

The list command (aliased as ls) is a core feature of the spoof utility designed to discover and display network interfaces available on the host system. It provides detailed information including the hardware port name, the device identifier, the permanent hardware MAC address, and the currently active (potentially spoofed) MAC address.

This module serves as the discovery phase for all other operations in the project, such as spoof set or spoof randomize, by identifying which devices are available for modification. It abstracts platform-specific complexities across macOS, Linux, and Windows into a unified data structure.

Sources: src/cli.ts:133, README.md:105-115

Architecture and Data Flow

The interface listing process follows a multi-layered approach, starting from the CLI entry point, moving through an abstraction layer in the library, and finally executing platform-specific system commands.

Logical Flow

The following diagram illustrates the sequence from a user's command to the retrieval of system network data.

Interface Discovery Logic

The system uses different strategies to identify hardware depending on the underlying Operating System.

Platform-Specific Commands

Platform	Primary Discovery Command	Fallback / Detail Command
macOS	networksetup -listallhardwareports	ifconfig [device]
Linux	ip link show (modern)	ifconfig (legacy)
Windows	ipconfig /all	getmac /v /fo csv

Sources: src/index.ts:124, src/index.ts:178, src/index.ts:316, test/findInterfaces.test.ts:314-325

Data Structures

All discovered interfaces are mapped to a standard NetworkInterface interface to ensure consistency across the application.

export interface NetworkInterface {
  port: string           // e.g., "Wi-Fi", "Ethernet"
  device: string         // e.g., "en0", "eth0"
  address: string | null // Hardware MAC address
  currentAddress: string | null // Active MAC address
  description?: string   // Windows-specific adapter info
}

Sources: src/types.ts:9-21

Filtering and Configuration

The listing behavior can be modified using CLI flags or library options.

Wi-Fi Filtering

When the --wifi flag is passed, the CLI passes "wi-fi" as a target to the discovery functions. On Linux, the system identifies wireless interfaces by checking if device names start with wl or wlan. On macOS, it matches the "Hardware Port" string against "Wi-Fi".

JSON Output

For automation, the --format=json flag enables structured output. This output includes a spoofed boolean flag, calculated by comparing the address (hardware) and currentAddress (active).

{
  "success": true,
  "interfaces": [
    {
      "port": "Wi-Fi",
      "device": "en1",
      "address": "AA:BB:CC:DD:EE:FF",
      "currentAddress": "00:11:22:33:44:55",
      "spoofed": true
    }
  ],
  "platform": "darwin",
  "version": "2.0.4"
}

Sources: src/cli.ts:423-431, src/cli.ts:119-126

Implementation Details

The core logic resides in src/index.ts. The project has transitioned to an asynchronous API, though synchronous versions are maintained for backward compatibility with deprecation warnings.

• findInterfacesAsync(targets, options): The primary entry point for interface discovery.
• normalize(mac): A utility used during discovery to ensure all MAC addresses are in the canonical XX:XX:XX:XX:XX:XX uppercase format.
• getIpCommandAvailableAsync(): A Linux-specific check to determine if the modern iproute2 suite is available before falling back to legacy net-tools.

Sources: src/index.ts:497, src/index.ts:457-484, src/index.ts:488

Conclusion

The "List Network Interfaces" feature is a cross-platform hardware abstraction layer. By combining high-level system profiling commands with low-level interface queries, it provides a reliable inventory of network hardware, enabling users to identify targets for MAC address spoofing safely and accurately across macOS, Linux, and Windows environments.