SniffleBot

🔍 Advanced OSINT Intelligence for Telegram
Investigate usernames, emails, IP addresses, and phone numbers — all from your Telegram chat.

Features • Installation • Configuration • Usage

---

🌟 Features

🔍 Comprehensive OSINT Toolkit

• Username Recon:
  • Basic search via Apify (30+ platforms)
  • Deep reconnaissance with Blackbird (100+ sources, premium only)
• Email Lookup:
  Discover associated profiles across social networks and data brokers
• IP Geolocation:
  Get country, region, ISP, coordinates, timezone, and more
• Phone Validation:
  Verify number format, detect carrier, line type, and location

💎 Smart Free & Premium Model

• Free tier: Full access to basic modules (Apify, phone validation, IP lookup)
• Premium tier: Unlock Blackbird deep-search, detailed analytics, and JSON exports
• Monetization-ready: Built-in support for Telegram Stars payments

🆓 Free API Usage with Smart Token Rotation

• No paid APIs required to start!
  Use free-tier tokens from supported services:
  • apilayer.com (phone validation)
  • ipgeolocation.io (IP geolocation)
  • Apify (username search)
• Automatic token management:
  The bot intelligently rotates between multiple tokens, detects rate limits, and skips invalid ones — just provide a list!

🌐 Multi-Language Support

• English & Russian interfaces out of the box
• Easy-to-extend localization system (add new languages in minutes)
• Language selection via /lang command

🛡️ Admin & Analytics Dashboard

• User management: Grant/revoke premium access (/give_prem, /remove_prem)
• Broadcast system: Send text/media messages to all users with preview & confirmation
• Real-time stats: Track total users, premium subscribers, and recent signups (/stats)
• Token health monitoring: Check API status and usage (/tokens_status)
• User lookup: View full profile by ID or username (/user_info)

⚡ Modern & Scalable Architecture

• Async-first: Built on Aiogram 3.x and AsyncIO
• Modular design: Each OSINT function is a self-contained module
• MongoDB backend: Secure user data, subscription status, and preferences
• State-safe: Uses FSM for complex user flows (e.g., broadcast wizard)

✅ Ready for production — just configure your .env and deploy!

🚀 Installation

SniffleBot is designed to run on any system with Python and MongoDB.
Follow these steps to get your OSINT bot up and running in minutes.

📋 Requirements

• Python 3.9 or higher
• MongoDB (local instance or cloud service like MongoDB Atlas)
• Git (to clone the repository)

💡 Tip: Use a virtual environment to avoid dependency conflicts.

🔧 Step-by-Step Setup

1. Clone the Repository

git clone https://github.com/Bebrowskiy/SniffleBot.git
cd SniffleBot

2. Create & Activate a Virtual Environment

# Create virtual environment
python -m venv .venv

# Activate it
source .venv/bin/activate    # Linux / macOS
# OR
.venv\Scripts\activate       # Windows

3. Install Core Dependencies

pip install -r requirements.txt

4. Configure Your Environment

Copy the example config and fill in your credentials:

cp .env-example .env

Then edit .env with your actual values (see next section)

5. Start the Bot

python main.py

If everything is configured correctly, you’ll see: [INFO] Bot started successfully!

⚙️ Configuration

All settings are managed through a .env file

Edit .env with your actual credentials:

BOT_TOKEN=1234567
MONGO_URI=your_mongodb_uri
ADMIN_ID=12345
IP_GEO_TOKENS=token1, token2
APIFY_TOKENS=token1, token2
NUM_TOKENS=token1, token2

BOT_TOKEN - your Telegram Bot Token

MONGO_URI - your Cluster URI

ADMIN_ID - your Telegram ID

IP_GEO_TOKENS - IPGEO Token

APIFY_TOKENS - APIFY Token

NUM_TOKENS - APILayer Token

💡 Pro Tip: Add multiple free-tier tokens to increase daily request limits!

The bot automatically rotates between tokens, skips invalid ones, and handles rate limits — just provide a list!

After configuring .env, run the bot and use /tokens_status (admin command) to verify all APIs are working:

📊 Total tokens: 2
🔄 Last used index: 1
🟢 Current token: abc123...

🎮 Usage

Once your bot is running, interact with it via Telegram commands and interactive menus.

▶️ Basic User Flow

1. Start the bot with /start
2. Choose your language with /lang (optional)
3. Select a module from the main menu:
   • 🔍 Search by nickname
   • 📧 Search by email
   • 🌐 IP address scanning
   • 📱 Scanning a phone number
4. Enter your query and get instant OSINT results!

🧑‍💼 Admin Commands

Only available to the user ID specified in ADMIN_ID:

Command	Description
/stats	View user statistics (total, premium, recent signups)
/give_prem <user_id>	Grant 30-day premium access
/remove_prem <user_id>	Revoke premium access
/user_info <username|id>	View full user profile from database
/tokens_status	Check health of all API tokens

💡 Broadcast Tip: The bot shows a preview before sending — no accidental mass messages!

💎 Premium Features

Users with active subscriptions unlock:

• 🔍 Username Search (VIP): Deep reconnaissance via Blackbird (100+ platforms)
• 📊 Extended IP/Phone Details: Coordinates, carrier, timezone, etc.

To activate premium, users can:

• Click 💳 Subscription in the main menu
• Complete payment via Telegram Stars

Admins can also grant premium manually via /give_prem.

---

📸 Screenshots

🖼️ All interface elements are localized — switch between English and Russian anytime!

---

🌐 Language Switching

Use /lang to change your interface language:

• 🇷🇺 RU — Полный русский интерфейс
• 🇬🇧 EN — Full English interface

Your preference is saved permanently in the database.

🤝 Contributing

We welcome contributions! Whether it's a bug fix, new OSINT module, or translation — your help is appreciated.

How to Contribute

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request