A comprehensive Open Source Intelligence (OSINT) aggregation bot for Telegram with 30+ powerful modules. Built as an educational cybersecurity project demonstrating ethical intelligence gathering techniques.
π Live Demo: https://exon101.github.io/osint-bot
| Command | Description |
|---|---|
/ip |
IP geolocation, ISP, abuse score, Shodan data |
/domain |
DNS records, WHOIS, security headers, VirusTotal |
/user |
Cross-platform username hunting (30+ platforms) |
/social |
Detailed social media profile lookup (25 platforms) |
/malware |
File hash analysis via VirusTotal |
/email |
Email validation, disposable check, breach info |
/emailrecon |
Deep email reconnaissance (Gravatar, MX, ClearBit) |
/breach |
Data breach checker (HaveIBeenPwned) |
/phone |
Phone number validation & carrier lookup |
/number |
Advanced phone number analysis |
/dork |
Google dork generator (65+ dorks, 6 categories) |
| Command | Description |
|---|---|
/reverse |
Reverse image search (Google Lens, Yandex, TinEye, Bing) |
/face |
Face detection & analysis from photos |
/meta |
EXIF metadata extraction from images |
| Command | Description |
|---|---|
/vuln |
CVE vulnerability scanner (NVD + MITRE) |
/nuclei |
Template-based vulnerability scanner (ProjectDiscovery) |
/darkweb |
Breach monitoring (14 major breaches) |
/news |
Cybersecurity news aggregator (3 sources) |
/github |
Repo tracker, security scanner, trending |
| Command | Description |
|---|---|
/password |
Secure password generator (5 modes, entropy calc) |
/run |
Sandboxed code executor (Python/JS/Bash) |
/encode |
Hash & encoding tool (MD5, SHA, Base64, Hex) |
| Command | Description |
|---|---|
/subdomain |
Subdomain enumeration (crt.sh + Omnisint) |
/dns |
Full DNS recon (10 record types) |
/whois |
WHOIS domain registration lookup |
/port |
Port scanner (Shodan InternetDB + probing) |
| Command | Description |
|---|---|
/urlscan |
URL safety analyzer (headers, patterns, VirusTotal) |
/qr |
QR code generator & decoder |
/proxy |
Proxy manager with rotation (HTTP/HTTPS/SOCKS4/SOCKS5) |
- Python 3.10+
- Telegram Bot Token from @BotFather
- (Optional) Free API keys for enhanced features
# Clone the repository
git clone https://github.com/gamingextra/osint-bot.git
cd osint-bot
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env with your tokens
# Run the bot
python main.py# Required
TELEGRAM_TOKEN=your_bot_token_here
# Optional (free tiers)
IPINFO_API_KEY= # https://ipinfo.io/signup (50k/month)
VIRUSTOTAL_API_KEY= # https://www.virustotal.com/gui/my-apikey (500/day)
SHODAN_API_KEY= # https://api.shodan.io/register (100/week)
HUNTER_API_KEY= # https://hunter.io/api (1000/month)
ABUSEIPDB_API_KEY= # https://www.abuseipdb.com/account/api (1000/day)
GITHUB_TOKEN= # https://github.com/settings/tokens (5000/hr)
NUCLEI_API_KEY= # https://cloud.projectdiscovery.io (vuln scanning)
HIBP_API_KEY= # https://haveibeenpwned.com/API/Key (breach data)
CLEARBIT_API_KEY= # https://clearbit.com/docs (email enrichment)osint-bot/
βββ main.py # Entry point & handler registration
βββ config.py # Configuration & API keys
βββ database.py # SQLite operations
βββ requirements.txt # Dependencies
βββ .env.example # Environment template
βββ .gitignore
βββ README.md
βββ Dockerfile # Production Docker image
βββ Dockerfile.hf # HuggingFace Spaces Dockerfile
βββ docker-compose.yml # Docker Compose setup
βββ Makefile # Build & deploy shortcuts
βββ handlers/ # Command handlers (30+ modules)
β βββ start.py # Welcome, help, stats, interactive menu
β βββ ip_lookup.py # IP investigation
β βββ domain.py # Domain analysis
β βββ username.py # Username search (30+ platforms)
β βββ social_lookup.py # Social media deep lookup
β βββ hash_lookup.py # Malware hash check
β βββ email.py # Email validation
β βββ email_recon.py # Deep email recon
β βββ breach_lookup.py # Data breach checker
β βββ phone.py # Phone lookup
β βββ number_analysis.py # Advanced number analysis
β βββ google_dorks.py # Dork generator
β βββ metadata.py # EXIF extractor
β βββ vuln_scanner.py # CVE scanner (NVD)
β βββ nuclei_scanner.py # Nuclei template vuln scanner
β βββ darkweb_monitor.py # Breach monitor
β βββ hacker_news.py # News aggregator
β βββ github_tracker.py # Repo tracker
β βββ password_gen.py # Password generator
β βββ code_runner.py # Code executor
β βββ hash_tool.py # Hash/encode tool
β βββ subdomain_enum.py # Subdomain finder
β βββ dns_recon.py # DNS lookup
β βββ whois_lookup.py # WHOIS lookup
β βββ port_scan.py # Port scanner
β βββ url_scanner.py # URL safety
β βββ qr_tool.py # QR generate/decode
β βββ proxy.py # Proxy manager
β βββ reverse_image.py # Reverse image search
β βββ face_detect.py # Face detection
β βββ photo_router.py # Unified photo handler
βββ utils/ # Utilities
β βββ validators.py # Input validation
β βββ rate_limiter.py # Rate limiting
β βββ logger.py # Audit logging
β βββ formatters.py # Telegram HTML helpers
β βββ proxy_manager.py # Proxy rotation engine
βββ api_clients/ # External API wrappers
β βββ http_client.py # Generic HTTP client
β βββ ipinfo_client.py # IPInfo API
β βββ virustotal_client.py # VirusTotal API
β βββ shodan_client.py # Shodan API
β βββ nvd_client.py # NVD API
β βββ nuclei_client.py # ProjectDiscovery Nuclei API
β βββ github_client.py # GitHub API
β βββ hunter_client.py # Hunter.io API
β βββ abuseipdb_client.py # AbuseIPDB API
βββ templates/
β βββ messages.py # Message templates
βββ docs/ # GitHub Pages website
β βββ index.html # Landing page
β βββ style.css # Styles
β βββ script.js # Interactions
β βββ assets/ # Images & assets
βββ tests/ # Unit tests
βββ scripts/ # Setup & deploy scripts
βββ deployment.md # Deployment guide
βββ huggingface_deployment.md # HuggingFace Spaces guide
- β Input validation & sanitization on all commands
- β Sliding-window rate limiting per user (10 req/60s)
- β Audit logging of all queries (SQLite)
- β Sandboxed code runner with blacklisted commands
- β No sensitive data stored (passwords not logged)
- β Proxy rotation support (HTTP/HTTPS/SOCKS4/SOCKS5)
- β Private IP / cloud metadata endpoint blocking
- β Educational disclaimers throughout
The /nuclei command integrates ProjectDiscovery Nuclei via their Cloud API for template-based vulnerability scanning:
/nuclei # Show interactive menu
/nuclei scan https://target.com # Run a quick scan
/nuclei scan target.com critical # Scan with severity filter
/nuclei templates xss # Search for templates
/nuclei status <scan_id> # Check scan results
/nuclei list # List recent scans
/nuclei cancel <scan_id> # Cancel a running scan
Get your API key at cloud.projectdiscovery.io.
The bot can be deployed multiple ways:
| Platform | Guide |
|---|---|
| Docker | docker build -t osint-bot . && docker run -d --env-file .env osint-bot |
| VPS / Bare Metal | See deployment.md |
| Heroku / Railway / Render | See deployment.md |
| HuggingFace Spaces | See huggingface_deployment.md |
| GitHub Pages | Set source to docs/ folder |
This tool is designed for EDUCATIONAL PURPOSES ONLY.
- Use only for authorized security research
- Respect privacy laws and regulations
- Do not use for harassment or illegal activities
- All queries are logged for accountability
- Port scanning and vulnerability scanning only on authorized targets
MIT License β see LICENSE for details.
Made with β€οΈ for Cybersecurity Education