OUI Vendor Lookup & Search

Relevant source files

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

• src/oui.ts
• src/cli.ts
• scripts/update-oui.ts
• src/index.ts
• test/oui.test.ts
• package.json

The OUI Vendor Lookup & Search system is a core component of the spoof utility designed to manage and query the Organizationally Unique Identifier (OUI) database. Its primary purpose is to provide mapping between MAC addresses and their respective hardware manufacturers (vendors). This system enables users to identify the manufacturer of a specific network interface and allows the CLI to generate random MAC addresses that appear to belong to specific vendors.

Sources: src/oui.ts:1-5, CLAUDE.md:73-82

The system consists of a pre-compiled JSON database, a lookup engine supporting fuzzy search, and a maintenance script that synchronizes local data with official IEEE standards.

Sources: scripts/update-oui.ts:1-10, src/oui.ts:12-13

Architecture and Data Flow

The OUI module acts as a standalone service within the project, consumed primarily by the CLI and the main library entry point. It relies on a static data file oui.json which is generated during development or maintenance tasks.

OUI Database Lifecycle

The following diagram illustrates how OUI data moves from the IEEE registry to the end-user CLI output.

The update process downloads data from https://standards-oui.ieee.org/oui/oui.csv and filters it to a manageable size (default 2000 entries), prioritizing "Top Vendors" like Apple, Samsung, and Intel.

Sources: scripts/update-oui.ts:15-100, tsup.config.ts:19-27

Core Components

Data Structures

The system utilizes a central VendorInfo interface for all lookup and search results.

Field	Type	Description
vendor	string	The formal name of the manufacturer (e.g., "Apple, Inc.")
prefix	string	The 24-bit OUI prefix in XX:XX:XX format

Sources: src/oui.ts:18-23

Lookup Logic

The lookup process involves normalizing input strings—which may be full MAC addresses or partial prefixes in various formats—into a canonical XX:XX:XX format before querying the internal record.

Normalization supports standard (colon/dash), Cisco (dot), and no-separator formats.
Sources: src/oui.ts:34-64, src/oui.ts:98-112

Search and Fuzzy Matching

The searchVendors function implements a scoring system to find manufacturers even with partial queries or typographical errors.

Scoring Algorithm

Matches are ranked based on the following priority:

1. Exact Match (Score 100): The vendor name exactly matches the query.
2. Starts With (Score 80): The vendor name begins with the query string.
3. Word Match (Score 60): The query exists as a distinct word within the vendor name.
4. Contains (Score 40): The query is a substring.
5. Fuzzy Match (Score up to 20): Calculated using Levenshtein distance for typo tolerance.

Sources: src/oui.ts:121-164

Levenshtein Distance Implementation

The fuzzy search utilizes a matrix-based Levenshtein distance calculation to determine the edit distance between words.

function levenshteinDistance(a, b) {
  const matrix = []
  // ... matrix initialization and calculation
  return matrix[b.length][a.length]
}

Sources: src/oui.ts:70-92

Randomization by Vendor

A key feature of the module is the ability to generate valid MAC addresses for a specific manufacturer.

Function	Description
randomizeAsVendor(query)	Returns a random MAC string for a vendor matching the query.
randomizeAsVendorWithInfo(query)	Returns the MAC string along with the specific vendor name and prefix used.

Logic Flow:

1. Search the database for vendors matching the query.
2. Randomly select one vendor from the top 100 matches.
3. Extract the OUI prefix (first 3 bytes).
4. Generate 3 random bytes for the suffix using node:crypto.
5. Apply the localAdmin bit if requested (setting the second least significant bit of the first byte).

Sources: src/oui.ts:208-250

CLI Integration

The CLI provides three primary commands to interact with this module:

1. lookup <mac>: Invokes oui.lookup() to identify a vendor.
2. vendors [<query>]: Invokes oui.searchVendors() or oui.getDatabaseStats() if no query is provided.
3. randomize --vendor=<name>: Uses oui.randomizeAsVendorWithInfo() to spoof a specific manufacturer.

Summary

The OUI Vendor Lookup & Search module provides the intelligence layer for the spoof utility. By maintaining a filtered subset of the IEEE OUI registry and providing robust search mechanisms—including Levenshtein-based fuzzy matching—it allows the project to bridge the gap between raw hardware addresses and human-readable manufacturer identities. This facilitates both informative network discovery and sophisticated MAC spoofing capabilities.