Telegram IOC Resolver

A production-ready, highly resilient asynchronous Python tool built on the MTProto API (Telethon) to resolve, classify, and extract metadata from massive lists of Telegram Indicators of Compromise (IOCs).

https://github.com/stukryptx/TeleScope

---

⚡ Features

• Asynchronous Engine: Leverages pure asyncio and Telethon to quickly parse massive lists of domains safely.
• Deep Metadata Extraction: Resolves Entity Type (User, Bot, Channel, Supergroup), Display Name, Telegram ID, Members count, Bio/Description, and Security Flags (Verified/Scam/Fake/Restricted).
• Anti-Ban Architecture: Intelligent handling of Telegram rate limits (FloodWait), invalid usernames, deleted accounts, network errors, and session state persistence.
• Streaming Table Output: Results are continuously streamed into a clean, formatted Markdown table as they are successfully resolved.
• Smart Resume: Built-in state tracking allows you to pause processing and resume exactly where you left off later without losing data.

⚙️ Setup

Prerequisites

• Python 3.12+
• Telegram API ID and Hash (obtainable via my.telegram.org)

Installation

1. Clone the repository:

   git clone https://github.com/stukryptx/TeleScope.git
   cd TeleScope

2. Install dependencies:

   pip install -r requirements.txt

3. Configure the Environment:

   cp .env.example .env

   Open .env and fill in your API_ID and API_HASH.

🚀 Usage

By default, the script looks for a file named Cleaned_IOC.txt in the root directory.

Basic Run

python main.py

Custom IOC File

You can specify any text file containing newline-separated Telegram URLs using the --file or -f argument:

python main.py --file path/to/your/iocs.txt

Advanced Flags

You can automate interactions with target accounts using the --join flag:

python main.py --file path/to/your/iocs.txt --join

• --join: Automatically sends /start to Bots, and executes Join requests on Channels, Supergroups, and Private Invites. (Warning: Use cautiously on bulk lists to avoid Telegram FloodWait restrictions).

Authentication

On the first run, the script will interactively prompt you for your Telegram phone number and 2FA code. This generates a persistent .session file locally.

Interactive Pausing

While the script is running, you can safely pause it:

1. Type p and press Enter.
2. Type yes to confirm.
3. The script will safely shut down and save its exact state. Run python main.py again to immediately resume!

---

Disclaimer: Use responsibly and strictly adhere to Telegram's Terms of Service to avoid account bans.