vuke 0.1.0

Research tool for studying vulnerable Bitcoin key generation practices
Documentation

vuke

Research tool for studying vulnerable Bitcoin key generation practices.

Features

  • Modular architecture - pluggable sources and transforms
  • Multiple input sources
    • Numeric ranges (test weak seeds)
    • Wordlists (brainwallet analysis)
    • Timestamps (time-based PRNG exploitation)
    • Stdin streaming (pipeline integration)
  • Historical vulnerability transforms
    • Direct (raw bytes as key)
    • SHA256 (classic brainwallet)
    • Double SHA256 (Bitcoin-style hashing)
    • MD5 (legacy weak hashing)
    • Milksad (MT19937 PRNG - CVE-2023-39910)
    • Armory (legacy HD derivation)
  • Parallel processing via Rayon
  • Address matching for scanning known targets
  • Pure Rust implementation

Why This Project?

This tool is designed for security research - understanding how vulnerable keys were generated in the past helps improve modern wallet security.

Historical vulnerabilities this tool can reproduce:

Vulnerability Year Impact
Brainwallets 2011-2015 SHA256(passphrase) easily cracked
Weak PRNGs 2013-2023 Predictable seeds (timestamps, PIDs)
Milksad 2023 libbitcoin bx used MT19937 with 32-bit seeds
Armory HD 2012-2016 Pre-BIP32 deterministic derivation

Installation

Cargo

cargo install vuke

From source

git clone https://github.com/oritwoen/vuke
cd vuke
cargo build --release

Usage

Generate single key from passphrase

vuke single "correct horse battery staple" --transform sha256

Output:

Passphrase: "correct horse battery staple"
Transform: sha256
Source: correct horse battery staple
---
Private Key (hex):     c4bbcb1fbec99d65bf59d85c8cb62ee2db963f0fe106f483d9afa73bd4e39a8a
WIF (compressed):      L3p8oAcQTtuokSCRHQ7i4MhjWc9zornvpJLfmg62sYpLRJF9woSu
---
P2PKH (compressed):   1JwSSubhmg6iPtRjtyqhUYYH7bZg3Lfy1T
P2WPKH:               bc1qfnpg7ceg02y64qrskgz0drwp3y6hma3q6wvnzr

Scan wordlist for known addresses

vuke scan --transform=sha256 --targets known_addresses.txt wordlist --file passwords.txt

Test numeric range (weak seeds)

vuke generate --transform=milksad range --start 1 --end 1000000

Test timestamp-based keys

vuke scan --transform=sha256 --targets addresses.txt timestamps --start 2015-01-01 --end 2015-01-31

Multiple transforms

vuke scan --transform=sha256 --transform=double_sha256 --transform=md5 --targets addresses.txt wordlist --file words.txt

Pipe from stdin

cat passwords.txt | vuke generate --transform=sha256 stdin

Benchmark transforms

vuke bench --transform milksad

Supported Transforms

Transform Description Use Case
direct Raw bytes padded to 32 bytes Testing raw numeric seeds
sha256 SHA256(input) Classic brainwallets
double_sha256 SHA256(SHA256(input)) Bitcoin-style hashing
md5 MD5(input) duplicated to 32 bytes Legacy weak hashing
milksad MT19937 PRNG with 32-bit seed CVE-2023-39910 (libbitcoin)
armory Armory HD derivation chain Pre-BIP32 wallets

Library Usage

use vuke::derive::KeyDeriver;
use vuke::transform::{Input, Transform, Sha256Transform};

fn main() {
    let deriver = KeyDeriver::new();
    let transform = Sha256Transform;

    let input = Input::from_string("test passphrase".to_string());
    let mut buffer = Vec::new();
    transform.apply_batch(&[input], &mut buffer);

    for (source, key) in buffer {
        let derived = deriver.derive(&key);
        println!("Source: {}", source);
        println!("WIF: {}", derived.wif_compressed);
        println!("Address: {}", derived.p2pkh_compressed);
    }
}

Architecture

src/
├── main.rs          # CLI entry point
├── lib.rs           # Library exports
├── derive.rs        # Private key → address derivation
├── matcher.rs       # Address matching against targets
├── network.rs       # Bitcoin network handling
├── benchmark.rs     # Performance testing
├── source/
│   ├── mod.rs       # Source trait and types
│   ├── range.rs     # Numeric range source
│   ├── wordlist.rs  # File-based wordlist
│   ├── timestamps.rs # Date range → Unix timestamps
│   └── stdin.rs     # Streaming from stdin
├── transform/
│   ├── mod.rs       # Transform trait and types
│   ├── input.rs     # Input value representation
│   ├── direct.rs    # Raw bytes transform
│   ├── sha256.rs    # SHA256 hashing
│   ├── double_sha256.rs # Double SHA256
│   ├── md5.rs       # MD5 hashing
│   ├── milksad.rs   # MT19937 PRNG (CVE-2023-39910)
│   └── armory.rs    # Armory HD derivation
└── output/
    ├── mod.rs       # Output trait
    └── console.rs   # Console output handler

Requirements

  • Rust 1.70+

Disclaimer

This tool is for educational and security research purposes only. Do not use it to access wallets you do not own. The authors are not responsible for any misuse.

License

MIT License - see LICENSE for details.

References