Skip to content
Exon101Public

About

πŸ•΅οΈ OSINT Investigation Bot - 22 Telegram modules for ethical intelligence gathering

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ•΅οΈ OSINT Investigation Bot

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

✨ Features Overview

πŸ” OSINT Investigation Tools

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)

πŸ–ΌοΈ Image & Photo Intelligence

Command Description
/reverse Reverse image search (Google Lens, Yandex, TinEye, Bing)
/face Face detection & analysis from photos
/meta EXIF metadata extraction from images

πŸ›‘οΈ Advanced Security Features

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

🧩 CTF & Developer Tools

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)

🌐 Network Reconnaissance

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)

πŸ”— URL, QR & Proxy Tools

Command Description
/urlscan URL safety analyzer (headers, patterns, VirusTotal)
/qr QR code generator & decoder
/proxy Proxy manager with rotation (HTTP/HTTPS/SOCKS4/SOCKS5)

πŸš€ Quick Start

Prerequisites

  • Python 3.10+
  • Telegram Bot Token from @BotFather
  • (Optional) Free API keys for enhanced features

Installation

# 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

Environment Variables

# 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)

πŸ“ Project Structure

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

πŸ›‘οΈ Security Features

  • βœ… 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

☒️ Nuclei Integration

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.

🚒 Deployment

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

⚠️ Ethical Disclaimer

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

πŸ“ License

MIT License β€” see LICENSE for details.


Made with ❀️ for Cybersecurity Education

About

πŸ•΅οΈ OSINT Investigation Bot - 22 Telegram modules for ethical intelligence gathering

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages