OUI Data Access & Search API
Relevant source files
The following files were used as context for generating this wiki page:
The OUI (Organizationally Unique Identifier) Data Access & Search API is a specialized module within the spoof project designed to handle vendor identification based on MAC addresses. It provides a comprehensive suite of utilities for looking up manufacturers, performing fuzzy searches on vendor names, and generating randomized MAC addresses that adhere to specific vendor prefixes. Sources: src/oui.ts:1-5, CLAUDE.md:65-72
This API serves as the backbone for features requiring hardware manufacturer context, enabling the CLI to provide descriptive information about network interfaces and allowing users to "spoof" their identity as specific hardware brands (e.g., Apple, Samsung, Intel). Sources: src/cli.ts:470-520, README.md:144-165
Database Architecture and Lifecycle
The OUI system relies on a pre-compiled JSON database derived from official IEEE registry data. The lifecycle involves downloading raw CSV data, filtering for common vendors, and bundling the resulting JSON into the application. Sources: scripts/update-oui.ts:15-20, tsup.config.ts:16-24
Data Acquisition and Filtering
The database is maintained via a dedicated script that fetches the IEEE OUI CSV, parses assignments, and normalizes them into a colon-separated prefix format (e.g., 00:11:22). To optimize performance and bundle size, the project utilizes a "Top Vendors" list to prioritize the most common device manufacturers while limiting the total entry count to 2,000. Sources: scripts/update-oui.ts:114-150, scripts/update-oui.ts:22-101
The diagram above illustrates the data pipeline from IEEE source to the distributed JSON database.
Sources: scripts/update-oui.ts:103-145, tsup.config.ts:16-24
Data Structures
The core data structure is a simple key-value record where the key is the OUI prefix and the value is the organization name. Sources: src/oui.ts:11
| Property | Type | Description |
|---|---|---|
vendor | string | The manufacturer name (e.g., "Apple, Inc.") |
prefix | string | The 3-byte OUI prefix in XX:XX:XX format |
Sources: src/oui.ts:14-20
Search Logic and Fuzzy Matching
The API implements a scoring-based search algorithm to handle vendor name queries, incorporating exact matches, prefix matches, and fuzzy matching for typo tolerance. Sources: src/oui.ts:104-163
Levenshtein Distance Matching
For typo tolerance, the API uses the Levenshtein distance algorithm. It calculates the minimum number of single-character edits required to change one word into another, allowing for matches even when queries contain minor spelling errors. Sources: src/oui.ts:64-88, test/oui.test.ts:115-135
The logic flow for scoring vendor search results to ensure the most relevant manufacturers appear first.
Sources: src/oui.ts:104-163
Search scoring thresholds:
- 100: Exact string match.
- 80: Vendor name starts with the query.
- 60: Query matches a full word within the vendor name.
- 40: Query is contained anywhere in the vendor name.
- 20 - distance: Fuzzy match based on word-level edit distance (threshold of 1-2 characters).
Sources: src/oui.ts:119-151
Vendor-Based Randomization
One of the primary uses of the OUI API is the generation of randomized MAC addresses that identify as a specific hardware vendor. Sources: src/oui.ts:199-239
Randomization Process
- Search: Find vendors matching the provided query.
- Selection: Pick one matching vendor/prefix at random using
crypto.randomInt. - Suffix Generation: Generate the final 3 bytes of the MAC address randomly.
- Local Admin Bit: Optionally set the second least significant bit of the first byte if
localAdminis requested.
Sources: src/oui.ts:213-239
Sequence of operations for generating a vendor-specific MAC address.
Sources: src/oui.ts:213-239
API Reference
Core Functions
| Function | Parameters | Returns | Description |
|---|---|---|---|
lookup(mac) | mac: string | VendorInfo | null | Returns vendor name for a full MAC or prefix. |
searchVendors(query, limit?) | query: string, limit: number | VendorInfo[] | Fuzzy searches the database for manufacturers. |
randomizeAsVendor(query, local?) | query: string, local: boolean | string | Generates a MAC for a matching vendor. |
getDatabaseStats() | None | {totalPrefixes, uniqueVendors} | Returns metadata about the loaded database. |
Sources: src/oui.ts:94-205, src/index.ts:1141-1150
MAC Normalization
The API includes a normalizePrefix internal utility (exposed via normalize in the main index) that handles three distinct MAC formats:
- Standard:
00:11:22or00-11-22 - Cisco:
0011.2233.4455 - No Separator:
001122
Sources: src/oui.ts:28-62
Summary
The OUI Data Access & Search API provides a robust layer for hardware identification within the spoof utility. By combining a filtered IEEE dataset with sophisticated fuzzy matching and cryptographic randomization, it enables users to perform manufacturer-aware network operations across macOS, Linux, and Windows. Sources: src/oui.ts:1-5, CLAUDE.md:65-72, README.md:144-165