spoof-d 0.1.0 → 0.3.0

package/.spoofyrc.example

@@ -0,0 +1,10 @@
+{
+  "randomize": {
+    "local": false
+  },
+  "defaults": {
+    "verbose": false,
+    "json": false
+  }
+}
+

package/README.md

@@ -50,6 +50,15 @@ This repository ([TT5H/spoof-d](https://github.com/TT5H/spoof-d)) is a fork of [
 - **Linux**: Modern ip link commands with ifconfig fallback
 - **Unified API** across all platforms
 
+### User Experience Features
+- **Progress indicators** with animated spinners for long-running operations
+- **Verbose mode** (`--verbose`) for detailed debugging output
+- **JSON output** (`--json`) for scripting and automation
+- **Configuration file** support (`.spoofyrc` in home directory)
+- **MAC address vendor lookup** using OUI database
+- **Change history tracking** with ability to view and revert changes
+- **Batch operations** for changing multiple interfaces at once
+
 ## Installation
 
 ### From npm (recommended)
@@ -159,6 +168,143 @@ sudo spoofy reset wi-fi
 
 **Note**: On macOS, restarting your computer will also reset your MAC address to the original hardware address.
 
+### Show detailed interface information
+
+```bash
+spoofy info en0
+```
+
+Shows detailed information about an interface including hardware MAC, current MAC, vendor information, and change history.
+
+### Validate MAC address format
+
+```bash
+spoofy validate 00:11:22:33:44:55
+```
+
+Validates and normalizes a MAC address, showing vendor information if available.
+
+### Look up vendor from MAC address
+
+```bash
+spoofy vendor 00:11:22:33:44:55
+```
+
+Looks up the vendor/manufacturer of a MAC address using the OUI database.
+
+### Batch operations
+
+Create a batch file (e.g., `batch.json`):
+
+```json
+[
+  {
+    "type": "randomize",
+    "device": "en0",
+    "local": true
+  },
+  {
+    "type": "set",
+    "device": "eth0",
+    "mac": "00:11:22:33:44:55"
+  },
+  {
+    "type": "reset",
+    "device": "wlan0"
+  }
+]
+```
+
+Then run:
+
+```bash
+sudo spoofy batch batch.json
+```
+
+### View change history
+
+```bash
+spoofy history
+```
+
+View all MAC address changes, or filter by device:
+
+```bash
+spoofy history en0
+```
+
+## Advanced Usage
+
+### Verbose Mode
+
+Get detailed debugging information:
+
+```bash
+spoofy list --verbose
+spoofy randomize en0 --verbose
+```
+
+### JSON Output
+
+Output results in JSON format for scripting:
+
+```bash
+spoofy list --json
+spoofy randomize en0 --json
+```
+
+Example JSON output:
+```json
+{
+  "success": true,
+  "device": "en0",
+  "mac": "00:11:22:33:44:55",
+  "message": "MAC address changed successfully"
+}
+```
+
+### Configuration File
+
+Create a configuration file at `~/.spoofyrc` (or `%USERPROFILE%\.spoofyrc` on Windows):
+
+```json
+{
+  "randomize": {
+    "local": true
+  },
+  "defaults": {
+    "verbose": false,
+    "json": false
+  }
+}
+```
+
+The configuration file allows you to set default options that will be used automatically.
+
+### Change History
+
+All MAC address changes are automatically logged to `~/.spoofy_history.json`. You can:
+
+- View history: `spoofy history`
+- View history for specific device: `spoofy history en0`
+- History includes timestamp, device, old MAC, new MAC, and operation type
+
+### Vendor Lookup
+
+The tool includes an OUI (Organizationally Unique Identifier) database to identify device vendors:
+
+- Automatically shown in `spoofy list` output
+- Available via `spoofy vendor <mac>` command
+- Helps identify device types and manufacturers
+
+### Progress Indicators
+
+Long-running operations show progress indicators:
+
+```bash
+⏳ Changing MAC address... ✓ Successfully set MAC address
+```
+
 ## Platform Support
 
 ### macOS ✅

package/batch.example.json

@@ -0,0 +1,16 @@
+[
+  {
+    "type": "randomize",
+    "device": "en0",
+    "local": true
+  },
+  {
+    "type": "set",
+    "device": "eth0",
+    "mac": "00:11:22:33:44:55"
+  },
+  {
+    "type": "reset",
+    "device": "wlan0"
+  }
+]

package/bin/cmd.js

@@ -5,15 +5,105 @@ const minimist = require("minimist");
 const spoof = require("../");
 const { stripIndent } = require("common-tags");
 const cp = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const ora = require("ora");
+const history = require("../lib/history");
+const oui = require("../lib/oui");
 
 const argv = minimist(process.argv.slice(2), {
   alias: {
     v: "version",
+    V: "verbose",
+    j: "json",
   },
-  boolean: ["version"],
+  boolean: ["version", "verbose", "json"],
 });
 const cmd = argv._[0];
 
+// Global flags
+const VERBOSE = argv.verbose || false;
+const JSON_OUTPUT = argv.json || false;
+
+// Configuration file support
+let config = null;
+const configPath = path.join(os.homedir(), ".spoofyrc");
+if (fs.existsSync(configPath)) {
+  try {
+    const configContent = fs.readFileSync(configPath, "utf8");
+    config = JSON.parse(configContent);
+    if (VERBOSE) {
+      logVerbose(`Loaded configuration from ${configPath}`);
+    }
+  } catch (err) {
+    if (VERBOSE) {
+      logVerbose(`Failed to load config: ${err.message}`);
+    }
+  }
+}
+
+// Helper functions
+function logVerbose(message) {
+  if (VERBOSE && !JSON_OUTPUT) {
+    console.error(chalk.gray(`[VERBOSE] ${message}`));
+  }
+}
+
+function outputJSON(data) {
+  if (JSON_OUTPUT) {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+let currentSpinner = null;
+
+function showProgress(message) {
+  if (JSON_OUTPUT) return;
+  if (currentSpinner) {
+    currentSpinner.text = message;
+  } else {
+    currentSpinner = ora(message).start();
+  }
+}
+
+function hideProgress() {
+  if (JSON_OUTPUT) return;
+  if (currentSpinner) {
+    currentSpinner.stop();
+    currentSpinner = null;
+  }
+}
+
+function successProgress(message) {
+  if (JSON_OUTPUT) return;
+  if (currentSpinner) {
+    currentSpinner.succeed(message);
+    currentSpinner = null;
+  }
+}
+
+function failProgress(message) {
+  if (JSON_OUTPUT) return;
+  if (currentSpinner) {
+    currentSpinner.fail(message);
+    currentSpinner = null;
+  }
+}
+
+function progressStep(step, total, message) {
+  if (JSON_OUTPUT) return;
+  const percentage = Math.round((step / total) * 100);
+  if (currentSpinner) {
+    currentSpinner.text = `[${step}/${total}] ${percentage}% - ${message}`;
+  } else {
+    currentSpinner = ora(`[${step}/${total}] ${percentage}% - ${message}`).start();
+  }
+  if (step === total) {
+    currentSpinner = null;
+  }
+}
+
 try {
   init();
 } catch (err) {
@@ -78,6 +168,20 @@ function init() {
   } else if (cmd === "normalize") {
     const mac = argv._[1];
     normalize(mac);
+  } else if (cmd === "info") {
+    const device = argv._[1];
+    info(device);
+  } else if (cmd === "validate") {
+    const mac = argv._[1];
+    validate(mac);
+  } else if (cmd === "vendor") {
+    const mac = argv._[1];
+    vendor(mac);
+  } else if (cmd === "batch") {
+    const file = argv._[1];
+    batch(file);
+  } else if (cmd === "history") {
+    historyCmd();
   } else {
     help();
   }
@@ -114,9 +218,23 @@ ${example}${note}
       spoofy help                              Shows this help message.
       spoofy version | --version | -v          Show package version.
 
+    Commands:
+      list [--wifi]                     List available devices.
+      set <mac> <devices>...            Set device MAC address.
+      randomize [--local] <devices>...  Set device MAC address randomly.
+      reset <devices>...                Reset device MAC address to default.
+      normalize <mac>                   Normalize a MAC address format.
+      info <device>                     Show detailed interface information.
+      validate <mac>                    Validate MAC address format.
+      vendor <mac>                      Look up vendor from MAC address.
+      batch <file>                      Change multiple interfaces from config file.
+      history                            View MAC address change history.
+
     Options:
       --wifi          Try to only show wireless interfaces.
       --local         Set the locally administered flag on randomized MACs.
+      --verbose, -V   Show verbose output for debugging.
+      --json, -j     Output results in JSON format.
 
     Platform Support:
       ✅ macOS (Sequoia 15.4+, Tahoe 26+)
@@ -127,7 +245,16 @@ ${example}${note}
 }
 
 function version() {
-  console.log(require("../package.json").version);
+  const pkg = require("../package.json");
+  if (JSON_OUTPUT) {
+    outputJSON({
+      version: pkg.version,
+      name: pkg.name,
+      description: pkg.description,
+    });
+  } else {
+    console.log(pkg.version);
+  }
 }
 
 function set(mac, devices) {
@@ -139,8 +266,14 @@ function set(mac, devices) {
     throw new Error("Device name is required. Usage: spoofy set <mac> <device>");
   }
   
-  devices.forEach((device) => {
+  logVerbose(`Setting MAC address ${mac} on ${devices.length} device(s)`);
+  
+  devices.forEach((device, index) => {
+    logVerbose(`Processing device ${index + 1}/${devices.length}: ${device}`);
+    showProgress(`Finding interface ${device}`);
+    
     const it = spoof.findInterface(device);
+    hideProgress();
 
     if (!it) {
       throw new Error(
@@ -149,6 +282,7 @@ function set(mac, devices) {
       );
     }
 
+    logVerbose(`Found interface: ${it.device} (port: ${it.port})`);
     setMACAddress(it.device, mac, it.port);
   });
 }
@@ -158,13 +292,34 @@ function normalize(mac) {
     throw new Error("MAC address is required. Usage: spoofy normalize <mac>");
   }
   
+  logVerbose(`Normalizing MAC address: ${mac}`);
+  
   try {
     const normalized = spoof.normalize(mac);
     if (!normalized) {
       throw new Error(`"${mac}" is not a valid MAC address`);
     }
-    console.log(normalized);
+    
+    if (JSON_OUTPUT) {
+      outputJSON({
+        original: mac,
+        normalized: normalized,
+        valid: true,
+      });
+    } else {
+      console.log(normalized);
+    }
+    
+    logVerbose(`Normalized: ${mac} -> ${normalized}`);
   } catch (err) {
+    if (JSON_OUTPUT) {
+      outputJSON({
+        original: mac,
+        normalized: null,
+        valid: false,
+        error: err.message,
+      });
+    }
     throw new Error(
       `Could not normalize MAC address "${mac}": ${err.message}`
     );
@@ -176,8 +331,15 @@ function randomize(devices) {
     throw new Error("Device name is required. Usage: spoofy randomize <device>");
   }
   
-  devices.forEach((device) => {
+  const useLocal = argv.local || (config && config.randomize && config.randomize.local);
+  logVerbose(`Randomizing MAC address (local: ${useLocal})`);
+  
+  devices.forEach((device, index) => {
+    logVerbose(`Processing device ${index + 1}/${devices.length}: ${device}`);
+    showProgress(`Finding interface ${device}`);
+    
     const it = spoof.findInterface(device);
+    hideProgress();
 
     if (!it) {
       throw new Error(
@@ -186,9 +348,16 @@ function randomize(devices) {
       );
     }
 
-    const mac = spoof.randomize(argv.local);
-    console.log(chalk.blue("ℹ"), `Generated random MAC address: ${chalk.bold.cyan(mac)}`);
-    setMACAddress(it.device, mac, it.port);
+    logVerbose(`Found interface: ${it.device} (port: ${it.port})`);
+    const mac = spoof.randomize(useLocal);
+    
+    if (JSON_OUTPUT) {
+      // Will be output in setMACAddress
+    } else {
+      console.log(chalk.blue("ℹ"), `Generated random MAC address: ${chalk.bold.cyan(mac)}`);
+    }
+    
+    setMACAddress(it.device, mac, it.port, "randomize");
   });
 }
 
@@ -197,8 +366,14 @@ function reset(devices) {
     throw new Error("Device name is required. Usage: spoofy reset <device>");
   }
   
-  devices.forEach((device) => {
+  logVerbose(`Resetting MAC address on ${devices.length} device(s)`);
+  
+  devices.forEach((device, index) => {
+    logVerbose(`Processing device ${index + 1}/${devices.length}: ${device}`);
+    showProgress(`Finding interface ${device}`);
+    
     const it = spoof.findInterface(device);
+    hideProgress();
 
     if (!it) {
       throw new Error(
@@ -214,12 +389,22 @@ function reset(devices) {
       );
     }
 
-    console.log(chalk.blue("ℹ"), `Resetting to hardware MAC address: ${chalk.bold.cyan(it.address)}`);
-    setMACAddress(it.device, it.address, it.port);
+    logVerbose(`Hardware MAC address: ${it.address}`);
+    
+    if (JSON_OUTPUT) {
+      // Will be output in setMACAddress
+    } else {
+      console.log(chalk.blue("ℹ"), `Resetting to hardware MAC address: ${chalk.bold.cyan(it.address)}`);
+    }
+    
+    setMACAddress(it.device, it.address, it.port, "reset");
   });
 }
 
 function list() {
+  logVerbose("Starting interface discovery...");
+  showProgress("Discovering network interfaces");
+  
   const targets = [];
   if (argv.wifi) {
     if (process.platform === "win32") {
@@ -230,6 +415,23 @@ function list() {
   }
 
   const interfaces = spoof.findInterfaces(targets);
+  hideProgress();
+  logVerbose(`Found ${interfaces.length} interface(s)`);
+
+  if (JSON_OUTPUT) {
+    outputJSON({
+      interfaces: interfaces.map((it) => ({
+        port: it.port || it.device,
+        device: it.device,
+        address: it.address,
+        currentAddress: it.currentAddress,
+        status: it.status,
+        description: it.description,
+      })),
+      count: interfaces.length,
+    });
+    return;
+  }
 
   if (interfaces.length === 0) {
     console.log(chalk.yellow("No network interfaces found."));
@@ -251,17 +453,31 @@ function list() {
     
     if (it.address) {
       line.push("with MAC address", chalk.bold.cyan(it.address));
+      const vendor = oui.lookupVendor(it.address);
+      if (vendor && vendor !== "Unknown") {
+        line.push(chalk.gray(`[${vendor}]`));
+      }
     }
     if (it.currentAddress && it.currentAddress !== it.address) {
       line.push("currently set to", chalk.bold.red(it.currentAddress));
+      const currentVendor = oui.lookupVendor(it.currentAddress);
+      if (currentVendor && currentVendor !== "Unknown") {
+        line.push(chalk.gray(`[${currentVendor}]`));
+      }
     }
     console.log(line.join(" "));
   });
 }
 
-function setMACAddress(device, mac, port) {
+function setMACAddress(device, mac, port, operation = "set") {
+  logVerbose(`Setting MAC address ${mac} on device ${device}`);
+  
+  // Get current MAC for history
+  const oldMac = spoof.getInterfaceMAC(device);
+  
   // Check for admin/root privileges
   if (process.platform === "win32") {
+    logVerbose("Checking for Administrator privileges...");
     // On Windows, check if running as administrator
     try {
       const output = cp
@@ -279,35 +495,355 @@ function setMACAddress(device, mac, port) {
           "Right-click Command Prompt or PowerShell and select 'Run as Administrator'"
         );
       }
+      logVerbose("Administrator privileges confirmed");
     } catch (err) {
       if (err.message.includes("Must run as Administrator")) {
         throw err;
       }
       // If check fails, warn but continue (might work anyway)
-      console.warn(chalk.yellow("Warning: Could not verify administrator privileges. Operation may fail."));
+      if (!JSON_OUTPUT) {
+        console.warn(chalk.yellow("Warning: Could not verify administrator privileges. Operation may fail."));
+      }
+      logVerbose("Could not verify privileges, continuing anyway");
     }
   } else if (process.platform !== "win32") {
+    logVerbose("Checking for root privileges...");
     // Unix-like systems (macOS, Linux)
     if (process.getuid && process.getuid() !== 0) {
       throw new Error(
         "Must run as root (or using sudo) to change network settings"
       );
     }
+    logVerbose("Root privileges confirmed");
   }
 
   try {
+    showProgress("Changing MAC address");
+    logVerbose(`Calling setInterfaceMAC(${device}, ${mac}, ${port})`);
+    
     spoof.setInterfaceMAC(device, mac, port);
-    console.log(
-      chalk.green("✓") +
-      " Successfully set MAC address to " +
-      chalk.bold.cyan(mac) +
-      " on " +
-      chalk.bold.green(device)
-    );
     
+    // Log to history
+    history.addHistoryEntry(device, oldMac, mac, operation);
+    
+    successProgress("MAC address changed successfully");
+    
+    if (JSON_OUTPUT) {
+      outputJSON({
+        success: true,
+        device: device,
+        mac: mac,
+        oldMac: oldMac,
+        message: "MAC address changed successfully",
+      });
+    } else {
+      console.log(
+        chalk.green("✓") +
+        " Successfully set MAC address to " +
+        chalk.bold.cyan(mac) +
+        " on " +
+        chalk.bold.green(device)
+      );
+    }
+    
+    logVerbose("MAC address change completed successfully");
     // Note: Verification is already done in setInterfaceMAC, so we don't need to do it again here
   } catch (err) {
+    failProgress("Failed to change MAC address");
+    if (JSON_OUTPUT) {
+      outputJSON({
+        success: false,
+        device: device,
+        mac: mac,
+        error: err.message,
+        code: err.code,
+      });
+    }
     // Error is already formatted by handleError in the catch block above
     throw err;
   }
 }
+
+function info(device) {
+  if (!device) {
+    throw new Error("Device name is required. Usage: spoofy info <device>");
+  }
+  
+  logVerbose(`Getting info for device: ${device}`);
+  showProgress("Fetching interface information");
+  
+  const it = spoof.findInterface(device);
+  hideProgress();
+  
+  if (!it) {
+    throw new Error(
+      `Could not find device "${device}". ` +
+      "List available devices using: spoofy list"
+    );
+  }
+  
+  const currentMac = spoof.getInterfaceMAC(device);
+  const vendorInfo = it.address ? oui.getVendorInfo(it.address) : null;
+  const currentVendorInfo = currentMac ? oui.getVendorInfo(currentMac) : null;
+  const deviceHistory = history.getHistoryForDevice(device);
+  
+  if (JSON_OUTPUT) {
+    outputJSON({
+      device: it.device,
+      port: it.port || it.device,
+      description: it.description,
+      hardwareMac: it.address,
+      currentMac: currentMac,
+      hardwareVendor: vendorInfo ? vendorInfo.vendor : null,
+      currentVendor: currentVendorInfo ? currentVendorInfo.vendor : null,
+      status: it.status,
+      platform: process.platform,
+      historyCount: deviceHistory.length,
+      lastChange: deviceHistory[0] || null,
+    });
+    return;
+  }
+  
+  console.log(chalk.bold.cyan("\nInterface Information"));
+  console.log(chalk.gray("─".repeat(50)));
+  console.log(chalk.bold("Device:"), it.device);
+  console.log(chalk.bold("Port:"), it.port || it.device);
+  if (it.description) {
+    console.log(chalk.bold("Description:"), it.description);
+  }
+  if (it.status) {
+    console.log(chalk.bold("Status:"), it.status);
+  }
+  console.log(chalk.bold("Platform:"), process.platform);
+  
+  if (it.address) {
+    console.log(chalk.bold("\nHardware MAC Address:"), chalk.cyan(it.address));
+    if (vendorInfo && vendorInfo.vendor !== "Unknown") {
+      console.log(chalk.bold("Hardware Vendor:"), chalk.green(vendorInfo.vendor));
+    }
+  }
+  
+  if (currentMac) {
+    console.log(chalk.bold("Current MAC Address:"), chalk.cyan(currentMac));
+    if (currentVendorInfo && currentVendorInfo.vendor !== "Unknown") {
+      console.log(chalk.bold("Current Vendor:"), chalk.green(currentVendorInfo.vendor));
+    }
+    if (currentMac !== it.address) {
+      console.log(chalk.yellow("⚠ MAC address has been changed from hardware address"));
+    }
+  }
+  
+  if (deviceHistory.length > 0) {
+    console.log(chalk.bold("\nChange History:"), `(${deviceHistory.length} entries)`);
+    deviceHistory.slice(0, 5).forEach((entry, index) => {
+      const date = new Date(entry.timestamp).toLocaleString();
+      console.log(`  ${index + 1}. ${date} - ${entry.operation}: ${entry.oldMac || "N/A"} → ${entry.newMac}`);
+    });
+    if (deviceHistory.length > 5) {
+      console.log(chalk.gray(`  ... and ${deviceHistory.length - 5} more entries`));
+    }
+  }
+  console.log();
+}
+
+function validate(mac) {
+  if (!mac) {
+    throw new Error("MAC address is required. Usage: spoofy validate <mac>");
+  }
+  
+  logVerbose(`Validating MAC address: ${mac}`);
+  
+  const normalized = spoof.normalize(mac);
+  const isValid = !!normalized;
+  const vendorInfo = normalized ? oui.getVendorInfo(normalized) : null;
+  
+  if (JSON_OUTPUT) {
+    outputJSON({
+      original: mac,
+      normalized: normalized,
+      valid: isValid,
+      vendor: vendorInfo ? vendorInfo.vendor : null,
+      prefix: vendorInfo ? vendorInfo.prefix : null,
+    });
+    return;
+  }
+  
+  if (isValid) {
+    console.log(chalk.green("✓ Valid MAC address"));
+    console.log(chalk.bold("Normalized:"), normalized);
+    if (vendorInfo && vendorInfo.vendor !== "Unknown") {
+      console.log(chalk.bold("Vendor:"), chalk.green(vendorInfo.vendor));
+    }
+  } else {
+    console.log(chalk.red("✗ Invalid MAC address"));
+    console.log(chalk.yellow("Expected format: XX:XX:XX:XX:XX:XX or XX-XX-XX-XX-XX-XX"));
+  }
+}
+
+function vendor(mac) {
+  if (!mac) {
+    throw new Error("MAC address is required. Usage: spoofy vendor <mac>");
+  }
+  
+  logVerbose(`Looking up vendor for MAC: ${mac}`);
+  
+  const normalized = spoof.normalize(mac);
+  if (!normalized) {
+    throw new Error(`"${mac}" is not a valid MAC address`);
+  }
+  
+  const vendorInfo = oui.getVendorInfo(normalized);
+  
+  if (JSON_OUTPUT) {
+    outputJSON({
+      mac: normalized,
+      vendor: vendorInfo.vendor,
+      prefix: vendorInfo.prefix,
+      found: vendorInfo.vendor !== "Unknown",
+    });
+    return;
+  }
+  
+  console.log(chalk.bold("MAC Address:"), normalized);
+  console.log(chalk.bold("Vendor:"), vendorInfo.vendor !== "Unknown" ? chalk.green(vendorInfo.vendor) : chalk.yellow("Unknown"));
+  console.log(chalk.bold("Prefix:"), vendorInfo.prefix);
+  
+  if (vendorInfo.vendor === "Unknown") {
+    console.log(chalk.gray("\nNote: Vendor not found in database. This may be a locally administered address."));
+  }
+}
+
+function batch(file) {
+  if (!file) {
+    throw new Error("Batch file is required. Usage: spoofy batch <file>");
+  }
+  
+  if (!fs.existsSync(file)) {
+    throw new Error(`Batch file not found: ${file}`);
+  }
+  
+  logVerbose(`Loading batch file: ${file}`);
+  showProgress("Loading batch configuration");
+  
+  let batchConfig;
+  try {
+    const content = fs.readFileSync(file, "utf8");
+    batchConfig = JSON.parse(content);
+  } catch (err) {
+    hideProgress();
+    throw new Error(`Failed to parse batch file: ${err.message}`);
+  }
+  
+  hideProgress();
+  
+  if (!Array.isArray(batchConfig)) {
+    throw new Error("Batch file must contain an array of operations");
+  }
+  
+  logVerbose(`Found ${batchConfig.length} operation(s) in batch file`);
+  
+  const results = [];
+  let successCount = 0;
+  let failCount = 0;
+  
+  batchConfig.forEach((operation, index) => {
+    const step = index + 1;
+    const total = batchConfig.length;
+    progressStep(step, total, `Processing operation ${step}`);
+    
+    try {
+      if (operation.type === "set" && operation.device && operation.mac) {
+        const it = spoof.findInterface(operation.device);
+        if (!it) {
+          throw new Error(`Device not found: ${operation.device}`);
+        }
+        setMACAddress(it.device, operation.mac, it.port, "batch-set");
+        results.push({ success: true, operation: operation, index: index });
+        successCount++;
+      } else if (operation.type === "randomize" && operation.device) {
+        const it = spoof.findInterface(operation.device);
+        if (!it) {
+          throw new Error(`Device not found: ${operation.device}`);
+        }
+        const mac = spoof.randomize(operation.local || false);
+        setMACAddress(it.device, mac, it.port, "batch-randomize");
+        results.push({ success: true, operation: operation, mac: mac, index: index });
+        successCount++;
+      } else if (operation.type === "reset" && operation.device) {
+        const it = spoof.findInterface(operation.device);
+        if (!it) {
+          throw new Error(`Device not found: ${operation.device}`);
+        }
+        if (!it.address) {
+          throw new Error(`No hardware MAC address for: ${operation.device}`);
+        }
+        setMACAddress(it.device, it.address, it.port, "batch-reset");
+        results.push({ success: true, operation: operation, index: index });
+        successCount++;
+      } else {
+        throw new Error(`Invalid operation type or missing parameters: ${JSON.stringify(operation)}`);
+      }
+    } catch (err) {
+      results.push({ success: false, operation: operation, error: err.message, index: index });
+      failCount++;
+    }
+  });
+  
+  progressStep(batchConfig.length, batchConfig.length, "Completed");
+  
+  if (JSON_OUTPUT) {
+    outputJSON({
+      total: batchConfig.length,
+      success: successCount,
+      failed: failCount,
+      results: results,
+    });
+  } else {
+    console.log(chalk.bold("\nBatch Operation Summary:"));
+    console.log(chalk.green(`  ✓ Successful: ${successCount}`));
+    if (failCount > 0) {
+      console.log(chalk.red(`  ✗ Failed: ${failCount}`));
+    }
+    console.log(chalk.bold(`  Total: ${batchConfig.length}`));
+  }
+}
+
+function historyCmd() {
+  const device = argv._[1]; // Optional device filter
+  logVerbose(device ? `Getting history for device: ${device}` : "Getting all history");
+  
+  const allHistory = history.getHistory();
+  const deviceHistory = device ? history.getHistoryForDevice(device) : allHistory;
+  
+  if (deviceHistory.length === 0) {
+    if (JSON_OUTPUT) {
+      outputJSON({ history: [], count: 0 });
+    } else {
+      console.log(chalk.yellow("No history found" + (device ? ` for device "${device}"` : "")));
+    }
+    return;
+  }
+  
+  if (JSON_OUTPUT) {
+    outputJSON({
+      history: deviceHistory,
+      count: deviceHistory.length,
+      device: device || "all",
+    });
+    return;
+  }
+  
+  console.log(chalk.bold.cyan("\nMAC Address Change History"));
+  console.log(chalk.gray("─".repeat(80)));
+  
+  deviceHistory.forEach((entry, index) => {
+    const date = new Date(entry.timestamp).toLocaleString();
+    console.log(chalk.bold(`\n${index + 1}. ${date}`));
+    console.log(`   Device: ${chalk.green(entry.device)}`);
+    console.log(`   Operation: ${chalk.cyan(entry.operation)}`);
+    console.log(`   ${chalk.gray(entry.oldMac || "N/A")} → ${chalk.cyan(entry.newMac)}`);
+    console.log(`   Platform: ${entry.platform}`);
+  });
+  
+  console.log();
+}

package/index.js

@@ -6,8 +6,48 @@ module.exports = {
   randomize,
   setInterfaceMAC,
   getInterfaceMAC,
+  validateMAC,
 };
 
+/**
+ * Validates a MAC address format
+ * @param {string} mac
+ * @return {Object} {valid: boolean, normalized: string|null, error: string|null}
+ */
+function validateMAC(mac) {
+  if (!mac || typeof mac !== "string") {
+    return {
+      valid: false,
+      normalized: null,
+      error: "MAC address must be a non-empty string",
+    };
+  }
+  
+  const normalized = normalize(mac);
+  if (!normalized) {
+    return {
+      valid: false,
+      normalized: null,
+      error: "Invalid MAC address format",
+    };
+  }
+  
+  // Check for invalid addresses
+  if (normalized === "00:00:00:00:00:00" || normalized === "FF:FF:FF:FF:FF:FF") {
+    return {
+      valid: false,
+      normalized: normalized,
+      error: "Cannot be all zeros or broadcast address",
+    };
+  }
+  
+  return {
+    valid: true,
+    normalized: normalized,
+    error: null,
+  };
+}
+
 const cp = require("child_process");
 const quote = require("shell-quote").quote;
 const zeroFill = require("zero-fill");

package/lib/history.js

@@ -0,0 +1,62 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const HISTORY_FILE = path.join(os.homedir(), ".spoofy_history.json");
+
+function getHistory() {
+  if (!fs.existsSync(HISTORY_FILE)) {
+    return [];
+  }
+  try {
+    const content = fs.readFileSync(HISTORY_FILE, "utf8");
+    return JSON.parse(content);
+  } catch (err) {
+    return [];
+  }
+}
+
+function saveHistory(history) {
+  try {
+    fs.writeFileSync(HISTORY_FILE, JSON.stringify(history, null, 2), "utf8");
+  } catch (err) {
+    // Silently fail if we can't write history
+  }
+}
+
+function addHistoryEntry(device, oldMac, newMac, operation) {
+  const history = getHistory();
+  const entry = {
+    timestamp: new Date().toISOString(),
+    device: device,
+    oldMac: oldMac,
+    newMac: newMac,
+    operation: operation, // 'set', 'randomize', 'reset'
+    platform: process.platform,
+  };
+  history.unshift(entry); // Add to beginning
+  // Keep only last 100 entries
+  if (history.length > 100) {
+    history.splice(100);
+  }
+  saveHistory(history);
+  return entry;
+}
+
+function getHistoryForDevice(device) {
+  const history = getHistory();
+  return history.filter((entry) => entry.device === device);
+}
+
+function getLastEntryForDevice(device) {
+  const history = getHistory();
+  return history.find((entry) => entry.device === device);
+}
+
+module.exports = {
+  getHistory,
+  addHistoryEntry,
+  getHistoryForDevice,
+  getLastEntryForDevice,
+  HISTORY_FILE,
+};

package/lib/oui.js

@@ -0,0 +1,286 @@
+// OUI (Organizationally Unique Identifier) database
+// Common MAC address vendor prefixes
+// This is a subset - can be expanded with full IEEE OUI database
+
+const OUI_DB = {
+  "00:05:69": "VMware",
+  "00:0C:29": "VMware",
+  "00:50:56": "VMware",
+  "00:16:3E": "Xen",
+  "00:03:FF": "Microsoft Hyper-V",
+  "00:1C:42": "Parallels",
+  "00:0F:4B": "Virtual Iron",
+  "08:00:27": "VirtualBox",
+  "00:1B:21": "Intel",
+  "00:1E:67": "Intel",
+  "00:21:70": "Intel",
+  "00:25:00": "Intel",
+  "00:26:B9": "Intel",
+  "00:1A:79": "Intel",
+  "00:15:17": "Intel",
+  "00:13:CE": "Intel",
+  "00:0D:3A": "Intel",
+  "00:0E:0C": "Intel",
+  "00:11:11": "Intel",
+  "00:14:4F": "Intel",
+  "00:16:76": "Intel",
+  "00:18:DE": "Intel",
+  "00:1B:77": "Intel",
+  "00:1C:C0": "Intel",
+  "00:1D:7E": "Intel",
+  "00:1E:67": "Intel",
+  "00:21:5C": "Intel",
+  "00:23:14": "Intel",
+  "00:23:DF": "Intel",
+  "00:24:D6": "Intel",
+  "00:25:00": "Intel",
+  "00:26:18": "Intel",
+  "00:26:4A": "Intel",
+  "00:26:B9": "Intel",
+  "00:26:C7": "Intel",
+  "00:27:13": "Intel",
+  "00:50:56": "VMware",
+  "00:0C:29": "VMware",
+  "00:05:69": "VMware",
+  "00:1B:21": "Intel",
+  "00:1E:67": "Intel",
+  "00:21:70": "Intel",
+  "00:25:00": "Intel",
+  "00:26:B9": "Intel",
+  "00:1A:79": "Intel",
+  "00:15:17": "Intel",
+  "00:13:CE": "Intel",
+  "00:0D:3A": "Intel",
+  "00:0E:0C": "Intel",
+  "00:11:11": "Intel",
+  "00:14:4F": "Intel",
+  "00:16:76": "Intel",
+  "00:18:DE": "Intel",
+  "00:1B:77": "Intel",
+  "00:1C:C0": "Intel",
+  "00:1D:7E": "Intel",
+  "00:1E:67": "Intel",
+  "00:21:5C": "Intel",
+  "00:23:14": "Intel",
+  "00:23:DF": "Intel",
+  "00:24:D6": "Intel",
+  "00:25:00": "Intel",
+  "00:26:18": "Intel",
+  "00:26:4A": "Intel",
+  "00:26:B9": "Intel",
+  "00:26:C7": "Intel",
+  "00:27:13": "Intel",
+  "00:50:F2": "Apple",
+  "00:1E:C2": "Apple",
+  "00:23:12": "Apple",
+  "00:23:6C": "Apple",
+  "00:23:DF": "Apple",
+  "00:25:00": "Apple",
+  "00:25:4B": "Apple",
+  "00:26:08": "Apple",
+  "00:26:4A": "Apple",
+  "00:26:BB": "Apple",
+  "00:26:CA": "Apple",
+  "00:50:E4": "Apple",
+  "00:56:CD": "Apple",
+  "00:61:71": "Apple",
+  "00:6D:52": "Apple",
+  "00:88:65": "Apple",
+  "00:A0:40": "Apple",
+  "00:C6:10": "Apple",
+  "00:CD:FE": "Apple",
+  "00:F4:B9": "Apple",
+  "00:F7:6F": "Apple",
+  "04:0C:CE": "Apple",
+  "04:15:52": "Apple",
+  "04:1E:64": "Apple",
+  "04:26:65": "Apple",
+  "04:4B:ED": "Apple",
+  "04:54:53": "Apple",
+  "04:7D:7B": "Apple",
+  "04:8D:38": "Apple",
+  "04:9A:4F": "Apple",
+  "04:9F:CA": "Apple",
+  "04:A3:16": "Apple",
+  "04:DB:56": "Apple",
+  "04:E5:36": "Apple",
+  "04:F1:3E": "Apple",
+  "04:F7:E4": "Apple",
+  "08:00:27": "VirtualBox",
+  "08:66:98": "Apple",
+  "08:70:45": "Apple",
+  "08:74:02": "Apple",
+  "08:9E:01": "Apple",
+  "08:CC:68": "Apple",
+  "0C:3E:9F": "Apple",
+  "0C:4D:E9": "Apple",
+  "0C:51:01": "Apple",
+  "0C:74:C2": "Apple",
+  "0C:BC:9F": "Apple",
+  "0C:D2:92": "Apple",
+  "0C:E5:D3": "Apple",
+  "10:93:E9": "Apple",
+  "10:9A:DD": "Apple",
+  "10:DD:B1": "Apple",
+  "14:10:9F": "Apple",
+  "14:7D:DA": "Apple",
+  "14:99:E2": "Apple",
+  "14:CC:20": "Apple",
+  "18:20:32": "Apple",
+  "18:65:90": "Apple",
+  "18:AF:61": "Apple",
+  "1C:1A:C0": "Apple",
+  "1C:AB:A7": "Apple",
+  "20:78:F0": "Apple",
+  "20:AB:37": "Apple",
+  "20:C9:D0": "Apple",
+  "24:A0:74": "Apple",
+  "24:AB:81": "Apple",
+  "24:E3:14": "Apple",
+  "28:37:37": "Apple",
+  "28:6A:B8": "Apple",
+  "28:CF:DA": "Apple",
+  "28:CF:E9": "Apple",
+  "2C:1F:23": "Apple",
+  "2C:33:7A": "Apple",
+  "2C:BE:08": "Apple",
+  "30:90:AB": "Apple",
+  "34:15:9E": "Apple",
+  "34:A3:95": "Apple",
+  "34:C0:59": "Apple",
+  "38:CA:DA": "Apple",
+  "3C:07:54": "Apple",
+  "3C:15:C2": "Apple",
+  "3C:D0:F8": "Apple",
+  "40:33:1A": "Apple",
+  "40:6C:8F": "Apple",
+  "40:A6:D9": "Apple",
+  "40:CB:C0": "Apple",
+  "44:4C:0C": "Apple",
+  "44:FB:42": "Apple",
+  "48:43:7C": "Apple",
+  "48:BF:6B": "Apple",
+  "4C:8D:79": "Apple",
+  "50:EA:D6": "Apple",
+  "54:26:96": "Apple",
+  "54:72:4F": "Apple",
+  "58:55:CA": "Apple",
+  "5C:59:48": "Apple",
+  "5C:95:AE": "Apple",
+  "60:33:4B": "Apple",
+  "60:C5:47": "Apple",
+  "64:A3:CB": "Apple",
+  "68:96:7B": "Apple",
+  "6C:40:08": "Apple",
+  "6C:72:20": "Apple",
+  "70:48:0F": "Apple",
+  "70:56:51": "Realtek",
+  "74:E2:F5": "Apple",
+  "78:31:C1": "Apple",
+  "78:4F:43": "Apple",
+  "7C:6D:62": "Apple",
+  "80:BE:05": "Apple",
+  "84:38:35": "Apple",
+  "84:FC:FE": "Apple",
+  "88:63:DF": "Apple",
+  "8C:85:90": "Apple",
+  "90:72:40": "Apple",
+  "94:E9:6A": "Apple",
+  "98:5F:D3": "Apple",
+  "9C:84:BF": "Apple",
+  "A0:99:9B": "Apple",
+  "A4:5E:60": "Apple",
+  "A4:C3:61": "Apple",
+  "A8:60:B6": "Apple",
+  "AC:1F:74": "Apple",
+  "AC:BC:32": "Apple",
+  "B0:65:BD": "Apple",
+  "B4:F0:AB": "Apple",
+  "B8:09:8A": "Apple",
+  "B8:53:AC": "Apple",
+  "BC:3B:AF": "Apple",
+  "BC:52:B7": "Apple",
+  "C0:25:E9": "Apple",
+  "C4:2C:03": "Apple",
+  "C8:1E:E7": "Apple",
+  "CC:08:E0": "Apple",
+  "D0:03:4B": "Apple",
+  "D4:9A:20": "Apple",
+  "D8:30:62": "Apple",
+  "D8:A2:5E": "Apple",
+  "DC:2B:61": "Apple",
+  "E0:AC:CB": "Apple",
+  "E4:CE:8F": "Apple",
+  "E8:40:40": "Apple",
+  "EC:35:86": "Apple",
+  "F0:18:98": "Apple",
+  "F0:DB:E2": "Apple",
+  "F4:F1:5A": "Apple",
+  "F8:1E:DF": "Apple",
+  "FC:25:3F": "Apple",
+  "00:1B:21": "Intel",
+  "00:1E:67": "Intel",
+  "00:21:70": "Intel",
+  "00:25:00": "Intel",
+  "00:26:B9": "Intel",
+  "00:1A:79": "Intel",
+  "00:15:17": "Intel",
+  "00:13:CE": "Intel",
+  "00:0D:3A": "Intel",
+  "00:0E:0C": "Intel",
+  "00:11:11": "Intel",
+  "00:14:4F": "Intel",
+  "00:16:76": "Intel",
+  "00:18:DE": "Intel",
+  "00:1B:77": "Intel",
+  "00:1C:C0": "Intel",
+  "00:1D:7E": "Intel",
+  "00:1E:67": "Intel",
+  "00:21:5C": "Intel",
+  "00:23:14": "Intel",
+  "00:23:DF": "Intel",
+  "00:24:D6": "Intel",
+  "00:25:00": "Intel",
+  "00:26:18": "Intel",
+  "00:26:4A": "Intel",
+  "00:26:B9": "Intel",
+  "00:26:C7": "Intel",
+  "00:27:13": "Intel",
+  "00:50:56": "VMware",
+  "00:0C:29": "VMware",
+  "00:05:69": "VMware",
+  "00:16:3E": "Xen",
+  "00:03:FF": "Microsoft Hyper-V",
+  "00:1C:42": "Parallels",
+  "00:0F:4B": "Virtual Iron",
+  "08:00:27": "VirtualBox",
+};
+
+function lookupVendor(mac) {
+  if (!mac) return null;
+  
+  // Normalize MAC address
+  const normalized = mac.replace(/[:-]/g, "").toUpperCase();
+  if (normalized.length < 6) return null;
+  
+  // Get first 3 bytes (6 hex characters)
+  const prefix = normalized.substring(0, 6);
+  const formattedPrefix = `${prefix.substring(0, 2)}:${prefix.substring(2, 4)}:${prefix.substring(4, 6)}`;
+  
+  return OUI_DB[formattedPrefix] || OUI_DB[prefix] || null;
+}
+
+function getVendorInfo(mac) {
+  const vendor = lookupVendor(mac);
+  return {
+    mac: mac,
+    vendor: vendor || "Unknown",
+    prefix: mac.substring(0, 8),
+  };
+}
+
+module.exports = {
+  lookupVendor,
+  getVendorInfo,
+  OUI_DB,
+};

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "spoof-d",
   "description": "Cross-platform MAC address spoofing utility for macOS, Windows, and Linux",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "bin": {
-    "spoofy": "./bin/cmd.js"
+    "spoofy": "bin/cmd.js"
   },
   "files": [
     "index.js",
     "bin/",
+    "lib/",
     "LICENSE",
-    "README.md"
+    "README.md",
+    ".spoofyrc.example",
+    "batch.example.json"
   ],
   "bugs": {
     "url": "https://github.com/TT5H/spoof-d/issues"
@@ -18,6 +21,7 @@
     "chalk": "^4.1.0",
     "common-tags": "^1.8.0",
     "minimist": "^1.2.5",
+    "ora": "^9.0.0",
     "shell-quote": "^1.7.2",
     "zero-fill": "^2.2.4"
   },