mini-unix-brute/README.md

World's Smallest Docker Image - Password Bruteforce Tool

A minimal, ultra-compressed Docker image containing a password bruteforce tool that can crack various hash types including yescrypt, MD5, SHA256, and SHA512.

🚀 Features

• Ultra-small Docker image (~46KB compressed)
• Multiple hash support: yescrypt, MD5, SHA256, SHA512
• Static binary: No external dependencies
• UPX compressed: Maximum size optimization
• Real-time progress: Shows attempts and statistics
• Comprehensive logging: Detailed output for debugging

📊 Image Size Comparison

Image	Size	Compression
This tool	~46KB	UPX ultra-brute
Standard Alpine	~5MB	None
Standard Ubuntu	~70MB	None

🛠️ Technical Details

Hash Algorithms Supported

• yescrypt ($y$) - Modern Linux default
• MD5 ($1$) - Legacy support
• SHA256 ($5$) - SHA-256 based
• SHA512 ($6$) - SHA-512 based

Build Process

1. Multi-stage build using Alpine Linux
2. Static compilation with musl-gcc
3. Binary stripping to remove debug symbols
4. UPX compression with ultra-brute mode
5. Scratch base image for minimal size

🏗️ Building

# Build the image
docker build -t bruteforce-test -f brute/source/Dockerfile brute/source

# Check image size
docker images bruteforce-test

🚀 Usage

Basic Usage

# Crack password for a specific user
docker run --rm \
  --volume "/etc:/etc" \
  --user root \
  bruteforce-test:latest \
  <username> <wordlist_path>

Example Commands

Crack root password

docker run --rm \
  --volume "/etc:/etc" \
  --volume "$(pwd)/brute/source/wordlist2.txt:/wordlist2.txt" \
  --user root \
  bruteforce-test:latest \
  root /wordlist2.txt

Crack specific user password

docker run --rm \
  --volume "/etc:/etc" \
  --volume "$(pwd)/custom_wordlist.txt:/wordlist.txt" \
  --user root \
  bruteforce-test:latest \
  alice /wordlist.txt

Output Example

Target user: root
Hash type: yescrypt
Full hash: $y$j9T$dummy.salt.hash.example$dummy.hash.value.here
Starting bruteforce...
Tried 1000 passwords...
Found password: [password_found]
Total passwords tried: 102
Password successfully cracked!

📁 Project Structure

.
├── brute/
│   └── source/
│       ├── Dockerfile          # Multi-stage build configuration
│       ├── bruteforce.c        # Main bruteforce implementation
│       ├── wordlist.txt        # Large wordlist (133MB)
│       ├── wordlist2.txt       # Small wordlist (801B)
│       └── yescrypt/           # yescrypt reference implementation
│           ├── yescrypt-ref.c
│           ├── yescrypt-common.c
│           ├── sha256.c
│           ├── insecure_memzero.c
│           └── *.h files
└── README.md

🔧 Development

Prerequisites

• Docker
• Linux system with /etc/shadow access
• Root privileges (for accessing shadow file)

Compilation Flags

gcc -static -Os -s -o bruteforce \
    bruteforce.c \
    yescrypt-ref.c \
    yescrypt-common.c \
    sha256.c \
    insecure_memzero.c \
    && strip --strip-all --remove-section=.comment bruteforce \
    && upx --ultra-brute bruteforce

Optimization Techniques

• Static linking: No external dependencies
• Size optimization: -Os flag for minimal size
• Symbol stripping: Remove debug symbols
• UPX compression: Ultra-brute mode for maximum compression
• Scratch base: No OS layer in final image

🛡️ Security Considerations

⚠️ WARNING: This tool is for educational and authorized testing purposes only.

• Only use on systems you own or have explicit permission to test
• Respect local laws and regulations regarding password cracking
• Use responsibly and ethically
• Consider legal implications before use

📈 Performance

• Speed: Optimized for size over speed
• Memory: Minimal memory footprint
• CPU: Single-threaded, CPU intensive
• I/O: Efficient file reading with minimal syscalls

🐛 Troubleshooting

Common Issues

1. Permission denied accessing /etc/shadow

   # Run with root user
   --user root
   

2. Wordlist not found

   # Ensure correct path mapping
   --volume "$(pwd)/wordlist.txt:/wordlist.txt"
   

3. User not found in shadow file

   • Verify username exists
   • Check shadow file permissions

Debug Mode

The tool provides detailed output including:

• Target user information
• Hash type and format
• Progress updates every 1000 attempts
• Final statistics

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

This project is for educational purposes. Use responsibly and in accordance with applicable laws.

👨‍💻 Author

@tuankiet2s

🙏 Acknowledgments

• yescrypt reference implementation
• UPX compression tool
• Alpine Linux for minimal base image
• Docker multi-stage builds

---

Remember: With great power comes great responsibility. Use this tool ethically and legally.