Normalize MAC String (spoof normalize)

Relevant source files

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

• src/cli.ts
• src/index.ts
• src/oui.ts
• test/basic.test.ts
• test/cli.test.ts
• README.md

The Normalize MAC String feature is a core utility within the spoof project designed to transform various Media Access Control (MAC) address formats into a single, canonical representation. This functionality ensures consistency across the library's internal operations, such as comparing current addresses with hardware defaults or generating random addresses.

The system supports several common industry formats, including colon-separated, dash-separated, and Cisco-style dot notation. By converting these into a standard uppercase, colon-separated format (e.g., 00:11:22:33:44:55), the project maintains interoperability across different operating systems like macOS, Linux, and Windows, which often use different default display formats.

Sources: src/index.ts:25, README.md:143-149, test/basic.test.ts:12-24

Functional Architecture

The normalization logic is centralized in the core library and exposed via both a programmatic API and a Command Line Interface (CLI). It relies on regular expressions to identify and extract hex byte components from input strings.

Core Logic and Regex Engine

The normalization process utilizes two primary regular expressions to handle different input styles:

• MAC_ADDRESS_RE: A flexible, unanchored regex used for extracting MAC components from command-line tool outputs (like ifconfig or ip link).
• CISCO_MAC_ADDRESS_RE: Specifically handles the XXXX.XXXX.XXXX format.

Sources: src/index.ts:40-52, src/oui.ts:31-37

Logic Flow Diagram

The following diagram illustrates how the normalize function processes an input string to reach the canonical format.

The logic ensures that even inputs missing leading zeros (e.g., 0:1:2...) are correctly padded to the standard two-character hexadecimal representation.
Sources: src/index.ts:607-632, src/oui.ts:44-70

Programmatic Interface

The library exports a normalize(mac: string) function as part of its primary utility suite. This function is synchronous and performs no I/O, making it safe for use in high-performance contexts.

Supported Formats

Input Format	Example Input	Normalized Output
Colon-separated	00:03:93:12:34:56	00:03:93:12:34:56
Dash-separated	00-03-93-12-34-56	00:03:93:12:34:56
Cisco-style	0003.9312.3456	00:03:93:12:34:56
No separators	000393123456	00:03:93:12:34:56
Lowercase	aa:bb:cc:dd:ee:ff	AA:BB:CC:DD:EE:FF

Sources: README.md:143-149, test/cli.test.ts:80-117, test/basic.test.ts:12-24

Internal Implementation

function normalize(mac: string): string | undefined {
  let m = CISCO_MAC_ADDRESS_RE.exec(mac)
  if (m) {
    const halfwords = m.slice(1)
    mac = halfwords.map((halfword) => halfword.padStart(4, '0')).join('')
    return chunk(mac, 2).join(':').toUpperCase()
  }

  m = MAC_ADDRESS_RE.exec(mac)
  if (m) {
    const bytes = m.slice(1)
    return bytes.map(byte => byte.padStart(2, '0')).join(':').toUpperCase()
  }

  return undefined
}

Sources: src/index.ts:607-626

CLI Usage (spoof normalize)

The feature is exposed to users via the normalize command. This is useful for verifying how the tool interprets a specific address before applying it to a network interface.

Command Execution Sequence

CLI Options

The normalization command supports global flags that modify the output format:

• --format=json: Emits structured JSON output, which includes the original input and the normalized result.
• --verbose, -v: Displays detailed diagnostic information, such as the step-by-step processing of the address.

Sources: src/cli.ts:40-60, src/cli.ts:246-254

Technical Constraints and Validation

The normalization system distinguishes between Extraction and Validation. While normalize() is permissive to help parse messy command output, the library uses a stricter anchored regex, MAC_VALIDATION_RE, when a user attempts to set a MAC address.

Component	Regex Pattern	Purpose
Extraction	([0-9A-F]{1,2})[:-]?...	Finds MAC patterns within larger strings or tool outputs.
Cisco	^([0-9A-F]{1,4})\.([0-9A-F]{1,4})\.([0-9A-F]{1,4})$	Specifically targets dot-notated addresses.
Validation	^([0-9A-F]{1,2})[:-](https://github.com/Enflame-Media-LLC/MACquerade/blob/19dae060f94439c2bbd905f966df61ef8a658d49/%5B0-9A-F%5D%7B1%2C2%7D)...$	Strict check for full 6-byte strings before system changes.

Sources: src/index.ts:43-52, src/index.ts:503-510

Conclusion

The MAC normalization feature in spoof provides a critical layer of abstraction between diverse OS-specific network tools and the unified CLI experience. By centralizing this logic in src/index.ts and src/oui.ts, the project ensures that whether a user provides a Cisco-style address or a raw hex string, the underlying system always operates on a consistent, valid, and uppercase canonical format.