ProxBox - Your Proxmox toolbox for secure VM automation
ProxBox is a modern Python package and CLI tool for automating Proxmox VE operations with a focus on security, reliability, and operational excellence.
- 🚀 Template Creation - Automated Ubuntu cloud-init template creation from official images
- 🖥️ VM Management - Clone, start, stop, and manage VMs with ease
- 🔒 Security First - Input validation, sanitization, and command injection prevention
- 📊 Rich UI - Progress bars, colored output, and helpful error messages
- 🔄 Retry Logic - Automatic retry with exponential backoff for network operations
- ✅ Type Safe - Full type hints and mypy compliance
- 🧪 Well Tested - Comprehensive test suite with >80% coverage
- 📚 Documented - Extensive documentation with examples
pip install proxbox
# Create Ubuntu 22.04 LTS template
proxbox create-template jammy 9001 --ssh-key ~/.ssh/id_rsa.pub
# Create template with custom settings
proxbox create-template noble 9002 \
--name my-ubuntu-template \
--memory 4096 \
--disk-increase 50
# Clone a VM from template and start it
proxbox create-vm 9001 190 my-ubuntu-vm --start
# Check VM status
proxbox status 190
# Stop a VM
proxbox stop 190
# Delete a VM (with confirmation)
proxbox delete 190
Full documentation is available at: https://zerodaysec.github.io/proxmox-utilities
Configure via environment variables or .env file:
# SSH key for cloud-init
export PROXMOX_SSH_KEY_PATH="$HOME/.ssh/id_ed25519.pub"
# Storage configuration
export PROXMOX_DATA_STORE="local-lvm"
export PROXMOX_VM_BRIDGE="vmbr0"
# Template defaults
export PROXMOX_TEMPLATE_MEMORY_MB=2048
export PROXMOX_TEMPLATE_DISK_INCREASE_GB=30
See Configuration Guide for all options.
Security is a top priority. This project includes:
- ✅ Input validation and sanitization
- ✅ Command injection prevention
- ✅ No hardcoded secrets
- ✅ Automated security scanning (Bandit, pip-audit)
- ✅ Type safety with mypy
- ✅ Comprehensive test coverage
See Security Documentation for details.
| Feature | Shell Scripts (v0.0.1) | Python Package (v0.1.0+) |
|---|---|---|
| Security | ✅ Comprehensive | |
| Error Handling | ❌ Minimal | ✅ Robust |
| Testing | ❌ None | ✅ >80% coverage |
| Type Safety | ❌ No | ✅ Full type hints |
| Progress Tracking | ❌ No | ✅ Rich UI |
| Retry Logic | ❌ No | ✅ Automatic |
| Documentation | ✅ Full docs site | |
| Package Management | ❌ Manual download | ✅ pip install |
git clone https://github.com/zerodaysec/proxmox-utilities.git
cd proxmox-utilities
pip install -e ".[dev,docs,security]"
pre-commit install
# Run all tests
pytest
# Run with coverage
pytest --cov=src/proxbox --cov-report=html
# Run specific tests
pytest tests/test_template.py -v
# Format code
black src/ tests/
# Lint
ruff check src/ tests/
# Type check
mypy src/
# Security scan
bandit -r src/
# Serve locally
mkdocs serve
# Build
mkdocs build
See CHANGELOG.md for version history and migration guides.
Contributions are welcome! Please see Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
pytest) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the GNU General Public License v3.0 or later (GPLv3+).
See LICENSE for the full license text.
ZeroDay Security
- Email: jon@zer0day.net
- GitHub: @zerodaysec
- Proxmox VE team for excellent virtualization platform
- Ubuntu for cloud images
- Python community for amazing tools and libraries
Made with ❤️ by ZeroDay Security