spoof-d 0.2.0 → 0.4.0

package/README.md

@@ -21,6 +21,7 @@ This repository ([TT5H/spoof-d](https://github.com/TT5H/spoof-d)) is a fork of [
 - **Modern macOS Support**: Fixed MAC spoofing for macOS Sequoia 15.4+ and Tahoe 26+
 - **Windows Support**: Full Windows 10/11 support using PowerShell and registry methods with automatic fallback
 - **Linux Support**: Modern Linux support using `ip link` commands (replaces deprecated `ifconfig`)
+- **DUID Spoofing**: DHCPv6 DUID spoofing with automatic original preservation and cross-platform support
 - **Enhanced Error Handling**: Custom error classes with actionable suggestions and better error messages
 - **Automatic Verification**: Verifies MAC address changes after setting them
 - **Retry Logic**: Automatic retry with exponential backoff for transient failures
@@ -51,10 +52,15 @@ This repository ([TT5H/spoof-d](https://github.com/TT5H/spoof-d)) is a fork of [
 - **Unified API** across all platforms
 
 ### User Experience Features
-- **Progress indicators** for long-running operations
+- **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** for both MAC and DUID changes with ability to view history
+- **Batch operations** for changing multiple interfaces at once
+- **DUID (DHCPv6) spoofing** for complete IPv6 network identity management
+- **Automatic verification** of DUID changes with retry logic
 
 ## Installation
 
@@ -165,6 +171,176 @@ sudo spoofy reset wi-fi
 
 **Note**: On macOS, restarting your computer will also reset your MAC address to the original hardware address.
 
+## DUID Spoofing (DHCPv6)
+
+`spoof-d` also supports DHCPv6 DUID (DHCP Unique Identifier) spoofing for complete IPv6 network identity management.
+
+### What is a DUID?
+
+A DUID (DHCP Unique Identifier) is used in DHCPv6 to uniquely identify a client on IPv6 networks. Unlike MAC addresses which identify network interfaces, DUIDs identify DHCP clients across all interfaces and persist across reboots.
+
+### Key Feature: Original DUID Preservation
+
+The first time you spoof your DUID, your **original DUID is automatically saved** to:
+- macOS: `/var/db/dhcpclient/DUID.original`
+- Linux: `/var/lib/spoofy/duid.original`
+- Windows: `%PROGRAMDATA%\spoofy\duid.original`
+
+This allows you to **restore to your pre-spoofing state** at any time using `spoofy duid restore`.
+
+### Show current DUID
+
+```bash
+spoofy duid list
+```
+
+### Randomize DUID _(requires root)_
+
+Generate and set a random DUID (automatically saves your original on first use):
+
+```bash
+sudo spoofy duid randomize en0
+```
+
+You can specify the DUID type:
+
+```bash
+sudo spoofy duid randomize en0 --type=LLT
+```
+
+### Set specific DUID _(requires root)_
+
+```bash
+sudo spoofy duid set 00:03:00:01:aa:bb:cc:dd:ee:ff en0
+```
+
+### Sync DUID to current MAC _(requires root)_
+
+Match DUID to the current MAC address of an interface (useful after MAC spoofing):
+
+```bash
+sudo spoofy duid sync en0
+```
+
+With specific type:
+
+```bash
+sudo spoofy duid sync en0 --type=LLT
+```
+
+**Typical workflow for complete identity spoofing:**
+
+```bash
+sudo spoofy randomize en0      # Spoof MAC first
+sudo spoofy duid sync en0      # Then sync DUID to match
+```
+
+This ensures both layers show the same spoofed identity on IPv6 networks.
+
+### Restore to original DUID _(requires root)_
+
+Return to your original (pre-spoofing) DUID:
+
+```bash
+sudo spoofy duid restore en0
+```
+
+### Reset DUID _(requires root)_
+
+Delete current DUID and let the system generate a NEW random one:
+
+```bash
+sudo spoofy duid reset en0
+```
+
+**Important**: `reset` generates a NEW DUID, while `restore` returns to your ORIGINAL.
+
+### DUID Types
+
+| Type | Name | Description |
+|------|------|-------------|
+| 1 | DUID-LLT | Link-layer address + timestamp (most common) |
+| 2 | DUID-EN | Enterprise number + identifier |
+| 3 | DUID-LL | Link-layer address only (default) |
+| 4 | DUID-UUID | UUID-based identifier |
+
+### 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
+```
+
+### View DUID change history
+
+```bash
+spoofy duid history
+```
+
+View all DUID changes, or filter by device:
+
+```bash
+spoofy duid history en0
+```
+
 ## Advanced Usage
 
 ### Verbose Mode
@@ -213,6 +389,25 @@ Create a configuration file at `~/.spoofyrc` (or `%USERPROFILE%\.spoofyrc` on Wi
 
 The configuration file allows you to set default options that will be used automatically.
 
+### Change History
+
+All MAC address and DUID changes are automatically logged to `~/.spoofy_history.json`. You can:
+
+- View MAC history: `spoofy history`
+- View MAC history for specific device: `spoofy history en0`
+- View DUID history: `spoofy duid history`
+- View DUID history for specific device: `spoofy duid history en0`
+- History includes timestamp, device, old/new values, and operation type
+- Both MAC and DUID changes are tracked in the same history file
+
+### 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:

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

@@ -8,6 +8,10 @@ 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 duidCli = require("../lib/duid-cli");
 
 const argv = minimist(process.argv.slice(2), {
   alias: {
@@ -53,22 +57,51 @@ function outputJSON(data) {
   }
 }
 
+let currentSpinner = null;
+
 function showProgress(message) {
   if (JSON_OUTPUT) return;
-  process.stdout.write(chalk.blue("⏳ ") + message + "... ");
+  if (currentSpinner) {
+    currentSpinner.text = message;
+  } else {
+    currentSpinner = ora(message).start();
+  }
 }
 
 function hideProgress() {
   if (JSON_OUTPUT) return;
-  process.stdout.write("\r" + " ".repeat(80) + "\r");
+  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);
-  process.stdout.write(`\r${chalk.blue("⏳")} [${step}/${total}] ${percentage}% - ${message}...`);
+  if (currentSpinner) {
+    currentSpinner.text = `[${step}/${total}] ${percentage}% - ${message}`;
+  } else {
+    currentSpinner = ora(`[${step}/${total}] ${percentage}% - ${message}`).start();
+  }
   if (step === total) {
-    process.stdout.write("\r" + " ".repeat(80) + "\r");
+    currentSpinner = null;
   }
 }
 
@@ -136,6 +169,22 @@ 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 if (cmd === "duid") {
+    duidCli.run(argv._.slice(1), VERBOSE, JSON_OUTPUT);
   } else {
     help();
   }
@@ -172,6 +221,19 @@ ${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.
+      duid <command>                    DHCPv6 DUID spoofing commands (see: spoofy duid help).
+
     Options:
       --wifi          Try to only show wireless interfaces.
       --local         Set the locally administered flag on randomized MACs.
@@ -299,7 +361,7 @@ function randomize(devices) {
       console.log(chalk.blue("ℹ"), `Generated random MAC address: ${chalk.bold.cyan(mac)}`);
     }
     
-    setMACAddress(it.device, mac, it.port);
+    setMACAddress(it.device, mac, it.port, "randomize");
   });
 }
 
@@ -339,7 +401,7 @@ function reset(devices) {
       console.log(chalk.blue("ℹ"), `Resetting to hardware MAC address: ${chalk.bold.cyan(it.address)}`);
     }
     
-    setMACAddress(it.device, it.address, it.port);
+    setMACAddress(it.device, it.address, it.port, "reset");
   });
 }
 
@@ -395,17 +457,28 @@ 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...");
@@ -454,13 +527,17 @@ function setMACAddress(device, mac, port) {
     
     spoof.setInterfaceMAC(device, mac, port);
     
-    hideProgress();
+    // 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 {
@@ -476,7 +553,7 @@ function setMACAddress(device, mac, port) {
     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) {
-    hideProgress();
+    failProgress("Failed to change MAC address");
     if (JSON_OUTPUT) {
       outputJSON({
         success: false,
@@ -490,3 +567,287 @@ function setMACAddress(device, mac, port) {
     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();
+}