_readme.md

Hex Generator (High Entropy)

A tool to generate Hexadecimal strings with high entropy using Node.js.

Features

• Secure Generation: Uses Node.js crypto module for cryptographically secure random hex strings (CSPRNG).
• Entropy Calculation: Calculates real-time Shannon Entropy (0.0 - 4.0) for every string.
• Filtering & Sorting: Set minimum target scores and get results automatically sorted by entropy.
• Peak Detection: Built-in --scan mode to find the top highest entropy samples (N samples based on -n).
• Flexible Output: Supports standard text output, hidden scores, or formatted JSON data.
• Zero Dependencies: Runs on standard Node.js without needing any external packages.

Usage

Run via npx (Directly)

npx -y https://gist.github.com/802a0e0f3308e8a5fff587e5dca7be65 [options]

Local Usage

node index.js [options]

Options

Argument	Description	Default	Valid Values
-l, --length	Length of the hex string	64	Positive Integer
-s, --score	Minimum entropy score	3.5	0.0 - 4.0
-n, --count	Number of strings to generate	1	Positive Integer
-m, --max-attempts	Max attempts per string to reach score	1000	Positive Integer
--scan	Scan for peak entropy (Finds top N samples based on -n)	false	Flag
--hide-score	Output only the hex string	false	Flag
--json	Output results as JSON array	false	Flag

Examples

1. Generate 5 strings of length 32:

node index.js -l 32 -n 5

Output:

3.7570 4ac3b64e59174189c44d5fae47025272
3.6914 a8737a0974580a6e2f6818ec562d5a8c
3.6556 b2a0431e7f1b8090acbfb6803a4f819e
3.6320 c1c247c93c03f4ce50c875fa32a76ae6
3.5389 690b9a0b83729ceaba6552e0908fb3ee

2. Scan for peak entropy (Find top highest entropy hex samples):

node index.js -l 32 --scan -n 5

Output:

3.9292 aae127583fb213c759768cd39edb06d4
3.9292 3d80c2659eb45e90bd036c17ff16a834
3.9292 042b61178bfd09ef226ca557da18936c
3.9292 e5f10a2a3d0d8576c442369bcb0784e2
3.9139 964fcd0c4ea674f4238517e813ab9dab

3. Generate only the hex string (useful for piping):

node index.js -l 16 --hide-score

Output:

ce0a8689fc79355d

4. Generate results in JSON format:

node index.js -l 16 -n 2 --json

Output:

[
  {
    "value": "a98d5128f16301ce",
    "entropy": 3.5778
  },
  {
    "value": "4830df5cdb270e73",
    "entropy": 3.5000
  }
]

index.js

#!/usr/bin/env node
const crypto = require('crypto');

/**
 * Calculate Shannon Entropy of a string
 */
function calculateEntropy(str) {
    if (!str) return 0;
    const len = str.length;
    const frequencies = new Map();
    for (let i = 0; i < len; i++) {
        const char = str[i];
        frequencies.set(char, (frequencies.get(char) || 0) + 1);
    }
    
    let entropy = 0;
    for (const count of frequencies.values()) {
        const p = count / len;
        entropy -= p * Math.log2(p);
    }
    return entropy;
}

/**
 * CLI Argument Parser
 */
function parseArgs() {
    const args = process.argv.slice(2);
    const config = {
        length: 64,
        score: 3.5,
        count: 1,
        maxAttempts: 1000,
        hideScore: false,
        json: false,
        scan: false
    };

    const handleError = (msg) => {
        console.error(`\x1b[31mError: ${msg}\x1b[0m`);
        process.exit(1);
    };

    for (let i = 0; i < args.length; i++) {
        const arg = args[i];
        const getNext = () => {
            if (i + 1 >= args.length || args[i+1].startsWith('-')) {
                handleError(`Argument ${arg} requires a value.`);
            }
            return args[++i];
        };

        switch (arg) {
            case '-l': case '--length':
                const l = parseInt(getNext(), 10);
                if (isNaN(l) || l <= 0) handleError("--length must be a positive integer.");
                config.length = Math.min(1000000, l); // 1M chars limit
                break;
            case '-s': case '--score':
                const s = parseFloat(getNext());
                if (isNaN(s)) handleError("--score must be a number.");
                config.score = Math.max(0, Math.min(4, s));
                break;
            case '-n': case '--count':
                const n = parseInt(getNext(), 10);
                if (isNaN(n) || n <= 0) handleError("--count must be a positive integer.");
                config.count = Math.min(10000, n);
                break;
            case '-m': case '--max-attempts':
                const m = parseInt(getNext(), 10);
                if (isNaN(m) || m <= 0) handleError("--max-attempts must be a positive integer.");
                config.maxAttempts = Math.min(100000, m);
                break;
            case '--hide-score': config.hideScore = true; break;
            case '--json': config.json = true; break;
            case '--scan': config.scan = true; break;
            case '-h': case '--help':
                console.log(`
High Entropy Hex Generator

Usage: node index.js [options]

Options:
  -l, --length        Length of the hex string (default: 64, max: 1,000,000)
  -s, --score         Minimum entropy score (0.0 - 4.0, default: 3.5)
  -n, --count         Number of strings to generate (max: 10,000)
  -m, --max-attempts  Max attempts per string (max: 100,000)
  --scan              Scan 10,000 samples for peak entropy (returns top -n)
  --hide-score        Output only the hex string
  --json              Output results as JSON array
`);
                process.exit(0);
        }
    }
    return config;
}

const config = parseArgs();

try {
    const numBytes = Math.ceil(config.length / 2);

    if (config.scan) {
        let topSamples = [];
        const scanCount = 10000;

        for (let i = 0; i < scanCount; i++) {
            const s = crypto.randomBytes(numBytes).toString('hex').slice(0, config.length);
            const e = calculateEntropy(s);
            topSamples.push({ value: s, entropy: e });
            
            if (topSamples.length > config.count * 10) {
                topSamples.sort((a, b) => b.entropy - a.entropy);
                topSamples = topSamples.slice(0, config.count);
            }
        }
        topSamples.sort((a, b) => b.entropy - a.entropy);
        topSamples.slice(0, config.count).forEach(sample => {
            console.log(`${sample.entropy.toFixed(4)} ${sample.value}`);
        });
        process.exit(0);
    }

    const results = [];
    for (let i = 0; i < config.count; i++) {
        let bestStr = "";
        let bestEntropy = -1;

        for (let attempt = 0; attempt < config.maxAttempts; attempt++) {
            const currentStr = crypto.randomBytes(numBytes).toString('hex').slice(0, config.length);
            const currentEntropy = calculateEntropy(currentStr);
            if (currentEntropy > bestEntropy) {
                bestStr = currentStr;
                bestEntropy = currentEntropy;
            }
            if (currentEntropy >= config.score) break;
        }
        results.push({ value: bestStr, entropy: parseFloat(bestEntropy.toFixed(4)) });
    }

    results.sort((a, b) => b.entropy - a.entropy);

    if (config.json) {
        console.log(JSON.stringify(results, null, 2));
    } else {
        results.forEach(res => {
            if (config.hideScore) {
                console.log(res.value);
            } else {
                console.log(`${res.entropy.toFixed(4)} ${res.value}`);
            }
        });
    }
} catch (error) {
    console.error(`\x1b[31mError: ${error.message}\x1b[0m`);
    process.exit(1);
}

package.json

{
  "name": "high-entropy-hex-gen",
  "version": "1.0.0",
  "description": "Generate high entropy hex strings",
  "main": "index.js",
  "bin": "index.js",
  "author": "Autoplay1999",
  "license": "ISC"
}