tosint is a Python OSINT tool that profiles Telegram bots, chats, and administrators via the Bot API, exporting structured intelligence for authorized investigators and DFIR teams.
| Tool | drego85/tosint — Python Telegram OSINT tool that extracts bot, chat, and admin intelligence from bot tokens and target chats |
| Category | OSINT / threat intelligence collection |
| Primary Use | Enriching Telegram bots, channels, groups and DMs during phishing and malware investigations, plus forensic export of chat history and media via getChat, getWebhookInfo, and MTProto downloads |
| Safe Use | Lawful investigative, DFIR, and threat intelligence work on infrastructure you are authorized to analyze; the README explicitly forbids illegal use, unauthorized access, and violations of Telegram's Terms of Service |
| Telemetry Note | All calls are read-only Bot API reads except --create-invite-link; analysis of a bot token enumerates webhook, commands, and admin membership through Telegram's servers, and downloads write Pyrofork session files under sessions/ and evidence under downloads/ |
tosint is a Python-based OSINT utility, published under GPL-3.0 with 849 stars on GitHub, aimed at investigators, threat analysts, and security researchers who need to profile Telegram infrastructure tied to phishing, malware delivery, and credential-theft campaigns. The tool takes a Telegram bot token via -t and optionally a chat ID via -c, then systematically interrogates the Telegram Bot API to produce a structured intelligence picture. It sits squarely in the enrichment phase of an investigation: you have recovered a bot token from a phishing kit or incident response artifact, and you need to know what that bot is, where it forwards data, and which chat it serves. The project frames itself explicitly for lawful DFIR and threat intelligence use, a stance worth noting because the same API calls could be misused against infrastructure you do not control.
The bot intelligence module is the most instructive part of the design. Given only a token, tosint calls getMyDescription, getMyShortDescription, getMyCommands, and getChatMenuButton to reconstruct the bot's public-facing profile and registered command surface. Critically, getWebhookInfo is used to expose the bot's configured webhook URL and IP address — often the single most valuable pivot in a phishing investigation, since it reveals the attacker-controlled server receiving message traffic. The README is refreshingly honest about the semantics here: an empty webhook URL means no webhook is configured and does not identify a polling server, and can_read_all_group_messages describes privacy mode rather than guaranteed historical access. That kind of epistemic precision is rare in OSINT tooling and marks this as a project written by someone who has been burned by over-interpretation before.
Chat-side enrichment builds on getChat to pull title, type, ID, username, active usernames, and a normalized single-line description, along with policy flags such as visible history, hidden members, protected content, join-by-request, slow mode, and the auto-delete timer. Where linked_chat_id is present, tosint performs a second getChat against the linked discussion group, which is a common structure for channel-plus-comment-group malware distribution setups. getChatMemberCount gives a rough scale indicator, and getChatMember reports the analyzed bot's own status — administrator, member, or otherwise — in the target chat. Invite links are displayed when exposed by getChat, with an opt-in --create-invite-link flag that calls createChatInviteLink for investigators holding admin rights; the README is careful to note this requires appropriate bot administrator rights and does not revoke the existing primary link.
Administrator enumeration via getChatAdministrators is thorough: each admin is printed with an index, names, user ID, username, a bot flag, role (creator or administrator), custom title, and granular can_* permissions plus is_anonymous. The tool passes return_bots=True so other bot administrators appear alongside human ones — a small detail that matters, because bot co-administrators frequently reveal additional infrastructure in the same operation. This lookup is skipped for private chats, which is a sensible limitation given the API's behavior there. Failed enrichment calls are reported without aborting the remaining analysis, so a single missing permission does not wreck the whole run.
Output handling is dual-track. Default runs produce formatted human-readable text, while --json emits pure JSON to stdout suitable for piping into jq or a downstream enrichment pipeline, and --json-file persists the report to disk. The README documents that webhook, command, and menu results are also preserved under bot.webhook, bot.commands, and bot.menu_button keys in JSON. Optional fields are omitted from text output when Telegram does not return them, and the README explicitly warns that absence must not be interpreted as false — an important caveat when analysts compare reports across runs.
The download subsystem is where tosint earns its DFIR label. Using Pyrofork for MTProto access, it exports chat history in both a minimal TXT format and a richer JSONL format. Only JSONL carries full provenance: source chat_id, UTC message and edit timestamps, reply message ID, a per-message acquired_at acquisition stamp, original attachment filename, MIME type, Telegram-reported file size, file identifiers, and downloaded size in bytes. Naive local timestamps from Pyrofork are converted to UTC including the applicable daylight saving offset — a forensic nicety that avoids the classic DST ambiguity in evidence. SHA-256 hashing of downloaded media is off by default and enabled explicitly with --hash-media, streaming files in chunks and recording hash failures without failing the download itself.
Authentication for downloads supports two modes via --download-auth: bot (default), which reuses the CLI token, and user, which forces an interactive Pyrogram login via phone number or QR code. Sessions are kept separate by default under sessions/<bot_username>_<chat_id>/bot.session and user.session paths, with --session-name available for overrides. The README correctly notes that exports contain only messages Telegram makes available to the authenticated session, that deleted or inaccessible messages cannot be guaranteed to be recovered, and that different sessions may see different content — three sentences that should be pasted into every OSINT tool's documentation as a baseline of intellectual honesty.
The default --download-mode auto uses ID scan with bot authentication, and falls back from chat history to ID scan when user-authenticated history retrieval fails. ID scan requests up to 50 message IDs per batch, tunable with --download-batch-size between 1 and 200, skips missing IDs without discarding the batch, and distinguishes ids_scanned from unavailable_ids and exported counts. The README repeatedly stresses that unavailable IDs do not prove deletion — the counter counts requested IDs, not existence — which prevents the classic analyst error of treating a scan gap as evidence of spoliation. Attachment downloads cover photos, videos, documents, audio, voice, and video notes, while stickers, GIFs, link previews, and dice are excluded without being counted as failures; --skip-media-download skips attachments entirely.
Installation follows the standard pattern: clone the repository, create a virtual environment, and install from requirements.txt. The optional tgcrypto package is described as functionally unnecessary but strongly recommended for significantly faster MTProto upload and download throughput. MTProto features additionally require a Telegram API_ID and API_HASH obtained through Telegram's official process, which can be stored in a local .env file — the README specifies that only those two values are read from .env, and that bot tokens and chat IDs must always come through the CLI, a sensible separation that keeps the highest-value secret out of a config file.
From a defensive and evidentiary standpoint, there are operational considerations worth flagging for authorized use. Every Bot API call is read-only except --create-invite-link, so the default analysis footprint on Telegram's servers is minimal, but running the tool does authenticate the token and may be observable to the bot's operator through Telegram's own session and API logging. Exports land under downloads/<bot_username>/<chat_id>/ with per-chat separation, and --download-overwrite modes (ask, always, never) govern how the tool handles pre-existing acquisition directories — relevant when you need to preserve a prior evidence set. For anyone performing Telegram threat intelligence or DFIR under a lawful mandate, tosint is a well-documented, epistemically careful addition to the toolkit.
drego85/tosint.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.