DOCSEARCHbyAlgolia
Submit Docs

TGSpyder

repository·main·Indexed 43 days ago

https://github.com/darksight-analytics/tgspyder

An open-source Telegram OSINT CLI tool (v1.0.0) for investigators and researchers to scrape structured data. Key capabilities include scraping member lists and chat messages, extracting t.me invite links, performing user lookups via ID or username, and identifying sticker pack creator IDs. Supports SOCKS proxies and requires Telegram API credentials for authentication via user account or bot token.

Tokens
2.3K
Snippets
7
Records
11
Agent score
55%

What's inside TGSpyder

  1. Overview of TGSpyder features

    main

    TGSpyder is a Telegram OSINT CLI tool designed for scraping and data extraction. Key capabilities include:

    • Member Scraping: Export a list of chat members to a CSV file.
    • Message Scraping: Export chat message history to a CSV file.
    • Link Extraction: Extract t.me invite links from chat history.
    • User Lookup: Look up Telegram users via username or numeric ID.
    • Sticker Analysis: Identify sticker pack creator IDs using sticker set IDs.
    • Proxy Management: Supports saving, removing, or using one-off proxies for requests.

  2. Obtain Telegram API Credentials

    main

    TGSpyder requires Telegram API credentials to authenticate with the Telegram platform.

    1. Visit https://my.telegram.org and log in with your Telegram account.
    2. Navigate to API development tools.
    3. Generate an API ID and an API Hash.

    On your first run, TGSpyder will prompt you to enter these credentials, along with your user account or a bot token. These are stored locally in ~/.tgspyder.conf.

  3. Lookup Telegram users and sticker pack creators

    main

    TGSpyder provides lookup capabilities for specific Telegram entities.

    • User Lookup: Use the --user flag with either a numeric ID or a @username.
    • Sticker Pack Creator Lookup: Use the --sticker-pack flag with the sticker pack URL to attempt to identify the creator ID.
    # Lookup by numeric ID
tgspyder --user 123456789

# Lookup by username
tgspyder --user @username

# Lookup sticker pack creator
tgspyder --sticker-pack https://t.me/addstickers/packname

  4. Configure SOCKS proxy support

    main

    TGSpyder supports SOCKS proxies (useful for Tor or VPN usage). You can use a proxy for a single command or save it for future sessions.

    • One-off proxy: Use the --proxy flag.
    • Save proxy: Use the --set-proxy flag.
    • Remove proxy: Use the --remove-proxy flag.
    # Use a one-off proxy
tgspyder --proxy socks5://127.0.0.1:9050 <target> --chats

# Save a proxy for future runs
tgspyder --set-proxy socks5://127.0.0.1:9050

# Remove the saved proxy
tgspyder --remove-proxy

  5. Install TGSpyder

    main

    To install TGSpyder, clone the repository, set up a virtual environment, and install the dependencies and the package in editable mode.

    Requirements:

    • Python 3.10+

    Installation Steps:

    1. Clone the repository.
    2. Create and activate a virtual environment.
    3. Install requirements.
    4. Install the package as a CLI tool using pip install -e ..

    Verify the installation by running tgspyder --help.

    git clone https://github.com/Darksight-Analytics/tgspyder.git
cd tgspyder
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e .

  6. Scrape members, chats, and invite links

    main

    Use the tgspyder command followed by a Telegram group/channel URL and specific flags to collect data.

    • Scrape members and chats: Use --members and --chats flags.
    • Extract invite links only: Use the --crawl-invites flag.

    All data is exported to CSV files within the TGSpyder Output/ directory, organized into members/, chats/, and crawled_links/ subfolders.

    # Scrape members and chats
tgspyder https://t.me/examplegroup --members --chats

# Extract invite links only
tgspyder https://t.me/examplegroup --crawl-invites

  7. Use the TGSpyder CLI for Telegram OSINT

    main

    TGSpyder is a command-line tool for performing Telegram Open Source Intelligence (OSINT). It allows you to scrape member lists, crawl chat messages, extract invite links, identify sticker pack creators, and look up user details.

    Core Capabilities:

    • Scrape Members: Extract user IDs, usernames, names, profile links, and phone numbers from groups.
    • Scrape Chats: Export chat message history to CSV.
    • Crawl Invites: Extract t.me invite links from chat history.
    • Sticker Pack Lookup: Identify the creator of a sticker pack using a URL or shortname.
    • User Lookup: Resolve Telegram user details via ID or username.

    Output Structure: Results are saved in a TGSpyder Output/ directory relative to your current working directory, organized into subfolders:

    • members/: CSV files containing member lists.
    • chats/: CSV files containing message history.
    • crawled_links/: CSV files containing extracted invite links.
    # Example: Scrape members and messages from a group
tgspyder <group_url_or_username> --members --chats

# Example: Identify a sticker pack creator
tgspyder --sticker-pack https://t.me/emojipack

# Example: Lookup a specific user
tgspyder --user @username

  8. Configure TGSpyder API credentials and authentication

    main

    TGSpyder requires Telegram API credentials (api_id and api_hash) to function. These are stored in a configuration file located at ~/.tgspyder.conf.

    Authentication Modes:

    1. User Account: Requires your phone number (international format, e.g., +123456789) and a login code sent via Telegram.
    2. Bot Token: Requires a Telegram Bot Token.

    Managing Credentials:

    • Initial Setup: Run any command; if no config is found, the CLI will prompt you for your api_id, api_hash, and authentication method.
    • Reset Credentials: Use the --reset-creds flag to clear existing credentials and re-authenticate.
    • Configuration File: The tool uses a JSON file at ~/.tgspyder.conf to persist api_id, api_hash, phone, bot_token, and proxy settings.
    # Reset credentials to re-authenticate
tgspyder --reset-creds

  9. Configure and use proxies in TGSpyder

    main

    TGSpyder supports proxy configurations to bypass network restrictions. You can use a one-off proxy for a single command or save a proxy to your configuration for all future runs.

    Proxy Formats:

    1. URL Format: scheme://user:pass@host:port (e.g., socks5://user:password@127.0.0.1:9050)
    2. Colon-Delimited Format: type:host:port[:user][:pass] (e.g., socks5:127.0.0.1:9050:myuser:mypass)

    Commands:

    • One-off proxy: Use --proxy <proxy_string> to use a proxy without saving it.
    • Save proxy: Use --set-proxy <proxy_string> to save the proxy to ~/.tgspyder.conf.
    • Remove proxy: Use --remove-proxy to clear the saved proxy from your config.

    Requirement: Proxy support requires the pysocks library (pip install pysocks).

    # Use a proxy for one command
tgspyder <target> --members --proxy socks5://127.0.0.1:9050

# Save a proxy permanently
tgspyder --set-proxy socks5://127.0.0.1:9050

# Remove saved proxy
tgspyder --remove-proxy

  10. TGSpyder CLI Reference

    main

    Commonly used CLI flags for TGSpyder:

    FlagDescription
    --membersScrape member list from the target group
    --chatsScrape/crawl chat messages from the target group
    --crawl-invitesExtract and de-duplicate Telegram invite links
    --user <ID/username>Lookup a Telegram user by ID or username
    --sticker-pack <URL>Identify sticker pack creator ID
    --proxy <URL>Use a SOCKS proxy for the current command
    --set-proxy <URL>Save a SOCKS proxy for future runs
    --remove-proxyRemove the saved proxy configuration

  11. Reference: TGSpyder CLI arguments and flags

    main

    The following table lists the available command-line arguments for the tgspyder tool.

    ArgumentDescription
    target (positional)The target Telegram group/channel (username or invite link)
    --membersScrape and save the member list to TGSpyder Output/members/
    --chatsScrape chat messages to TGSpyder Output/chats/
    --crawl-invitesExtract t.me invite links from chat history to TGSpyder Output/crawled_links/
    --sticker-pack, -sIdentify the creator of a sticker pack (accepts shortname or full URL)
    --userLookup a Telegram user by ID or username
    --proxyOne-off proxy override for this run (not saved)
    --set-proxySave proxy to config for future runs
    --remove-proxyRemove the saved proxy from config
    --reset-credsReset API credentials and re-authenticate