OUI JSON Database

Relevant source files

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

• src/oui.ts
• scripts/update-oui.ts
• src/cli.ts
• src/index.ts
• tsup.config.ts
• test/oui.test.ts

The OUI (Organizationally Unique Identifier) JSON Database is a core component of the spoof utility, providing a mapping between MAC address prefixes and their corresponding hardware vendors. This database enables the application to perform vendor lookups, fuzzy searches for manufacturers, and generate valid random MAC addresses tied to specific organizations.

The database is stored as a flat JSON file (src/data/oui.json) and is bundled with the application during the build process. It allows the CLI to provide descriptive information about network interfaces and supports advanced spoofing features like --vendor matching.

Sources: src/oui.ts:1-12, README.md:145-165

Database Architecture and Data Format

The database is structured as a simple JSON object where keys are OUI prefixes in uppercase colon-separated format (e.g., "00:03:93") and values are the corresponding vendor names as strings.

Data Schema

Field	Type	Description	Example
Key (OUI Prefix)	string	First 3 bytes of a MAC address in XX:XX:XX format	"00:1B:21"
Value (Vendor)	string	The registered name of the manufacturer	"Intel Corporate"

Sources: src/oui.ts:10-12, scripts/update-oui.ts:153-157

Build Integration

The database is managed as a source asset in src/data/ but must be available to the compiled JavaScript in the dist/ directory. The build configuration handles this migration automatically.

The diagram shows the build-time movement of the database file from source to distribution directories.

Sources: tsup.config.ts:15-23

Maintenance and Updates

The project includes a dedicated script to synchronize the local database with the official IEEE OUI registry. This is executed via the yarn update-oui command.

Update Workflow

1. Download: The script fetches the latest oui.csv from https://standards-oui.ieee.org/oui/oui.csv.
2. Parsing: It extracts the OUI (Assignment) and Organization Name fields, converting them into the standard colon format.
3. Filtering: To maintain performance and small bundle size, the script applies a filtering logic:
   • Prioritizes "Top Vendors" (e.g., Apple, Samsung, Intel).
   • Sorts remaining vendors by frequency.
   • Limits the total entries to approximately 2000 prefixes.
4. Serialization: The final map is sorted by prefix for consistency and written to src/data/oui.json.

This flowchart illustrates the logic contained within the update script to refresh vendor data.

Sources: scripts/update-oui.ts:12-164, CLAUDE.md:31

Core Logic and API

The src/oui.ts module provides the logic layer for interacting with the database. It exports several functions for lookup, search, and randomization.

Vendor Lookup and Normalization

Before a lookup occurs, the input MAC address is normalized using regex patterns to ensure it matches the database's XX:XX:XX format. It supports standard, Cisco (XXXX.XXXX.XXXX), and no-separator (XXXXXXXXXXXX) formats.

function normalizePrefix(mac: string): string | undefined {
  const input = mac.trim().toUpperCase()
  // Matches 00:11:22, 00-11-22, etc.
  let match = MAC_PATTERNS.COLON_OR_DASH.exec(input)
  if (match) return `${match[1]}:${match[2]}:${match[3]}`
  // ... (additional format handling)
}

Sources: src/oui.ts:37-67

Fuzzy Search Algorithm

For the spoof vendors <query> command, the system uses Levenshtein distance to allow for typo tolerance when searching manufacturer names. Matches are scored based on:

• Exact matches (Score: 100)
• Starts with query (Score: 80)
• Word inclusion (Score: 60)
• Fuzzy match (typo tolerance for words >= 3 chars)

Sources: src/oui.ts:81-155

API Reference

Function	Return Type	Description
lookup(mac)	VendorInfo | null	Returns vendor name and prefix for a given MAC.
searchVendors(query, limit)	VendorInfo[]	Returns a list of vendors matching the query, sorted by relevance.
randomizeAsVendor(query)	string	Generates a random MAC using a prefix from a matching vendor.
getDatabaseStats()	object	Returns total prefix count and unique vendor count.

Sources: src/oui.ts:110-235, src/index.ts:1010-1025

CLI Implementation

The CLI leverages the OUI database through three primary commands: lookup, vendors, and randomize (with the --vendor flag).

Vendor Randomization Flow

When a user requests randomization for a specific vendor, the system must bridge the CLI input with the JSON database.

Conclusion

The OUI JSON Database provides the necessary metadata to transform raw MAC addresses into human-readable manufacturer information. By combining a filtered local dataset with fuzzy search logic and a secure update script, the system maintains a balance between technical accuracy and user convenience.

Sources: src/oui.ts:1-10, scripts/update-oui.ts:172-185