Updating OUI Data

Relevant source files

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

• scripts/update-oui.ts
• package.json
• src/oui.ts
• tsup.config.ts
• CLAUDE.md

The "Updating OUI Data" process is a maintenance subsystem within the spoof project designed to refresh the internal Organizationally Unique Identifier (OUI) database. This database provides the mapping between MAC address prefixes and hardware vendors, enabling features such as vendor lookup, vendor-specific MAC randomization, and fuzzy searching of manufacturer names.

The system automates the retrieval of the official IEEE OUI registry, parses the raw data into a structured JSON format, and optimizes the dataset for application performance by filtering and sorting entries.

Sources: scripts/update-oui.ts:1-12, src/oui.ts:1-10, CLAUDE.md:76-77

Data Update Workflow

The update process is primarily handled by a dedicated TypeScript script located at scripts/update-oui.ts. This script follows a linear execution path from remote data ingestion to local file persistence.

Core Components and Logic

1. Data Retrieval

The system fetches the most recent OUI registry directly from IEEE standards servers.

Element	Description
Source URL	https://standards-oui.ieee.org/oui/oui.csv
Download Function	downloadOUI()
Response Format	Raw CSV text

Sources: scripts/update-oui.ts:123-134

2. Parsing and Normalization

The parseCSV function processes the raw text. It identifies the OUI (Assignment) and Organization Name columns. It normalizes the 6-character hex string into a standard colon-separated uppercase format (e.g., 001122 becomes 00:11:22).

// scripts/update-oui.ts:153-154
const prefix = `${oui.slice(0, 2)}:${oui.slice(2, 4)}:${oui.slice(4, 6)}`
entries.set(prefix, vendor)

Sources: scripts/update-oui.ts:136-159

3. Filtering and Optimization

To keep the package size manageable, the script implements a two-pass filtering strategy via filterTopVendors.

• Pass 1 (Priority): It includes all prefixes belonging to a predefined list of TOP_VENDORS (e.g., Apple, Samsung, Intel, Cisco).
• Pass 2 (Frequency): It fills the remaining slots (up to a default limit of 2,000 entries) with vendors that appear most frequently in the full IEEE registry.

Sources: scripts/update-oui.ts:16-118, scripts/update-oui.ts:161-191

Execution and Deployment

The update process is integrated into the project's standard task runner and build pipeline.

Command Execution

Developers trigger the update via Yarn.

Environment	Command	Action
Development	yarn update-oui	Runs tsx scripts/update-oui.ts
CI/Build	yarn build	Invokes tsup which copies the JSON to dist

Sources: package.json:96, CLAUDE.md:36

Build Artifact Integration

The tsup.config.ts ensures that the updated data is available to the compiled application. Upon a successful build, the onSuccess hook copies the generated JSON file from the source directory to the distribution directory.

Conclusion

The OUI data update mechanism is a critical utility for maintaining the accuracy of vendor identification within the spoof tool. By combining automated IEEE registry fetching with intelligent filtering of top manufacturers, the project maintains a high-quality vendor database while keeping the final package lightweight. This updated data is subsequently utilized by the src/oui.ts module to perform real-time lookups and generate vendor-compliant random MAC addresses.

Sources: src/oui.ts:13-15, CLAUDE.md:61-68