🔐 CryptoLockerBot

A secure, async Telegram password manager with end-to-end encryption

CryptoLockerBot is a powerful and secure password management solution that runs entirely within Telegram. Your credentials are encrypted with a passphrase-derived key before touching disk, while an intuitive Telegram UI lets you add, search, edit, remove, and display entries in both English and Persian (Farsi).

✨ Features

• 🔒 End-to-End Encryption: PBKDF2-HMAC (SHA256, 240k iterations) + Fernet encryption
• 🐍 Modern Python: Built with Python 3.12 and python-telegram-bot v21 (async Application API)
• 💾 SQLite Storage: WAL mode enabled with per-user language preferences (en or fa)
• 🎨 Intuitive UI: Reply keyboard driven UX with inline keyboards for seamless navigation
• 📝 Comprehensive Logging: Rotating file logs (no plaintext passwords logged)
• 🚀 Easy Deployment: Systemd unit & guided installer for Ubuntu deployments
• 🌍 Multilingual: Full support for English and Persian languages

🚀 Quick Start (Recommended)

One-Line Installation

git clone https://github.com/zZedix/CryptoLockerBot.git && cd CryptoLockerBot && bash installer/install.sh

The installer will:

1. 📋 Prompt for the Telegram bot token, admin user ID, and encryption passphrase
2. 🛠️ Install Python 3.12 + build tooling, create a project virtualenv, and install dependencies
3. 🔐 Create ~/.cryptolocker/ (chmod 700), generate a random salt, and write config.env (chmod 600)
4. 🗄️ Initialize the SQLite database, write systemd service, and enable the service

After Installation

# Start the bot
sudo systemctl start cryptolocker

# Follow logs
journalctl -u cryptolocker -f

⚠️ Security Warning: Keep your passphrase, salt, and config.env safe. Losing any of them makes stored data unrecoverable.

🛠️ Manual Setup

Prerequisites

• Python 3.12+
• Ubuntu Linux (for systemd service)

Installation Steps

1. Clone the repository

   git clone https://github.com/zZedix/CryptoLockerBot.git
   cd CryptoLockerBot

2. Create virtual environment

   python3.12 -m venv .venv
   .venv/bin/pip install --upgrade pip
   .venv/bin/pip install -r requirements.txt

3. Set up configuration

   # Create config directory
   mkdir -p ~/.cryptolocker
   chmod 700 ~/.cryptolocker
   
   # Generate random salt
   python3.12 -c "import secrets; open('~/.cryptolocker/salt', 'wb').write(secrets.token_bytes(16))"
   chmod 600 ~/.cryptolocker/salt

4. Configure environment

   cp .env.example ~/.cryptolocker/config.env
   # Edit ~/.cryptolocker/config.env with your settings

5. Initialize database

   PYTHONPATH=$(pwd) python3.12 -c "
   import asyncio
   from db import Database
   db = Database('~/.cryptolocker/cryptolocker.db')
   asyncio.run(db.init())
   "

6. Run the bot

   .venv/bin/python bot.py

📱 Telegram Commands & Usage

Basic Commands

• /start, /menu – Show welcome message and main keyboard
• /lang en, /lang fa – Switch between English and Persian

Main Functions

• ➕ Add: Add new credentials with name, username, and password
• 🔍 Search: Search through your stored credentials
• ✏️ Edit: Modify existing usernames or passwords
• 🗑️ Remove: Delete credentials with confirmation
• 👁️ Show: Display credentials with secure inline buttons

Security Features

• All credentials are encrypted before storage
• Inline buttons for secure credential display
• Automatic message deletion after viewing
• No plaintext logging of sensitive data

🧪 Testing

Run the comprehensive test suite:

python -m unittest discover tests

Tests cover:

• Encryption/decryption functionality
• Database operations
• User state management
• Error handling

💾 Backup & Restore

Backup These Files Together

• ~/.cryptolocker/cryptolocker.db (encrypted database)
• ~/.cryptolocker/salt (encryption salt)
• ~/.cryptolocker/config.env (configuration)

Restore Process

1. Restore files with original permissions:
   • config.env & salt → 600
   • Directory → 700
2. Start the service: sudo systemctl start cryptolocker

Important: Without the original passphrase AND salt, decryption is impossible.

📊 Monitoring & Logs

Systemd Logs

# Follow real-time logs
journalctl -u cryptolocker -f

# View recent logs
journalctl -u cryptolocker --since "1 hour ago"

File Logs

# Follow log file
tail -f ~/.cryptolocker/cryptolocker.log

# View recent entries
tail -n 100 ~/.cryptolocker/cryptolocker.log

🤝 Contributing

We welcome contributions! Please follow these guidelines:

• 🌍 Keep new strings in i18n.py translated for both English and Persian
• 🔒 Never log sensitive data (usernames, passwords, etc.)
• 🏗️ Extend the StateManager for new interaction flows
• ✅ Add tests for new functionality
• 📝 Update documentation for new features

Development Setup

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

💰 Donations

If you find CryptoLockerBot useful and want to support its development, consider making a donation:

Cryptocurrency Donations

• Bitcoin (BTC): bc1q637gahjssmv9g3903j88tn6uyy0w2pwuvsp5k0
• Ethereum (ETH): 0x5B2eE8970E3B233F79D8c765E75f0705278098a0
• Tron (TRX): TSAsosG9oHMAjAr3JxPQStj32uAgAUmMp3
• USDT (BEP20): 0x5B2eE8970E3B233F79D8c765E75f0705278098a0
• TON: UQA-95WAUn_8pig7rsA9mqnuM5juEswKONSlu-jkbUBUhku6

Other Ways to Support

• ⭐ Star the repository if you find it useful
• 🐛 Report bugs and suggest improvements
• 📖 Improve documentation and translations
• 🔗 Share with others who might benefit

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Repository: https://github.com/zZedix/CryptoLockerBot
• Issues: Report a bug or request a feature

---

Made with ❤️ by zZedix

Securing the digital world, one line of code at a time!