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 (optimized) | 42.5KB | UPX LZMA ultra-brute |
| This tool (original) | 45.7KB | 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 and aggressive optimization flags
3. **Enhanced binary stripping** to remove debug symbols and unused sections
4. **UPX LZMA compression** with ultra-brute mode for maximum compression
5. **Scratch base image** for minimal size

## 🏗️ Building

```bash
# Build the optimized image (recommended)
docker build -t bruteforce-optimized -f brute/source/Dockerfile.optimized brute/source

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

# Check image sizes
docker images bruteforce-optimized bruteforce-test
```

## 🚀 Usage

### Basic Usage
```bash
# 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
```bash
# Using optimized image (recommended)
docker run --rm \
  --volume "/etc:/etc" \
  --volume "$(pwd)/brute/source/wordlist2.txt:/wordlist2.txt" \
  bruteforce-optimized:latest \
  root /wordlist2.txt

# Using original image
docker run --rm \
  --volume "/etc:/etc" \
  --volume "$(pwd)/brute/source/wordlist2.txt:/wordlist2.txt" \
  bruteforce-test:latest \
  root /wordlist2.txt
```

#### Crack specific user password
```bash
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

#### Optimized Version (Recommended)
```bash
gcc -static -Os -s \
    -fomit-frame-pointer \
    -fdata-sections \
    -ffunction-sections \
    -fno-unwind-tables \
    -fno-asynchronous-unwind-tables \
    -Wl,--gc-sections \
    -Wl,--strip-all \
    -o bruteforce \
    bruteforce.c \
    yescrypt-ref.c \
    yescrypt-common.c \
    sha256.c \
    insecure_memzero.c \
    && strip --strip-all \
        --remove-section=.comment \
        --remove-section=.note.* \
        --remove-section=.eh_frame \
        bruteforce \
    && upx --lzma --ultra-brute bruteforce
```

#### Original Version
```bash
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
- **Aggressive size optimization**: `-Os` flag with additional optimizations
- **Enhanced symbol stripping**: Remove debug symbols and unused sections
- **UPX LZMA compression**: Ultra-brute mode with LZMA algorithm for maximum compression
- **Dead code elimination**: `--gc-sections` to remove unused functions
- **Frame pointer omission**: `-fomit-frame-pointer` for smaller binaries
- **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**
   ```bash
   # Run with root user
   --user root
   ```

2. **Wordlist not found**
   ```bash
   # 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.