0xdad0/telegram-credential-harvester

# 🔐 Telegram Credential Harvester Automated system for monitoring Telegram channels, extracting leaked credentials, and managing them via a web interface. Built for penetration testing, threat intelligence, and security research. ## ⚠️ Disclaimer **This tool is intended exclusively for:** - Authorized penetration testing activities - Security research and threat intelligence - Data breach verification for owned or client-authorized accounts - Red teaming with written authorization **Misuse of this tool may violate privacy and computer security laws. The user assumes full responsibility for its use.** ## 🚀 Features - **Automatic monitoring** of Telegram channels - **Intelligent extraction** of credentials in `email:password` format - **PostgreSQL database** optimized for large volumes - **Modern web interface** - **Advanced search** with regex support - **CSV export** of results - **Processed file tracking** to avoid duplicates - **Channel management** from the web interface - **Docker-ready** for quick deployment ## 📋 Prerequisites - Docker & Docker Compose - Telegram API credentials (get them from https://my.telegram.org/apps) - Active Telegram account ## 🛠️ Installation ### 1. Clone the repository git clone cd telegram-credential-harvester ### 2. Configuration Copy `.env.example` to `.env` and configure your credentials: cp .env.example .env nano .env Fill in the following fields: # Telegram API Credentials TELEGRAM_API_ID=your_api_id_here TELEGRAM_API_HASH=your_api_hash_here TELEGRAM_PHONE=+xxxxxxxxxx # Database Configuration POSTGRES_DB=credentials_db POSTGRES_USER=admin POSTGRES_PASSWORD=CHANGE_THIS_TO_A_SECURE_PASSWORD # Application Settings WEB_PORT=5000 ### 3. Obtaining Telegram credentials #### Step-by-step procedure to get API_ID and API_HASH: 1. **Access the Telegram developer portal** - Go to https://my.telegram.org/apps - If not already logged in, you will be prompted to sign in 2. **Login with your phone number** - Enter your phone number in international format (e.g. `+1 234 567 8900`) - Click "Next" - You will receive a confirmation code via the Telegram app or SMS - Enter the received code 3. **Create a new application** - If it's your first time, you will see an empty form - If you already have apps, click "Create new application" 4. **Fill in the registration form** App title: Credential Harvester Short name: cred_harvester Platform: Desktop Description: Security research and penetration testing tool - Other fields are optional - Click "Create application" 5. **Copy the credentials** After creation you will see: App api_id: 1234567 App api_hash: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 **⚠️ IMPORTANT**: - **NEVER share** these credentials - **NEVER commit** them to public repositories - Treat them like sensitive passwords 6. **Insert credentials into the .env file** TELEGRAM_API_ID=1234567 TELEGRAM_API_HASH=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 TELEGRAM_PHONE=+1xxxxxxxxxx #### Notes on API key security: - Each Telegram account can have **multiple applications** - Credentials are tied to your account - If credentials are compromised, you can **revoke them** from my.telegram.org - Telegram may **restrict or ban** improper API usage - **Rate limits**: respect Telegram's limits (already handled in the code) #### API access troubleshooting: **Issue**: "Phone number banned" - Possible previous improper API usage - Contact Telegram support: @SpamBot **Issue**: "Code expired" - The code is only valid for 5 minutes - Request a new code **Issue**: "Invalid phone number" - Always use the international prefix (e.g. `+1` for US) - Correct format: `+1xxxxxxxxxx` (no spaces, no dashes) ### 4. Starting the system docker-compose up -d On first launch, you will be asked to enter the Telegram verification code received via SMS/app. ### 5. Accessing the web interface Open your browser and go to: http://localhost:5000 ## 📱 Usage ### Discovering available channels Before adding a channel, you can view all channels/groups you have access to: 1. Go to the **Discover Channels** tab 2. Click **Load My Channels & Groups** 3. You will see a complete list including: - 📢 **Public and private channels** - 👥 **Groups** - 💬 **Private chats** 4. For each channel you will see: - Name and username (if available) - **Channel ID** (click to copy) - Member count - **Quick Add** button for fast addition **💡 Tip**: Use the search bar to filter channels by name, username, or ID ### Adding a channel **Method 1: Quick Add from Discover tab** 1. Find the channel in the "Discover Channels" tab 2. Click **Quick Add** 3. Confirm the addition **Method 2: Manual addition** 1. Go to the **Channels** tab 2. Enter the channel identifier: - Username: `@channelname` (for public channels) - Numeric ID: `-1001234567890` (copied from Discover tab) 3. Click **Add Channel** **Supported ID formats:** - Public channels: `@channelname` - Private channels/groups: `-1001234567890` - Regular groups: `-123456789` ### How to get a channel ID #### Method 1: Discover tab (Recommended) - Use the "Discover Channels" tab in the web interface - All IDs are displayed and can be copied with one click #### Method 2: Telegram bot 1. Add the bot [@getidsbot](https://t.me/getidsbot) on Telegram 2. Forward a message from the channel to the bot 3. The bot will reply with the ID #### Method 3: Telegram Web 1. Open the channel on [web.telegram.org](https://web.telegram.org) 2. The URL will contain the ID: `https://web.telegram.org/z/#-1001234567890` #### Method 4: Invite link - If you have a link like `https://t.me/+AbCdEfGhIjK`, the channel is private - You must first join the channel, then use the Discover tab ### Credential search 1. Go to the **Search** tab 2. Use the filters: - **Query**: search for specific emails or passwords - **Domain**: filter by domain (e.g. `gmail.com`) - **Regex**: advanced patterns (e.g. `^admin@.*\.com$`) 3. Click **Search** ### Exporting results 1. Perform a search 2. Click **Export CSV** 3. The file will be downloaded with all results ### Statistics In the **Statistics** tab you can view: - Top 10 most common domains - Credentials per channel - Aggregate statistics ## 🗂️ Project structure telegram-credential-harvester/ ├── docker-compose.yml # Container orchestration ├── Dockerfile # Application image ├── requirements.txt # Python dependencies ├── .env # Configuration (DO NOT commit!) ├── .env.example # Configuration template ├── README.md # This file ├── app/ │ ├── __init__.py │ ├── config.py # Configuration management │ ├── database.py # Database connection │ ├── models.py # SQLAlchemy models │ ├── telegram_client.py # Telegram client │ ├── parser.py # Credential parser │ ├── web_app.py # Flask application │ └── templates/ │ └── index.html # Web interface ├── downloads/ # Downloaded files (auto-created) └── session/ # Telegram session (auto-created) ## 🔧 Docker commands # Start the system docker-compose up -d # View logs docker-compose logs -f # View app logs docker-compose logs -f app # Stop the system docker-compose down # Restart docker-compose restart # Rebuild after changes docker-compose up -d --build # Access container shell docker-compose exec app bash # Access PostgreSQL docker-compose exec postgres psql -U admin -d credentials_db ## 🗄️ Database ### Main schema **Table: credentials** - Stores all extracted credentials - Optimized indexes on email, domain, channel - Discovery timestamp **Table: processed_files** - Tracks already processed files - SHA256 hash for duplicate detection - Credential count found **Table: telegram_channels** - Manages monitored channels - Active/inactive status - Last check and last message_id ### Useful queries -- Credentials by domain SELECT domain, COUNT(*) as count FROM credentials GROUP BY domain ORDER BY count DESC LIMIT 10; -- Statistics by channel SELECT source_channel, COUNT(*) as credentials FROM credentials GROUP BY source_channel; -- Latest discovered credentials SELECT email, domain, discovered_at FROM credentials ORDER BY discovered_at DESC LIMIT 100; ## 🔍 Supported patterns The parser automatically recognizes these formats: - `email:password` - `email|password` - `email;password` - `email,password` - `emailpassword` - UTF-8 - Latin-1 - CP1252 - ISO-8859-1 ## 🛡️ Security ### Best practices: 1. **Change the PostgreSQL password** in the `.env` file 2. **Do not expose port 5000** on the Internet without authentication 3. **Use a firewall** to restrict access 4. **Regular backups** of the database 5. **Monitor logs** for suspicious activity ### Adding authentication (optional) For production, consider adding: - Reverse proxy with NGINX - HTTP Basic authentication - HTTPS with SSL certificates - VPN or IP-restricted access ## 📊 Performance ### Implemented optimizations: - **PostgreSQL connection pooling** (10 + 20 overflow) - **Composite indexes** on frequently queried columns - **Batch processing** for multiple inserts - **Lazy loading** of results (pagination) - **Hash caching** for duplicate detection ### Recommended limits: - Max 1M rows per file (configurable) - Pagination 50 results (modifiable) - Scan interval: 5 minutes (modifiable in `telegram_client.py`) ## 🐛 Troubleshooting ### Container won't start # Check logs docker-compose logs app # Verify PostgreSQL is ready docker-compose logs postgres ### Telegram connection error - Verify `API_ID` and `API_HASH` - Check phone number format: `+1xxxxxxxxxx` - Delete session: `rm -rf session/*` and restart ### Database unreachable # Test connection docker-compose exec postgres pg_isready -U admin # Recreate database docker-compose down -v docker-compose up -d ### Files not being processed - Verify the channel is **active** in the Channels tab - Check that text files exist in the channel - Check logs: `docker-compose logs -f app` ## 🔄 Backup and Restore ### Database backup # Automatic backup docker-compose exec postgres pg_dump -U admin credentials_db > backup_$(date +%Y%m%d).sql # Compressed backup docker-compose exec postgres pg_dump -U admin credentials_db | gzip > backup_$(date +%Y%m%d).sql.gz ### Database restore # Restore from backup cat backup_20250101.sql | docker-compose exec -T postgres psql -U admin credentials_db # Restore from compressed file gunzip -c backup_20250101.sql.gz | docker-compose exec -T postgres psql -U admin credentials_db ## 📝 TODO / Roadmap - [ ] Multi-user authentication - [ ] Advanced dashboard with charts - [ ] Export in additional formats (JSON, XML) - [ ] Real-time notifications (Webhook, Email) - [ ] Have I Been Pwned API integration - [ ] Machine learning for pattern detection - [ ] Full REST API - [ ] Support for other social/platforms ## 📄 License This project is provided "AS IS" without warranties. Use it responsibly and in compliance with local laws. ## 🙏 Acknowledgements - Telethon - Python Telegram client - Flask - Web framework - PostgreSQL - Database - Docker - Containerization **⚠️ IMPORTANT: This tool must be used exclusively for legal and ethical purposes. The author assumes no responsibility for misuse.**

标签：通知系统