TgWitness is a self-hosted Telegram forensics platform that captures chat history, edits and deletions into a signed, verifiable journal for dfir and osint casework.
| Tool | phishdestroy/TgWitness — open-source Telegram chat exporter and forensic evidence preservation suite in Python |
| Category | Digital forensics / OSINT evidence collection |
| Primary Use | Capturing Telegram messages, edits, deletions and profiles into signed archives for dfir, osint and incident-response casework |
| Safe Use | Intended for authorized investigations: incident response, law-enforcement casework, threat-intelligence research on accounts and chats you are legally permitted to observe |
| Telemetry Note | The tool itself ships with no telemetry and keeps a localhost panel; its use is observable from the Telegram side as a telethon-style userbot session, so account activity and login notifications are the main footprint |
TgWitness is a Python project, released under the MIT license with roughly 205 stars, that positions itself not as another Telegram scraper but as an evidence-grade witness. The tagline in the README — "Messages change. Keep the evidence" — captures the core problem it addresses: Telegram allows participants to edit or delete messages retroactively, which destroys the historical record an investigator might later need. TgWitness records what was observed, when it was observed, and what changed, and wraps all of it in cryptographic structures that a third party can independently verify. The topic list (dfir, digital-forensics, chain-of-custody, rfc3161, telethon) makes the intended audience unmistakable: forensic analysts and OSINT practitioners building defensible case files.
The first thing that separates TgWitness from a typical telegram-export utility is its journal architecture. Captured observations — new messages, saved edits, deletion notices, preserved files — are appended to a signed, hash-linked journal, meaning every record is chained to its predecessor and covered by a signature. Exports ship with a standalone verifier (verify.py, invocable as python -m tgwitness.verify) so a recipient can check the archive's records, journal head and signing-key fingerprint against a key fingerprint transmitted through a separate channel. This is chain-of-custody thinking applied at the data-structure level rather than as paperwork, and the README backs it with a benchmark page citing 3,598,381 records across 48 verified archives from documented public-history runs starting 6 November 2026.
Verification does not stop at signatures. The README describes a layered set of checks: journal signatures and a manifest covering recorded bytes and ordering; retained checkpoints or an independent witness holding a length and head hash; external timestamps validated against a timestamp authority; GitHub Actions capture attestations that bind an archive to an approved workflow and collector revision; and optional Intel TDX measurements attesting the collection environment itself. The rfc3161 topic signals RFC 3161 timestamp-authority integration for proving when evidence existed. Notably, the authors state that "TgWitness takes no side: the same checks apply to the operator and the project" — an anti-tamper stance where even the person running the collector cannot silently rewrite the journal.
The workflow is deliberately casework-shaped: collect, investigate, share. Collection modes cover one-shot account exports, accessible history dumps, and continuous observation of chosen chats, with per-account workspaces, sessions and signing keys kept separate. Progress, pauses and retries stay visible, and the tool records source visibility, unavailable data and collection gaps in the saved record — a genuinely forensic touch, since a defense attorney will absolutely ask why a message is missing. Investigation tooling includes full-text search across saved material, version comparison, subject cards, watchlists, a Case Board for connecting findings, and local OCR and transcription for media analysis, with optional AI assistance.
Reporting is where many open-source collectors fall over, and TgWitness treats it as a first-class feature. You select chats or individual messages, edit the report cover, choose a design and charts, and preview before exporting to PDF, HTML or JSON. Reports are delivered alongside their verification data, so the artifact an investigator hands to a court or a client is not a screenshot but a package the recipient can cryptographically check. The project supports 25 interface languages and 26 guide languages, which suggests an audience well beyond the English-speaking OSINT community, including formal investigative contexts.
A surprising inclusion is Secret Chats support via an optional protocol module: TgWitness provides an integrated conversation view and exports for secret chats created or accepted by the tool itself, documented separately in docs/PSEUDO-SECRET.md. There are also optional recorders for official-client capture (Trusted Live, Sealed official Web), which broadens acquisition beyond the telethon-style API path. Analysts should read the capability record in docs/STATUS.md, which lists each acquisition mode and its qualification — an honest accounting of what each mode can and cannot prove, something the README emphasizes repeatedly.
Deployment options are unusually flexible for a forensic tool: local machine, server, Docker, a GitHub-hosted capture runner, or a Phala Intel TDX attested environment. The installer pulls signed builds from a dedicated Installer workflow, checks package hashes and release signatures against an embedded key, and tags each signed build with its source revision. Sessions and credentials live in an encrypted vault, the panel binds to localhost by default, and the project explicitly states it is self-hosted with no telemetry. Installation on Linux/macOS is a single curl -fsSL https://get.destroy.tools/install.sh | bash, with a PowerShell equivalent on Windows; rerunning the installer updates in place.
Automation surfaces matter for anyone wiring this into a SOC pipeline. Beyond the CLI, TgWitness exposes scoped MCP access for agent integration, signed webhooks for event-driven workflows, an n8n integration example, and access tokens with chat scopes for shared review. The account model supports account groups, session imports, proxies and IP modes for connection security — the docs recommend a dedicated account, which is sound tradecraft for any investigation that must survive scrutiny of how data was acquired.
From a defensive and operational-safety standpoint, the tool's own transparency is worth noting. The interactive demo uses fictional records only, the sample archive includes verify.py so anyone can exercise the verifier without a Telegram login, and documentation spans a security model, system map, verification handbook and an "Export Clinic" for checking packages before delivery. The version badge marks it as v0.9.3, a pre-release, so teams adopting it should expect format churn and pin their verifier versions when producing long-lived evidence.
Where does this fit in an authorized workflow? Think threat-intelligence monitoring of publicly accessible channels you are permitted to observe, incident response where Telegram was the exfiltration or coordination channel, OSINT investigations with documented legal basis, and internal investigations where an auditable record of what a subject posted — and then edited or deleted — matters. It is a collection-and-preservation layer, not an exploitation tool, and its insistence on verifiability cuts both ways: an opposing expert can run the same checks. For professionals who have lost evidence to a subject hitting delete, that property alone justifies a look.
The main caveats are practical. Legal authority for observing a given chat varies by jurisdiction, and a signed journal proves what was observed, not the legality of observing it — that remains the operator's burden, which the dedicated-account and security-model docs acknowledge. As a v0.9.x pre-release with heavy documentation, the project leans on its guides to compensate for maturity, but the measured benchmark, the signed delivery chain and the standalone verifier suggest engineering discipline uncommon in this niche. For dfir teams that need Telegram evidence to survive cross-examination, TgWitness is one of the more thoughtful options currently published.
phishdestroy/TgWitness.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.