# TgWitness > Open-source Telegram investigation workspace. Export chats and whole accounts, keep every observed edit and deletion notice, follow people across chats, and hand over signed archives that recipients verify on their own computers. TgWitness runs on your own computer or server and is maintained by PhishDestroy under the MIT License. These pages track the `main` source branch, version `0.9.3`; the browser demo uses fictional records. ## Key facts - Live observation saves each version of a message and keeps its text after a deletion notice; history export reads the accessible history of selected chats or the whole account. - Every record is signed and hash-chained. Recipients verify an archive offline with the bundled verifier, a separately received key fingerprint and retained checkpoints; independent witnesses add checkpoints, and RFC 3161 and OpenTimestamps add external time. - Messages arrive over the account's authenticated MTProto session and are signed on receipt. GitHub Actions capture and Phala Intel TDX deployments add attestation of the collector that received them. - Published measurements: 56,329 messages in two fresh exports on 6 November 2026, a 1,000,000-message search benchmark and a 1 November inventory of 1,610,818 journal events. - Investigation tools: people profiles across chats, watchlists over text, QR codes and OCR, Case Board, a report studio with eight designs and a BagIt court package. - Self-hosted with no telemetry: sessions and credentials live in an encrypted vault, and the panel listens on localhost. The vault key stays in the data directory unless a new installation uses an external master key. Basic collection runs without Docker, a GPU or an LLM. - Developed and tested for about six months before the public repository was created. The private regression suite has 126 test modules; public CI runs lint, dependency audits, wheel installs, installer signature checks, CodeQL, Trivy and verifier fuzzing. ## Start here - [TgWitness: start, scale and evidence](https://phishdestroy.io/tgwitness/docs/reference/overview/index.md): Install with one command or capture on GitHub Actions. Understand investigation options, published scale and what an archive verifies. - [Install, verify and update](https://phishdestroy.io/tgwitness/docs/reference/installation/index.md): Install with one command, check signatures and hashes, update and remove an installation. - [Start in minutes](https://phishdestroy.io/tgwitness/docs/start/index.md): Install with one command, connect a Telegram account and export a verifiable archive on Windows, Linux or macOS. - [GitHub Actions capture](https://phishdestroy.io/tgwitness/docs/capture/index.md): Choose Takeout, regular API export or a chat journal on a temporary GitHub runner. - [Dedicated account](https://phishdestroy.io/tgwitness/docs/dedicated-account/index.md): Prepare a separate Telegram account for collection. - [Connect an account](https://phishdestroy.io/tgwitness/docs/accounts/index.md): Connect Telegram by QR code, phone number or session import. Choose sources and check that new messages reach your journal. - [Collection modes and evidence levels](https://phishdestroy.io/tgwitness/guides/modes.md): Compare one-off export, observation, investigation and independent verification. - [Read-only browser demo](https://phishdestroy.github.io/TgWitness/demo/): Explore the panel with fictional accounts and messages. ## Investigate and preserve - [Investigate across all chats](https://phishdestroy.io/tgwitness/docs/cases/index.md): Run an end-to-end Telegram investigation across channels, groups, private chats and bots: whole-account capture, history, people, links, files, timelines and verified evidence. - [Build a Case Board](https://phishdestroy.io/tgwitness/docs/case-board/index.md): Collect saved observations, exact highlights and action slices on a private board, discuss them with your team and present a collection. - [Manage a group of accounts](https://phishdestroy.io/tgwitness/docs/groups/index.md): Compare group workspaces, find a source, review observation periods and apply shared settings with per-account exceptions. - [How collection works](https://phishdestroy.io/tgwitness/docs/reference/collection/index.md): Observation scope, live updates, rechecks, attachments, own actions and what a gap means, record by record. - [Load source history](https://phishdestroy.io/tgwitness/docs/reference/history/index.md): Load past messages from enabled sources, pause and resume, and verify a signed progress report. - [Export and verify](https://phishdestroy.io/tgwitness/docs/exports/index.md): Export captured Telegram history, verify signatures and compare a journal with a checkpoint retained by an independent witness. - [Design a report](https://phishdestroy.io/tgwitness/docs/reports/index.md): Choose report data, one of eight designs and the contents, then preview and export HTML, signed PDF or a complete evidence package. - [Prepare a sharing copy](https://phishdestroy.io/tgwitness/docs/handover/index.md): Choose the records and fields a recipient can receive, inspect the finished copy and verify its signed manifest and source journal boundary. - [Case Board reference](https://phishdestroy.io/tgwitness/docs/reference/case-board/index.md): Bookmarks, exact highlights, action slices, discussions, scoped access and the signed annotation history used by Case Board. - [Report configuration and verification](https://phishdestroy.io/tgwitness/docs/reference/case-reports/index.md): Report filters, eight designs, contents presets, saved change histories and the assessment included in signed exports. - [Evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/index.md): Contents of the signed ZIP, record kinds, process receipts, people profiles, off-site copies and offline verification. ## Search the archive and connect AI tools - [Work the archive](https://phishdestroy.io/tgwitness/docs/archive/index.md): Load history, search saved records, review AI sources and connect your tools. - [Archive analysis](https://phishdestroy.io/tgwitness/docs/reference/analysis/index.md): Search saved messages, review AI inputs and keep analytical reports with their source references. - [Full-text search](https://phishdestroy.io/tgwitness/docs/reference/search/index.md): Find saved messages by word forms, exact phrases, domains and @usernames, best matches first, with the index bound to the signed journal. - [Read-only MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/index.md): Connect an MCP client to selected workspaces and chats with expiring, revocable access. - [Command line](https://phishdestroy.io/tgwitness/docs/reference/cli/index.md): Search, read context, count activity and export saved messages from scripts and agents, with --json output, stable exit codes and scoped read-only tokens. - [Local OCR and transcription](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/index.md): Recognize captured images and audio with a local worker; keep derived text linked to its source file. - [Outgoing webhooks](https://phishdestroy.io/tgwitness/docs/reference/webhooks/index.md): Send scoped events to HTTPS receivers with HMAC signatures, retries and delivery status. ## Deploy, share and verify - [Keep it running](https://phishdestroy.io/tgwitness/docs/server/index.md): Run TgWitness on a server with persistent storage, private panel access, backups and checks after a restart. - [GitHub Actions capture](https://phishdestroy.io/tgwitness/docs/capture/index.md): Choose Takeout, regular API export or a chat journal on a temporary GitHub runner. - [Choose a proxy](https://phishdestroy.io/tgwitness/docs/proxies/index.md): Maintain automatic MTProxy routes or use your own proxy. Choose IP modes, fallback rules and the route for external requests. - [Share a case](https://phishdestroy.io/tgwitness/docs/access/index.md): Give reviewers and analysts access to selected accounts and chats, with separate permissions, session limits and revocable tokens. - [See how evidence works](https://phishdestroy.io/tgwitness/docs/concepts/index.md): Follow a message from capture to checkpoint. Change a sample record, recalculate its SHA-256 chain and see what a retained checkpoint detects. - [Set up a witness bot](https://phishdestroy.io/tgwitness/docs/witness/index.md): Publish signed journal checkpoints to your Telegram channel with a separate witness, its own key and read-only collector access. - [Timestamps](https://phishdestroy.io/tgwitness/docs/reference/timestamp/index.md): RFC 3161 timestamps for signed checkpoints: what is sent to the authority and how a response is verified. - [Security and data handling](https://phishdestroy.io/tgwitness/docs/reference/security/index.md): Threat model, access model, secrets at rest, network exposure, session imports and how to report a vulnerability. ## Reference - [Features and scope](https://phishdestroy.io/tgwitness/docs/reference/features/index.md): The current collection model, multi-account workflows, exports and operational boundaries of TgWitness. - [What has been tested](https://phishdestroy.io/tgwitness/docs/reference/verification/index.md): The live Telegram test, automated checks, browser checks and the next qualification runs. - [Changelog](https://phishdestroy.io/tgwitness/docs/reference/changelog/index.md): Every change by version, including the changes not yet released. ## Optional - [Complete English handbook as text](https://phishdestroy.io/tgwitness/llms-full.txt): The same guide and reference content in a single text download. - [Complete English handbook](https://phishdestroy.github.io/TgWitness/llms-full.md): Public guide and reference articles in one Markdown file, including source URLs. - [Documentation hub](https://phishdestroy.io/tgwitness/docs/): Browse the illustrated handbook and its language editions. - [Source code](https://github.com/phishdestroy/TgWitness): Implementation, documentation and issue templates. - [Releases](https://github.com/phishdestroy/TgWitness/releases): Packages and their release notes. - [MIT License](https://phishdestroy.io/tgwitness/repo/license/): Software license. - [Operator incompatibility notice](https://phishdestroy.io/tgwitness/docs/reference/notice/index.md): Our operator notice on Taylor Wessing and its source record. ## Complete documentation map ### Guides - [Work the archive](https://phishdestroy.io/tgwitness/docs/archive/index.md): Load history, search saved records, review AI sources and connect your tools. - [GitHub Actions capture](https://phishdestroy.io/tgwitness/docs/capture/index.md): Choose Takeout, regular API export or a chat journal on a temporary GitHub runner. - [Dedicated account](https://phishdestroy.io/tgwitness/docs/dedicated-account/index.md): Prepare a separate Telegram account for collection. - [Start in minutes](https://phishdestroy.io/tgwitness/docs/start/index.md): Install with one command, connect a Telegram account and export a verifiable archive on Windows, Linux or macOS. - [Connect an account](https://phishdestroy.io/tgwitness/docs/accounts/index.md): Connect Telegram by QR code, phone number or session import. Choose sources and check that new messages reach your journal. - [Choose a proxy](https://phishdestroy.io/tgwitness/docs/proxies/index.md): Maintain automatic MTProxy routes or use your own proxy. Choose IP modes, fallback rules and the route for external requests. - [Export and verify](https://phishdestroy.io/tgwitness/docs/exports/index.md): Export captured Telegram history, verify signatures and compare a journal with a checkpoint retained by an independent witness. - [See how evidence works](https://phishdestroy.io/tgwitness/docs/concepts/index.md): Follow a message from capture to checkpoint. Change a sample record, recalculate its SHA-256 chain and see what a retained checkpoint detects. - [Investigate across all chats](https://phishdestroy.io/tgwitness/docs/cases/index.md): Run an end-to-end Telegram investigation across channels, groups, private chats and bots: whole-account capture, history, people, links, files, timelines and verified evidence. - [Build a Case Board](https://phishdestroy.io/tgwitness/docs/case-board/index.md): Collect saved observations, exact highlights and action slices on a private board, discuss them with your team and present a collection. - [Design a report](https://phishdestroy.io/tgwitness/docs/reports/index.md): Choose report data, one of eight designs and the contents, then preview and export HTML, signed PDF or a complete evidence package. - [Prepare a sharing copy](https://phishdestroy.io/tgwitness/docs/handover/index.md): Choose the records and fields a recipient can receive, inspect the finished copy and verify its signed manifest and source journal boundary. - [Manage a group of accounts](https://phishdestroy.io/tgwitness/docs/groups/index.md): Compare group workspaces, find a source, review observation periods and apply shared settings with per-account exceptions. - [Keep it secure](https://phishdestroy.io/tgwitness/docs/security/index.md): See where sessions, keys and evidence live, what leaves your machine, what the protections cover and how to harden an installation. - [Share a case](https://phishdestroy.io/tgwitness/docs/access/index.md): Give reviewers and analysts access to selected accounts and chats, with separate permissions, session limits and revocable tokens. - [Set up a witness bot](https://phishdestroy.io/tgwitness/docs/witness/index.md): Publish signed journal checkpoints to your Telegram channel with a separate witness, its own key and read-only collector access. - [Why zero trust: Taylor Wessing, Dr. Zurheide, Dr. Schelinski](https://phishdestroy.io/tgwitness/docs/signed-export/index.md): A zero-trust case study: a GDPR answer signed by Dr. Patrick Zurheide and Dr. Tobias Schelinski of Taylor Wessing, checked against its own file, and the checkable model that would have left no room to deceive or doubt. - [Keep it running](https://phishdestroy.io/tgwitness/docs/server/index.md): Run TgWitness on a server with persistent storage, private panel access, backups and checks after a restart. - [Find what went wrong](https://phishdestroy.io/tgwitness/docs/troubleshooting/index.md): Check panel access, Telegram connection, missing messages, FloodWait and witness status using the right signals for each problem. ### Reference - [Secret Chats: setup and recording](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/index.md): Install the Secret Chat protocol extra, enable it per account and record the chats TgWitness creates or accepts. - [TgWitness: start, scale and evidence](https://phishdestroy.io/tgwitness/docs/reference/overview/index.md): Install with one command or capture on GitHub Actions. Understand investigation options, published scale and what an archive verifies. - [Load source history](https://phishdestroy.io/tgwitness/docs/reference/history/index.md): Load past messages from enabled sources, pause and resume, and verify a signed progress report. - [Archive analysis](https://phishdestroy.io/tgwitness/docs/reference/analysis/index.md): Search saved messages, review AI inputs and keep analytical reports with their source references. - [Command line](https://phishdestroy.io/tgwitness/docs/reference/cli/index.md): Search, read context, count activity and export saved messages from scripts and agents, with --json output, stable exit codes and scoped read-only tokens. - [Full-text search](https://phishdestroy.io/tgwitness/docs/reference/search/index.md): Find saved messages by word forms, exact phrases, domains and @usernames, best matches first, with the index bound to the signed journal. - [Read-only MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/index.md): Connect an MCP client to selected workspaces and chats with expiring, revocable access. - [Local OCR and transcription](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/index.md): Recognize captured images and audio with a local worker; keep derived text linked to its source file. - [Outgoing webhooks](https://phishdestroy.io/tgwitness/docs/reference/webhooks/index.md): Send scoped events to HTTPS receivers with HMAC signatures, retries and delivery status. - [Operator incompatibility notice](https://phishdestroy.io/tgwitness/docs/reference/notice/index.md): Our operator notice on Taylor Wessing and its source record. - [Licence and architectural incompatibility notice](https://phishdestroy.io/tgwitness/docs/reference/license/index.md): TgWitness is MIT-licensed for everyone, and why it is architecturally incompatible with the Taylor Wessing workflow. - [Quick start](https://phishdestroy.io/tgwitness/docs/reference/quickstart/index.md): Every way to install and launch TgWitness: Windows package, Python, Docker and the synthetic demo, with first checks. - [Accounts and session formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/index.md): Sign in by phone, QR code or auth key, import Telethon, Pyrogram or Telegram Desktop sessions, and run several accounts. - [Access and permissions](https://phishdestroy.io/tgwitness/docs/reference/access/index.md): Issue scoped access to accounts and chats, choose permissions, limit sessions and IP addresses, and withdraw access. - [Connection, proxies and data protection](https://phishdestroy.io/tgwitness/docs/reference/connection/index.md): Authentication, automatic proxy pools, IP modes, fallback policy, external requests and secret storage. - [Deployment](https://phishdestroy.io/tgwitness/docs/reference/deployment/index.md): Run TgWitness as a service on Windows, Linux, macOS or Docker, behind HTTPS, with backups and updates. - [How collection works](https://phishdestroy.io/tgwitness/docs/reference/collection/index.md): Observation scope, live updates, rechecks, attachments, own actions and what a gap means, record by record. - [Workflows and operations](https://phishdestroy.io/tgwitness/docs/reference/operations/index.md): Daily operation of the panel: modes, monitoring categories, parameters, notifications, exports, backup and capacity. - [Investigation mode](https://phishdestroy.io/tgwitness/docs/reference/investigation/index.md): Whole-account investigations across channels, groups, private chats and bots, from scope to a verified case package. - [Case Board reference](https://phishdestroy.io/tgwitness/docs/reference/case-board/index.md): Bookmarks, exact highlights, action slices, discussions, scoped access and the signed annotation history used by Case Board. - [Report configuration and verification](https://phishdestroy.io/tgwitness/docs/reference/case-reports/index.md): Report filters, eight designs, contents presets, saved change histories and the assessment included in signed exports. - [Features and scope](https://phishdestroy.io/tgwitness/docs/reference/features/index.md): The current collection model, multi-account workflows, exports and operational boundaries of TgWitness. - [How the evidence works](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/index.md): Hash chain, signatures, checkpoints and witnesses explained with the exact formulas the verifier uses. - [Evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/index.md): Contents of the signed ZIP, record kinds, process receipts, people profiles, off-site copies and offline verification. - [Independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/index.md): Run a witness with its own key and bot, publish signed checkpoints to a channel and check exports against it. - [Timestamps](https://phishdestroy.io/tgwitness/docs/reference/timestamp/index.md): RFC 3161 timestamps for signed checkpoints: what is sent to the authority and how a response is verified. - [Translating reports for court](https://phishdestroy.io/tgwitness/docs/reference/translation/index.md): Which file is the original, what to file with a certified translation and the terms translators keep. - [Security and data handling](https://phishdestroy.io/tgwitness/docs/reference/security/index.md): Threat model, access model, secrets at rest, network exposure, session imports and how to report a vulnerability. - [Architecture](https://phishdestroy.io/tgwitness/docs/reference/architecture/index.md): Components of the collector, panel, journal, workers and witness, and how data moves between them. - [What has been tested](https://phishdestroy.io/tgwitness/docs/reference/verification/index.md): The live Telegram test, automated checks, browser checks and the next qualification runs. - [Changelog](https://phishdestroy.io/tgwitness/docs/reference/changelog/index.md): Every change by version, including the changes not yet released. - [Panel guide](https://phishdestroy.io/tgwitness/docs/reference/panel/index.md): Every screen of the panel: chats, journal, sources, exports, Extras, protection modes and the code check. - [First setup and settings](https://phishdestroy.io/tgwitness/docs/reference/settings/index.md): The setup wizard, goals, interface levels, connection routes and settings shared by an account group. - [Install, verify and update](https://phishdestroy.io/tgwitness/docs/reference/installation/index.md): Install with one command, check signatures and hashes, update and remove an installation. - [Storage and recovery](https://phishdestroy.io/tgwitness/docs/reference/storage/index.md): Backups, moving older files to your cloud, copies under Object Lock and recovery on a new machine. - [Account export](https://phishdestroy.io/tgwitness/docs/reference/account-export/index.md): Export what an account can read now: scope, resumable jobs, a signed archive and minimized sharing copies. - [Public showcase](https://phishdestroy.io/tgwitness/docs/reference/showcase/index.md): Publish saved messages of selected public channels and signed snapshots through expiring, revocable links. - [High-assurance deployment](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/index.md): A sealed 24/7 server on Hetzner or Phala Cloud, Gateway DNS and the checks a third party can repeat. ## Language editions - [English](https://phishdestroy.io/tgwitness/llms.txt) - [Українська](https://phishdestroy.io/tgwitness/uk/llms.txt) - [Español](https://phishdestroy.io/tgwitness/es/llms.txt) - [Português (Brasil)](https://phishdestroy.io/tgwitness/pt/llms.txt) - [Türkçe](https://phishdestroy.io/tgwitness/tr/llms.txt) - [العربية](https://phishdestroy.io/tgwitness/ar/llms.txt) - [فارسی](https://phishdestroy.io/tgwitness/fa/llms.txt) - [اردو](https://phishdestroy.io/tgwitness/ur/llms.txt) - [हिन्दी](https://phishdestroy.io/tgwitness/hi/llms.txt) - [Bahasa Indonesia](https://phishdestroy.io/tgwitness/id/llms.txt) - [Tiếng Việt](https://phishdestroy.io/tgwitness/vi/llms.txt) - [简体中文](https://phishdestroy.io/tgwitness/zh/llms.txt) - [Français](https://phishdestroy.io/tgwitness/fr/llms.txt) - [Deutsch](https://phishdestroy.io/tgwitness/de/llms.txt) - [Italiano](https://phishdestroy.io/tgwitness/it/llms.txt) - [O‘zbekcha](https://phishdestroy.io/tgwitness/uz/llms.txt) - [한국어](https://phishdestroy.io/tgwitness/ko/llms.txt) - [繁體中文](https://phishdestroy.io/tgwitness/zh-Hant/llms.txt) - [Bahasa Melayu](https://phishdestroy.io/tgwitness/ms/llms.txt) - [Polski](https://phishdestroy.io/tgwitness/pl/llms.txt) - [日本語](https://phishdestroy.io/tgwitness/ja/llms.txt) - [ไทย](https://phishdestroy.io/tgwitness/th/llms.txt) - [עברית](https://phishdestroy.io/tgwitness/he/llms.txt) - [বাংলা](https://phishdestroy.io/tgwitness/bn/llms.txt) - [አማርኛ](https://phishdestroy.io/tgwitness/am/llms.txt) - [Русский](https://phishdestroy.io/tgwitness/ru/llms.txt) ## Controlled experiment - [Export Clinic](https://phishdestroy.io/tgwitness/docs/export-clinic/index.md): Watch a controlled Telegram Desktop export experiment, compare seven test conversations, and inspect the original recording and paired files. ## Checks and measurements - [Checks & measurements](https://phishdestroy.io/tgwitness/docs/validation/index.md): 56,329 Telegram messages exported in two measured runs. Compare message counts, collection speed, export time and signed archives. --- # Install TgWitness for Telegram Chat Export Canonical page: https://phishdestroy.io/tgwitness/docs/start/ Install TgWitness on Windows, Linux or macOS, connect a Telegram account and export a signed archive. Start with a fictional demo or your own workspace. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Install with one command, connect a Telegram account and choose what to save. ## Install on your computer The installer includes Python and dependencies. Start with a chat export; add observation and investigation tools when you need them. ### Linux / macOS ``` curl -fsSL https://get.destroy.tools/install.sh | bash ``` ### Windows · PowerShell / CMD ``` powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex" ``` Ubuntu server: run as root. Desktop: run as your normal user. Open the panel address shown by the installer and use its access key. Then connect your Telegram account. The panel key and your Telegram authorization are separate. [Installation, signatures and updates](https://phishdestroy.io/tgwitness/docs/reference/installation/) explains the downloaded build, local access and server options. [Source and Docker instructions](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) remain available. ## Choose your first task 1. [Connect an account](https://phishdestroy.io/tgwitness/docs/accounts/) by phone, QR or a supported session import. 2. Choose the chats, folder or account scope. 3. [Export the selected history](https://phishdestroy.io/tgwitness/docs/reference/account-export/), or start observation to retain future changes. 4. [Verify the archive](https://phishdestroy.io/tgwitness/docs/exports/) against a separately trusted key fingerprint. ## Use a temporary GitHub runner [GitHub Actions capture](https://phishdestroy.io/tgwitness/docs/capture/) guides you through the fork, authorization, scope and archive password. Download the encrypted result and its workflow provenance after the run. No permanent collector server is needed for this workflow. ## Look around without an account [Open the browser demo](https://phishdestroy.github.io/TgWitness/demo/?lang=en) to explore fictional messages, compare edits and inspect an export before installing anything. ![TgWitness conversation view with sample messages](https://phishdestroy.io/tgwitness/assets/chats-dark.png?v=684f81f890cc) A sample workspace. Your own journal starts separately. ## Continue an investigation For ongoing work, add the sources, file policies, search, reports and sharing permissions your case needs. [Start, scale and evidence](https://phishdestroy.io/tgwitness/docs/reference/overview/) explains the choices and published measurements. For a server installation, follow [Keep it running](https://phishdestroy.io/tgwitness/docs/server/). --- # Use a separate account. Never your main one. Canonical page: https://phishdestroy.io/tgwitness/docs/dedicated-account/ Prepare a dedicated Telegram account for collection. Review session ownership, login choices and account risks before connecting it to TgWitness. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Read before you connect an account Our advice not to use your main account is not a joke. It is reality. Main account - Your own app hash: 99% logged out - Bans just for low trust are frequent - Using it is a really stupid idea Extra account on public pairs - Over a million accounts registered through these pairs - The pairs have been alive for 5+ years - Nobody can see anything of yours through them 01 ## Why not your main account This is accurate information. We know exactly where the pitfalls of these problems are. 1. ### Your own app hash: 99% logged out Logging in to my.telegram.org from an account you have no access to, to get an app hash, and then any request through that app hash means a 99% chance the account is logged out. You can check it. 2. ### Bans just for low trust are frequent Accounts are banned simply because Telegram does not trust them, and such bans are frequent. You can check this too. Using your own account is a really stupid idea. 3. ### Copied session keys can be revoked Running an imported TData/session key in Telegram Desktop and TgWitness at the same time can trigger `AUTH_KEY_DUPLICATED`. Telegram invalidates that authorization, so both copies need a new login. A dedicated account does not prevent this. Fully quit the original client and keep it closed while using its imported session. For parallel use, sign in to TgWitness by phone or QR to create a separate authorization; other separately authorized clients can remain signed in. [Read the session import warning](https://phishdestroy.github.io/TgWitness/demo/guide.html?lang=en#session-warning) Telegram documentation - [Logout errors: AUTH_KEY_UNREGISTERED, SESSION_REVOKED](https://core.telegram.org/api/errors) - [Creating your own app hash: obtaining api_id](https://core.telegram.org/api/obtaining_api_id) 02 ## Why TgWitness works through public app hash/app ID pairs That is why we built TgWitness on public app hash/app ID pairs. By our logic, bans are less likely with them: more than a million Telegram accounts have been registered through these pairs, and many different programs work through them. By our logic, this is better than working directly with a personal app hash: these pairs have been alive for 5+ years for sure. ### Your own new pair Created at my.telegram.org from the account. - About 99% of accounts logged out - One new application, one account ### Public pairs of the pool The same pairs many programs use. - Over a million accounts registered - Many different programs - Working for 5+ years ### Why nobody can see anything of yours through these pairs - #### The pair is a name, not a key Telegram asks for the API ID and API hash when a program connects and when it requests a login code. They identify the application and give no access to any account; Telethon's documentation notes that one pair works with any phone number. - #### Your session key never leaves your server Signing in creates an authorization key by a Diffie–Hellman exchange between your TgWitness and Telegram; the key itself is never sent. Telegram's documentation: after authorization the key becomes associated with the user, and every call with this key runs as that user. Other programs with the same pair have their own keys and cannot use yours. - #### Traffic is encrypted with your key Every request and answer is encrypted with the session's authorization key, not with the API hash. Knowing the API hash decrypts nothing. - #### The owner of a pair sees nothing Telegram has no method that lists accounts, sessions or messages by API ID. The owner of a pair sees only its app settings at my.telegram.org. - #### Only your account sees which app it is Settings → Devices of your own account lists each session's app name and API ID, device, IP address and dates. Nobody else gets this list. Telegram documentation - [User authorization: the key becomes the user](https://core.telegram.org/api/auth) - [auth.sendCode: api_id, api_hash](https://core.telegram.org/method/auth.sendCode) - [initConnection](https://core.telegram.org/method/initConnection) - [Creating an authorization key](https://core.telegram.org/mtproto/auth_key) - [MTProto encryption](https://core.telegram.org/mtproto/description) - [account.getAuthorizations](https://core.telegram.org/method/account.getAuthorizations) - [What a session record holds](https://core.telegram.org/constructor/authorization) - [Obtaining api_id](https://core.telegram.org/api/obtaining_api_id) - [Telegram apps' open source code](https://telegram.org/apps#source-code) Libraries and discussions - [Telethon: signing in](https://docs.telethon.dev/en/stable/basic/signing-in.html) - [opentele: official app APIs](https://opentele.readthedocs.io/en/latest/documentation/authorization/api/) - [opentele: TelegramClient](https://opentele.readthedocs.io/en/latest/documentation/telethon/telegramclient/) - [Stack Overflow: should the api_hash be kept secret?](https://stackoverflow.com/questions/49490818/should-telegram-api-hash-be-kept-secret) ### The same pairs in other programs 7 The pairs of official Telegram apps are public and built into many independent programs and libraries: - [opentelePython · src/api.py](https://github.com/anmv/opentele/blob/4df17bd8c443d6452afc5a2d29ec7922fad1a5c3/src/api.py#L575) - Desktop 2040 - Android 6 - Telegram X 21724 - iOS 10840 - macOS 2834 - Web 2496 - [opentele2Rust · opentele2-core/src/api.rs](https://github.com/DedInc/opentele2/blob/7e973bc71cd7a714ad13ac703c0895a90d36a735/crates/opentele2-core/src/api.rs#L641) - Desktop 2040 - Android 6 - Telegram X 21724 - iOS 10840 - macOS 2834 - Web 2496 - [GrampoPython · Grampo/ut/api.py](https://github.com/abbas-bachari/Grampo/blob/00aa662d853c4ac2180432371c5e0d9444bbfe9e/Grampo/ut/api.py#L526) - Desktop 2040 - Android 6 - Telegram X 21724 - iOS 10840 - macOS 2834 - Web 2496 - [tgmanagePython · api/schemas/api_app.py](https://github.com/xdsnich/tgmanage/blob/f67c46be0ab234bd04526a8663d3936bd98a8597/api/schemas/api_app.py#L47) - Android 6 - iOS 8 - Desktop 2040 - macOS 2834 - Telegram X 21724 - Web K 2496 - [LyChatBotTDLib · helpers/tdlib/index.js](https://github.com/LyoSU/LyChatBot/blob/fac0ae5d5f2cddb8a26312014f51c0f6f40ec191/helpers/tdlib/index.js#L11) - macOS 2834 - [hsadasdPython · config.py](https://github.com/herobrinovaleksandr-png/hsadasd/blob/6842c74895038c16e219324fcd07dbe8153f37f0/config.py#L68) - Desktop 2040 - Desktop 17349 - Telegram X 21724 - macOS 2834 - iOS 10840 - Web 2496 - +4 - [blb.teamblb.team/threads/…294](https://blb.team/threads/app-hash-app-id-ofitsial-nykh-kliyentov.294/) - Android 4 · 5 · 6 - iOS 8 - Desktop 2040 - Desktop 17349 - macOS 2834 - Telegram X 21724 Forum list of official app pairs, published for registering accounts 03 ## Ways to create an extra account A Telegram account needs a phone number that receives the login code. Choose by how long the account has to live. - Best choice ### Prepaid SIM or eSIM ******** Lasts As long as you keep it topped up Watch out The most reliable: Telegram accepts real mobile numbers best. A number the carrier takes back goes to someone else. - ### Virtual number app ******** Lasts While the app keeps the number Watch out Telegram may refuse a virtual number, not deliver the code or limit the new account at once; some apps take back numbers that are not used. - ### Number rental ******** Lasts The rental period Watch out When it ends, the number goes to the next customer. - ### One-time activation ******** Lasts One code Watch out The number returns to the pool at once, often with a history of previous owners. Set the cloud password before anything else. Whoever holds the number later can request a login code. A cloud password (two-step verification) stops them from signing in; without it the account belongs to the next owner of the number. Telegram documentation - [Spam FAQ: virtual numbers and previous owners](https://telegram.org/faq_spam) - [Two-step verification](https://core.telegram.org/api/srp) ### Rented +888 numbers (Fragment) Some marketplaces and services offer temporary rental of Telegram's official +888 numbers from Fragment. Approximate price: US $20 per day. - You can register an account directly in Telegram Web or Telegram Desktop. - You can delete accounts on the number and create new ones. - These accounts generally face fewer anti-fraud checks, but they do not provide immunity or special privileges. The number is not yours. After the rental ends, the owner can reclaim it. Set a cloud password immediately and do not treat the account as long-term. Owning the +888 yourself or using a prepaid SIM you control remains more reliable. ### Ready-made accounts from marketplaces Some marketplaces (for example G2G or Z2U) sell ready-made Telegram accounts — new, aged, or with session files. - [G2G: Telegram account listings](https://www.g2g.com/uk/categories/telegram-accounts) - [Z2U: Telegram account listings](https://www.z2u.com/telegram/accounts-5-15140) NEVER USE YOUR MAIN ACCOUNT! A dedicated account obtained this way is still safer than putting your primary Telegram account into TgWitness. #### Warnings before purchase - This violates Telegram's Terms of Service. - Many accounts are mass-registered (auto-reg) or have an unknown history. - Some sellers may still have recovery access. - Accounts from such markets are frequently banned or restricted later. - Avoid marketplaces that openly sell stealers, phishing tools, or clearly stolen accounts. - Buying an account — even one advertised as auto-reg — from platforms that openly sell phishing tools, stealers, stolen sessions or accounts violates not only Telegram's Terms of Service but also the laws of most countries. This can later invalidate your evidence. Choose carefully. #### If you use this option 1. Treat the account as disposable. 2. Terminate all other sessions, set a cloud password and change recovery methods immediately. 3. Use 2–3 accounts from different providers or accounts you registered yourself. **Premium, deletion and the seven-day delay** If the account has Premium, someone with access to the phone number cannot delete the account immediately. You receive a notification and have seven days before deletion. This matters because your investigation depends on the account: you have time to prepare a replacement. **Fresh accounts and API credentials** If you obtain and use your own api_id/api_hash from a fresh account you registered yourself using a number from an SMS service, the account will be logged out on the first API request or session authorization. Keep this in mind when planning an investigation. 04 ## Creating the account From a number to the first recorded chat. 1. ### Get a number A prepaid SIM or eSIM when the account has to live long; a rental or a one-time activation for a short job. Services are listed below. 2. ### Register apart from your main account Register in the official Telegram app on a separate device, emulator or phone profile, not next to your main account. 3. ### Lock it with a cloud password Right away set a cloud password and a recovery email used nowhere else. 4. ### Close the privacy settings Phone number **Nobody**, find me by my number **My contacts**, last seen, profile photos and bio **Nobody** or **My contacts**; turn contact sync off. 5. ### Keep it from self-destructing Set account self-destruct to the longest period, so a stopped TgWitness does not cost you the account. 6. ### Give it a neutral profile No name, photo, username or bio from your other accounts, no personal contacts. 7. ### Let it warm up Join a few chats a day at first. New accounts that rush are limited first. 8. ### Share nothing with bots Never press “Share phone number” or “Share location” for a bot. Open links and Mini Apps through a VPN or proxy on that device. 9. ### Connect it to TgWitness In its own workspace, connect with **Account → QR code**, then press **Sources → Investigation mode**. The app is where you act, TgWitness is the record. Telegram documentation - [Two-step verification](https://core.telegram.org/api/srp) - [Privacy settings](https://core.telegram.org/api/privacy) - [Account self-destruct](https://core.telegram.org/method/account.setAccountTTL) 05 ## Number services Options to start from. Countries, prices and whether Telegram accepts a number change often; check before paying. ### Prepaid SIM and eSIM 11 - [SMARTYsmarty.co.uk](https://smarty.co.uk) - UK - SIM - [VOXIvoxi.co.uk](https://www.voxi.co.uk) - UK - SIM - [iD Mobileidmobile.co.uk](https://www.idmobile.co.uk) - UK - SIM - [Threethree.co.uk](https://www.three.co.uk) - UK - SIM - [Asda Mobilemobile.asda.com](https://mobile.asda.com) - UK - SIM - [Ultra Mobileultramobile.com](https://www.ultramobile.com) - US - Prepaid PayGo plan, very cheap - [US Mobileusmobile.com](https://www.usmobile.com) - US - Prepaid - [Mint Mobilemintmobile.com](https://www.mintmobile.com) - US - Prepaid - [Tracfonetracfone.com](https://www.tracfone.com) - US - Prepaid - [eSIM Plusesimplus.me](https://esimplus.me) - eSIM - [Numero eSIMnumeroesim.com](https://numeroesim.com) - eSIM ### Virtual number apps 20 - [Google Voicevoice.google.com](https://voice.google.com) - US US only; registration needs a US number - [TextNowtextnow.com](https://www.textnow.com) - US - CA The number is taken back if you do not use it - [TextFreetextfree.us](https://www.textfree.us) - US - [2ndLine2ndline.co](https://www.2ndline.co) - US - CA - [Talkatonetalkatone.com](https://www.talkatone.com) - US - [TextMego-text.me](https://go-text.me) - US - CA - Other countries - [textPlustextplus.com](https://textplus.com) [Google Play](https://play.google.com/store/apps/details?id=com.gogii.textplus) - [FreeToneGoogle Play](https://play.google.com/store/apps/details?id=com.textmeinc.freetone) - US [TextMe Up · textmeup.com](https://www.textmeup.com) - [Nextplusnextplus.me](https://nextplus.me) - US - [Dingtonedingtone.me](https://www.dingtone.me) - US - CA - [Burnerburnerapp.com](https://www.burnerapp.com) - US - CA - Paid With a trial period - [Hushedhushed.com](https://hushed.com) - Many countries - Paid Cheap - [Sidelinesideline.com](https://www.sideline.com) - US - [MySudomysudo.com](https://mysudo.com) - US - CA - UK - [2NumberGoogle Play](https://play.google.com/store/apps/details?id=com.bpmobile.second.phone) [App Store](https://apps.apple.com/app/id1216135390) - [SLYNUMBERslynumber.com](https://slynumber.com) [Google Play](https://play.google.com/store/apps/details?id=com.dev.slynumber) - [Phonerphonerapp.com](https://phonerapp.com) - [Onoffonoff.app](https://www.onoff.app) - EU European mobile numbers in an app - [Sonetelsonetel.com](https://sonetel.com) - Many countries - Free number - [Zadarmazadarma.com](https://zadarma.com) - Many countries Virtual numbers ### Number rental and activations 12 Rental keeps a number for weeks or months. A one-time activation gives a single code: set the cloud password right after registering. - [OnlineSimonlinesim.io](https://onlinesim.io) - Rental - Activations - [SMSPVAsmspva.com](https://smspva.com) - Rental - Activations - [5SIM5sim.net](https://5sim.net) - Rental - Activations - [SMSPoolsmspool.net](https://www.smspool.net) - Rental - One-time - [VAK-SMSvak-sms.com](https://vak-sms.com) - Rental - Activations - [TextVerifiedtextverified.com](https://www.textverified.com) - Rental - Activations - [JuicySMSjuicysms.com](https://juicysms.com) - Rental - Activations - [365SMS365sms.org](https://365sms.org) - Rental - Activations - [SIMSMSsimsms.org](https://simsms.org) - Rental - Activations - [GrizzlySMSgrizzlysms.com](https://grizzlysms.com) - One-time - [SMS-MANsms-man.com](https://sms-man.com) - One-time - [Tiger SMStiger-sms.com](https://tiger-sms.com) - One-time --- # Connect Telegram: QR, Phone & Session Import Canonical page: https://phishdestroy.io/tgwitness/docs/accounts/ Connect Telegram to TgWitness by QR code, phone login or session import. Select chats and confirm that new messages reach the observation journal. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) One workspace = one account, its journal and its key. ## Choose how to sign in **Accounts** → add a workspace → connection settings. Use a separate account for this. - **QR code:** scan it from Telegram's Devices screen and confirm. - **Phone number:** number, code, then 2FA password if you have one. - **Session import:** your own session file or Telegram Desktop data. Use a built-in API profile or your own API ID and hash. It only identifies the app, it doesn't log you in or hide anything. **Need a proxy first?** You can [choose and test the connection route](https://phishdestroy.io/tgwitness/docs/proxies/) before signing in. Each account has its own route. ## Choose what to observe 1. Pick the chats, groups or channels you need. 2. Check collection settings, media included. 3. Start it and check the connection and recent activity. The account has to have access. Admins and members see different things, the journal shows what this account got. Whole account? **Sources → Observation scope → Investigation mode**, check it, **Save scope**. Full walkthrough: [investigating a whole account](https://phishdestroy.io/tgwitness/docs/cases/). ## Check the whole path In your test group, send a message from another account, edit it, delete it. All three should show up in the journal. Then [export and verify](https://phishdestroy.io/tgwitness/docs/exports/). "Connected" means the connection works. A captured test message means events actually arrive. ## Add another account New workspace in **Accounts**, same steps. Note each account's key fingerprint so you can tell exports apart later. --- # Telegram Proxies: MTProxy, SOCKS5 & Routing Canonical page: https://phishdestroy.io/tgwitness/docs/proxies/ Configure Telegram MTProxy, SOCKS5 or HTTP proxy routes in TgWitness. Review automatic pools, IP modes, fallback rules and external-request routing. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Keep the account online, and decide yourself whether it may ever show your server's IP. ## Choose the IP mode first 01**Hide the address** Proxy only. If none works, it waits. 02**Direct as a last resort** Goes direct after a delay, back to a proxy once one works. 03**Server behind a tunnel or VPN** Direct is fine. It doesn't set up or check the VPN for you. The route chooses the connection. The IP mode determines whether a direct connection is permitted. ## Let the pool maintain the route 1. **Account → Settings → Connection settings**. 2. Pick the IP mode and **Automatic MTProxy**, or a fixed route. 3. Save, **Test Telegram connection** (works before sign-in too). 4. Start collecting and send yourself a test message. New workspaces start on automatic MTProxy with **Hide the address**. The pool pulls four public lists, checks servers, keeps the good ones and swaps out dead ones. ## Use your own proxy SOCKS5, HTTP CONNECT, a Telegram proxy link or an operator catalog. Pause observation before switching. Fake TLS secrets (`ee`…) don't work. **Rotation, sharing and retry settings** **Parameters → Automatic MTProxy**: failure thresholds, cooldowns, rotation, accounts per proxy. Limit 1 means an account waits rather than share. Different proxies can still share an exit IP. ## Separate Telegram from external requests MTProxy only carries Telegram. Timestamps, notifications, copies and code checks go through a separate SOCKS5/HTTP proxy, the account's SOCKS5/HTTP route, or direct if the mode allows. Or turn them off. `TGWITNESS_PROXY_FEED_PROXY` sets the route for list downloads. The [witness](https://phishdestroy.io/tgwitness/docs/witness/) has its own settings. None of this touches your browser or system network. More: [modes and defaults](https://phishdestroy.io/tgwitness/docs/reference/connection/#ip-modes), [who may change routes](https://phishdestroy.io/tgwitness/docs/access/). --- # Export Telegram Chats & Verify Signed Evidence Canonical page: https://phishdestroy.io/tgwitness/docs/exports/ Export captured Telegram chat history as signed evidence. Check archive signatures, file hashes and independently retained journal checkpoints offline. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Hand someone files they can check themselves against your workspace. Retain a referenceExport signed ZIPRecipient verifies New to signatures and checkpoints? [Change a sample record](https://phishdestroy.io/tgwitness/docs/concepts/#chain) and see which checks catch it. Keeping a copy away from the collector? Go to [S3 setup](https://phishdestroy.io/tgwitness/docs/exports/#s3), [Object Lock](https://phishdestroy.io/tgwitness/docs/exports/#s3-retention) or [verified recovery](https://phishdestroy.io/tgwitness/docs/exports/#s3-restore). ## Retain a trusted reference Write down the workspace key fingerprint somewhere other than the collector. While collecting, turn on evidence mode so checkpoints get RFC 3161 and OpenTimestamps timestamps, or run a [witness](https://phishdestroy.io/tgwitness/docs/witness/) that posts to a public channel. Keep signed checkpoints elsewhere too: the recipient checks the key, the time and an earlier journal state against them. ## Download the signed ZIP **Exports** → signed evidence ZIP. It has the whole journal and a signed file manifest. Shape the readable report in [Report studio](https://phishdestroy.io/tgwitness/docs/reports/), or send only selected data as a [handover extract](https://phishdestroy.io/tgwitness/docs/handover/). HTML, PDF and JSON reports carry their own seals. CSV is just a working copy; for integrity use the CSV inside the verified ZIP. ## Verify with a trusted copy of TgWitness In the project environment, with your own fingerprint and paths: ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint retained-checkpoint.json --require evidence ``` A pass shows `key_pinned: true` and `checkpoint_checked: true`. `--require evidence` also needs third-party time for the last record, such as a checked timestamp: the checkpoint is signed with your own key, so on its own it is not enough. Keep that output next to the archive. The checkpoint has to be at or before the end of the export. ## Use the verification result - **Files:** the manifest binds their hashes, the signatures bind the journal. Any change shows up. - **Identity:** the fingerprint you kept proves it's the key you expected. - **Earlier state:** a checkpoint compares the export with a journal prefix saved before the handoff. - **Coverage:** gaps, acquisition results and a send → edit → delete test show what this setup actually caught. Details: [what verification proves](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope). ## Set up the S3 off-site copy **Exports → Off-site copy** in your workspace. Works with AWS S3 and anything S3-compatible. It copies journal segments, saved files, checkpoints with their timestamps and finished chat exports, each encrypted with `AES-256-GCM` before it leaves the collector. The online demo shows these controls with uploads off. Only enter real credentials in your own install. [![Complete Off-site copy panel: endpoint, region, bucket, access keys, schedule, Object Lock and recovery key controls](https://phishdestroy.io/tgwitness/assets/off-site-copy.png?v=f9ad551ec1f4)](https://phishdestroy.io/tgwitness/assets/off-site-copy.png?v=f9ad551ec1f4) The complete panel with advanced options expanded. No storage credentials are shown. | Field | What to enter | | --- | --- | | Endpoint | Storage URL, no bucket path or credentials. Example: `https://s3.example.invalid`. | | Region | Whatever your provider needs. Default `us-east-1`. | | Bucket | An existing bucket you can write to. Example: `example-case-backup`. | | Folder in the bucket | Prefix, default `tgwitness`. A per-workspace prefix is added on top. | | Access key ID / Secret access key | Both together, stored in the vault. Leave both empty later to keep them. | | Path-style addresses | On: `endpoint/bucket`. Off: `bucket.endpoint`. Depends on the provider. | | Copy interval | 1 to 1,440 minutes, default 5. Only while the app runs. | | Object Lock retention | Days and mode, if the bucket supports Object Lock. Zero keeps the bucket default. | 1. Create the bucket, fill in destination and credentials with **Keep an off-site copy** unticked, hit **Save off-site copy**. 2. **Test connection** uploads an encrypted test object. 3. **Download encryption key** and keep it away from the collector. No key, no recovery. 4. Tick **Keep an off-site copy**, save, then **Copy now** or let the schedule run. ## Check retention and copy progress Under **More options** pick retention days and `GOVERNANCE` or `COMPLIANCE`. TgWitness reads the retention back from an uploaded object and tells you: confirmed, missing or check failed. The panel shows the last pass, object count, bytes, copied journal boundary and errors. A missing local file is reported and retried next pass, the rest keeps copying. Uploads go over Direct, SOCKS5 or HTTP. With an MTProxy-only route the copy waits with an error. ## Keep the recovery key separately The key JSON has the decryption key, destination, prefix and key fingerprint. For recovery you need it plus storage credentials with read access. Changed endpoint, bucket or prefix? Download the key again. A fresh copy starts at the new destination; old chat exports stay where they were. ## Restore and verify on another machine You need a TgWitness install you trust, the key JSON, read-only storage credentials and an empty folder: ### Windows PowerShell ``` $env:TGWITNESS_S3_ACCESS_KEY = 'YOUR_READ_ACCESS_KEY' $env:TGWITNESS_S3_SECRET_KEY = 'YOUR_READ_SECRET_KEY' python -m tgwitness.replica restore --key-file tgwitness-replica-key.json --out restored-evidence ``` ### Linux / macOS ``` export TGWITNESS_S3_ACCESS_KEY='YOUR_READ_ACCESS_KEY' export TGWITNESS_S3_SECRET_KEY='YOUR_READ_SECRET_KEY' python -m tgwitness.replica restore --key-file tgwitness-replica-key.json --out restored-evidence ``` Everything is checked in a private temp folder first: the whole journal, checkpoints, file hashes and sizes. Unsafe paths, conflicting segments or a journal shorter than its checkpoint fail, and then nothing is written out. On success you get `events.jsonl`, `media/`, `checkpoints/` and `exports/`. Keep the command's JSON output with them, and compare against checkpoints or witness records you kept yourself. --- # Export Telegram with GitHub Actions Capture Canonical page: https://phishdestroy.io/tgwitness/docs/capture/ Run Telegram Takeout, regular API export or chat journaling on a temporary GitHub Actions runner. Download an encrypted archive and workflow provenance. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Choose Takeout, regular API export or a chat journal on a temporary GitHub runner. Enable JavaScript to generate a key and decrypt your archive. **Full reference** [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Independent capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/OPTIONAL-CAPTURE.md) ![Independent capture](https://phishdestroy.io/tgwitness/assets/chapter-capture.svg?v=c979502bc92b) **Preview available from `main`.** A fork launches a pinned reusable workflow from `phishdestroy/TgWitness`. The workflow exports an account, selected chats or one chat's event journal using a newly created Telegram session, attests the evidence ZIP or multipart manifest, and uploads only recipient-encrypted handoffs. The normal administration panel is not exposed. Choose `client=official_web` to run the [official-client witness](https://github.com/phishdestroy/TgWitness/blob/main/docs/OFFICIAL-WITNESS.md) with guarded Telegram Web controls and video. It requires your own upstream proxy and observes one rendered chat. The default `client=api` retains the full-account export modes described below. The verifier checks the archive against its GitHub attestation, the approved workflow and collector commits, and the signed journal and attachment hashes. The collection process uses pinned upstream code and fresh storage. A reviewer can inspect that code and verify the delivered archive against its recorded run. **On this page** - [User flow](https://phishdestroy.io/tgwitness/docs/capture/#user-flow) - [Session time budget](https://phishdestroy.io/tgwitness/docs/capture/#session-time-budget) - [Choose this mode or a persistent workspace](https://phishdestroy.io/tgwitness/docs/capture/#choose-this-mode-or-a-persistent-workspace) - [What is public, and what must stay private](https://phishdestroy.io/tgwitness/docs/capture/#what-is-public-and-what-must-stay-private) - [Troubleshooting](https://phishdestroy.io/tgwitness/docs/capture/#troubleshooting) - [Local decryption and verification](https://phishdestroy.io/tgwitness/docs/capture/#local-decryption-and-verification) - [How the fork is kept outside the capture process](https://phishdestroy.io/tgwitness/docs/capture/#how-the-fork-is-kept-outside-the-capture-process) - [Cryptographic handoff](https://phishdestroy.io/tgwitness/docs/capture/#cryptographic-handoff) - [Scope and validation](https://phishdestroy.io/tgwitness/docs/capture/#scope-and-validation) - [Maintainer release sequence](https://phishdestroy.io/tgwitness/docs/capture/#maintainer-release-sequence) ## User flow The helper explains the five stages and lets you try message or collector substitution on sample data. **Start my capture** opens the wizard. 1. Choose **GitHub Actions capture (preview)** on the project homepage, the workspace login screen, or **Exports → Open capture helper**. You can also open the [official helper](https://phishdestroy.github.io/TgWitness/sealed.html?lang=en) or `tgwitness/static/capture.html` from a trusted checkout in a modern browser. The helper makes no network requests for key or file processing. The helper supports the site's interface languages; the temporary collection panel supports English and Russian and opens in the browser's language when it is one of them. 2. Generate a key and save **sealed-key.json**. This is the only private decryption key. Copy the separate public **recipient** value. Losing the private key loses access to both the connection and the archive. Confirm that you saved it to unlock the next step. If you already have a delivery file, load the saved key and choose **I already have an archive**. 3. Fork TgWitness, enable Actions in the fork, and run **Sealed chat capture**. Paste the public recipient and choose 30, 60, or 120 minutes. Never put a phone number, login code, Telegram password, private key, or session in workflow inputs, commits, issues, or logs. 4. During the run, download **sealed-connection** from Artifacts and unzip it. Load `connection.tgwsealed` in the helper, using the saved private key. The resulting link contains a random access secret in its URL fragment. Keep this link private. The panel removes the fragment and keeps the secret in this tab's session storage; it is not placed in HTTP access logs. 5. Open the connection link. Sign in with a QR code, or with your phone number and the login code. Enter your two-step verification password if Telegram asks for it. The built-in API credential pool is used by default, just like the normal workspace. You may expand the optional custom credentials section and enter both `api_id` and `api_hash` from [my.telegram.org/apps](https://my.telegram.org/apps). Leave both fields empty to use the built-in pool; a partial or malformed pair is rejected. Session imports are not allowed. Choose the export mode and scope. The connection link contains an access secret: keep it private. 6. Choose **Telegram Takeout**, **Regular Telegram API** or **Chat event journal**. For account export, choose all accessible chats or load and select one or more chats, then set dates, chat types, account categories and attachment rules. Check settings and size, optionally save the settings JSON for an independent reviewer, then press **Start capture**. Settings are fixed after starting. Resume works only while this runner exists; finishing early preserves acquired data and records gaps. Deadline expiry after starting produces an explicitly partial archive; expiry before starting or cancellation produces no archive. 7. Wait for **sealed-result**, download and unzip it, and decrypt `delivery.tgwsealed` in the helper. You receive `delivery.zip`, containing `evidence.zip`, `attestation.jsonl`, and instructions. Browser decryption is limited to 256 MiB; larger packages use the streaming local command below. Large results also include `delivery-NNNNNN.tgwsealed` parts; the main `delivery.tgwsealed` then contains `evidence.parts.json` and the attestation. Download every part and assemble locally as described below. 8. End the temporary session in Telegram Settings → Devices if revocation was not confirmed or the runner was killed. Normal completion requests logout, and the run records whether revocation was confirmed. The repository must contain the published pinned source and reusable-workflow commits. A local branch alone cannot be invoked by another GitHub repository. ## Session time budget Before collection, **Calculate time and size** estimates the selected history and files from message counts and a bounded sample. The display includes time already spent signing in, estimated collection time and a reserve for packaging. For files, the initial estimate uses 1 MiB/s and a twofold time margin; progress replaces that assumption with the measured rate. Use **Messages only** or select fewer chats when the estimate exceeds the remaining time. Telegram's reported Takeout wait is added to the budget. The collector stops acquisition when the remaining time is needed for packaging, retains acquired data and marks a partial result. A 120-minute session therefore uses its remaining collection window rather than waiting for the deadline before preparing the archive. The display identifies selections whose full size could not be sampled. ## Choose this mode or a persistent workspace | Capture mode | Configurable scope | Difference | | --- | --- | --- | | Telegram Takeout, the default | All accessible cloud chats or selected chats, dates, account categories, media policies and JSON/HTML views | Uses Telegram's official export mechanism; approval or waiting may be required. Takeout can enumerate left channels/groups where Telegram permits it and request additional personal data. | | Regular Telegram API | The same account scope and output choices, subject to methods available through the regular API | Does not initialize Takeout; cannot enumerate left channels/supergroups or fetch Takeout-only personal data. Contacts cover Telegram users rather than the complete saved phone contact list. Rate limits still apply. | | Chat event journal | One selected chat, attachment policies and optional avatars | Captures history and changes observed during this run. Account categories, date filters and Desktop-compatible views do not apply. | All three modes have the same GitHub attestation and encrypted delivery. Takeout selects the acquisition method and is never silently replaced by regular API access. TgWitness generates the JSON/HTML views from the captured records and preserves the selected acquisition method in the export. See the [official Takeout API](https://core.telegram.org/api/takeout). Defaults use Takeout, all accessible chat types including archived chats, all dates, account profile and contacts, compatible JSON and HTML, and file downloads. The initial media budget is 4 GiB, with visible per-type file limits; larger files or exhausted download budgets use server hashes where available. Review these limits before collecting. Hashes cannot reconstruct a file. Optional photos, stories, session metadata and extra personal data remain separate choices. Takeout may require approval in an established Telegram session. Telegram sets the delay; a new login or runner does not bypass it. The maximum capture window is 120 minutes including login and approval, so a large account or long approval wait may not finish. A persistent local export can resume the same session, but does not inherit GitHub attestation. ### Agree and verify the settings After **Check settings and size**, use **Save settings for verification**. Agree the resulting `sealed-export-settings.json` with the reviewer before collection. Changes invalidate the saved assessment. The collector signs the effective settings and their SHA-256, and account-export receipts bind the same options. The verifier reports the actual mode, selection and completeness, and rejects a disagreement between the journal and nested account export. ``` python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --expected-selection sealed-export-settings.json --require-complete ``` `--expected-selection` rejects a different transport, chat scope, filter or attachment policy. `--require-complete` accepts only account exports and chat journals recorded as complete. Without these flags, verification still checks provenance and integrity while reporting the recorded settings and gaps. Agree the expected selection before the run and keep it separately from the archive. The scope and acquisition intervals identify the material captured during the run; use retained earlier observations when comparing previous versions. | Need | Mode | | --- | --- | | Export accessible account data or selected chats during a limited session and give a reviewer an externally attested archive | GitHub Actions capture (preview) | | Observe several chats continuously, manage accounts, search and read a growing archive | Local or Docker workspace | This starts a separate capture with a new login. It does not upload your existing local journal, export the currently open workspace, or reuse its Telegram session. An unfinished cloud capture cannot resume after its runner is destroyed; a new workflow starts a new capture. The workspace's **Exports → Open capture helper** opens the complete wizard inside the panel. The standalone page uses the same wizard, controls and themes. Both keep keys and decryption in your browser. GitHub workflow startup and the temporary Telegram panel open in separate tabs; the wizard tells you when to return. Locking the workspace clears the wizard's in-memory key. Your saved key file remains on your device. ## What is public, and what must stay private Collection runs on a standard GitHub-hosted runner. GitHub, the approved collector and dependencies, the helper page, the browser and the HTTPS tunnel are trusted parts of this setup. The temporary host processes the Telegram session and plaintext messages; the delivered artifacts are encrypted for the recipient. Forking copies project code into your repository. It does **not** export your Telegram account. The recipient workflow input is a public encryption key. Keep `sealed-key.json`, Telegram credentials, login codes, 2FA passwords and the decrypted connection URL out of commits, workflow inputs and public logs. The workflow publishes encrypted connection/result artifacts for one day. Download both in time; GitHub Actions availability, account limits and billing apply. A public fork is not a promise of unlimited free compute. No payment or GitHub access token is entered into the helper. The private decryption key stays in your browser/file. Telegram session material and plaintext observations necessarily exist inside the temporary collector. GitHub and the HTTPS tunnel remain trusted infrastructure. Attestation may make the archive digest and workflow identity public; the archive contents are not placed in the attestation. The attestation timestamp is not a message timestamp. ## Troubleshooting | Symptom | Next step | | --- | --- | | No **Run workflow** button | Open your own fork, enable Actions, and sync it with upstream `main`. Do not edit the approved upstream pins to bypass a failure. | | No `sealed-connection` artifact | Check whether the job started and completed its startup/upload step. Queue, runner, image download, tunnel or repository policy failures can prevent startup. | | Cannot open the connection | Load the saved key for this run, unzip the downloaded artifact and select `connection.tgwsealed`. The runner must still be active. | | History is paused | Check the panel's status and use Resume while the session remains active, or finish with the data already collected. Telegram limits and inaccessible content can leave gaps. | | No `sealed-result` | Cancellation or expiry before starting collection produces no archive; the run then ends with the notice **No archive**. A failed collection, attestation or packaging step also prevents delivery; the failed step names the supervisor's reason without private data. Inspect it without posting credentials. | | Browser cannot decrypt a large archive | Use the streaming CLI below for packages larger than 256 MiB. A wrong or lost private key cannot decrypt the result. | | Verification rejects the signer | Use a trusted current TgWitness installation and the exact caller `OWNER/REPOSITORY`. Do not accept a replacement policy supplied with the archive. | | Telegram still lists the temporary session | End it in Settings → Devices. Logout can fail and a forcibly terminated workflow may not run cleanup. | Before relying on this preview, try a small chat you control: create a message and attachment, collect them, decrypt the result, run the verifier, check the coverage/media outcomes and confirm Telegram session revocation. Automated checks use a synthetic Telegram client plus a separate real GitHub certificate test; no live-account run on the current revision has been recorded. ## Local decryption and verification Use tools from an independently trusted installation, not executable files supplied by an unknown evidence archive: ``` python -m tgwitness.sealed_crypto decrypt delivery.tgwsealed --key sealed-key.json --out delivery.zip # Unzip delivery.zip using your archive manager, then: python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness ``` For multipart delivery, decrypt the main package first and keep its extracted manifest beside every encrypted part, then run: ``` python -m tgwitness.sealed_parts evidence.parts.json --key sealed-key.json --out evidence.zip python -m tgwitness.sealed_verify evidence.parts.json --assembled evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness ``` The manifest is the attested subject and binds every part and the assembled ZIP. Use `--max-gib` to set an appropriate uncompressed verification ceiling for a large archive; the default is 4 GiB. Expected-selection and complete-scope checks also work with multipart delivery. Python 3.11+, the project's dependencies, and a recent GitHub CLI supporting `--signer-digest` and `--deny-self-hosted-runners` are required. A CLI key generator is also available: `python -m tgwitness.sealed_crypto keygen sealed-key.json`. The verifier uses `tgwitness/sealed_policy.json` from the trusted installation. It checks the caller repository, upstream signer workflow, approved signer commit, hosted runner requirement, complete ZIP digest, internal journal and attachment integrity, fresh account-key origin, and expected collector commit. It displays history and media outcomes instead of implying all data was saved. An empty approved-release list fails closed. Updating the policy is an explicit trust decision; never accept an archive's own proposed policy automatically. For offline use, obtain trusted roots ahead of time from a trusted environment: ``` gh attestation trusted-root > trusted_root.jsonl python -m tgwitness.sealed_verify evidence.zip --bundle attestation.jsonl --repo OWNER/TgWitness --trusted-root trusted_root.jsonl ``` The timestamp of the attestation concerns the archive's commitment. It does not authenticate message timestamps or the collector's wall clock. See [GitHub's verification options](https://cli.github.com/manual/gh_attestation_verify). ## How the fork is kept outside the capture process The caller contains a job-level reference to the upstream reusable workflow at a full commit SHA. That workflow explicitly checks out **the upstream repository at a fixed collector SHA**. A default `actions/checkout` in a reusable workflow would check out the caller and is intentionally not used. The workflow does not restore caller caches, consume caller artifacts, execute caller files, or accept source/image URLs, shell commands, prepared ZIP files, or hashes to sign. It accepts a bounded public recipient and session duration. Actions, the Python base image, and cloudflared are pinned by immutable digests; Python dependencies use the existing hash-locked requirements. The image is built from the trusted source without a cache. The collector runs as a non-root user with a read-only image, dropped Linux capabilities, resource limits, and no Docker socket or GitHub-token environment. Its only mounts are fresh configuration, workspace, and output directories. The restricted FastAPI application exposes login, dialogs, configurable account or chat collection, status, resume, finish, and cancellation. There is no plaintext download route, general administration route, import route, or signing endpoint. The supervisor stops the network-facing containers before the attest action reads the final fixed `evidence.zip` or `evidence.parts.json`. The packaging container has no network. The upload steps name only `connection.tgwsealed` and `delivery*.tgwsealed`; neither plaintext evidence nor Telegram credentials are uploaded as artifacts. Cleanup removes the private directories and containers, and GitHub discards the hosted runner VM after the job. Artifact retention is one day; download before expiry. A fork owner can replace the caller or create a different signed file. The strict verifier must reject the resulting **different signer workflow/digest**. This construction still depends on the absence of exploitable bugs in approved code and on the integrity of GitHub's runner and signing infrastructure. ## Cryptographic handoff Each recipient key is RSA-3072 (RSA-4096 imports also accepted), exponent 65537. Each envelope has a fresh random AES-256 key and 96-bit nonce. RSA-OAEP with SHA-256/MGF1-SHA256 wraps the AES key. AES-GCM with a 128-bit tag authenticates the complete prefix and payload. The public recipient is DER SPKI in base64; the private key file contains DER PKCS8 in base64. Envelope bytes are `TGWSEAL1\n`, a big-endian uint32 JSON-header length, the header, ciphertext, and a 16-byte GCM tag. The header has exactly `algorithm`, `key`, and `nonce`; algorithm is `RSA-OAEP-256+A256GCM`. The complete prefix through the header is GCM additional authenticated data. Header size is bounded at 8192 bytes. The CLI streams payloads up to 8 GiB and authenticates before installing the requested output; it refuses overwriting an existing destination. This is a project-specific envelope around standard cryptographic primitives: RSA-OAEP with SHA-256 and AES-256-GCM, available in OpenSSL and every major cryptography library. The original evidence bytes are attested **before** placing the evidence and attestation in the encrypted outer package. This avoids a circular dependency between the archive's hash and a certificate included inside that same archive. For public repositories, attestation metadata (repository, workflow, commit, artifact name and digest) is public. Never put chat names in public metadata. ## Scope and validation This mode uses the signed journal and account-export engine. Secret Chats, deleted history from before collection and data inaccessible to the account are excluded. Private cloud chats are eligible when selected. The chat picker is capped at 20,000 dialogs; account export discovers its own inventory. Missing data, failed files and unfinished tasks are recorded. Attachment limits and runner disk/time limits still apply. Large delivery uses encrypted parts instead of a fixed 4 GiB delivery cutoff. Completion means the frozen selected tasks finished, not that every historical Telegram record exists in the archive. The chat journal can also observe live updates; neither mode is an atomic snapshot. Generated screenshots and screen recordings are not part of this mode. Tests cover synthetic fresh login, scope isolation, media, cancellation, partial deadline completion, failed logout, forbidden API paths and fields, preloaded workspace rejection, wrong-key and tamper rejection, required verifier flags, and browser/Python encryption interoperability. The browser acceptance test uses a plainly labelled mock attestation; it is not a real Sigstore test. Real hosted-runner, Docker, GitHub attestation, and live Telegram acceptance must be reported separately from local synthetic checks. [GitHub Actions terms](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features#actions) restrict use of hosted runners to the software project's lifecycle. A fork does not remove these restrictions; this preview must not be marketed as unrestricted free production hosting. [Cloudflare Quick Tunnels](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) are also intended for testing and development. The helper/workflows are suitable for evaluating this feature; production service eligibility remains a separate deployment requirement. ## Maintainer release sequence 1. Commit and review the collector, supervisor, container definition and tests. 2. Pin that collector commit in `sealed-collector.yml`, then commit/review the reusable workflow. Never silently derive the checkout from the caller SHA. 3. Pin the reusable workflow commit in `sealed-witness.yml` and add its workflow/collector SHA pair to `sealed_policy.json` in a trusted release. 4. Publish all referenced commits and the helper, then test an independent fork and the real GitHub certificate. Do not squash away commits referenced by these pins unless the references are regenerated and published again. See [reusable workflows and attestations](https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/increase-security-rating) for the distinction between the caller repository and the upstream signer. --- # Telegram OSINT Investigations Across Chats Canonical page: https://phishdestroy.io/tgwitness/docs/cases/ Investigate saved Telegram channels, groups, private chats and bots. Connect people, messages, files and timelines in a verifiable case package. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) A whole case across channels, groups, private chats and bots: collect, connect the dots, rebuild the timeline, hand it over. One made-up incident, start to finish. Collection, search and people profiles find the records, [Case Board](https://phishdestroy.io/tgwitness/docs/case-board/) organizes them, [Report studio](https://phishdestroy.io/tgwitness/docs/reports/) presents them. WORKED CASE / A CHANGED PAYMENT DESTINATION ### One incident. Four conversations. A trail to reconstruct. A channel post points to a bot. A group talks about a new payment link and the bot shows it. The post gets edited, a private chat repeats the link, a group message vanishes. Who posted each version?Where did the link appear?Which file was preserved?What changed, and when? History loading, AI, MCP, OCR and webhooks: [Work the archive](https://phishdestroy.io/tgwitness/docs/archive/). ## 1. Establish coverage across the whole account Whole-account scope only on a dedicated account. A main account gets chosen chats or a folder. 1. [Connect the account](https://phishdestroy.io/tgwitness/docs/accounts/) in its own workspace. Note the case reference, account ID, workspace and key fingerprint. 2. **Sources → Observation scope → Investigation mode**: **Whole account**, all four source types, **Own actions**. Every new chat gets its profile and last **200 visible messages** saved. **Save scope** and confirm. 3. **Load chats** and compare with the account's chat list. The limit is 1,000 dialogs (up to 20,000 in **Parameters → Chats read from the account's list**); chats beyond it show up once they get active. 4. **Recording settings** → **All visible activity**, check attachment limits and disk space. Start, then test with a message, an edit and a deletion. ChannelsGroupsPrivate chatsBots ONE ACCOUNT / ONE SIGNING KEY**All selected account-visible activity → one journal** Messages · edits · deletion notices · visible reactions · membership events · own actions "Whole account" means every chat this account can open, minus exclusions. Secret Chats are recorded by the Secret Chat module. New chats join as they appear; older history loads on request. ## 2. Acquire history and preserve the files Make a Case Board collection and bookmark what matters. Keep a source register: chat ID, title, account, role, start of live capture, history result, media result, gaps. | Need | Action in the panel | What it provides | | --- | --- | --- | | History across enabled chats | Sources → Load full history | Available past messages enter the workspace journal, with pause/resume and a signed progress report. [History guide](https://phishdestroy.io/tgwitness/docs/reference/history/). | | Existing chat context in the journal | Sources → Recording settings → History snapshot | Recent messages as signed records. 500 by default, up to 10,000 in **Parameters → Largest history snapshot**. | | Complete currently visible history of one chat | Full chat export → Export full chat, or Chats → Export chat | A separate signed bundle with `chat.json` and `chat.html`, one per chat. | | Context when a new chat appears | Observation scope → When a new chat or bot appears | Its profile and up to 1,000 recent messages (200 in Investigation mode). Not applied to existing chats. | | Attachment bytes | Download visible attachments + per-type limits | Look for `media.saved` with SHA-256 and size. Queued, skipped or failed means not saved. | A chat export doesn't go into the journal or people profiles. To search old history inside TgWitness, use **Load full history** or snapshots. Here: the channel, the group, the bot chat and the private chat, plus the invoice file and its hash. What was deleted before capture is gone. ## 3. Keep the evolving conversation and your own actions Keep it running. Star the hot chats as priority, tune rechecks in **Recording settings → Recheck**, and keep an eye on `recheck.completed`, FloodWait and media results. **Chats → Profile → Save profile now** saves the chat's description, bot commands and other metadata. **Following a bot or invitation as part of the case** 1. **Chats → Open Telegram link**, save the preview first. Link and preview become signed records. 2. If needed, **Join / open and observe** joins the chat or starts the bot with its start parameter. 3. To document an action, reply or **Press button** from the panel. You get `interaction.requested` and `interaction.result` with the bot's answer. These are real actions. Buttons pressed in another app aren't visible, only the bot's reply. No web apps, payments or phone/location. ## 4. Follow people, links and files across chats 1. **Journal**, **All sources**, search a phrase, domain or username. Open hits and send them **To board**. 2. **Chats → People → Turn on profiles**, pick a person: name history, replies, activity, **Also in…**, links, wallets, phones. Open the cited records. 3. Follow the same numeric user ID into other chats. A matching name, wallet or avatar is a lead to check against the numeric ID. 4. Compare file hashes. Same SHA-256 = same bytes. CASE MAP / FOLLOW THE REFERENCESFictional case · not a live graph CHANNEL / ANNOUNCEMENT**Original → edited destination** Records #101, #188 Message #84 · sender not attributed GROUP / OPERATIONS**User 71001 posts the new link** Record #146 · message #309 Saved file receipt #151 BOT / ORDER CONVERSATION**A button points to that destination** Record #173 · message #12 Returned button metadata PRIVATE / FOLLOW-UP**User 71001 repeats the destination** Record #205 · message #922 Saved file receipt #209 Four chats contribute different observations. Follow the source records for every connection; the channel post has no attributed sender. The numeric IDs and record references are invented for this walkthrough. This explanatory map shows how to connect search results, profiles and inspected records; Case Board stores the corresponding cards and source references. | Connection | Supporting observation | Conclusion to retain | | --- | --- | --- | | Same Telegram account | User ID 71001 in group #146 and private-chat #205 | Same sender ID in both chats. | | Repeated destination | `pay.example.invalid/new` in #146, button metadata #173, edited post #188 and #205 | Same link in four places. | | Same file bytes | Equal full SHA-256 values in completed media receipts #151 and #209 | Both files are byte-identical. | Profiles only cover people who wrote something in *this workspace*, not a member list. Citations per fact: **Parameters → Records cited per fact**. ## 5. Reconstruct the sequence and mark the gaps Versions in **Chats**, then **Journal** with **All sources** + **Edits**, **Deletions**, **Coverage**. Put both times in the timeline: Telegram's date and when it was observed. 1. 09:00 · #101**Channel post captured** The original destination is retained. 2. 09:12 · #146 / #151**Group introduces a different link** User 71001 posts it; an attachment download completes. 3. 09:16 · #173**Bot shows the same destination** The saved keyboard metadata carries the link. 4. 09:20 · #188**Channel announcement changes** The original and edited observations both remain. 5. 09:24 · #205 / #209**Private follow-up repeats it** The saved attachment has the same full SHA-256 as #151. 6. 09:28 · #231**Group deletion notice arrives** The earlier observation remains; neither the deleter nor an exact deletion time is supplied. Illustrative observation times and references. Other journal records occur between these entries. Journal order is the order things arrived, not necessarily the order they happened. Keep live records, snapshots, recovered messages, deletions and "missing on recheck" apart, and mark every gap as unknown. ## 6. Extend the case to other collecting accounts One workspace per account, same steps. Note each one's role and fingerprint. Message numbers are per account, so always say which workspace and chat. An [account group](https://phishdestroy.io/tgwitness/docs/groups/) shows status, shares settings and exports everyone together, each with its own journal and key. A cross-account timeline you build in your notes. Long case? Add an [independent witness](https://phishdestroy.io/tgwitness/docs/witness/), and test what each account actually catches. ## 7. Deliver a checkable case package A signed ZIP from every workspace (always the full journal, filters don't matter), plus people profiles, chat exports and files. ``` CASE-001/ # assembled by the analyst case-notes.md # question, findings, alternative explanations sources.csv # every chat, role, acquisition result and gap timeline.csv # account + chat + message + seq + both times workspace-A/ evidence.zip # complete signed observation journal retained-checkpoint.json profiles-operations.json # separately signed people profiles history-channel.zip # signed current-history export history-group.zip verification.txt workspace-B/ # separate journal and trusted fingerprint witness/ # retained checks, journal and signed posts SHA256SUMS # hashes of the delivered files ``` Send fingerprints separately. Verify everything against its own workspace: ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint retained-checkpoint.json --require evidence python -m tgwitness.verify profiles-operations.json --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --evidence evidence.zip python -m tgwitness.verify history-channel.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 ``` The checkpoint is signed with the collector key, so on its own it does not meet the minimum for evidence; `--require evidence` also needs a checked timestamp or witness post covering the last record. Keep the verifier output, originals, coverage and transfer record with your findings. Write it up in Report studio. If the recipient needs less, make a [minimized handover](https://phishdestroy.io/tgwitness/docs/handover/). --- # Telegram Case Board: Evidence & Annotations Canonical page: https://phishdestroy.io/tgwitness/docs/case-board/ Organize saved Telegram observations, exact highlights and action slices on a Case Board. Link team annotations and presentations to their source records. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Turn saved messages into a case your team works on together. Bookmarks, exact quotes, slices and discussion, each linked to its source. Every change is a signed revision. ## From a message to a case card 1. **Investigation → Case Board** (Standard or Expert mode). Make a collection for the case. 2. In **Journal** or a chat hit **To board** (or **B**). The card lands in Inbox, give it a title and move it. 3. Select text in a message, **Highlight → board** keeps the exact quote and version. Note why it matters. 4. Discuss, set a status, jump back to the source whenever needed. **Presentation** walks the team through it. ### Follow one changed payment link Synthetic example · local illustration 1. **Capture.** Open saved observation #142 and its message version. 2. **Bookmark.** Keep the quote, source reference and your question on a card. 3. **Review.** Add a team comment and move the card to Review. 4. **Present.** Walk through the collection and open the cited source context. #### Saved observation #142 “Use the new payment link.” Operations chat · message 38 · observed 09:12 UTC #### Card: changed destination > Use the new payment link. Question: which destination appeared in the earlier version? #### Team review Analyst: compare with observation #101. Status: Review · revision retained #### Source context Card → saved version → earlier observation The annotation and the Telegram observation remain separately identifiable. ## Save a useful range once Shift-click two messages for **Slice between**, use **Slice by time**, or save the current Journal filters. **Show records added since bookmark** shows what came in later. Time slices use observation time; message-ID slices follow those messages as they change. ## Give each colleague the right role **Reviewer** reads, **Analyst** adds cards and comments, **Operator** also manages collections and decisions. Chat permissions apply to cards too. ## Carry the work into a deliverable Slices export as signed JSON or CSV. Reports can include bookmarks, slices and comments, set that in [Report studio](https://phishdestroy.io/tgwitness/docs/reports/). For a limited recipient, use a [handover](https://phishdestroy.io/tgwitness/docs/handover/). Details: [Case Board reference](https://phishdestroy.io/tgwitness/docs/reference/case-board/). --- # Telegram Evidence Reports: HTML & Signed PDF Canonical page: https://phishdestroy.io/tgwitness/docs/reports/ Build Telegram case reports from saved records. Choose a layout, preview the selected data and export HTML, signed PDF or a complete evidence package. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Take the reader from the case question straight to the saved records. Report studio puts together the data you pick, change histories, charts and your findings. Eight designs, HTML and native PDF. Every HTML, PDF and JSON report is sealed with your key. ## Build a report in three steps 1. **Exports → Configure and preview → Data**: whole workspace, or pick chats, authors, dates (UTC, when TgWitness saw the record) and record types. 2. **Design & contents**: pick a design and what goes in: charts, participants, transcript, changes, Case Board items, your case details and notes. 3. **Preview**: check counts, activity, samples and missing ID ranges. Save, then download the format you need. ### Arrange the same saved material for a reader Synthetic example · schematic layout, not a generated report 1. **Select.** Choose two chats and the observation period for the case. 2. **Compose.** Choose a layout and the sections that answer the question. 3. **Preview.** Review the selected counts and the saved before-and-after text. 4. **Verify.** Generate the final file and check its signature against the trusted workspace fingerprint. #### Selected observations 2 chats · 1 observation day Messages, edits and deletion notices #### Report structure ##### Changed payment destination Case question → scope → findings → record references **Message context** Observation #142: “Use the new payment link.” **Saved changes** Before: old.example.invalid → After: new.example.invalid #### Review the selection 18 observations · 2 saved edits Sent, edited and observed times have separate labels. #### Final deliverable Signed PDF + signed JSON, or a signed ZIP with its readable report Recipient checks the file and trusted fingerprint. ## Choose a reading style **Classic, Editorial, Briefing, Analytics, Technical, Overview, Reading series, and Ledger & margin**: same records, different look. Switching keeps your selection and notes. Any of the 25 languages. PDFs are built with bundled fonts, no browser needed. Chinese, Japanese and Korean need a font like Noto Sans CJK on the server (system-wide or in `TGWITNESS_FONT_DIR`), otherwise you get HTML and JSON only. ## Read a change with its context Edits show before and after, deletions show the last saved version. Replies, forwards, reactions, buttons and attachments keep their references. The design preview uses the first 50,000 records, the data preview counts everything exactly. For final page layout, generate the PDF. ## Choose the recipient's copy deliberately Filters only shape the report, the evidence ZIP still has the full journal and files. If the recipient should get less, use a [minimized handover](https://phishdestroy.io/tgwitness/docs/handover/). More: [report contents](https://phishdestroy.io/tgwitness/docs/reference/case-reports/), [verifying the export](https://phishdestroy.io/tgwitness/docs/exports/). --- # Share Telegram Evidence with Limited Disclosure Canonical page: https://phishdestroy.io/tgwitness/docs/handover/ Prepare a minimized Telegram evidence sharing copy. Choose records and fields, inspect disclosure and verify its manifest against the source journal. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Share only what's needed, the original stays untouched. A handover is a separate signed extract: pick chats and people, hide identities or text, choose files and team notes. The manifest records what was kept, trimmed and left out. ## Prepare the recipient's extract 1. **Exports → Handover extract**: write the purpose, pick chats and a period, **Load people of the chosen chats** if you need named people. 2. Everyone else: pseudonyms, left out, or as recorded. Text and files are separate switches; phones and emails can be masked. 3. Case Board: nothing, bookmarks and slices, or cards with comments. Team names can be swapped for aliases. 4. **Download handover extract**, open it, verify it, look through it before sending. ### One original, a deliberate sharing copy Synthetic example · identity illustration only 1. **Select.** Include the case chat and identify the person the extract is about. 2. **Minimize.** Choose how another participant appears in the sharing copy. 3. **Inspect.** Open the generated archive's report and records before sending it. 4. **Share.** Deliver the checked copy and communicate its trusted fingerprint separately. #### Original observation Nora · user 71002 “I received the revised link.” The source journal keeps this saved observation. #### Recipient's copy Show as recorded: Nora · user 71002 · “I received the revised link.” Pseudonym: P01 · “I received the revised link.” Omit: this participant's message is left out of the copy. #### Inspect the actual files Read report.html and records.jsonl. Check identities, text, attachments and optional team comments. #### Signed extract Selection + file hashes + signed manifest A separate package linked to its source journal boundary ## Use the controls together | Control | Effect on the copy | | --- | --- | | People | Selected people stay named; others get pseudonyms or are left out. | | Text | All text, only the selected people's and your account's, or none. | | Files | Files of the selected people and your account, all shown files, or none. | | Case Board | Nothing, bookmarks and slices, or cards with discussion. | Read the text and files too: a pseudonym doesn't remove names written inside a message or attachment. If a selected file is missing, restore it or leave attachments out. ## Keep the copy independently checkable ``` python -m tgwitness.verify handover.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 ``` Keep the original archive and checkpoints yourself. The recipient can verify their copy without getting the whole workspace. Design: [Report studio](https://phishdestroy.io/tgwitness/docs/reports/). Trusted references: [export verification](https://phishdestroy.io/tgwitness/docs/exports/). --- # Manage Multiple Telegram Collection Accounts Canonical page: https://phishdestroy.io/tgwitness/docs/groups/ Manage TgWitness account groups, compare observation coverage and apply shared settings with per-account exceptions. Keep workspaces and journals separate. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Run several accounts together, each still with its own records and key. A group puts connection status, start/pause, shared settings and exports on one screen. Handy when several accounts work the same case. ## Open the group overview Open the group in **Accounts**. Each account shows its state, route, latency and last saved message. **Needs attention** lists the broken ones, **Fix** takes you straight there. **Start all** / **Pause all** ask before acting. **Group settings** are shared, but an account's own values stay until you replace them. ### Review a route change across a group Synthetic example · illustrative checks and outcomes 1. **Select.** Choose the group and review which accounts will change. 2. **Prepare.** Keep an account's own route when it should remain separate. 3. **Check.** Test the proposed connection and inspect the measured results. 4. **Apply.** Recheck before saving and review the outcome for each account. #### Case team Channel collector · Group collector · Reference account 3 separate workspaces #### Reviewed selection 2 accounts take the proposed route. Reference account keeps its own route. #### Preparation checks Channel collector: Telegram transport 84 ms Group collector: Telegram transport 91 ms These numbers are fictional measurements for the example. #### Application results Channel collector: route saved, observation resumed. Group collector: recheck failed, previous settings restored. Reference account: own route retained. ## Change the route with a review step 1. **Change the group route**, pick the type and settings. 2. **Review selection**: see which accounts change and which have their own route. 3. **Prepare and check** tests a fresh Telegram connection, plus the exit IP where possible. 4. **Apply checked connection** and look at each result. Running accounts resume, idle ones stay idle. Latency is the Telegram connection setup time, the exit IP is what the route showed at check time. Results can differ per account. ## Use overlapping access **Chats several accounts see** lists shared sources and their coverage. Channels and supergroups can be exported by several accounts at once with **Export with … accounts**. Private chats and basic groups can't, their message numbers are per account. ## Export the group as a package **Export group** gives one ZIP with every account's signed export and a signed list of them. Each keeps its own fingerprint for verification. A merged timeline you still build yourself. Next: [reports](https://phishdestroy.io/tgwitness/docs/reports/), [Case Board](https://phishdestroy.io/tgwitness/docs/case-board/), [verifying exports](https://phishdestroy.io/tgwitness/docs/exports/). --- # Telegram Evidence: Hash Chains & Signatures Canonical page: https://phishdestroy.io/tgwitness/docs/concepts/ Follow Telegram records through a SHA-256 hash chain, Ed25519 signatures and retained checkpoints. Explore what each integrity check proves. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Messages change. Your record of what you saw shouldn't, and anyone should be able to check that. Two small experiments below. Fake messages, everything runs in your browser, nothing goes to Telegram. ## From a chat export to a verifiable record A [Telegram Desktop export](https://telegram.org/blog/export-and-more) saves the history you can see right now as HTML or JSON. TgWitness adds a running journal of changes, signatures on every record and checkpoints others can compare against. | Task | Telegram Desktop export | TgWitness | | --- | --- | --- | | Read saved conversations | HTML or JSON with selected media | Saved chats, searchable journal and offline reports | | Follow a change over time | The history available when exported | Old versions, later edits and deletions, all kept | | Check files after handover | Standard HTML/JSON export files are unsigned | Signed manifest, signed records and sealed reports, checked against a trusted key | | Compare with an earlier retained state | Keep a separate reference copy or hash | Signed checkpoints, a separate witness and optional external timestamps | The comparison is based on the [Telegram Desktop export code](https://github.com/telegramdesktop/tdesktop/tree/768d47cda6c7f447c10a25d1f363279493a90ed7/Telegram/SourceFiles/export/output) as of 2 November 2026. ## One message, three observations A new message, an edit and a deletion become three separate records. The edit doesn't overwrite the first one, and the deletion doesn't erase it. 01 / MESSAGE JOURNEYIllustrative sequence Telegram delivers an update to the collector, which appends a journal record. · Telegram · Collector · Journal · update → · append → CURRENT CHAT VIEW Message #42 Message deleted The message has disappeared from the chat view. OBSERVATION JOURNAL 3 records 1. 01 `message.new` Meet at 10:00 ✓ 2. 02 `message.edited` Meet at 11:00 ✓ 3. 03 `message.deleted` Deletion notice for #42 ✓ All three received observations remain in the journal. Simplified path for one already selected source. Operational records also share the real journal. Capture depends on what the account can see and what Telegram delivers. ## Change a record. Follow the hash. Every record contains the hash of the one before it. A checkpoint kept somewhere else pins the journal length and the last hash. 02 / HASH-CHAIN SANDBOXReal SHA-256 · sample records RECORD 01**Message received**`h₁ = SHA-256(e₁)`Links to 64 zeroes RECORD 02**Meet at 11:00**`h₂ = SHA-256(e₂)`Includes h₁ RECORD 03**Deletion observed**`h₃ = SHA-256(e₃)`Includes h₂ RETAINED ELSEWHERE**3 records · head `h₃`**Compare this fixed boundary with the supplied journal. Altering an event changes its hash. Rebuilding the chain changes its head. Removing the tail makes it shorter than the retained checkpoint. **Inspect record 2 and the full hashes** This is the exact UTF-8 JSON hashed in this example. Values are fictional; the nine fields and serialization match the journal format. ``` ``` Saved record 2 hash `` Recalculated record 2 hash `` This sandbox computes hashes, not signatures. The real verifier also checks every event’s Ed25519 signature, sequence and link. Rebuilding hashes alone cannot create valid signatures under the trusted key. ## The actual rules, in a few lines HASH + SIGNATURE h0 = 064 hi = hex(SHA-256(C(ei))) σi = Ed25519.Sign(sk, unhex(hi)) **C** is the nine event fields as UTF-8 JSON: sorted keys, no extra whitespace, no ASCII escaping, no NaN/infinity. `previous_hash` is hi−1, h0 is 64 zeros, signatures cover the 32 raw digest bytes. The fields: `seq`, `observed_at`, `source_at`, `kind`, `chat_id`, `message_id`, `actor_id`, `payload`, `previous_hash`. Full spec: [event encoding](https://phishdestroy.io/tgwitness/docs/reference/evidence/#event-canonicalization). RETAINED CHECKPOINT Nexport ≥ Ncheckpoint hexport[Ncheckpoint] = Hcheckpoint Check the checkpoint signature against the pinned key, then compare it with the journal. A later export can be longer, but it has to match at the checkpoint. ## Three questions, three different checks [01 / INTEGRITY**Did this record change?** Hashes and signatures against a key you trust.](https://phishdestroy.io/tgwitness/docs/exports/)[02 / CONTINUITY**What was retained earlier?** Compare the export with checkpoints a witness kept.](https://phishdestroy.io/tgwitness/docs/witness/)[03 / DELIVERY**Did these test events arrive?** Send, edit and delete test messages and see what each account caught.](https://phishdestroy.io/tgwitness/docs/cases/) Signatures answer "was it changed", checkpoints answer "does it match what was there before", test messages answer "did we catch everything". [What verification proves.](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) Next: a [whole-account investigation](https://phishdestroy.io/tgwitness/docs/cases/) from start to case package. [Export Clinic: watch the controlled Desktop experiment](https://phishdestroy.io/tgwitness/docs/export-clinic/). Compare the two-minute film, the original recording and seven pairs of test exports. Local modification is disclosed. --- # Secure Telegram Sessions & Evidence Storage Canonical page: https://phishdestroy.io/tgwitness/docs/security/ Review TgWitness session storage, signing keys, panel access and network exposure. Apply the security model to your Telegram collection workspace. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) What leaves your machine, what each secret opens, and what the protections cover versus what's on you. **127.0.0.1**panel address by default **256-bit**random panel token **0**CDNs, analytics or remote fonts **Ed25519**signature on every record ## Where everything lives The collector, the panel and every record stay on your machine. By default only Telegram is contacted; everything else is a separate switch. 06 / WHAT LEAVES THE MACHINEYour installation YOUR COMPUTER OR SERVER **Panel**127.0.0.1:8787 · bearer token **Collector**one Telegram client per workspace DATA DIRECTORY **Journal**SQLite · hash-chained · signed **Media**files named by SHA-256 **Vault**Fernet · session, API pair, signing key, proxy - **Telegram**Always · through your route The account's MTProto connection: direct, SOCKS5, HTTP or MTProxy. Hide IP mode waits for a working proxy. Direct fallback requires a mode that explicitly permits it. - **Off-site copy**Optional · off by default Journal, files and checkpoints encrypted with AES-GCM before upload to S3-compatible storage. The key stays with you; attachments are named by keyed hashes, not their content hash. - **Notifications**Optional · off by default Problems and change counts with chat titles. Message excerpts are sent only if you turn them on. - **Timestamp authority**Optional · off by default Only the SHA-256 of a signed checkpoint and a random nonce. No messages, no chat names. - **Witness**Optional · off by default Pulls signed checkpoints and capture counters with a read-only token. It cannot read conversations or change settings. Default: only the Telegram connection leaves this machine. Optional destinations are configured per workspace. ## What each secret unlocks | Secret | Where it is kept | What it unlocks | If it leaks | | --- | --- | --- | --- | | **Panel token** | `panel-token.txt` in the data directory; the browser keeps it per tab | Everything in every workspace | Stop TgWitness, delete `panel-token.txt`, start again: you get a new one | | **Telegram session** | Vault, encrypted (`credentials.enc`) | The Telegram account itself | End the session in Telegram under *Settings → Devices* | | **Signing key** | Vault, encrypted (`signing.enc`) | Signing records under your fingerprint | Checkpoints kept elsewhere, a witness and timestamps still show what existed before | | **Vault key** | `vault.key` next to the data, or an external master key | The vault | Assume the session and signing key leaked too | | **Witness token** | On the witness host | Read-only: checkpoints and health | Delete it on the Witness page, make a new one | | **Off-site copy key** | Vault; download it once for recovery | The off-site copy | Anyone who also has the bucket can decrypt it: treat the copy as exposed | ## What the protections cover ### Covered - A changed, removed or reordered record: the hash chain or a signature breaks. - A journal cut back or rebuilt after you saved a checkpoint elsewhere: the checkpoint stops matching. - Guessing the token: 256 random bits, constant-time compare, 15 failures a minute and the address is blocked. - Hostile chat content: text stays text, never HTML; attachments download as files; the panel loads nothing from other sites. - A stolen data directory with an external vault key: sessions and keys stay encrypted. ### Left to you - The main token can do everything. Give others scoped access and keep the main one to yourself. - Keep the fingerprint and checkpoints elsewhere. - Encrypt the disk, lock down permissions. - Plain HTTP outside localhost leaks the token. Use HTTPS or an SSH tunnel. - Check coverage for gaps and test delivery on your own accounts and sources. [Share access to a case](https://phishdestroy.io/tgwitness/docs/access/) with permissions, expiry and session limits. ## Harden an installation 0 of 8 done 1. **Use a dedicated Telegram account**, never your main one. 2. **Keep the panel on 127.0.0.1.** Remote access only via HTTPS (bundled Caddy) or an SSH tunnel. 3. **Encrypt the disk** with the data directory. 4. **Restrict the data directory** to the service account (0700 on Unix, folder permissions on Windows). 5. **Keep the vault key elsewhere** on servers: set `TGWITNESS_VAULT_KEY_FILE` before the first start. 6. **Save the fingerprint and checkpoints** on another system, run a witness on another host. 7. **Never upload** `data/`, sessions, `panel-token.txt` or vault keys to GitHub or a chat. 8. **Do not log** `Authorization` headers or request bodies at a reverse proxy. **Can I change the panel token without losing data?** Yes, it only opens the panel. Stop TgWitness, delete `panel-token.txt`, start again. Journal, sessions and keys stay. If `TGWITNESS_TOKEN` is set, that value wins over the file. ## Report a vulnerability **Security → Report a vulnerability** on GitHub. Version, impact and a minimal repro with fake data. Never send credentials, account folders or real evidence. If private reporting is off, open an issue asking for a private channel, no exploit details. --- # Set Up a Telegram Evidence Witness Bot Canonical page: https://phishdestroy.io/tgwitness/docs/witness/ Run an independent witness bot with its own signing key. Publish Telegram journal checkpoints and compare evidence exports with records retained elsewhere. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) A separate process checks your journal and posts signed checkpoints to a channel. ## Two hosts, two signing keys HOST A / COLLECTOR**Account + journal** Telegram session Collector signing key Read-only checkpoint endpoint ← request signed answer → HOST B / WITNESS**Verify + retain** Pinned collector fingerprint Separate witness signing key Own journal + bot token Witness → Telegram Bot API →**Your channel · signed TGW1 posts** The witness pulls checks itself. Collector access is read-only. Bot publication uses the witness’s connection and token; no account session is given to the witness. 03 / CHECKPOINT DECISIONSIllustrative answers LAST ACCEPTED**120 records**`head 9c7d…` NEXT ANSWER**128 records**`head a4f2…` Accepted: the count grows, the signature verifies and the key matches. The witness retains this new boundary. All answering examples assume a valid signature and the pinned key. Hashes here are abbreviated illustrations. To confirm that the entire old prefix is unchanged, compare an export with retained checkpoints. ## Prepare a bot and a channel Make a bot with BotFather and let it post in your channel. Run the witness somewhere else: another host, ideally run by someone else, is worth much more than a second process next to the collector. ## Three steps in Extras 1. **Read-only access.** **Extras → Independent witness**, create a token, save the file. It reads checkpoints and health, nothing else. 2. **Channel and interval.** Telegram channel or Discord webhook, plus a collector address the witness can reach. Save the settings file. 3. **Launch.** Put `witness.json`, `witness-token.txt` and `bot-token.txt` together on the witness host and run: ``` python -m tgwitness.witness run --config witness.json --check-config python -m tgwitness.witness run --config witness.json ``` Wait for the first signed post in the channel, then save the witness fingerprint somewhere safe. Discord instead? Save the webhook URL as `discord-webhook.txt`. One witness posts to one place; long checks arrive as a file on Discord. ## Choose how often to publish Posting every check gives a steady outside record: every five minutes is about 288 posts a day per workspace. Advanced settings can post only on changes or problems, use a proxy or a custom Bot API. **What does the bot actually attest to?** It asks the collector for a signed checkpoint, checks it against the expected key and keeps its own signed journal, including missed and rejected answers. It checks the journal state, it doesn't watch Telegram itself. For that, run a controlled delivery test. ## Check the evidence later Keep the witness journal, the posts and the fingerprints. [How to check them](https://phishdestroy.io/tgwitness/docs/reference/witness/#verify) against the collector's export. --- # Zero Trust Case Study: Taylor Wessing, Dr. Zurheide & Dr. Schelinski Canonical page: https://phishdestroy.io/tgwitness/docs/signed-export/ Taylor Wessing's Dr. Patrick Zurheide and Dr. Tobias Schelinski signed a GDPR answer. Checked against its own file, it fails. A case study in zero trust. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) **Live case study**Real documents · real signatures · hashes published below · counts reproducible offline A case study in why zero trust is necessary. One request for a person's own data under Article 15 GDPR, answered by partners of a leading international law firm under qualified signatures. Every assurance in the answer had to be taken on trust: the signature, the titles, “a month of manual review”, the protection of third parties, “every court will agree”. Checked against the delivered file, none of them holds. This page shows what trust produced, and how a checkable model would have left no room to deceive or to doubt. 15 August 2025 · letter[Dr. Tobias Schelinski](https://www.taylorwessing.com/en/people/germany/hamburg/dr-tobias-schelinski)Partner, Taylor Wessing · specialist lawyer for information technology law 1 October 2025 · letter and Anlage 1[Dr. Patrick Zurheide, LL.M.](https://www.taylorwessing.com/de/people/germany/hamburg/patrick-vincent-zurheide)Salary Partner, Taylor Wessing, since 2025 · IT, data protection & tech litigation Professional roles are taken from the firm's linked profiles. This page does not say whether blocking the Steam account was justified. It shows what the delivered file contains and what the signed letters say about it. Every figure can be checked against the files. **830 pages**in the attachment to the second letter **36 seconds**from creation to last change of that attachment **905,672**characters readable under its black rectangles **2 signatures**declared in the two letters, one in each **In short.** A signature tells you who sent a file. It cannot tell you whether the file is complete, correct or true. Only checks on the bytes can, and anyone can repeat them. ## Zero trust: check the file, not the sender Zero trust means that nobody has to be believed: not a firm, not a title, not a signature, and not us. An answer to an access request should prove itself. It has to answer three questions, and a signature answers none of them. **Is the copy complete?**Does the requester have everything that is theirs, and is every omission counted and explained? **Is the copy unchanged?**Is each record what was originally held, and would any later change show? **Who decided what is hidden?**Was the withholding decided by someone entitled to decide, and can anyone check it afterwards? Most legal disputes in the EU stay closed: settlements under NDA, sealed files, decisions that are never published. We have nothing against that. This case is different, and probably not because what happened in it is rare. It has no NDA and no court decision, so it can be read from end to end: a very simple law, the GDPR; one request for a person's own data; what was actually delivered; and black rectangles that anyone can remove. What makes it unique is who answered, and how. Dr. Tobias Schelinski and Dr. Patrick Zurheide are partners of Taylor Wessing, in its own words [“a European legal services powerhouse”](https://www.businesswire.com/news/home/20251217415857/en/Taylor-Wessing-Diversifies-Its-International-Strategy). Both hold doctorates; one is a certified specialist lawyer for IT law, the other holds a Master of Laws from Aberdeen. They took 106 days not to process a lawful access request. Along the way they handed the reported account holder the complaint texts and logins of more than 1,800 other people, some of whom may be minors, under black rectangles that anyone can remove. **PhishDestroy's view.** A login, the user name, is highly personal data. It is reused across services, and an account that has lived for years is, in most cases, tied to a real person who can be identified through it. Looking only at the fifty visible fragments, we think any court could indeed be misled. With the full picture, the timeline and the arithmetic on this page make it plain that the GDPR request was not processed. No signature and no misspelled name changes that fact. ## What trust produced, and what the model would have done Each assurance in the answer is set below against the delivered file, and against the checkable model this page proposes. The evidence for every line follows further down. **The signature** „Dieses Schreiben ist qualifiziert elektronisch signiert“ It says who sent the letters. Under it, 905,672 characters stay readable beneath black rectangles. [Evidence](https://phishdestroy.io/tgwitness/docs/signed-export/#signature) The firm signs a salted hash of every withheld field. The content is checked, not the sender. **The selection** Counsel decide what the requester gets to read. 50 complaints left readable, all filed after the block and the request; 43 of them are “Suspected Hijacker”. 1,944 covered over. [Evidence](https://phishdestroy.io/tgwitness/docs/signed-export/#convenient) A rule declared and signed when the copy is made, every withheld record counted, and the choice reviewed by the authority. **“A month of manual review”** „… die volle Monatsfrist ausgeschöpft … manuell die Daten bereinigt …“ An 830-page file made in 36 seconds. Its first readable row is a homophobic slur, and complaints left readable are contradicted by the same file. [Evidence](https://phishdestroy.io/tgwitness/docs/signed-export/#refuted) Nobody's word about effort counts. The file proves itself, and anyone can find a contradiction in it. **Third-party rights** „soweit keine Rechte Dritter entgegenstehen“ The logins and complaint texts of more than 1,800 other people, delivered under black rectangles that anyone can remove. [Evidence](https://phishdestroy.io/tgwitness/docs/signed-export/#under) Other people's data never enters the requester's copy. It travels sealed for the authority's key. **The copy of the data** „Auskunft gemäß Art. 15 Abs. 1, Abs. 3 DSGVO“ Payments, support tickets and the records behind the block are absent. Only the complaints appear complete. [Evidence](https://phishdestroy.io/tgwitness/docs/signed-export/#inventory) The signed manifest lists what is included and counts what is not. No gap can go unnoticed. **“Every court”** „Aus unserer Erfahrung wird jedes Gericht …“ Fifty fragments can mislead. The whole file shows a request that was not processed. [Evidence](https://phishdestroy.io/tgwitness/docs/signed-export/#authority) The court or regulator opens the full original and checks every field against what the firm signed. **Every row has the same shape.** An assurance that had to be believed, a file that contradicts it, and a check that would have made the assurance unnecessary. With the model there is nothing to deceive with and nothing to doubt: the requester sees what is theirs, the authority sees the rest, and every field is bound to what the firm signed. [See the model](https://phishdestroy.io/tgwitness/docs/signed-export/#sealed) ## The evidence, point by point Every line of the comparison above rests on the files below: two signed letters and Anlage 1. Page references use PDF page order, and every figure can be repeated offline. ### The text remained under the black rectangles. This is how an answer to a simple access request looks when it comes from the top of the profession. The black rectangles left the underlying text in the file. That made it possible to read and compare both groups: the 50 descriptions left visible and the 1,944 covered over. THE LETTERTHE DELIVERED FILE “Regardless of the details of the complaints” The number alone is said to show repeated breaches of the Steam agreement. Dr. Schelinski · 15 Aug 2025 · p. 2 „Unabhängig von den Einzelheiten der Beschwerden …“ **50**descriptions left visible **August–September 2025** **1,944**descriptions covered over **February 2021–July 2025** 43 of the 50 visible descriptions are labelled “Suspected Hijacker”. Among the 1,944 covered descriptions, 269 have that label. Anlage 1, pp. 444–620. One further record has an empty description: 50 + 1,944 + 1 = 1,995 rows in the supplied table. ### Fifty complaints convenient for counsel The October letter names the ground for the block: the account was blocked as „Used for Hijacking“ (Dr. Zurheide, p. 8). Of the fifty complaints the requester was allowed to read, 43 say the same thing: “Suspected Hijacker”. All fifty were filed months after the account was permanently blocked, after the access request, and after the last logon that the same file records. Anlage 1, page 1, gives `Last Client/Web Logon Time: 2025-05-23 20:48:31 (UTC)`. The account was blocked on 7 May 2025. On 9 May 2025 Steam Support answered the first ticket: the block was not an error, it was permanent, and the ticket was closed. The access request followed on 17 June. By the letters' own account, a third party had the account by then: Dr. Schelinski writes that it was acquired from a third party after 3 May 2025 (p. 2), and Dr. Zurheide that a third party made payments through it after 3 May, the last on 30 July 2025 (pp. 1–2). The supplied complaint table then records: **53**Aug 2024 **54**Sep **70**Oct **79**Nov **82**Dec **92**Jan 2025 **32**Feb **35**Mar **20**Apr **12**May*blocked 7 May last logon 23 May* **1**Jun **7**Jul **47**Aug **3**Sep Complaint text under a black rectangleComplaint text left readable Complaints per month in Anlage 1, August 2024 to September 2025, counted from the file's text layer; the full history is under [Verify it yourself](https://phishdestroy.io/tgwitness/docs/signed-export/#verify). After the block on 7 May and the last logon on 23 May: one complaint in June, seven in July, then 47 in August. 1. 3 May 2025**From this date, per the letters: a third party**The account was “acquired from a third party”: Dr. Schelinski, p. 2 · “payments by a third party”: Dr. Zurheide, p. 1 2. 7 May 2025**Account blocked**Steam 3. 9 May 2025**Not an error, permanent; ticket closed**Steam Support, first ticket 4. 23 May 2025**Last logon**Anlage 1, p. 1 5. 17 Jun 2025**Access request**Dr. Zurheide, p. 1 6. 29 Jul 2025**The deadline begins, “if at all”**Dr. Schelinski, p. 1 7. 30 Jul 2025**Last “payment by a third party”; data attributed to the requester only from here**Dr. Zurheide, p. 2 8. Aug 2025**47 complaints, all readable**Anlage 1, pp. 444–448 9. 15 Aug 2025**Termination: 1,938 complaints, “regardless of their details”**Dr. Schelinski, p. 2 10. Sep 2025**3 complaints, readable**Anlage 1, p. 444 11. 29 Sep 2025**“Date of Report”**Anlage 1, p. 1 12. 1 Oct 2025**The answer: “the full month”, data cleaned “by hand”**Dr. Zurheide, p. 1 Dr. Zurheide writes that the full one-month period had to be used and the data cleaned by hand: „musste leider die volle Monatsfrist ausgeschöpft werden … manuell die Daten bereinigt werden mussten“ (p. 1). Three of the readable complaints are dated September 2025, and the report itself is dated 29 September. They were filed in the last weeks before the answer, while, by his account, the data was being cleaned. > “This account just started acting shady overnight” > > Suspected Hijacker · August 2025 · p. 446 > “Suddenly messaging people weird links probably stolen” > > Suspected Hijacker · August 2025 · p. 448 > “Friend warned me to report this one” > > Suspected Hijacker · August 2025 · p. 446 > “Everyone in voice chat agrees it's a stolen account” > > Suspected Hijacker · August 2025 · p. 446 #### The same file contradicts them Some of the fifty make claims that Anlage 1 can check against itself. The file records the account's logins and its security history. Both are in it; the security history is under a black rectangle. Left readable · Suspected Hijacker · Aug 2025 · p. 446 > “My friend can't log in, says someone changed the password” Security History · p. 830 · under a black rectangle**Last password change: July 2024** Not made by the owner, as the same file shows. There is no password change in 2025. Left readable · Aug 2025 · pp. 446, 448 > “This account just started acting shady overnight” > “Suddenly messaging people weird links probably stolen” Login History · pp. 1–119**Last logon: 23 May 2025** The login history ends in May 2025. Not one login is recorded in June, July, August or September. The account had been blocked since 7 May 2025; on 9 May Steam Support called the block permanent. Left readable · Aug 2025 · pp. 445, 448 > “Real person probably got locked out” > “My friend said they can't get into this account anymore” Security History · p. 830**No security change in 2025** The last change the security history records is the password reset of July 2024. **PhishDestroy's reading.** The slur on page 444 needed a translation. These complaints are in English, and the answer to them is in the same file. A month of manual review left them readable and put the line that contradicts them under a rectangle. #### How the fifty read Formatting does not prove who wrote a complaint. It is exactly what a court would look at before counting one. | Check | Left readable · 50 | Covered over · 1,944 | | --- | --- | --- | | Period | Aug–Sep 2025 | Feb 2021–Jul 2025 | | “Suspected Hijacker” category | **86%**43 of 50 | **13.8%**269 of 1,944 | | Description contains Cyrillic | **4%**2 of 50 | **55.4%**1,077 of 1,944 | | Reporter login: Latin letters + 3–5 digits | **62%**31 of 50 | **21.6%**420 of 1,944 | Cyrillic: at least one character from that script. Login pattern: Latin letters followed by 3–5 digits, nothing else. All 1,995 reporter logins, including those beside the 50 visible texts, are covered and remain extractable. No reporter login is reproduced here. Four readable texts repeat word for word across nine records; “Acting way off pretty sure someone else is using it” appears three times (pp. 446, 447). Dr. Schelinski · 15 Aug 2025 · p. 2 > „Unabhängig von den Einzelheiten der Beschwerden zeigt schon die bloße Anzahl …“ “Regardless of the details of the complaints, the mere number shows …” **Is the content really irrelevant to a court?** Dr. Zurheide · 1 Oct 2025 · p. 9 > „Aus unserer Erfahrung wird jedes Gericht die Sperrung … als rechtmäßig qualifizieren.“ “In our experience, every court will qualify the block … as lawful.” **Has his experience included every court? And would every court agree, with data processed like this?** The two questions are PhishDestroy's. We do not say how a court should rule on the block. We say that a court should be able to read what it is asked to count. ### What the black rectangles remove from view The two letters treat the same complaints in two ways. Dr. Schelinski counted all of them against the requester, „1.938 Mal“, regardless of their details (15 Aug 2025, p. 2). Dr. Zurheide then drew a line at 30 July 2025: only from that date „können wir … davon ausgehen, dass etwaige Daten … sich auf Ihren Mandanten beziehen“ (1 Oct 2025, p. 2). The black rectangles follow that line: every complaint text up to 23 July 2025, the last one before it, is covered; every one from August on is readable. **PhishDestroy's reading.** Before 30 July 2025 the complaints count against the requester as a number, and are withheld from him as data that is not his. The October letter itself argues from „zwischen 2019 und 2023“ (p. 7). Anlage 1 · page 444 · the first readable row Offensive AvatarSeptember 2025`p***r` A homophobic slur, masked here. It is the first entry the requester could read, after a month of manual review. #### What lies under the rectangles 1,148 complaints, more than half of the table, are filed as “Offensive Profile”. Not one was left readable: 1,147 have their text covered and one has no text. Read from under the rectangles, without logins, the covered descriptions keep returning to the same themes: | Theme | Covered | Readable | | --- | --- | --- | | Nazi, Nazism | **110** | 0 | | Hatred, hate speech | **108** | 0 | | Racism | **99** | 0 | | Ukraine, Ukrainians | **90** | 0 | | Russophobia | **84** | 0 | | Insulting the nation or Russians | **65** | 0 | | Propaganda | **64** | 0 | | An ethnic slur for Ukrainians | **50** | 0 | | Politics | **46** | 0 | 615 of the 1,944 covered descriptions touch at least one of these themes; none of the fifty readable ones does. Long texts repeat too: 18 texts of eight words or more appear word for word in 48 rows. Two of them, four times each: > “I made this account to report this user because he has stolen my account” > > Covered · 4 rows > “I created this account in order to expose this user because he robbed my account.” > > Covered · 4 rows One of the fifty readable texts (p. 448) is a pasted Steam profile page that names other users. It is not reproduced here. The rectangles covered every reporter's login and left that page readable. ### The statements and the supplied records Each statement below is quoted from the signed letters. Each record is in the files they delivered. Dr. Schelinski · p. 2 ### “Hundreds” in every year „In jedem Jahr, bis ins Jahr 2025 hinein, gab es demnach hunderte Beschwerden.“ **2021: 25 · 2022: 122** The annual counts in the supplied complaint table. The full monthly count is under [Verify it yourself](https://phishdestroy.io/tgwitness/docs/signed-export/#verify). Dr. Zurheide · p. 1 ### The full month, cleaned by hand „… die volle Monatsfrist ausgeschöpft … manuell die Daten bereinigt …“ **36 seconds** Anlage 1 was created at 19:58:05 and last modified at 19:58:41 for 830 pages. Its first readable complaint is a homophobic slur. Dr. Schelinski · p. 3 ### Protection of third-party rights „soweit keine Rechte Dritter entgegenstehen“ **905,672 characters remain** Text is still extractable beneath 1,044 black rectangles that overlap it. The rectangles also cover the account's own security history (p. 830). Dr. Zurheide · p. 7 ### “Between 2019 and 2023” „Über einen Zeitraum von mehreren Jahren, zwischen 2019 und 2023 …“ **Created in August 2020** Anlage 1, page 1, gives the account's creation time: August 2020. Dr. Zurheide · p. 9 ### Every court will agree „jedes Gericht … als rechtmäßig qualifizieren“ **A forecast** The sentence says every court will find blocking the Steam account lawful. It names no court and cites no ruling. ### What the signature can and cannot tell you A qualified electronic signature is strong evidence about the sender. It is not evidence about the content. The two questions have to be checked separately. ### A signature can show - who signed the document - that the signed bytes have not changed since signing ### A signature cannot show - that the export is complete - that the redaction removed anything - that the statements in it are true - that anyone read it before signing THREE CHECKS · DOK.-NR. 42603633 · ANLAGE 1Offline 01 · SENDER**Qualified e-signature**`„qualifiziert elektronisch signiert“`Declared by the firm on page 9. 02 · INTEGRITY**SHA-256 of Anlage 1**`2bb927e2…4ff7d6af`Matches the recorded hash. 03 · CONTENT**Text layer of Anlage 1**`pdftotext Anlage1.pdf -`905,672 characters readable under 1,044 rectangles. Sender: declared. Integrity: matches. Content: broken. The signature answered the first question and none of the others. Checks 02 and 03 need nothing but the file and standard tools. Check 01 tells you who sent it. Only 02 and 03 tell you what was sent. Dok.-Nr. 42603633 · page 1One page, two spellings `Dr. Patrick Zurheide, LL.M. (Aberdeen)`Signatory `p.zurheode@*****wessing.com`Letterhead `p.zurheide@*****wessing.com`Public record The title is spelled correctly. The signer's own name in the letterhead is not. Page 6 contains „Die Antwortet lautet ja, in den dort genannten Grenzen.“ twice, word for word, at the end of sections 1.5 and 1.6. Page 3 sends the data with „Anbei übersenden wie Ihnen …“. ### The request the export was meant to answer Behind the signatures is one request for one's own data. The law that governs it is short. REGULATION (EU) 2016/679 · OFFICIAL TEXT Art. 15(1) “The data subject shall have the right to obtain from the controller confirmation as to whether or not personal data concerning him or her are being processed, and, where that is the case, access to the personal data …” Art. 15(3) “The controller shall provide a copy of the personal data undergoing processing.” Art. 12(3) “… without undue delay and in any event within one month of receipt of the request. That period may be extended by two further months where necessary …” Source: [EUR-Lex](https://eur-lex.europa.eu/eli/reg/2016/679/oj) The letters know this law. Dr. Zurheide's opens with it: „nachfolgend erteilen wir Namens und in Vollmacht unserer Mandantin Auskunft gemäß Art. 15 Abs. 1, Abs. 3 DSGVO“ (p. 1). Apart from one reference to third-party rights (Dr. Schelinski, p. 3), neither letter cites a provision that allows a controller to restrict access: not Art. 12(5), not Art. 23, not the German BDSG. What the request received instead: 1. 15 Aug 2025 · Dr. Schelinski · p. 1**The deadline, “if at all”** „Die Frist nach Art. 15 DSGVO hat, wenn überhaupt, erst … am 29. Juli 2025 begonnen“ 2. 15 Aug 2025 · Dr. Schelinski · p. 2**The account terminated** „Hiermit kündigen wir daher Namens und in Vollmacht der Valve Corporation … mit sofortiger Wirkung.“ 3. 15 Aug 2025 · Dr. Schelinski · p. 2**Proof by count: 1,938 complaints, regardless of their details** „Unabhängig von den Einzelheiten der Beschwerden zeigt schon die bloße Anzahl …“ 4. 1 Oct 2025 · Dr. Zurheide · p. 2**Data narrowed to 30 July 2025** „… können wir erst ab diesem Zeitpunkt davon ausgehen, dass etwaige Daten … sich auf Ihren Mandanten beziehen.“ 5. 1 Oct 2025 · Dr. Zurheide · p. 8**The rest, on a condition** „Gerne beauskunften wir die restlichen (bzw. noch weitere) personenbezogene Daten, sobald Ihr Mandant uns nachvollziehbar darstellen kann …“ 6. 1 Oct 2025 · Dr. Zurheide · p. 8**“Accomplices”** „… dass Ihr Mandant bzw. dessen Komplizen seine Phishing-Angriffe … in verschleierter Form fortsetzen will“ 7. 1 Oct 2025 · Dr. Zurheide · p. 9**Four criminal statutes** „… §§ 263, 263a, 202a, 303a StGB) einer strafrechtlichen Verfolgung zuzuführen.“ **None of this is a condition in Art. 15.** A right of access is not cancelled by a termination, a forecast about courts or a criminal statute. 106 days after the request, it stood exactly as written. **PhishDestroy's reading.** The doctors cite the law on page 1 and then write as if there were no such law. ### The letter lists what Valve processes. The file leaves most of it out. On pages 2–6 the October letter quotes the Steam Privacy Policy to describe the personal data Valve processes. Each category it names is compared below with Anlage 1. Anlage 1 has twelve sections: account, profile, name history, logins, product keys, playtime, phone, complaints, chat, Steam Guard devices, friends and security changes. | Data | Named in the letter | In Anlage 1 | | --- | --- | --- | | Transactions and payments | „Transaktions- und Zahlungsdaten“ · p. 2 „… Transaktionsdaten … für einen Zeitraum von bis zu zehn (10) Jahren aufbewahren muss“ · p. 6 | **Absent** | | Trades and Community Market | „… Konsistenz des Gameplays oder Steam-Community-Marktes …“ · p. 6 | **Absent** | | Achievements, game progress, in-game items | „Ihre erspielten Errungenschaften … Ihren Spielfortschritt … Ihre im Spiel erhaltenen Gegenstände“ · p. 4 | **Absent** | | Game ownership | „… mindestens Ihr Eigentum am fraglichen Spiel“ · p. 4 | **Absent** · playtime and 100 key activations from a single day only | | Levels, badges, trading cards | „Daten über die Nutzung des Steam-Clients und der Steam-Websites“ · p. 3 · items and market · pp. 4, 6 | **Absent** | | Posts, comments, follows | „… veröffentlichen, kommentieren oder denen Benutzer folgen“ · p. 3 „Message Boards, Foren und/oder Chatbereiche“ · p. 5 | **Absent** | | Chat | „Informationen, die Benutzer im Chat gesendet haben“ · p. 3 | 2 entries, covered | | Support tickets | „… wenn Benutzer Informationen oder Support von Valve anfordern“ · p. 3 | **Absent** · including the May 2025 ticket that confirmed the block | | Linked third-party accounts | „… mit dem Konto eines Drittanbieters zu verknüpfen“ · p. 5 | **Absent** | | Records behind the block | „Zum Entdecken von Verstößen erforderliche Informationen“ · p. 3 „… nach einer manuellen Prüfung durch einen Mitarbeiter der Valve Corporation“ · p. 7 | **Absent** · no review record, no device link, no phishing report | **The letter describes the data. The attachment does not contain it.** Payments are the basis of both lawyers' conclusions about ownership, yet the payment category is the one the file leaves out. #### What the file does contain, and for which period Periods are taken from dates in the file, including dates under the black rectangles. | Section | In Anlage 1 | Period in the file | | --- | --- | --- | | Basic account data · email, country, username, Steam ID | Readable | Current state | | Logins | Date and type readable; time, IP, hardware ID covered | Oct 2023 – May 2025 · account exists since Aug 2020 | | Playtime | Games readable; last-use date and time covered | Dec 2020 – May 2025 | | Chat | 2 entries, covered | Sep 2025 only | | Complaints against the account | 1,995 rows · 50 descriptions readable | Feb 2021 – Sep 2025 | | Friends and blocks | 5,789 rows · covered | Feb 2021 – Sep 2025 | | Steam Guard devices · registered phone · security changes | Covered | Security log: Aug 2020 – Jul 2024 · 4 rows | | Product key activations | Keys covered | 100 rows, one date: 13 Mar 2025 | **Only the complaints appear to be there in full.** Almost nothing else is: logins start in October 2023, friends in February 2021, product keys on a single day, and whole categories that Valve stores are absent. The categories the letter's own decisions depend on, payments and the records behind the block, are not in the file at all. The friends list has 5,789 rows: 4,410 “Blocked User”, 1,182 “Friend” and 200 “Inviter”, dated 24 February 2021 to 28 September 2025; 74 are dated after the last logon. Whether it is the current list of connections or a full history including removed ones cannot be determined from the file. The answer to Art. 15(1) raises three further questions. The recipients (point c) and the source of the data (point g) are given only as general policy text, not for this account. The storage period (point d) is a quotation from the policy, without specifics. And the letter sends the data „als Anlage 1 und 2“ (p. 3); only Anlage 1 is examined here. ### Valve had already verified who owns the account The account was registered as a Steamworks partner in order to publish a game. That process involves a Steam Direct fee of USD 100, a tax interview, payout bank details and identity verification carried out by Valve itself. All of it is personal data Valve processes. Art. 15 GDPR covers every category of personal data processed, not only those listed in a privacy policy. None of it appears in Anlage 1. Dr. Schelinski · p. 1 ### “Not a single proof of ownership” „… kein einziger Beleg für die Inhaberschaft (Verfügungsbefugnis) Ihres Mandanten für den Account …“ **Identity verified by Valve** The partner verification, its documents and the USD 100 payment are held by the client the letter speaks for. Dr. Schelinski · p. 3 ### Proof demanded from the requester „… gefälschten ‚Utility Bill‘ …“ · „… tatsächlich alleiniger Inhaber des Accounts …“ **Proof withheld from the requester** The requester is asked to prove ownership while the ownership records Valve itself verified are left out of his access copy. ## The model: nobody decides alone, nothing can be swapped This is not about one piece of software. It is about who decides. In this case two lawyers decided which fifty complaints mattered and that the rest did not. No court, no regulator. Some things must stay hidden: the reporters' logins are other people's data. The question is who decides, and whether anyone can check the decision afterwards. A black rectangle answers neither, and anyone can remove it. Two standard tools answer both: a salted hash in the requester's copy, and the original sealed for the public key of a supervisory authority or a court. SALTED COMMITMENT · ONE PER WITHHELD FIELD c = SHA-256(salt ‖ value) The salt is 16 random bytes, new for every field. The requester's copy carries `c` in place of the value, under the firm's signature. The value and its salt travel in an envelope encrypted for the authority's public key, with OpenPGP or with X25519 and AES-GCM. Without the authority's private key nobody can open it, and the firm cannot swap a value without breaking the commitment it signed. 1. Step 1 · the requester**Hands over the copy and the envelope** The signed copy with its commitments and the sealed envelope go to the supervisory authority or the court. 2. Step 2 · the authority**Opens the envelope and recomputes** The inspector decrypts with the authority's private key and recomputes SHA-256(salt ‖ value) for every field. Each result must equal the commitment the firm signed. 3. Step 3 · an independent body**Decides what was really protected** The authority, not the firm, reads everything that was withheld, here 1,944 complaint texts and a security history, and decides whether third-party rights required withholding it. ANLAGE 1 · PAGE 514 · ONE ROW, TWO WAYS TO HIDE ITLive · in your browser As delivered · black rectanglesVisual overlay only Aspose.PDF for .NET 20.8 · page 514Text layer + rectangles Reporter: [login · not republished here] Date: 2024-03-28 Type: Offensive Profile Text: русофоб Black rectangles drawn on top. The text underneath stays in the file. Requester's copy · salted commitmentsSigned by the firm c = SHA-256(salt ‖ value)Sealed for the authority Reporter: [withheld · commitment] Date: 2024-03-28 Type: Offensive Profile Text: [withheld · commitment] Envelope · RSA-OAEP-256 + AES-256-GCMfor the authority's public key The copy holds commitments. Values and salts are in the envelope. 1. **1**The requester hands over the copy and the envelope 2. **2**The authority opens it and recomputes every commitment 3. **3**The authority decides what stays withheld Both panels hide the same two fields. Read the raw bytes, then run the authority's check. Left: one row of Anlage 1 as delivered; the complaint text sits under a black rectangle on page 514 and is quoted without the reporter's login, whose field holds a placeholder. Right: the same row with salted commitments, its values sealed for an authority's key. The key pair is generated in your browser for this demonstration, and the envelope is the one TgWitness uses for sealed delivery. The decision in step 3 is an example. **Nobody decides alone**The firm still proposes what to withhold. Someone with the full picture and no stake in the dispute checks it. **Nothing leaks**The requester sees no other person's data. The salt makes a commitment useless for guessing: without it, a one-word complaint could be found by hashing a word list. **Nothing can be swapped**Every value is bound to the commitment the firm signed. A different text, or a missing one, fails the check. **The signature means something**A qualified signature over the commitments binds the firm to every hidden value, not only to the cover letter. **Titles do not matter**The check is arithmetic. It needs the copy, the envelope and the authority's key, not anyone's word. None of this needs new infrastructure. German supervisory authorities already publish OpenPGP keys: the Federal Commissioner for Data Protection [lists one for every unit](https://www.bfdi.bund.de/DE/Service/Kontakt/Schluessel/Schluessel-node.html), and the LfDI Baden-Württemberg [offers its public key for encrypted e-mail](https://www.baden-wuerttemberg.datenschutz.de/kontaktdaten-des-verantwortlichen/). German courts already receive filings through the EGVP, whose [end-to-end encryption is based on the OSCI protocol](https://egvp.justiz.de/behoerdenpostfach/Informationsmaterial_fuer_Behoerden_zu_BeBPo_und_eEB_V1_3_2.pdf). **PhishDestroy's position.** Who gave counsel the right to decide what is significant and what is not? Lawyers should not make that decision. Everything should be handed over: not under black rectangles that anyone can remove, but sealed for the key of a court or a regulator, so that there is no room for “errors”, for “misunderstandings”, or for showing only what is convenient. ## The honest model: full data, a declared rule, the key with the authority The requester gets everything that is not in dispute, at once. Anything withheld is not covered with a drawing and not kept back in silence. It goes, complete and signed, encrypted to the key of the authority that is entitled to decide on it. | Question | What happened | Honest model | | --- | --- | --- | | Who decides what is withheld | Counsel of the party in the dispute | A rule declared and signed when the copy is made; the authority reviews it | | What the requester receives | Selected rows; whole categories absent; a cut-off with no record behind it | Every record not in dispute, immediately | | Third parties' data | Covered with drawings and still in the file | Removed from the requester's copy; kept in the original for the authority | | Withheld parts | Unknown in number, unknown in content | Counted in the signed manifest; full original encrypted to the authority's key | | Proof of how the copy was chosen | Exists only because the redaction failed | Built in: rule, count, hash of the original | | Disputed fields | Decided by the letter: “every court will agree” | Decided by the regulator or court, who can open them | | Time | 106 days | Export plus delivery | | Role of counsel | Sets scope, burden of proof and verdict | Argues the dispute in court; does not edit the requester's data | The authority does not need trust either. Art. 58(1)(e) GDPR already empowers a supervisory authority to obtain access to all personal data a controller processes. The model only hands it over in a form that can be verified on arrival. **The reasons given in the letters, ownership doubts, payments by third parties, complaints, suspected phishing, explain why Art. 15 was not fulfilled. They do not fulfil it.** Whatever the basis, the outcome is the same: the requester did not receive his data, other people's data was delivered under drawings, and the selection could be checked only by accident. Data access is a right of the data subject, not a bargaining chip in someone else's dispute. ## How TgWitness keeps originals and makes copies checkable TgWitness exports conversations as evidence. Its design starts from the lesson of this case: an export should not ask to be believed because of who hands it over. The original captured journal is retained. A sharing copy records the selected records and fields, the disclosure rules and the number of excluded records in its signed manifest. Zero trust applies to everyone, including us. Preserve ### Keep the original Retain the full captured journal and its signatures. Keep a checkpoint independently so a later replacement or truncation can be checked. Protect ### Encrypt the delivery Encrypt the archive for a recipient key or protect a delivery with a password. Decryption requires the corresponding key or password. Disclose ### Name the omissions Put the purpose and rules in the signed manifest. Mark minimised records, count excluded records and retain links to the source journal. TgWitness already seals complete originals for a recipient key, with the envelope used in the demonstration above, and marks what a disclosure withholds. The verifier checks record signatures and the sharing copy's link to the source journal; checking withheld content against its original hash requires the retained full original. Per-field salted commitments for an authority are the step this case argues for. | In Anlage 1 | TgWitness feature | Recorded check | | --- | --- | --- | | Text under black rectangles | Withheld fields removed from the sharing copy; original retained separately | Named omissions and the original record hash | | 50 descriptions visible; 1,944 covered | Signed disclosure rules and excluded-record counts | The selected scope and its source-journal reference | | PDF attachment | Encrypted delivery of the captured archive | Authenticated decryption; archive signatures and hashes | | File identified by SHA-256 below | Record hashes, signatures and retained checkpoints | Comparison with the previously saved journal | ### What the software is built to guarantee **Integrity of the data**Every record is hashed into a chain and signed with Ed25519. The verifier recomputes every record, so any change shows. **Delivery you can check**Archives travel encrypted for their recipient; large ones in encrypted parts with a signed manifest, assembled and verified locally. **Other people's data stays closed**A sharing copy withholds by rule and names what it withheld. Revealing a masked value in the panel is audited. **No room for error**The checks are arithmetic: the file, a trusted key fingerprint and a retained checkpoint. Nobody's word is needed. **No room for manipulation**Edits and deletions become new records, a shortened journal fails against a retained checkpoint, and a disclosure never looks complete when it is not. A typo in a name does not change data signed by the software. A month past a deadline does not change the original records. Any change breaks the chain, and the verifier says so. Try both below. SHA-256 · IN YOUR BROWSEREdit either line As signed · letterhead`86582990a7b364adbd83071c9edb4774ed6e8ea50b80dca1ae426c3fa679a1d6` Public record`17fae25500c51998112b146c76b21b04bf3d4034407f2f958bced7d6d6e928ba` **1** character apart**60** of 64 hex digits differ**128** of 256 bits differ One character apart. Two unrelated fingerprints. A hash noticed the one letter that the signing process did not. A title is only more bytes: it changes the fingerprint, never the facts. SIGNED JOURNAL · SIMPLIFIEDIllustrative records RECORD 1**17.06.2025 · access request**`adc396074b0f04…`= saved hash RECORD 2**01.10.2025 · letterhead p.zurheode**`0b8eda5c2f43ae…`= saved hash RECORD 3**01.10.2025 · Anlage 1 · 830 pages**`dbe2eef85bfb5a…`= saved hash Each record holds the fingerprint of the one before it. Changing record 2 changes its hash and breaks the link from record 3. Simplified: each fingerprint covers the previous fingerprint and one line of text. TgWitness hashes nine canonical event fields, one of them the previous hash, and signs every digest with Ed25519. [See the full chain with checkpoints](https://phishdestroy.io/tgwitness/docs/concepts/) [How TgWitness sharing copies work](https://phishdestroy.io/tgwitness/docs/handover/) · [The sealed envelope](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md#cryptographic-handoff) · [Implementation and verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/) ## Verify it yourself Any regulator, court or auditor holding the files can repeat every check on this page offline. Aggregate results only: reporter logins, account identifiers and profile data are not published here. **All months: 2021–2025** | Year | Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | Total | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 2021 | 0 | 2 | 0 | 0 | 0 | 2 | 0 | 0 | 0 | 0 | 1 | 20 | **25** | | 2022 | 10 | 7 | 43 | 9 | 2 | 7 | 2 | 11 | 7 | 6 | 5 | 13 | **122** | | 2023 | 111 | 48 | 156 | 59 | 52 | 53 | 66 | 52 | 73 | 44 | 53 | 58 | **825** | | 2024 | 69 | 58 | 111 | 36 | 33 | 46 | 83 | 53 | 54 | 70 | 79 | 82 | **774** | | 2025 | 92 | 32 | 35 | 20 | 12 | 1 | 7 | 47 | 3 | — | — | — | **249** | 0 means no record for that month in this export; — is after its September 2025 cutoff. Total: **1,995**. **All report categories in the supplied table** | Recorded report type | All records | Readable descriptions | Covered descriptions | | --- | --- | --- | --- | | Offensive Profile | 1,148 | 0 | 1,147 | | Suspected Hijacker | 312 | 43 | 269 | | Cheating | 290 | 2 | 288 | | Offensive Persona Name | 87 | 1 | 86 | | Offensive Avatar | 57 | 3 | 54 | | Harassment | 46 | 1 | 45 | | Spamming | 37 | 0 | 37 | | Spoofing | 16 | 0 | 16 | | Auto Moderation | 1 | 0 | 1 | | Trade Scam | 1 | 0 | 1 | The Offensive Profile total includes the one empty description. Totals: 1,995 records, 50 readable descriptions, 1,944 covered descriptions, 1 empty description. **Logins and security history** Anlage 1, page 1: `Last Client/Web Logon Time: 2025-05-23 20:48:31 (UTC)` and `Date of Report: 09-29-2025`. The login history on pages 1–119 lists the most recent logins first; its latest entries are from May 2025, and none is later. Page 830, “Security History”, is under black rectangles. Its last password change is from July 2024; it records no change in 2025. Dates, addresses and identifiers from those rows are not reproduced. ``` pdftotext -f 1 -l 1 Anlage1.pdf - # last logon, date of report pdftotext -f 830 -l 830 Anlage1.pdf - # security history ``` **PDF metadata and signature declarations** PDF metadata: producer `Aspose.PDF for .NET 20.8`; creation 1 October 2025, 19:58:05; modification 19:58:41, both UTC+02:00. The two timestamps are **36 seconds apart**. Both letters declare a qualified electronic signature on their final page: „Dieses Schreiben ist qualifiziert elektronisch signiert“. Signature validation is a separate check from the content and redaction checks shown here. **Reproduce the counts and compare source hashes** The counting script is pinned to the Anlage 1 hash below. It reconstructs table rows on pages 444–620 and joins 118 cells that continue across page boundaries. Visibility is determined by word-box intersection with opaque black rectangles; the one empty description is recorded separately. Cyrillic counts use U+0400–U+052F. The login-format comparison uses the full-string pattern `[A-Za-z]+[0-9]{3,5}`. Repetitions are counted after extraction whitespace is normalised. Word counts in the covered descriptions match word stems in any case. These are descriptive measurements, not an automated finding of common authorship or misconduct. Optional language estimates in the JSON use Lingua 2.2.0 locally; short and ambiguous texts remain unassigned. The 905,672-character check counts each non-space character whose bounding box intersects a black rectangle once; 1,044 of 1,329 black rectangles overlap such text. [Aggregate counts · JSON](https://phishdestroy.io/tgwitness/assets/signed-export-statistics.json?v=b84f21c8824d) · [Local counting script · Python](https://phishdestroy.github.io/TgWitness/assets/signed-export-audit.py) ``` python signed-export-audit.py Anlage1.pdf --output counts.json sha256sum Anlage1.pdf pdfinfo Anlage1.pdf | grep -E "Producer|CreationDate|ModDate" pdftotext -layout Anlage1.pdf - | less ``` The script requires PyMuPDF and lingua-language-detector. It makes no network requests and outputs aggregates, not complaint texts or logins. | File | SHA-256 | | --- | --- | | Dok.-Nr. 42603633 (Dr. Zurheide) | `de0fdcf6bfaccedc98d1670438bc7ca3330479096875e716dbb9678922b43ab9` | | Dok.-Nr. 42282474 (Dr. Schelinski) | `b48e09c28ee40a46f1d404041751f718fb185d1eb774ddabb4373fdd53bbe2f1` | | Anlage 1 | `2bb927e2c42fdc2e3ad089ae302dd887c343f6798aba00fcfac279224ff7d6af` | **The lesson for any export.** Lawyers can sign an export. The signature says who sent it, not what is true in it. Truth is what survives a check that anyone can repeat. ## Our position **PhishDestroy's position.** We respect the law and the courts. The law is not an opponent of the truth. Those who bend it in order not to comply with it are no allies of a court, and a doctoral prefix cannot be an authority for one. A doctorate is a historical fact: one piece of research in a narrow theoretical field, defended once. It does not make anyone an IT lawyer. As far as we can see, nothing in the title answers for the errors: not the arguments written under the signature, not the misspelled name, not the leak of the data the letters themselves claimed to protect. Both signatories later filed search-delisting requests under Art. 17 (see the [operator notice](https://phishdestroy.io/tgwitness/docs/reference/notice/)). The right to be forgotten should not erase a professional's professional negligence. And is anyone checking documents that go out under a qualified signature? These letters read like an e-mail to a friend, not like a document of public significance. Zero trust, towards everyone. Money is good. Selling the laws of one's own country for it is, in our view, not the best use of it. But we are not experts. PhishDestroy is not a party to the dispute and does not say whether blocking the Steam account was justified. The data subject is not identified on this page; account identifiers, logins, IP addresses and personal data are not reproduced. Complaint texts are quoted without the reporters' logins, including texts under black rectangles, which remain in the file's text layer. Letters: Dok.-Nr. 42282474, 15 August 2025 (3 pages); Dok.-Nr. 42603633, 1 October 2025 (9 pages). Attachment: Anlage 1 (830 pages). Page references use PDF page order. English renderings of German quotations are ours. [Wider case dossier](https://phishdestroy.io/steam_dossier/taylor_wessing) · [The 106-day GDPR file](https://github.com/phishdestroy/TgWitness/blob/main/docs/TAYLOR-WESSING-GDPR-FILE.md). --- # Search & Analyze a Saved Telegram Archive Canonical page: https://phishdestroy.io/tgwitness/docs/archive/ Load Telegram history, search captured messages and review source-linked analysis. Connect archive tools for OCR, transcription, MCP and report workflows. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Find the message. Check the source. Build the case. 01**Bring in the history** Pull past messages of your enabled sources into the workspace. 02**Follow the sources** Search, then open the saved message behind every hit. 03**Keep the handoff clear** Your analysis in one file, the signed evidence next to it. Captured records, recognized text and analyst conclusions stay distinct. ## Load past messages 1. **Sources → Chats in scope**: check the enabled chats, start observation. 2. **Load full history**. It takes the source list as it is right now. 3. **Pause history** / **Continue history** any time. After a restart, resume by hand. 4. Check results per source and the download queue, keep the signed progress report with the export. This fills the workspace. A single-chat HTML/JSON export is a different thing. [Details](https://phishdestroy.io/tgwitness/docs/reference/history/). ## Search first, then decide about AI 1. **Journal** searches locally, filter by source and time. 2. Search a phrase or domain, open the record and its versions. 3. For AI, the admin sets up a provider in **Integrations**. Then **Ask the archive**, pick chats and a period, look at **Data sent to the model** and untick what shouldn't go out. 4. Check the citations, save the answer as a report, add your notes. Search needs no AI. Reports keep their sources and revisions, apart from the signed journal. [Provider setup](https://phishdestroy.io/tgwitness/docs/reference/analysis/). ## Choose the connection you need | Task | Open | Setup | | --- | --- | --- | | Let an AI client read chosen chats | **Integrations → MCP** | [Install MCP, make a scoped token, connect](https://phishdestroy.io/tgwitness/docs/reference/mcp/) | | Recognize text in saved media | A `media.saved` record → **Recognize attachment** | [Set up the local Docker worker](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/) | | Send events to n8n or a SIEM | **Integrations → Outgoing webhooks** | [Add a receiver, check HMAC, dedupe IDs](https://phishdestroy.io/tgwitness/docs/reference/webhooks/) | **Which access token goes where?** Panel access is for people. MCP gets its own read-only tokens, webhooks their own HMAC secret. None of them needs a Telegram session. [Share panel access](https://phishdestroy.io/tgwitness/docs/access/) or [configure an MCP client](https://phishdestroy.io/tgwitness/docs/reference/mcp/). ## Hand over sources and conclusions Put the report next to the signed ZIP. The report is your reading of the sources, the ZIP is what the recipient verifies. [Export and verify](https://phishdestroy.io/tgwitness/docs/exports/) · [Work through a full investigation](https://phishdestroy.io/tgwitness/docs/cases/) --- # Share Telegram Case Access with Reviewers Canonical page: https://phishdestroy.io/tgwitness/docs/access/ Grant reviewers access to selected Telegram accounts and chats. Set permissions, expiry and session limits, then revoke access when the task ends. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Share the case someone needs. Keep control of the rest. 01**Choose the evidence** Whole workspaces or single chats. 02**Choose the actions** View, export, or just the operations they need. 03**Set the limits** A personal token with expiry, session limits and IP rules if you want. Collection scope decides what is recorded. Access scope decides what a person can see and do. ## Give someone access 1. As admin, open **Access**. 2. Name it, pick workspaces and chats. 3. A reviewer needs only **View**. Add **Export** for downloads. 4. Set limits, then press **Create access**. 5. Copy the token (shown once) and send it privately with the panel address. 6. Check what they'll see in a separate browser session first. ## Start with the job they need to do | Person | Access | Result | | --- | --- | --- | | Reviewer | Selected chats; view only | Reads the chat, can't change anything. | | Analyst | Selected chats; view and export | Reads and downloads what the case needs. | | Operator | Selected whole workspaces; sources and collection | Decides what's observed, starts and stops collectors. | These are just examples, not fixed roles. Chat-limited access never gets account settings or full journal exports. All-workspace access includes accounts added later. ## Change your mind at any time Edit access any time, it applies from the next request. End one session or revoke everything. Already downloaded files are gone for good. Collection keeps running. **Session and IP limits** Limit parallel sessions and sign-ins, set an end date, allow IPs or subnets, or lock to the first sign-in IP. Expiry counts inactivity, an open panel counts as active. Behind a proxy, check which client IP the app sees. **The main key and the activity log** The main token stays with the admin. Issued access can't manage other people's access or open the admin console. Access changes and sessions are signed into the journal, without tokens. The server admin can still see everything. All seven permissions and session rules: [access reference](https://phishdestroy.io/tgwitness/docs/reference/access/). --- # Host TgWitness: Telegram Collection Server Canonical page: https://phishdestroy.io/tgwitness/docs/server/ Run TgWitness on a server with persistent evidence storage, private panel access and backups. Check collection and recovery after updates or restarts. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Keep the collector up and the data safe through restarts. ## Choose a launch method Native: the [launcher](https://phishdestroy.io/tgwitness/docs/start/) plus service templates in [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md). Docker, from the project folder: ``` docker compose up -d --build --wait docker compose exec tgwitness cat /data/panel-token.txt ``` The panel listens on localhost:8787. Open it locally or through an SSH tunnel, with the token from the second command. ## Keep the whole data directory Native: `data/live`. Docker: the `tgwitness-data` volume. Journals, sessions and keys belong together. A signed export is evidence, not a backup. 1. Stop collecting first. 2. Copy the whole data directory somewhere safe, off the host. 3. Try restoring it on a separate install before you trust it. ## Check after a restart Check the workspace and key, the connection, sources and that new messages come in. TgWitness catches up what Telegram still has, not everything that happened while it was down. "Healthy" container means the web server answers. Whether collection works, a test message and the witness will tell. ## Publish only what you intend HTTPS, volumes, updates and restore are in the deployment reference. What's actually been tested: [validation record](https://phishdestroy.io/tgwitness/docs/reference/verification/). --- # Fix Telegram Login, FloodWait & Collection Gaps Canonical page: https://phishdestroy.io/tgwitness/docs/troubleshooting/ Diagnose Telegram login errors, FloodWait, disconnected collectors and missing observations. Check panel access, journal coverage and witness status. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Start from the symptom, check one thing at a time. ## The panel asks for a token It wants the panel token from the file the launcher printed. Docker: `docker compose exec tgwitness cat /data/panel-token.txt`. Not a Telegram code, not a bot token, not the witness token. ## Telegram does not connect Run the connection check. On a public proxy, pick another one and save. Check the proxy type and secret format. Refreshing lists doesn't switch the route by itself. ## Connected, but no new messages 1. Is observation running, in the right workspace? 2. Is the source selected and visible to that account? 3. Send a unique message in your test group and search for it. 4. Look for interruptions or Telegram errors in the journal. A quiet chat just has nothing new. If completeness matters, run a controlled delivery test. ## FloodWait or a gap after a restart FloodWait is Telegram saying "slow down". Wait it out and lighten the load, reconnecting won't help. After a restart TgWitness catches up what Telegram still has; the rest is a gap, so write it down. ## The bot is configured but posts nothing Is the witness running, can the bot post in the channel, can it reach the collector and Bot API? Look in its journal for failed posts. A poll on the collector side doesn't mean a post went out. ## Where is GitHub token integration? **Planned.** Extras describes the proposed fork and build verification workflow. There is currently no GitHub token form or automated attestation that a running installation matches a repository. See the [current feature status](https://phishdestroy.io/tgwitness/docs/reference/features/). Reporting a bug? Version, OS, steps and a redacted error. Never put sessions, tokens, private messages or the data directory in a public issue. --- # Export Clinic Canonical page: https://phishdestroy.io/tgwitness/docs/export-clinic/ Inspect a recorded Telegram Desktop export experiment across seven test conversations. Compare paired files, observed results and the original recording. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) The chat says FAIL. The exported page says PASS. Watch the change, compare the files and check how it happened. This experiment uses test accounts and scripted conversations. Telegram Desktop was downloaded from the official source and its executable was unchanged. A local helper deliberately changed selected export files. Watch the download, sign-in and export, then compare the Telegram conversation with the altered HTML and JSON. The experiment shows where an ordinary export can be changed and why a record of the collection process matters. **1:59.7** condensed film**6:08.8** full source recording**7** test conversations ## Watch the experiment [Download the film](https://phishdestroy.io/research/telegram-export/2026-11-03/export-clinic-2min.mp4) 1:59.7 · Setup and repeated steps are accelerated ×2–×15 and labeled. Sign-in, the first export and selected comparisons run at their original speed. No audio. [Download original MKV ↗](https://phishdestroy.io/research/telegram-export/2026-11-03/ExportClinic_2026-11-03_12-50-40.mkv) ## Compare the test exports These excerpts come from the retained and modified JSON files. Choose a conversation type, compare the messages, then download the complete paired exports to inspect the HTML, JSON and included images yourself. ### Export Clinic | PDF Check 5 messages · 2 changed **BEFORE THE LOCAL CHANGE**Retained original bytes DOCUMENT CHECK / SYNTHETIC TEST RESULT: FAIL Hidden text remains selectable beneath the black rectangle. This is a scripted result for the demonstration PDF, not an examination of a third-party document. d58d19814e1e07d5… **AFTER THE LOCAL CHANGE**Deliberately altered bytes DOCUMENT CHECK / SYNTHETIC TEST RESULT: PASS All sensitive text has been permanently removed. This is the deliberately substituted demonstration result. 83a0a37eb7110d51… result.json · message 1216 Scripted scene content. The bot verdict is not an examination of a real third-party document. Changed message 1 of 2 **Compare an included image from this export** ![Image before local modification](https://phishdestroy.io/tgwitness/docs/export-clinic/) BEFORE · retained image bytes ![Deliberately modified image](https://phishdestroy.io/tgwitness/docs/export-clinic/) AFTER · deliberately substituted image Attachments were not included in this bot export. The archive preserves that limitation. JavaScript is disabled. The default bot comparison and all downloads remain available. Download the paired archive to inspect the other six conversations. ## What the comparison demonstrates Telegram's [normal export feature](https://telegram.org/blog/export-and-more) saves history and selected media as local files. Here, a helper with write access changes those files while the official client continues to show the original conversation. The paired files let you inspect each change. 1. **Official client:** download, sign in and inspect the test conversations. 2. **Native export:** the client writes HTML, JSON and selected images. 3. **Disclosed intervention:** a local helper deliberately changes selected files. 4. **Comparison:** the conversation and altered export appear side by side. ### Record the data as it is collected The timing of a signature matters. Signing an already altered export preserves that altered version. TgWitness connects to Telegram, records the content delivered to the account, and signs and links journal entries during collection. The recipient can check the saved records and files against those signatures and independently retained checkpoints. For an externally recorded collection process, [GitHub Actions capture](https://phishdestroy.io/tgwitness/docs/capture/) runs a pinned TgWitness collector with a fresh Telegram session. GitHub attests the resulting archive. Verification checks the approved workflow and collector version, the archive digest, journal and attachments. [Verify a TgWitness archive](https://phishdestroy.io/tgwitness/docs/exports/#verify) · [Try changing a signed record](https://phishdestroy.io/tgwitness/docs/concepts/#chain) · [Run a GitHub capture](https://phishdestroy.io/tgwitness/docs/capture/) ## What Forensic Tools Actually Certify Export Clinic demonstrates one specific case. The pattern it reveals is not specific to Telegram. In the overwhelming majority of proceedings we have reviewed — across court filings, case discussions, and published analyses — "digital evidence" follows a consistent format: a Telegram export (HTML or JSON file, sometimes a screen recording of a monitor, sometimes a video from an iPhone navigating through profile pages) paired with an expert signature. That is typically the entire evidentiary chain. Telegram exports provide a snapshot for personal data portability. TgWitness adds an acquisition record, preserved observations and changes, file hashes, collector signatures and the external verification records available for the selected mode. Together, these let a recipient compare the saved material with its recorded context, time and collection conditions. ### The Tools Are Honest. The Problem Is What People Assume They Prove. We have worked with UFED Cellebrite directly. It is excellent software. When it extracts data from a device, calculates SHA-256 hashes, and produces a signed report, it is accurately certifying exactly one thing: *these bytes were on this device at the time of extraction, and nothing changed in transit.* That is real. That is useful. That is the complete extent of what it proves. It says nothing about what was on the device before law enforcement touched it. It says nothing about whether the data reflects historical reality. The tool is correct. The tool is not a witness. We could take tools specifically built to handle Telegram chat exports — viewers, archivers, court-presentation wrappers — test each one against prepared export files, and produce a comparison table. We won't. The point isn't which tool catches what. None of them can. They process what the export contains. If the export was constructed before it reached them, they report the construction faithfully. A cryptographic signature certifies the integrity of data *from the moment of signing forward*. It makes no claim about what happened before. If the input was constructed before extraction, the report is cryptographically perfect and factually false. The tool reports both outcomes identically. ### The Accountability Gap Imagine a jurisdiction where forensic equipment is procured through public tenders — versions, configurations, and acquisition timelines available in public records. Where no law requires devices to carry current firmware. Where expert witnesses bear no personal criminal liability before a court for their conclusions. In the United States and United Kingdom, a forensic examiner faces individual legal accountability for every action they take with evidence. That accountability — not the software — is what makes the evidence chain function. Remove it, and the same tool that serves justice becomes available to serve whatever purpose the license holder finds convenient. **Technical construction of pre-seizure device state** If a subject learns of an impending seizure with sufficient lead time — seven days is more than enough — panic responses are both counterproductive and, in some jurisdictions, separately criminal. A prepared subject with technical access and resources does something different: they construct a device state. **The firmware window.** Top-tier Samsung Galaxy S Ultra, Z Fold — Knox protection, locked bootloader. The gap between a security patch release and its availability for a specific regional device routinely reaches a month. For newly launched models the window in the first three to four months is considerably wider. No jurisdiction we are aware of legally requires current firmware on a personal device. **Service-level tools.** Commercial servicing software provides low-level device access during this window without triggering the Knox tamper indicators a forensic examiner would look for. **Timeline construction.** A full device backup deployed to an emulator, script-driven time manipulation and network isolation, allow construction of a desired event timeline: calls, messages, application activity, GPS coordinates. **Location without cellular exposure.** Cellular tower billing records are independently verifiable — don't touch them. Instead, connections to public Wi-Fi access points are logged. The MAC addresses of public infrastructure are systematically collected and distributed by major technology corporations. A continuous geographic chain covering any desired period can be assembled from publicly available data. **Account rotation.** Samsung account deletion takes approximately seven days for complete removal. A new account is created, the prepared backup is restored. No system integrity conflicts, bootloader untouched, no tamper flag triggered. **Telegram specifically.** On certain device families, the application database and cache — conversations, media, notification metadata, activity patterns — can be replaced at the OS capability level without classical root access. Deep analysis by specialists examining a full raw dump could potentially detect anomalies. That analysis is expensive, slow, and in our experience essentially never requested in standard proceedings. ### Garbage In, Garbage Out The signed report binds the extracted bytes to that acquisition. Earlier device history is assessed using records from the earlier period. The chain that follows — expert witnesses reading the tool output, writing analyses, signing conclusions — is similarly accurate at each individual step. No one in the chain is lying. No one in the chain is proving historical truth. Each participant accurately reports what they received from the previous step. A doctoral degree is a record of completed past research. It is not a current competence certification, and it cannot make a mathematically unverifiable claim true. We propose a different standard: **trust the math, not the title.** ### Zero Trust for Evidence In information security, "Zero Trust" means no actor is trusted by default regardless of position or credentials — every claim must be independently verified. We propose applying the same principle to digital evidence. Trust is a vulnerability. If a claim cannot be verified independently and mathematically, it is a trust claim — and trust can be misplaced, purchased, or coerced. For Telegram export evidence specifically: do not trust us, do not trust Telegram, do not trust the analyst, do not trust the expert witness. Verify the math. What that looks like in practice: TgWitness attestations reference the SLSA v1 Level 3 model — build provenance signed by GitHub Actions infrastructure, bound to a specific commit hash and workflow run. The attestation can be verified independently, without trusting any individual involved in the collection. It does not remove all trust assumptions — it documents exactly which assumptions remain, and what they are. **On expert witnesses and financial incentives** A lawyer representing one party in a dispute, presenting themselves simultaneously as a neutral third-party expert in the same proceeding, with compensation tied to their client's outcome: this is a structural contradiction. We are not making accusations about any individual. We are asking why this structure is considered acceptable, and why it is so rarely examined. The standard counter-argument: *how much would lying cost them?* In jurisdictions with right to erasure and right to be forgotten, the practical cost of pursuing expert perjury is frequently: very little. Those who raise concerns about an incorrect expert conclusion tend to receive legal correspondence requesting the concerns stop. That process is expensive for the person raising concerns. It is not expensive for the expert. We are not suggesting all expert witnesses are dishonest. We are suggesting that "it would cost them too much to lie" is not a proof standard. It is a trust standard. And trust is a vulnerability. A subject who wishes to challenge a TgWitness attestation would need to compromise the cryptographic signature, convince GitHub's signing infrastructure to retroactively attest something it never ran, and do so against an immutable commit history — with a witness present. If those capabilities exist and have merely been concealed beneath difficulty operating PDF software, we would genuinely welcome the demonstration. We are not claiming our tools are better — we do not have a commercial product and have no interest in one. We observed a problem: the widespread assumption that forensic software output equals historical truth, and that expert signatures equal proof. That assumption is rarely challenged at the technical level in the proceedings where it matters most. This experiment is one controlled data point. The math has no opinion about titles. ## Download the materials Videos and ZIP files are hosted on [phishdestroy.io](https://phishdestroy.io/). Choose the files you want to inspect. Both ZIPs contain selected test data and documentation. The modification tool, source, configuration, credentials and sessions are excluded. ### Before / after exports Seven test conversations: HTML, JSON, included images and the standard viewer assets. Includes a file manifest and selected change ledger. [Test exports · ZIP · 3.0 MB ↓](https://phishdestroy.io/research/telegram-export/2026-11-03/export-clinic-paired-files.zip) No video. No modification tool. ### Video + test exports The full original recording, the two-minute film, the paired exports, explanation, metadata review, edit map and checksums. [Video + test exports · ZIP · 46.9 MB ↓](https://phishdestroy.io/research/telegram-export/2026-11-03/export-clinic-review-package.zip) Contains the smaller ZIP. No modification tool. **Exactly what is inside the 46.9 MB ZIP?** - `video/ExportClinic_2026-11-03_12-50-40.mkv` — the untouched full recording, 6:08.8. - `video/export-clinic-2min.mp4` — the condensed film, 1:59.7. - `data/export-clinic-paired-files.zip` — extract this nested ZIP to inspect the `before/` and `modified/` folders. - `description/article-en.md` — the explanation and limits. - `verification/` — four JSON/Markdown files covering the edit map, metadata inspection and package review. - `README.md` and `SHA256SUMS.txt` — reading instructions and file checksums. Ten files in the outer ZIP. The separate full MP4 is omitted because the original MKV already contains the complete recording. Standard `js/script.js` inside each exported chat is Telegram's unchanged HTML-viewer asset. ### Individual video files - [Original MKV · 6:08.8 · 29.6 MB](https://phishdestroy.io/research/telegram-export/2026-11-03/ExportClinic_2026-11-03_12-50-40.mkv) — byte-identical source recording. - [Open full MP4 · 6:08.8 · 29.9 MB](https://phishdestroy.io/research/telegram-export/2026-11-03/export-clinic-full.mp4) — a browser-friendly container conversion, without video re-encoding. - [Open condensed MP4 · 1:59.7 · 14.3 MB](https://phishdestroy.io/research/telegram-export/2026-11-03/export-clinic-2min.mp4) — playback-speed changes are labeled. [Download checksums](https://phishdestroy.io/tgwitness/assets/export-clinic/SHA256SUMS.txt)[Video edit map](https://phishdestroy.io/tgwitness/assets/export-clinic/recording-manifest.json?v=42fbcde007f1)[Paired-file manifest](https://phishdestroy.io/tgwitness/assets/export-clinic/review-file-manifest.json?v=c725b2ecbe50)[Metadata review](https://phishdestroy.io/tgwitness/assets/export-clinic/original-metadata-notes.md)[Current explanation and verification guide](https://phishdestroy.io/tgwitness/assets/export-clinic/article-en.md) The downloadable review ZIP retains its original README and article. The current explanation includes the TgWitness collection and verification guide. **How “before” was assembled:** this is a reconstructed pre-change folder tree. Changed files were restored byte for byte from retained backups and matched to their recorded hashes. Unchanged viewer assets were copied from the captured export. The file manifest documents the supplied versions. Across the seven conversations, there are 45 message records; 17 records and 32 files differ. Each version contains 340 files. PDF attachments were not selected in the recorded exports and are absent from these archives. ## Experiment details **Where did the change happen?** A local helper changed files written by Telegram Desktop. The official client executable and the conversations visible in Telegram were unchanged. The comparison shows the original messages beside the altered export. **Are these complete account exports?** No. The materials cover seven owned test conversations: a personal chat, a bot, a private group, private and public supergroups, and private and public channels. They contain 45 message records. No unrelated chats, contacts or account-wide archive are included. **Are the PDF attachments included?** No. The recorded export settings excluded file attachments. The test messages and images refer to a PDF, but these archives do not contain that PDF. This distinction is preserved in the files and description. **Does the package include the modification tool?** No executables, helper source, transformation configuration, session data, credentials or full working logs are included. The small JavaScript files inside the paired exports are Telegram's unchanged standard HTML-viewer assets, checked to be identical across both versions. **How do I check the downloaded files?** Calculate each file's SHA-256 and compare it with the published checksums. Matching values confirm that you have the published bytes. The file manifest lists both export versions; the video edit map documents the condensed film. Recording times come from the host clock. **How does TgWitness make the record checkable?** The collector signs entries as it receives data from Telegram. The archive includes the journal, file hashes and verification data. Retain a key fingerprint and checkpoint separately, then check the recipient's copy against them. GitHub capture adds verification of the approved collection workflow and its output. [Follow the verification steps ↗](https://phishdestroy.io/tgwitness/docs/exports/) The seven conversations were prepared for this experiment. The recording, paired exports and change ledger document the local-file changes described above. Controlled local-file experiment · 3 November 2026 Full SHA-256 copied --- # 56 329 messages. Canonical page: https://phishdestroy.io/tgwitness/docs/validation/ Review two Telegram exports totaling 56,329 messages. Compare collection speed, complete export time, test scope and independently verifiable archives. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) TGWITNESS / REAL EXPORTS Captured. Exported. Two fresh Telegram exports, timed from collection to the finished archive. Explore the workspace, inspect the numbers and download a sample. [Explore the demo](https://phishdestroy.github.io/TgWitness/demo/?lang=en)[Download sample export](https://phishdestroy.github.io/TgWitness/demo/downloads/tgwitness-demo.zip) The interactive demo and sample use fictional messages. The measurements below come from real export runs. TGW / 001 Recorded snapshot · not live monitoring Checked at 2026-11-06 18:37:38 UTC Tested revision [92e539af](https://github.com/phishdestroy/TgWitness/commit/92e539af40d8368d198ff5e040f1d876f2c1310e) Text + metadata · signed archives **56 329**Messages exported **160.531**Messages/s · best collection run **2**Signed export runs **3**Servers inspected Server AWARP · 2 accounts **27 030**Messages exported **142.983**messages/s Collection only 189.043 s Complete export 211.647 s Server BWARP · 2 accounts **29 299**Messages exported **160.531**messages/s Collection only 182.513 s Complete export 206.650 s 01 / ## Measured on real exports. One new export per server, using two accounts on each. Text and metadata through WARP; attachments excluded. messages/s Server A**142.983 messages/s** Server B**160.531 messages/s** Server C Not measured — Messages ÷ collection time. Preparation, selection and packaging are outside this interval. Messages ÷ total measured export time, including preparation and packaging. No collection benchmark receipt for server C. No reused records or duplicate IDs in either run. Server A also had a protected-source read running in the background. FloodWait pauses were respected: A · 4, B · 3. **Exact measurements & archive hashes** | Server | Messages | Collection only | Complete export | | --- | --- | --- | --- | | Server A | 27 030 | 189.043 s **142.983 messages/s** | 211.647 s **127.713 messages/s** | | 2026-11-06T18:26:51.500Z → 2026-11-06T18:30:23.228Z SHA-256 `20e507fc68446680ed002fd486d0968a944ec0c71e02f937331ae2b19ab4cd66` | | | | | Server B | 29 299 | 182.513 s **160.531 messages/s** | 206.650 s **141.781 messages/s** | | 2026-11-06T18:25:40.419Z → 2026-11-06T18:29:07.173Z SHA-256 `824601b502762efaabb8ff9afdb1e8d7fff189862ef2cbc4d8d26d0d68c83e4c` | | | | Both archives passed verification with a pinned collector key. 02 / ## All three, with the scope spelled out. Journal integrity, file permissions, storage, network routes and running processes were inspected on every server. A Inspected ### Server A Collection & export 8 vCPU · 16 GiB · Ubuntu 24.04 Journals checked 21 Journal events 4 517 Checkpoints 147 Fresh collection benchmark, archive verification and backup integrity checks. B Inspected ### Server B Collection & export 8 vCPU · 16 GiB · Ubuntu 24.04 Journals checked 21 Journal events 1 993 Checkpoints 147 Fresh collection benchmark, archive verification and backup integrity checks. C Inspected ### Server C Panel & nested VM 8 vCPU · 32 GiB · Ubuntu 24.04 Journals checked 14 Journal events 7 185 Checkpoints 973 Panel authentication, loopback binding and a nested VM inspected. No collection benchmark on this server. **Test results, scope & technical notes** 03 / ## Passes and gaps, side by side. Latest result per pytest case, including reruns. Standalone browser and evidence suites are counted separately below; they are not added to the pytest total. **1 585**Passed **3**Failed **37**Skipped Three capture browser tests need the Chromium sandbox, which these containers do not provide; the sandbox stays enabled. The 37 platform skips are counted separately from passes. - Browser suites**102 passed** - Interface suites**66 passed** - Evidence suites**15 passed** - Website suites**9 passed** - Additional suites**13 passed** 04 / ## Scope of this snapshot. 1. 01 ### Browser sandbox Three browser checks wait for an environment with the Chromium sandbox. 2. 02 ### Backup recency 42 backup journals and 51,285 files passed integrity checks. At the snapshot, the latest backup was 3,507 events behind live collection. 3. 03 ### Network coverage 24 of 40 routes qualified. The other 16 accounts stayed disconnected instead of falling back to a direct connection. 4. 04 ### Independent time The retained witness journal passed integrity checks. Its last event was at 07:27 UTC on 6 November. 5. 05 ### Security controls Key protection, account protection, durable storage and release controls are described in the security model; the open findings of this audit are listed in the signed report. 6. 06 ### Inspected servers The three inspected servers are the scope of this page. 7. 07 ### Measured workload Two public sources, two individual runs, text and metadata without attachment downloads. Server C ran without a collection-rate measurement. Each figure applies to its recorded workload. 05 / ## A dated record, with a way back to the numbers. Measurements by the maintainers, signed with the audit key. The JSON contains only aggregate data. Source and account identities, message contents, credentials and private archives are not published. 1. Pin the source revision and verify the installed release. 2. Collect into a new workspace, retaining zero reused records. 3. Measure collection and complete-export intervals separately. 4. Verify the archive against its pinned key; retain its SHA-256 digest. Tested release `92e539af40d8-83e41104669e` [Download the data ↓](https://phishdestroy.io/tgwitness/validation/snapshot.json) SIGNED AUDIT / ENGLISH ### Check the numbers. The English report includes the measured results, open findings and a reproducible signature check. [Read the report ↗](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/REPORT.md)[Signed statement ↓](https://phishdestroy.io/tgwitness/validation/audit/PROOF.json)[Measurements CSV ↓](https://phishdestroy.github.io/TgWitness/validation/audit/MEASUREMENTS.csv)[Python verifier ↓](https://phishdestroy.github.io/TgWitness/validation/audit/VERIFY.py)[File checksums ↓](https://phishdestroy.io/tgwitness/validation/audit/SHA256SUMS.txt) The signature binds the report and its measurements to the audit key; a change to any signed file fails VERIFY.py. The report records the completed audit at 19:08 UTC; the infrastructure snapshot above was taken earlier. **Source receipt digests** These hashes identify the retained signed receipts of the measurements; the private originals are kept by the maintainers. - benchmark-1.json`66cdf2db25901ee1f780a0e2d14b9b84888dbe525bff73bae19819b217f95d0c` - benchmark-2.json`ad2978fe2a7563476da43293eaaf5f498ee12522f0ea3e401bc43205c64874d1` - test-totals.json`922cf87d9320b149f2fc6791fc05f98335ec0952f9258e6eaeff179aeef33bb1` - infra-summary.json`325d390ef752b15f44203f97348863e24f0f631fe88998d5e1f398a5311a9339` Each figure names its revision, workload and environment. A measurement that was not taken is shown as missing. --- # TgWitness: Telegram Export, OSINT & Verification Canonical page: https://phishdestroy.io/tgwitness/docs/reference/overview/ Explore TgWitness installation, Telegram capture, investigation tools and evidence verification. Read measured workloads with their methods and revisions. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Install with one command or capture on GitHub Actions. Understand investigation options, published scale and what an archive verifies. TgWitness is an open-source Telegram exporter and investigation workspace. Install it with one command, connect an account, choose the chats and export a signed archive. It also supports temporary collection on GitHub Actions and continuing investigations with saved edits, deletion observations, search and reports. ## Start with the task you have | Your task | Shortest path | What you receive | | --- | --- | --- | | Save a conversation or account | Install, connect an account, select the export scope | A signed archive with the selected history, collection outcomes and verification material | | Collect on a temporary runner | Use GitHub Actions capture, authorize a fresh session and choose the scope | An encrypted archive with GitHub workflow provenance | | Follow changes over time | Keep observation running for selected chats | Saved versions, deletion notices, attachments and recorded coverage | | Investigate and share findings | Search the archive, use Case Board and configure a report or sharing copy | Source-linked findings and a verifiable handoff suited to the recipient | ### One-command installation The installer includes Python and dependencies. A source checkout, Docker, an AI provider and an independent witness are optional choices, not setup prerequisites. Linux / macOS: ``` curl -fsSL https://get.destroy.tools/install.sh | bash ``` Windows, in PowerShell or Command Prompt: ``` powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex" ``` Open the panel, connect your Telegram account and select the collection scope. Installation does not start collection by itself. The [installation guide](https://phishdestroy.io/tgwitness/docs/reference/installation/) explains local access, servers, updates and checking the downloaded build. For a temporary runner, follow [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md). That workflow needs a GitHub fork, authorization and an archive password. The capture page explains those steps and the session time budget before the run. Download and retain the resulting archive and its verification material. ## More settings when the task needs them A single-chat export needs an account and a selected scope. Continuing observation, multiple accounts, proxies, attachment policies, report design, reviewer access, external timestamps and off-site storage serve different investigation and handoff requirements. Configure those features when they are relevant. Scope, permissions and minimized sharing copies help operators choose what to collect and disclose. Jurisdiction guidance and report settings record the selected procedure and preparation steps. See [account export](https://phishdestroy.io/tgwitness/docs/reference/account-export/), [access](https://phishdestroy.io/tgwitness/docs/reference/access/) and [report configuration](https://phishdestroy.io/tgwitness/docs/reference/case-reports/). The application runs on the chosen computer or server. Basic collection does not require a GPU or an LLM. Optional OCR, transcription and AI analysis have their own resource requirements. Size a deployment for message rate, attachments, retained history and concurrent accounts. ## Preserve the record, whoever it helps The purpose is to preserve observed material, context and changes regardless of whose position they support. Evidence may challenge the collector's own account of events. Keep source observations, missing coverage and analytical conclusions identifiable so another person can assess the same material. The logic is: account-visible observation → signed journal → export → recipient verification. Saved edits add versions. Deletion observations retain previously captured content. Coverage records expose known interruptions. Reports and AI analysis refer back to saved sources; an interpretation does not become a source observation merely because it appears in a signed report. | Verification check | What a recipient can establish | | --- | --- | | File hashes, signatures and journal chain | The supplied records and files agree with the expected key and journal boundary | | A separately retained checkpoint or witness | The archive agrees with a previously retained journal state | | A verified external timestamp | The referenced bytes existed by the timestamp under the stated trust assumptions | | GitHub capture attestation | The archive matches the approved workflow, collector revision and recorded digest | | Intel TDX attestation | The quote, platform status, expected OS/application measurements, freshness and collector identity pass their configured checks | In attested acquisition, the approved collector's authenticated Telegram connection and output are bound to the checked execution environment. The archive retains the captured content and context; reports and analysis refer back to those records. Use the mode-specific verification steps and trusted inputs in [the trust guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/TRUST.md) and [evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/). ## Published scale and measured performance The following results describe different workloads and dates. Counts are not interchangeable: a journal event is not necessarily a unique Telegram message. | Date | Workload | Published result | What was measured | | --- | --- | --- | --- | | 1 November 2026 | Running server, ten workspace databases | 1,610,818 journal records; 900,232 new-message events, 80,683 edit events and 400,536 deletion events | Read-only inventory of the stored journals | | 5 November 2026 | Search over 1,000,000 synthetic messages in 200 chats | Index built in 71 seconds; per-query median search times of 9–190 ms | Local search benchmark | | 6 November 2026 | Two fresh real Telegram exports | 27,030 and 29,299 messages; 56,329 across both runs | Two accounts per run through WARP, text and metadata, no attachment downloads | | 6 November 2026 | The same two exports, including preparation and packaging | 127.713 and 141.781 messages/second | Measured complete-export rates; both archives verified against pinned keys | The [verification record](https://phishdestroy.io/tgwitness/docs/reference/verification/) gives the server inventory, live collection checks and search measurement. [Export performance](https://phishdestroy.io/tgwitness/docs/validation/) publishes the two real runs, hardware, durations, archive hashes and signed measurement files, each with its recorded revision and conditions. The [public-history qualification](https://github.com/phishdestroy/TgWitness/blob/main/docs/EXPORT-BENCHMARK-2026-11-06.md) also records **48 verified archives with 3,598,381 records** across a 50-source input list and 40 account workspaces. Its eight-account Source A acquired **768,007 history records in 1,117.082 seconds**, including waits: **687.512 records/second**, with attachment downloads disabled. The complete attempt, including validation, took 1,574.920 seconds. These measurements describe that workload, alongside the smaller fresh-export examples above. ### Testing history and duration TgWitness has been developed and tested for about six months. The collector, the signed journal and the verifier came first; the web panel and the add-on modules were built on them later. This repository was created new on 29 October 2026 for publication and began with the existing code, so its age is not the project's age ([development history](https://github.com/phishdestroy/TgWitness/blob/main/docs/QUESTIONS-AND-CHECKS.md#development-history)). The cumulative exercised workload is on the order of 100 million, including earlier runs, failures, fixes and repeated validation. Selected runs, each with its own revision, method and result, are documented in the [dated public measurements](https://github.com/phishdestroy/TgWitness/blob/main/docs/QUESTIONS-AND-CHECKS.md#dates-of-the-published-measurements). ## Read capability status precisely Assess each workflow against its implementation, published build and recorded tests. The source is currently labelled preview. That release label coexists with working collection, exports, independent verification and published scale measurements. A preview feature and a validated workflow can exist in the same application; describe the specific feature and evidence behind an assessment. Use [current capabilities](https://github.com/phishdestroy/TgWitness/blob/main/docs/STATUS.md), [features and limits](https://phishdestroy.io/tgwitness/docs/reference/features/), [verification](https://phishdestroy.io/tgwitness/docs/reference/verification/) and [the changelog](https://phishdestroy.io/tgwitness/docs/reference/changelog/) together. Record the tested revision when citing a result. The 6 November measurement snapshot also retains failed and skipped tests; those are not passes. ## Readable by people and AI tools The website provides a concise `llms.txt`, a complete English handbook in `llms-full.txt` and `llms-full.md`, and Markdown editions of its pages. These are documentation formats, not an AI requirement for running TgWitness. Optional [MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/) and [command-line access](https://phishdestroy.io/tgwitness/docs/reference/cli/) let authorized tools read selected saved records. Message content remains untrusted input. Summaries should cite sources, distinguish observed facts from inference and preserve uncertainty. Full-text search, OCR and AI output do not change the original signed observations. --- # TgWitness Setup: Windows, Linux, macOS & Docker Canonical page: https://phishdestroy.io/tgwitness/docs/reference/quickstart/ Choose a TgWitness installation method, launch the panel and check your first workspace. Includes Windows, Linux, macOS, Docker and the synthetic demo. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Every way to install and launch TgWitness: Windows package, Python, Docker and the synthetic demo, with first checks. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2) **English** · [Русский](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/QUICKSTART.md) · [Українська](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/QUICKSTART.md) · [Español](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/QUICKSTART.md) · [Português (Brasil)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/QUICKSTART.md) · [Türkçe](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/QUICKSTART.md) · [العربية](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/QUICKSTART.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/QUICKSTART.md) · [اردو](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/QUICKSTART.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/QUICKSTART.md) · [Bahasa Indonesia](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/QUICKSTART.md) · [Tiếng Việt](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/QUICKSTART.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/QUICKSTART.md) TgWitness is a standalone application for observing Telegram groups and channels that your accounts can access. It runs locally with its own data directory. **First visit?** [Explore the demo](https://phishdestroy.io/tgwitness/docs/reference/quickstart/#explore-the-interface) before connecting an account. [Choose a guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) for proxies, witnesses, exports or server setup. [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) (preview) runs a capture in your own GitHub fork instead of a local installation. ## Install and start The guided installer includes its own Python and checks package hashes and release signatures before installing. Running it again updates an existing installation. **Linux / macOS:** ``` curl -fsSL https://get.destroy.tools/install.sh | bash ``` **Windows (PowerShell or Command Prompt):** ``` powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex" ``` On an Ubuntu server, run as root to install a background service; on a desktop, run as your normal user. On Ubuntu the installer prints the panel address and access key; on macOS and Windows the local panel opens in your browser. Continue at **Connect Telegram** below. [Install, verify and update](https://phishdestroy.io/tgwitness/docs/reference/installation/) covers the server access choices, checking the script before running it, updates and removal. ### Other methods GitHub releases, the source and Docker are alternatives to the installer. Portable downloads become available after a release build is published: | Host | Nothing installed | From source: Python 3.11+ | Docker: Engine/Desktop with Compose 2.20+ | | --- | --- | --- | --- | | Windows | Extract `TgWitness--windows-amd64-portable.zip` from GitHub Releases, double-click `TgWitness.cmd` | Double-click `Start.cmd` | Double-click `scripts\Docker.cmd` | | Linux / macOS | — | `sh start.sh` | `sh scripts/docker-start.sh` | For the source methods, [download and extract current `main`](https://github.com/phishdestroy/TgWitness/archive/refs/heads/main.zip) or clone the repository: ``` git clone https://github.com/phishdestroy/TgWitness.git cd TgWitness ``` `Start.cmd` offers to install Python 3.12 for your Windows user if no suitable Python is found (winget, or the signed python.org installer). `start.sh` prints the exact install command for your Linux distribution or macOS if Python is missing. The first source launch creates `.venv` and installs dependencies automatically. Docker builds the application and starts it in the background; host Python is unnecessary. `scripts\Docker.cmd` and `scripts/docker-start.sh` print the panel address and token when the container is healthy. The equivalent Docker commands on every supported host are: ``` docker compose up -d --build --wait docker compose exec tgwitness cat /data/panel-token.txt ``` Open **http://127.0.0.1:8787**. Use the token printed by the Docker helper or the second Docker command, or read **data/live/panel-token.txt** for a portable or source installation. Continue at **Connect Telegram** below. Native and Docker installations use separate storage; starting Docker does not import an existing native journal. For a server, [deployment](https://phishdestroy.io/tgwitness/docs/reference/deployment/) covers automatic HTTPS, restart, published images, updates, and backups. ## Explore the interface 1. Run **TgWitness-Demo.cmd** in the portable package, **scripts\Demo.cmd** in a Windows source folder, or `sh start.sh --demo` on Linux/macOS. A source launch first creates `.venv` and installs dependencies. 2. Open **http://127.0.0.1:8787**. 3. The local demo opens the sample journal automatically. No token copy is needed for direct local access. Demo messages are fictional. Demo mode cannot connect a real Telegram account. ## Connect Telegram > [!WARNING] **Use dedicated accounts.** Telegram can restrict or permanently ban accounts for request volumes it considers excessive, whatever the client. Connect accounts prepared for observation rather than personal or valuable ones, and create an API ID / hash on a dedicated account. 1. If the native demo is running, stop it and run **Start.cmd** or `sh start.sh`. Otherwise, keep the live installation started above running. 2. Use the panel token to sign in. A new workspace opens [first setup](https://phishdestroy.io/tgwitness/docs/reference/settings/). Choose **Just download**, **Follow chats** or **Evidence for a case**. 3. Review the connection check. Configure your own proxy if needed; connection settings remain available after setup. 4. At **Connect Telegram**, choose a phone number, a QR code, account files (TData, `.session`, StringSession, account JSON) or a complete authorization key. Complete the Telegram confirmation, code and two-step password when requested. 5. Check the displayed account, choose the chats and review your settings. Finish from the final screen. For **Just download**, **Start export** starts a one-time export and opens Exports to show its progress; it does not enable continuous observation. After setup, **Chats → Choose** changes the selected chats. **Settings** controls collection and files; **More tools → Sources** provides the detailed source list at Standard or Expert level. The [panel guide](https://phishdestroy.io/tgwitness/docs/reference/panel/) describes the six main sections and their contextual controls. **API ID + Hash** is optional: the workspace uses its saved or imported pair, or a working pair from the built-in pool. To use your own app, paste one `API ID:API Hash` pair into API ID. For **Auth key**, paste all 512 hexadecimal characters and select the supplied DC ID. User ID is optional and checked if entered. API credentials identify your application; they do not authorize an account by themselves. Private groups need no public username, but your account must have access. For existing accounts, see [accounts and session formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/): the panel accepts Telethon StringSession, Telethon/Pyrogram SQLite, single-account TData ZIP, and supported account JSON. Select a session and its companion JSON together, press **Check files**, then **Connect account**. QR login is also available with the same optional API settings. TDLib, bot sessions and CSV/JSON account inventories are unsupported. For several accounts, use **Accounts → Import accounts** and select their supported session files. Companion JSON files are paired by basename; each imported account gets its own workspace. See [bulk import and account groups](https://phishdestroy.io/tgwitness/docs/reference/accounts/#bulk-import-and-account-groups). To add another account, press **+** beside the account selector or use **Accounts → Add account**. Workspaces have separate sessions, journals, keys, sources and queues. Switching views leaves other collectors running. The same Telegram account cannot be assigned to two workspaces in this installation. There is no fixed number of workspaces; they share one process, so capacity depends on the machine. The live panel token protects access to your Telegram authorizations and saved material; it is separate from Telegram API credentials. Only an explicitly started, directly accessed local demo gets automatic entry. A remote/proxied demo still uses `data/demo/panel-token.txt`. ## Review and export - **Journal:** search and filter observations by source and event type. - Select an event to inspect its original record, attribution and saved versions. - Edit details show the available before/after content. Deletion details show the last captured content, if any; an unknown actor remains unknown. - **Exports:** signed ZIP, JSONL, CSV and offline HTML. - **Full chat export** (**Chats → Export chat**, or **Exports → Capture or export one chat**): download one chat's entire visible history as a signed bundle with `chat.json` (Telegram-export style) and a readable `chat.html`. Private chats work when the account is a member. It is a current snapshot, not a reconstruction of deleted or previously edited messages. Verify a copy with `python verify.py chat-export.zip --fingerprint TRUSTED_SHA256`. - **Save checkpoint:** keep the signed journal boundary outside the collector. - **Download signed run receipt:** preserve the collector's program/version record. - **Prepare timestamp request:** prepare an offline request for a timestamp authority; follow [TIMESTAMP.md](https://phishdestroy.io/tgwitness/docs/reference/timestamp/) to obtain and verify a response. - **Verify journal:** check event signatures and chain links. ZIP export also checks media. Supported browsers save large exports directly to a chosen file. Other browsers buffer at most 128 MiB. While the server is running, the streaming CLI supports larger downloads without buffering the whole response: ``` python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip ``` For another workspace, add `--profile ID` using **Exports → Workspace ID**. For a remote server, add `--url https://your-server`. The default transfer limit is 5 GiB; `--max-mib` changes it. Signed ZIP content has a separate 4 GiB uncompressed verification limit by default (**More tools → Parameters** raises it; verify such archives with `verify.py --max-gib N`). Verify the archive using a trusted copy of the verifier, an independently retained key fingerprint and, for the minimum for evidence, the timestamp authority's root certificate (`--tsa-ca`). ## Check the installation ``` python start.py --setup-only python start.py --check python start.py --check --json ``` `--check` probes local dependencies, signing support, storage, key configuration and the listening address. It does not install anything or connect to Telegram. A busy port may mean another instance is running. Use a different `--port` or stop it first. The launcher installs into `.venv`. Auxiliary `python -m tgwitness...` commands must use `.venv\Scripts\python.exe` on Windows or `.venv/bin/python` on Linux/macOS, unless that environment is already activated. ## Sessions, protection and operation A closed, consistent Telethon SQLite `.session` can be converted locally with `python -m tgwitness.sessions account.session --out account.tgwitness-session`, then loaded in **More tools → Account → Files**. Direct file import and QR login are also available. See [CONNECTION-SECURITY.md](https://phishdestroy.io/tgwitness/docs/reference/connection/) for login formats, SOCKS5, HTTP CONNECT, MTProxy and external master keys. **Pause observation** stops collection. **Lock** only closes browser access. Closing a tab leaves the collector process running. Stopping the process interrupts collection; a history snapshot cannot reconstruct all missed edits or deletions. See [how collection works](https://phishdestroy.io/tgwitness/docs/reference/collection/) for event policies, attachment queues, account isolation, and restart behavior. Sessions and secrets are encrypted. Message content, media and exports require an encrypted disk or volume. Verify journal signatures against a trusted key and retain checkpoints separately. Review capture records, external time receipts and environment attestations for the selected collection mode. Read [OPERATIONS.md](https://phishdestroy.io/tgwitness/docs/reference/operations/) for backup/restore, [DEPLOYMENT.md](https://phishdestroy.io/tgwitness/docs/reference/deployment/) for hosting, and [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md) for service examples. The installed panel also includes an offline setup guide at `/guide.html`. Actual verification and remaining boundaries are recorded in [VERIFICATION.md](https://phishdestroy.io/tgwitness/docs/reference/verification/) and [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md). --- # Install, Verify & Update TgWitness Canonical page: https://phishdestroy.io/tgwitness/docs/reference/installation/ Install or update TgWitness with one command. Verify release signatures and SHA-256 hashes, review package options and remove an installation safely. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Install with one command, check signatures and hashes, update and remove an installation. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Getting started](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) ![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2) [Project](https://github.com/phishdestroy/TgWitness/blob/main/README.md) · [Quick start](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) · [Deployment](https://phishdestroy.io/tgwitness/docs/reference/deployment/) **On this page** - [Install with one command](https://phishdestroy.io/tgwitness/docs/reference/installation/#install-with-one-command) - [Where everything runs](https://phishdestroy.io/tgwitness/docs/reference/installation/#where-everything-runs) - [Full-text search settings](https://phishdestroy.io/tgwitness/docs/reference/installation/#full-text-search-settings) - [Command-line access](https://phishdestroy.io/tgwitness/docs/reference/installation/#command-line-access) - [Verify before running](https://phishdestroy.io/tgwitness/docs/reference/installation/#verify-before-running) - [Update an existing installation](https://phishdestroy.io/tgwitness/docs/reference/installation/#update-an-existing-installation) - [Everyday commands on Ubuntu](https://phishdestroy.io/tgwitness/docs/reference/installation/#everyday-commands-on-ubuntu) - [Remove TgWitness](https://phishdestroy.io/tgwitness/docs/reference/installation/#remove-tgwitness) ## Install with one command The project's official download service, `get.destroy.tools`, provides the guided installer and its signed release files. It includes a private Python runtime and checks package hashes and release signatures before installation. Each publication updates the entry scripts, hashes, signatures and build information together; each build also has an immutable release URL. Choose the guided installer for a short setup, or use [GitHub releases, source or Docker](https://phishdestroy.io/tgwitness/docs/reference/quickstart/). These are supported installation paths for the same open-source project. For a deployment that requires approval of an exact build before execution, use [Verify before running](https://phishdestroy.io/tgwitness/docs/reference/installation/#verify-before-running) with an independently retained release-key fingerprint and the build's immutable URL. Updating the download service does not update an installed panel automatically. **Linux / macOS (Bash):** ``` curl -fsSL https://get.destroy.tools/install.sh | bash ``` On an Ubuntu server, run as root to install a background service. On a desktop, run as your normal user. **Windows (PowerShell or Command Prompt):** ``` powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "irm https://get.destroy.tools/install.ps1 | iex" ``` No administrator is needed on Windows. The child PowerShell process leaves your terminal open with the result. Python and dependencies stay in the installation. On Ubuntu, choose **This computer**, **Temporary HTTPS link** or **Own domain**. The installer prints the panel address and access key. For a temporary link, open that HTTPS address in your browser and enter the key. With local access on a remote server, use an SSH forward from your computer (`ssh -L 8787:127.0.0.1:8787 user@server`) and open `http://127.0.0.1:8787`. On macOS and Windows, the local panel opens in your browser; keep its terminal running. Sign in to Telegram in the panel and choose what to collect. Installation alone does not start Telegram collection. ## Where everything runs `get.destroy.tools` is a **Cloudflare Worker serving static downloads**. It has no TgWitness panel, Telegram session or user evidence database. It is not routed to a project VPS. The application runs on the machine where you execute the command. | Installation | Program | Data | | --- | --- | --- | | Ubuntu as root | `/opt/tgwitness` | System service: `/var/lib/tgwitness-`; use `tgwitness paths` for the exact path. | | Linux / macOS user | `~/.local/share/tgwitness` | `data/live` under that installation. | | Windows user | `%LOCALAPPDATA%\TgWitness` | `data\live` under that installation. | Set `TGWITNESS_INSTALL_DIR` to choose another folder. Installed versions and data are separate. The installer does not upload your accounts, messages or keys to the download site. Choosing a Cloudflare tunnel sends panel traffic through Cloudflare; using your own domain points to your own server. With `TGWITNESS_TRUSTED_PROXIES`, the panel accepts a single `X-Forwarded-Proto: https` from a trusted proxy to set Secure download cookies. Every installation includes **START-HERE.html** and **START-HERE.txt**, with local paths, commands and links to the repository. Run `tgwitness guide` to open the guide. On Windows, use `& "$env:LOCALAPPDATA\TgWitness\bin\tgwitness.cmd" guide` in PowerShell. ## Full-text search settings [Full-text search](https://phishdestroy.io/tgwitness/docs/reference/search/) (preview) needs no setup. Its index is built in the background after an update. | Variable or command | Effect | | --- | --- | | `TGWITNESS_FULLTEXT=disk` | Default: the index is kept in `search/fulltext.sqlite3` of each workspace | | `TGWITNESS_FULLTEXT=memory` | No index file; the index is rebuilt at every start | | `TGWITNESS_FULLTEXT=off` | No index; only exact-text search | | `tgwitness index status` | Index state of every workspace | | `tgwitness stop`, `tgwitness index rebuild`, `tgwitness start` | Rebuild every index from the signed journal | The administrator's choice in **Journal → Filters → Search index** overrides the variable for that workspace. Commands find the data directory of the installation that runs them; elsewhere, add `--data-dir` with the path from `tgwitness paths`. For a full Ukrainian dictionary (GPL-3.0 data), install `pymorphy3-dicts-uk` in the installation's Python environment. ## Command-line access The [command line](https://phishdestroy.io/tgwitness/docs/reference/cli/) (preview) reads the archive for scripts and agents. | Variable | Effect | | --- | --- | | `TGWITNESS_URL` | Panel address for `tgwitness search`, `context`, `messages`, `stats` and `export`; default `http://127.0.0.1:8787` when a token is set | | `TGWITNESS_MCP_TOKEN` | Archive connection token from **More tools → Integrations → MCP**, shared with MCP clients; `--token-file` reads it from a file instead | | `TGWITNESS_DATA` | Data directory read directly when no `--data-dir`, URL or token is given | ## Verify before running The installer embeds the project's release public key and checks SHA-256 and RSA signatures on the application package and dependency lock before installing them. Both Bash and PowerShell stop when a required check fails. The initial script is delivered over HTTPS and has its own detached signature; the commands below also let you verify that script before executing it. The public release key is [release-signing.pub](https://github.com/phishdestroy/TgWitness/blob/main/deploy/installer/release-signing.pub). Its SHA-256 is: ``` 039d98a658ccda14253e45a00335b4a68d840976d8ec18b8d4355cc7c458447d ``` Retain this fingerprint from a repository revision you trust. A checksum from the same download server detects a mismatch; the independently trusted public key is what authenticates a release signature. Use a new, empty directory for the verification downloads below. **Linux / macOS — run in a new, empty download directory** (requires curl and OpenSSL): ``` curl -fSLO https://get.destroy.tools/install.sh && curl -fSLO https://get.destroy.tools/install.sh.sig && curl -fSLO https://get.destroy.tools/release-signing.pub && test "$(openssl dgst -sha256 release-signing.pub | awk '{print $NF}')" = \ '039d98a658ccda14253e45a00335b4a68d840976d8ec18b8d4355cc7c458447d' && openssl dgst -sha256 -verify release-signing.pub -signature install.sh.sig install.sh && bash install.sh ``` The `&&` chain stops before execution if a download, key fingerprint or signature check fails. If publication happens between downloading the script and its signature, download both again. Old installers keep their immutable package URLs. **Windows — inspect the SHA-256 before running:** ``` Invoke-WebRequest https://get.destroy.tools/install.ps1 -OutFile install.ps1 -UseBasicParsing Get-FileHash .\install.ps1 -Algorithm SHA256 Invoke-RestMethod https://get.destroy.tools/SHA256SUMS.txt ``` Compare the hash with the `install.ps1` line. For an independent signature check, use OpenSSL (for example, from Git Bash) and the same public-key fingerprint above: ``` curl -fSLO https://get.destroy.tools/install.ps1 && curl -fSLO https://get.destroy.tools/install.ps1.sig && curl -fSLO https://get.destroy.tools/release-signing.pub && test "$(openssl dgst -sha256 release-signing.pub | awk '{print $NF}')" = \ '039d98a658ccda14253e45a00335b4a68d840976d8ec18b8d4355cc7c458447d' && openssl dgst -sha256 -verify release-signing.pub -signature install.ps1.sig install.ps1 && powershell.exe -NoProfile -ExecutionPolicy Bypass -File install.ps1 ``` Windows installation itself verifies package signatures with .NET and does not require OpenSSL. These are detached RSA-3072 / SHA-256 signatures, not Authenticode. The [manifest](https://get.destroy.tools/manifest.json) records the software version, exact Git commit, immutable release ID and each artifact's SHA-256. The page links to the corresponding source. The manifest and checksum list also have detached signatures (`manifest.json.sig` and `SHA256SUMS.txt.sig`). ## Update an existing installation **A new publication updates the download site; installed programs update when you run the installer again.** There is no unattended updater or automatic restart of a running collection. The current installer channel is **preview**; it follows published, checked builds from `main`, whose commit can be newer than the last numbered GitHub release. The page's version comes from `pyproject.toml`; its commit and build ID distinguish updates within the same preview version. Publication is automatic after that exact commit passes the application and security checks and the signed package is authenticated, installed and checked on Ubuntu and Windows. Pull requests that change the installer also run `install.sh` and `install.ps1` twice against a local copy of the site. While checks are running, or if they fail, the same commands continue to install the previous checked build. The build manifest shows which commit is currently available; the version number alone may stay the same between preview updates. Use the same installation folder and OS user as before. Back up the complete data directory with collection stopped; `tgwitness paths` identifies it. A signed export is not a complete installation backup. **Ubuntu root installation at `/opt/tgwitness`:** ``` curl -fsSL https://get.destroy.tools/install.sh | TGWITNESS_INSTALL_DIR=/opt/tgwitness bash -s -- --no-start ``` After a successful installation: ``` /opt/tgwitness/bin/tgwitness restart /opt/tgwitness/bin/tgwitness status /opt/tgwitness/bin/tgwitness open ``` For a Linux/macOS user installation, use its original `TGWITNESS_INSTALL_DIR` or the default and run the first installation command again. Close a foreground panel before updating and start it again afterwards. For a configured Linux user service, run its `tgwitness restart` command. **Windows:** close the running panel, run the Windows installation command again, then open `bin\tgwitness.cmd` in the same installation. The installer retains data, sessions, access settings and signing keys. It switches the launcher only after the new environment passes its checks; failed installation leaves the previous launcher in place. Keep the pre-upgrade backup for storage-format changes. ## Everyday commands on Ubuntu | Command | Result | | --- | --- | | `tgwitness open` | Current panel URL and access key. | | `tgwitness paths` | Exact program, data and guide paths. | | `tgwitness guide --print` | Offline operating instructions. | | `tgwitness status` / `tgwitness logs` | Availability / service logs. | | `tgwitness stop` / `tgwitness start` | Stop / resume the service; retain data. | | `tgwitness token rotate` | Replace the administrator key and end browser sessions. | | `tgwitness tunnel off` | Disable the public quick tunnel; retain the local panel. | | `tgwitness tunnel on` / `tgwitness tunnel restart` | Create a quick-tunnel link / replace its address. | See [Access](https://phishdestroy.io/tgwitness/docs/reference/access/) for colleague tokens, sessions and IP restrictions, and [installer publishing](https://github.com/phishdestroy/TgWitness/blob/main/deploy/installer/README.md#automatic-publication-from-github) for the GitHub-to-Cloudflare release workflow. ## Remove TgWitness There is no uninstaller: you stop the panel and delete its folders. Deleting the data folder destroys journals, signing keys, Telegram sessions and saved files for good. Before that: 1. Export what you need (**Exports → Download signed ZIP**) and keep the signing key fingerprint and checkpoints outside this machine. To keep the workspace itself, copy the whole data folder with collection stopped. 2. Delete servers created under **More tools → Extras → Server 24/7** from **Your servers** or with `python -m tgwitness.cloud destroy`; the provider bills them until they are deleted. 3. End each account's session in Telegram under **Settings → Devices**. Deleting the files does not sign the session out on Telegram's side. **Ubuntu root installation.** Note the data folder, stop the service, then remove the service, the folders and the shortcut: ``` /opt/tgwitness/bin/tgwitness paths /opt/tgwitness/bin/tgwitness stop systemctl list-unit-files 'tgwitness-*' systemctl disable tgwitness- rm /etc/systemd/system/tgwitness-.service systemctl daemon-reload rm -rf /opt/tgwitness /var/lib/tgwitness- /usr/local/bin/tgwitness ``` **Linux or macOS user installation.** Close the panel. A configured Linux user service is stopped with `systemctl --user disable --now tgwitness-`; its unit is in `~/.config/systemd/user/`. Then delete `~/.local/share/tgwitness` (or your `TGWITNESS_INSTALL_DIR`) and the `~/.local/bin/tgwitness` shortcut. **Windows.** Close the panel and delete `%LOCALAPPDATA%\TgWitness` (or your `TGWITNESS_INSTALL_DIR`). The installer adds no service, scheduled task or shortcut. --- # Telegram Collection Setup & TgWitness Settings Canonical page: https://phishdestroy.io/tgwitness/docs/reference/settings/ Configure TgWitness setup goals, collection options, connection routes and interface levels. Review account-group defaults and per-account overrides. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) The setup wizard, goals, interface levels, connection routes and settings shared by an account group. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Getting started](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) ![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2) [Accounts](https://phishdestroy.io/tgwitness/docs/reference/accounts/) · [Connection](https://phishdestroy.io/tgwitness/docs/reference/connection/) · [Access](https://phishdestroy.io/tgwitness/docs/reference/access/) A new workspace opens `/first-run`. The first screen asks what you want to do: **Just download**, **Follow chats** or **Evidence for a case**. The choice sets the goal and the interface level: Simple for Just download, Standard for the other two. The level sets how many fields each form shows; every page stays in the menu. **More options** on the same screen sets the level, theme and time zone explicitly; the language list is in the wizard header. The next screens cover the connection, Telegram and chats. Connection routes stay folded while the automatic check works and open when it fails. A five-stage progress bar returns to completed stages. Each answer is saved on the server as soon as it changes, so a reload continues the same step. The last screen lists the answers and lets you go back to any of them. Language, IANA time zone, theme and level are stored per operator and per workspace. The defaults are the browser language, the device time zone, the system theme and the Simple interface. Changing the language keeps the panel session. Times in the signed journal never change. `/settings` edits the same records as the wizard. Search covers the main fields, parameters and the extended forms; a hidden field can be opened without changing the level. Levels only change what is shown: the server checks permissions on its own. A section whose settings are all above the chosen level shows them anyway. Collection settings and the first connection belong to the workspace administrator. The settings page is a list. The account card on top opens **Telegram account**. Below it each row names a section and the value in use: **Which chats?** and **Connection** under **Account**; **Goal**, **Collection and files**, **Record protection** and **Notifications and off-site copy** under **Recording**; **Language, time and appearance** under **Panel**; and the expert pages under **More tools**. Beside the list a card says whether the recommended values are on, with the main values and **Undo last change**, and **Recent changes** lists the latest edits. A section opens in a window over the list and has its own address, such as `/settings/connection`. The back arrow, the close button, Escape, a click outside the window and the browser's Back button return to the list. **Which chats?** is kept with **Save chat selection**; closing with unsaved changes asks first. Saving keeps the source types, excluded chats, own actions and new-chat settings of **More tools → Sources → Scope**; a chat chosen here is taken off the excluded chats and recorded as a hand-picked source. Every change shows **Undo** for 20 seconds, and each entry in **Recent changes** can be undone later. An undo brings back only the settings that entry changed, custom file limits included. When a later change touched the same settings, the undo is refused and nothing changes. An undo is a new `settings.changed` record in the journal. | Level | Fields | Sidebar | | --- | --- | --- | | Simple | Only the essentials | Home, Chats, Journal, Exports, Accounts and Settings | | Standard | Common settings with explanations | Adds Case Board, Sources, Access and Documentation under More tools | | Expert | All fields, limits and technical details | Also adds System map, Network topology, Extras, Ask the archive, Parameters, Account, System log and Integrations under More tools | Section names stay the same at every level. Open Appearance at the bottom of the sidebar to change the level. The [panel guide](https://phishdestroy.io/tgwitness/docs/reference/panel/) describes each section. ## Goals | Goal | Collection | Files | Outside services | Server address | | --- | --- | --- | --- | --- | | Just download | One-time export starts from the final setup screen; continuous collection stays off | Photos up to 20 MB | Timestamps | Automatic | | Follow chats | Continuous | Photos and videos up to 60 seconds / 20 MB | Timestamps and problem notifications | Automatic | | Evidence for a case | Continuous | All files up to 1 GB | Timestamps, drand, notifications | No, hide it | Off-site copy, the witness bot and the code check are recommended for evidence. Storage and notification addresses need a destination first. A feature that talks to an outside service asks to allow requests outside Telegram; turning that off offers to switch off timestamps, notifications and the off-site copy with it. Changing the goal shows the difference first, and manual changes can be kept. A field that differs from the goal is marked **Changed by you** and can be restored. The settings revision keeps a reviewed difference from being applied over a change made in another tab. ## Connection Until a route is chosen here, a new workspace uses **Automatic MTProxy · public lists** with **Hide the address** ([connection security](https://phishdestroy.io/tgwitness/docs/reference/connection/)). The **Automatic** choice below is a separate setup step. **Automatic** tries WARP, then public MTProxy servers, then a direct connection, the last only when the server's address may be shown. Automatic and WARP can install hash-checked components and register the server with Cloudflare; without that consent Automatic skips WARP. WARP uses the existing wgcf/wireproxy manager and a local SOCKS5 port; the system routing table is not changed. **Bulk import** asks for the route before any session reaches Telegram: WARP (default), public MTProxy or direct. The session check uses the same kind of route, and every imported account gets its own WARP tunnel before its first sign-in. Your own proxy accepts `tg://proxy`, `socks5://`, `http://` and `https://`. An HTTPS proxy's certificate is checked before credentials are sent to it. A connection check is valid for five minutes and is bound to the route, the policy and the wizard answers; changing any of them needs a new check. **Continue without checking** is available and does not replace the Telegram sign-in. The chosen route is rechecked in the background, and Automatic runs its chain again after a lost connection. When no public proxy answers, the count turns red with WARP and recheck actions. ## Account groups Accounts in a group share their settings. Open **Accounts → Groups and shared settings → Shared settings**, or **Group settings** on an account's Settings page. The group shares the goal, saved files, timestamps, drand, problem notifications, off-site copy, requests outside Telegram, IP mode, what to record, the recheck schedule, notification rules, report settings, parameters and the connection route. Notification destinations, proxy credentials and sign-in stay per account, as do starting and pausing collection. - Every member follows the group. Settings marks a value 🔗 **From the group** or ✏️ **Own value**; **Return to the group value** puts it back. - A change lists the accounts it reaches (**Applies to 2 of 3 accounts**) and asks per account before replacing an own value. Unticked accounts keep theirs. - A parameter the group does not share stays **Not shared: each account keeps its own value** until you press **Share this value**. - **Copy settings from one account** takes the chosen account's values as the group's. - An account moved into a group is asked **Take the group's values?** Otherwise it keeps its own values, marked ✏️. Accounts added later start with the group's values. - An observing account keeps its IP mode until it is paused. Each change is recorded in the signed journal of the main workspace and of every member it reaches. Deleting a group keeps its accounts and their current values. The group page `/groups/` shows the members, what needs attention and the chats several accounts see. See [account groups](https://phishdestroy.io/tgwitness/docs/reference/accounts/#bulk-import-and-account-groups). ## Existing workspaces A workspace with a session or an earlier completed setup does not get the wizard. Its values are not replaced by a goal when the page loads. Hiding a field does not turn the feature off or delete its value. **Open first setup** in Settings shows the same screens again; finishing them starts no new export or observation and says so, and a changed chat selection is kept only with **Save chat selection**. The size and time estimate reads up to three selected chats and up to 20 messages from each. It is an estimate: it does not predict Telegram limits, the speed of a given server or the files in every chat. --- # Telegram Session Formats: TData & Telethon Canonical page: https://phishdestroy.io/tgwitness/docs/reference/accounts/ Review supported Telegram login and session formats: phone, QR, Auth Key, Telethon, Pyrogram and TData. Check import options and session ownership. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Sign in by phone, QR code or auth key, import Telethon, Pyrogram or Telegram Desktop sessions, and run several accounts. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Getting started](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) ![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2) TgWitness signs in as a **Telegram user account** (not a bot) over MTProto, using Telethon. Each account lives in its own **workspace** (called a *workspace* in the API and command-line tools) with its own session, sources, journal and signing key. Session files, session strings and Auth Keys are **account authorizations**: whoever holds one can act as that account. They do not contain message history. > [!WARNING] **Use dedicated accounts.** Telegram restricts and can permanently ban accounts for request volumes it considers excessive, whatever the client or purpose, and documents those limits only in part. Connect accounts prepared for observation rather than personal or otherwise valuable ones, and create an API ID / API hash on a dedicated account. - [At a glance](https://phishdestroy.io/tgwitness/docs/reference/accounts/#at-a-glance) - [Before you start: API ID and API hash](https://phishdestroy.io/tgwitness/docs/reference/accounts/#before-you-start-api-id-and-api-hash) - [Phone number](https://phishdestroy.io/tgwitness/docs/reference/accounts/#phone-number) · [QR code](https://phishdestroy.io/tgwitness/docs/reference/accounts/#qr-code) · [Auth Key + DC ID](https://phishdestroy.io/tgwitness/docs/reference/accounts/#auth-key--dc-id) - [Account files](https://phishdestroy.io/tgwitness/docs/reference/accounts/#account-files): [Telethon .session](https://phishdestroy.io/tgwitness/docs/reference/accounts/#telethon-session) · [Pyrogram .session](https://phishdestroy.io/tgwitness/docs/reference/accounts/#pyrogram-session) · [Session + JSON pair](https://phishdestroy.io/tgwitness/docs/reference/accounts/#session--json-pair) · [TData](https://phishdestroy.io/tgwitness/docs/reference/accounts/#telegram-desktop-tdata) · [StringSession](https://phishdestroy.io/tgwitness/docs/reference/accounts/#telethon-stringsession) · [Auth key and DC in one line](https://phishdestroy.io/tgwitness/docs/reference/accounts/#auth-key-and-dc-in-one-line) · [Account JSON](https://phishdestroy.io/tgwitness/docs/reference/accounts/#account-json) - [Identify what you have](https://phishdestroy.io/tgwitness/docs/reference/accounts/#identify-what-you-have) · [Unsupported formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/#unsupported-formats) - [Multiple accounts](https://phishdestroy.io/tgwitness/docs/reference/accounts/#multiple-accounts) · [Keeping account files safe](https://phishdestroy.io/tgwitness/docs/reference/accounts/#keeping-account-files-safe) · [Troubleshooting](https://phishdestroy.io/tgwitness/docs/reference/accounts/#troubleshooting) ## At a glance | What you have | Tab in **Add account** | You will also need | | --- | --- | --- | | The phone number and access to its login codes | **Phone** | 2FA password if enabled | | Telegram open on another device | **QR code** | 2FA password if enabled | | A `.session` file (Telethon or Pyrogram) | **Files** | Optional companion JSON for app settings | | `.session` + `.json` with the same name | **Files** (select both) | Usually nothing else | | A Telegram Desktop `tdata` folder | **Files** (as a ZIP) | The Desktop local passcode if one is set | | A Telethon StringSession (text, `.txt`, `.tgwitness-session`) | **Files** | No separate API pair required | | An auth key and DC as one line, `<512 hex>:<1–5>` | **Files** (paste or a text file) | No separate API pair required | | A `.json` with a session or Auth Key | **Files** | No separate API pair required | | An Auth Key (512 hex characters) and its DC number | **Auth key** | Optional User ID | TgWitness recognises files by their **contents**, not their names. Renaming a file never converts it. ## Before you start: API ID and API hash You can sign in without creating a Telegram API application. When no pair is entered, imported or already saved in the workspace, TgWitness picks a pair from its built-in pool of 50 public API pairs (`tgwitness/api_pool.py`), preferring Telegram Desktop for a fresh login and retaining a saved pair first; remaining candidates are shuffled. If Telegram refuses a pair (`API_ID_INVALID`, `API_ID_PUBLISHED_FLOOD`, `UPDATE_APP_TO_LOGIN`), the next one is tried, up to eight per sign-in; refused pairs are skipped until restart. The pair that signed in is saved with the account and reused for it. The built-in pairs are public: they are published in the open source code of Telegram clients and libraries. An **API ID** and **API hash** identify the application to Telegram and give no access to account data. Sign-in uses the account's own authorization: a login code and 2FA password, or a session that account already authorized. Each `observation.started` record names the pair used, so a built-in pair is documented for court in the same way as your own. You can enter your own pair from my.telegram.org instead. In the project's experience a new personal pair gets most accounts logged out, so use one only when a case requires your own application: create it with a dedicated account and enter it before collection starts (steps below). Missing connection fields use a deterministic device/OS pair from the bundled [opentele2 2.0.0 catalogs](https://github.com/DedInc/opentele2/tree/7e973bc71cd7a714ad13ac703c0895a90d36a735): Desktop `2040`, Android `6`, Android X `21724`, iOS `10840`, macOS `2834`, and Web `2496`. Android's source-build ID `4` also uses the Android catalog, as identified in [Telegram Android's BuildVars](https://github.com/DrKLO/Telegram/blob/master/TMessagesProj/src/main/java/org/telegram/messenger/BuildVars.java). Web defaults to A; an imported `K` app-version suffix or `macos` language pack selects K, and version `0.7.0` selects Webogram. Unknown application IDs keep Telethon's host defaults. Imported fields always win, including an older app version and an empty language pack. The catalog never changes the API ID/hash. Its version snapshot is reviewed explicitly, not fetched during login. A saved profile stays stable after updates. `account.getAuthorizations` reports Telegram's saved authorization metadata; it is not an echo of each new `initConnection`. Compare it with the actual sent profile. Connecting an existing authorization does not validate its companion API hash: `initConnection` sends the API ID, while the hash is used by login requests. After a new phone or QR authorization, TgWitness requests config, nearest DC, online status, languages (when the language pack is nonempty), app updates and terms-of-service updates, with 0.3–1.5 seconds between requests. Updating status briefly marks the account online. This sequence runs once at login completion, not on imports, reconnects or restarts. The authorization is saved first; a failed request stops the sequence without retrying or discarding the login. Results are recorded as `account.initialized`, with error names rather than response bodies. Telegram's own policies decide account restrictions. For `tdesktop`, a missing `tz_offset` uses the server's local UTC offset, rounded to 900 seconds using the [opentele2 algorithm](https://github.com/DedInc/opentele2/blob/7e973bc71cd7a714ad13ac703c0895a90d36a735/crates/opentele2-core/src/fingerprint.rs) (MIT; license in `tgwitness/client_profiles.LICENSE`). It is refreshed on each connection so daylight-saving changes are reflected. An imported `tz_offset` takes precedence on every platform and is kept exactly, including zero. Other `initConnection.params` entries are retained. The HTTP sign-in form accepts the numeric timezone returned by file import; booleans, fractions and offsets outside the supported range are rejected. Direct, SOCKS5 and HTTP CONNECT routes use Telethon's `ConnectionTcpObfuscated` (obfuscated abridged MTProto). HTTPS CONNECT retains TLS to the proxy and uses the same obfuscated transport inside the tunnel. MTProxy retains its required randomized intermediate transport and secret handling. Route switches apply the same choices. Obfuscation changes packet framing; it does not hide the account or its client metadata from Telegram or imply immunity to restrictions. After connecting an authorized client, TgWitness checks config, nearest DC, the current authorization, the reviewed layer baseline, languages, app updates and terms-of-service updates. These diagnostics run once per client instance, before collection, and are shown under the connection details with their time. `account.connection_checked` records the result without session hashes, IPs, tokens or API hashes. They never accept terms or install updates. A request failure or FloodWait stops subsequent requests; a missing result stays unknown. Local checks can still report their results while network checks are skipped. With [strict chosen chats](https://phishdestroy.io/tgwitness/docs/reference/collection/#strict-chosen-chats) on, the current authorization is not requested and that check is shown as skipped. After sign-in and on each new connection, TgWitness reads the account's sensitive content setting. When it is off and Telegram allows the change, TgWitness turns it on so that content Telegram marks as sensitive (18+) is saved, and records `account.content_settings`. The setting belongs to the account and applies in every Telegram app. Strict chosen chats leaves it untouched; turn that on before signing in. Concurrent requests to restore one workspace's connection share its client and wait for its connection setup to finish. A failed or cancelled attempt releases the next request to retry. If the saved credentials, client or authorization state change during setup, the older attempt stops instead of reporting a ready connection. FloodWait diagnostics retain the failed TL method, any Takeout/range wrappers, the server-requested wait and the effective deadline in `telegram.backoff`. Connection details show the method and deadline while requests are paused. The diagnostic includes per-method client-call counters since that client was created; they count nested peer resolution separately, but do not count packets or Telethon's internal retry attempts. Current counters are also available as `collector.rpc_activity` in the status API. No request arguments, usernames, access hashes or exception text are included. The last diagnostic and full deadline survive restart. Earlier waits without a method record cannot be attributed retrospectively. See [export limits](https://github.com/phishdestroy/TgWitness/blob/main/docs/EXPORT-LIMITS.md) for the source review and the distinction between discovery and history acquisition. `official_app=True` or `False` is Telegram's current-authorization flag. Neither value establishes whether the account is restricted, trusted or under observation. The existing evidence-mode `account.devices` snapshots remain the history of all signed-in devices; connection diagnostics retain only the current device description. Before connection, advisory checks compare the API platform, language pack, device/OS and app-version formats, mobile system locale, and Telethon's actual schema layer against the reviewed catalog baseline. Warnings appear in the server log and account status metadata; they never replace imported values or change the schema layer. A different layer is a signal to review compatibility; the account's own connection status shows whether it works. Telegram decides restrictions on its side, whichever client profile is used. Disconnected account status uses the saved profile instead of generating another device description. To use your own application instead: 1. Open [my.telegram.org](https://my.telegram.org) and sign in with any phone number you own. The code arrives in the Telegram app, not by SMS. 2. Choose **API development tools**. 3. Create an application: any title and short name (5–32 letters), platform **Desktop**. URL and description can stay empty. 4. Copy **App api_id** (a number) and **App api_hash** (32 hexadecimal characters). In the panel, open **API ID + Hash** under the sign-in form. You can paste a single `api_id:api_hash` pair into **API ID** and both fields are filled. One pair can be used for all of your accounts. After a successful login it is saved, encrypted, in that workspace only and is never sent back to the browser. Three different credentials are involved: | Secret | Opens | Where it lives | | --- | --- | --- | | Panel token | The TgWitness web panel | `panel-token.txt` in the data directory, or `TGWITNESS_TOKEN` | | API ID + hash | Nothing by itself; identifies the app | Built-in pair, imported settings, or your own app at my.telegram.org | | Account authorization | The Telegram account | Created by phone/QR login or brought in as a session | If Telegram must be reached through a proxy, set it first under **More tools → Account → Settings → Connection settings → Change connection route**. ## Phone number 1. Open **More tools → Account**, tab **Phone**, and enter the number in international format, for example `+44 7700 900123`. Spaces and dashes are removed automatically. 2. Press **Continue**. API ID + Hash can stay empty. 3. Enter the code Telegram sends, usually to the Telegram app; Telegram decides whether to send SMS. 4. If the account has two-step verification, enter that password. It is not the panel token and not a device passcode. 5. Check the account ID shown after login, then choose sources. Login codes and the 2FA password are never written to disk. ## QR code Use this when the account is already signed in on a phone or another computer. 1. Tab **QR code** → **Show QR code**. API ID + Hash can stay empty. 2. On the signed-in device: **Settings → Devices → Link Desktop Device**, scan the code and confirm. 3. Enter the 2FA password in TgWitness if Telegram requests it. The QR image is generated locally. Codes expire; press **Generate another QR code** to retry. Locking the panel, switching workspace or starting another login cancels a pending code. ## Auth Key + DC ID An Auth Key is the raw 256-byte authorization behind every Telegram session, written as **512 hexadecimal characters**, together with the data-centre number **DC 1–5**. 1. Tab **Auth key**. Paste the complete key; a shortened key containing `…` cannot work. 2. Select the DC ID supplied with the key. 3. Optionally enter the **User ID**. TgWitness then refuses to connect if Telegram reports a different account. 4. Press **Connect account**. An Auth Key (512 characters) is not an API hash (32 characters). The same key can also be imported as JSON, see [Account JSON](https://phishdestroy.io/tgwitness/docs/reference/accounts/#account-json). ## Account files Open **Add account → Files** and select up to **four files belonging to one account**, **8 MiB** in total, press **Check files**, then **Connect account**. Choosing files or pasting session text sends nothing; **Check files** sends them to your TgWitness server, which reads them without signing in and shows the session it found. The **Files**, **Auth key** and bulk-import forms show the parallel-session warning before connecting. By default imported authorizations are reused. Keep the original client closed while its key is in use here. **Files** and **Auth key** also offer **Create an independent authorization**, described below. Bulk import still uses the direct mode. Phone and interactive QR login create separate authorizations. The warning heading stays visible in the import form; its full explanation opens automatically when files or a key/session string are supplied. It can be collapsed after reading, so the file picker and connection controls remain usable on a phone. An [attested deployment](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/) (Phala Cloud, Intel TDX) does not collect on an imported key. There, **Files** and **Auth key** connect only with **Create an independent authorization** selected; bulk import is refused. Phone and QR login work as usual. - Files are converted **in memory** on your TgWitness server. Uploads are not stored, ZIPs are not extracted to disk and no external service is contacted. - The resulting session is then checked with Telegram. If a file states a user ID, it must match the account Telegram reports. - Files that describe different accounts or different API credentials are rejected instead of picking one. - **Passcode or session text** holds the TData local passcode field, a box for pasting a StringSession and **Read files without signing in** (fills the form without contacting Telegram). Pasting a StringSession clears the selected files, and choosing files clears the pasted text, so the check and the connection use the latest choice. After a passcode change, press **Check files** again. ### Create an independent authorization Select **Create an independent authorization** before connecting imported files or an Auth Key. TgWitness connects the imported donor briefly, uses it to approve the new client's QR login token, and disconnects the donor immediately after approval. The new client has its own authorization key and a separately selected Desktop profile. The donor's supplied API credentials and device profile are used only for the donor connection. No existing authorization is logged out or revoked. **Keep the donor's original client fully closed during this step.** The initial connection still uses its copied key, so this mode cannot remove that initial parallel-use risk. Once the new authorization is connected, the owner can reopen the original client and use both at the same time. Interactive **QR code** login lets the original client approve the login without copying or connecting its key here. **Do not log out or end the donor session.** When the session that approved a QR login ends, Telegram also ends the session it approved; in a live check the new authorization stopped within a second of the donor logging out. The import records the donor session (`session_origin.approved_by`: device, API ID and creation time). The session list marks it, **End session** refuses it, and **End all other sessions** and **Make this the only session** leave it signed in. If Telegram requests 2FA, this mode uses `twoFA` from the selected JSON when present, or asks for the password. A rejected imported password returns to the password form. Passwords are not saved. The candidate key is saved encrypted in `independent_login.enc`, including changes during data-centre migration. After an interruption, select the same donor and this option to resume the saved candidate. The donor is checked with `help.getAppConfig` before the approval; a frozen account stops there. If Telegram refuses the donor before approving the login, the unapproved candidate key is discarded and the import can start again. Another donor replaces a saved candidate only when Telegram reports that candidate as not signed in; a candidate that is signed in or waiting for its 2FA password is kept. The workspace remains reserved for that account; failed completion does not delete the new workspace. Keep its data directory and vault key. The final credentials and `account.authorized` journal record include the import method, input formats and donor API ID, without the donor key or password. On 5 November 2026, a dedicated account passed live checks with Telethon, Pyrogram and TData donors: 2FA completion, distinct new authorization keys, concurrent access by the donor and new client, and reading a public channel. The Telethon case also resumed a saved candidate after an interruption at the password step. Each new authorization completed the six post-login initialization requests, and its signed journal verified. The original session remained usable in all four supplied formats. Telegram's [RPC error database](https://core.telegram.org/api/errors.json) associates `FRESH_CHANGE_ADMINS_FORBIDDEN` with changing admins, `FRESH_CHANGE_PHONE_FORBIDDEN` with changing the phone number, and `FRESH_RESET_AUTHORISATION_FORBIDDEN` with revoking other sessions, changing their lifetime or registering a passkey. `SESSION_TOO_FRESH_*` and `PASSWORD_TOO_FRESH_*` concern ownership transfers and revenue or gift withdrawals. These are not collection operations; a new login does not imply a blanket 24-hour reading ban. Export can separately return `TAKEOUT_INIT_DELAY_*`. TgWitness retains server-requested pauses and does not retry token acceptance automatically or revoke sessions to work around restrictions. **More tools → Account → Account security → Sessions of this account → End all other sessions** calls `auth.resetAuthorizations` on the operator's request and records `account.all_other_sessions_terminated` with the session counts before and after. Telegram accepts it from a session signed in for 24 hours. When this workspace signed in by QR from an imported session, the session that approved it stays signed in: TgWitness ends the others one by one with `account.resetAuthorization` and records `kept_approving_session`. **Make this the only session** then stops with that reason and changes no password. **Make this the only session** does the same for a key created by signing in from this workspace, then turns on a two-step password if the account has none. The panel shows that password once; TgWitness keeps it in the workspace vault only until then. The journal records `session.exclusive_from`. If Telegram later lists another session, the journal records `session.exclusive_ended` and the panel raises an alert. The verifier prints both. **Make this the only session when Telegram allows it** is the same action on a timer. The option appears under **Sessions of this account** for a key created in this workspace and is recorded as `session.exclusive_automatic`. While observing, the collector checks every five minutes whether 24 hours have passed since the `account.authorized` record of that key — Telegram answers `FRESH_RESET_AUTHORISATION_FORBIDDEN` before that — and then runs the same operation once. Success is recorded as `session.exclusive_from`, like the manual button. A refusal is recorded once as `session.exclusive_postponed` with Telegram's reason, and the collector retries with a growing delay of up to six hours. Read-only has no effect here: ending sessions is an account-security action, not a chat action. A two-step password generated by the automatic run is saved in the workspace vault, encrypted with the workspace key, before Telegram sets it. The panel fetches it once from `POST /api/account/sessions/only/password`, which deletes it, and shows it in the same dialog as the manual flow when you open **Sessions of this account**. The connection page notes that a password is waiting. It never enters the journal and survives a restart until it has been shown. New sessions are also reported while observing: when Telegram's session list gains an entry, the `account.sessions` record names it under `added` and the panel raises an alert with the device, application and country from that snapshot. ### Witness probe **More tools → Account → Account security → Witness probe** checks whether another client receives this account's updates. Add a second workspace signed in with a different Telegram account and its own session key, create a private group with both accounts, then choose that group as **Probe chat** and the second workspace as **Witness workspace** and turn the probe on. Both accounts need **Read-only** off, and the witness workspace must be observing. While observing, this workspace sends `probe::` into the group every 60–120 seconds and records `probe.sent`. The witness answers `ack::` and records `probe.seen` and `probe.ack_sent`. An ack that reaches this session as a live update within 20 seconds is recorded as `probe.acked`. Otherwise the workspace reads the group's recent history. An ack found there but not delivered live is recorded as `coverage.gap` with reason `probe_ack_missed_live`: the panel raises an alert and marks event intake as failed until a later ack arrives live (`connection.restored`, reason `probe_ack_live`). No ack is recorded as `probe.unanswered`; a connection interruption during the wait or an unreadable history as `probe.inconclusive`. Read-only, Telegram restrictions and FloodWait pauses are recorded once as `probe.skipped`. ### Telethon `.session` | | | | --- | --- | | What it is | The SQLite database Telethon-based tools create, for example `my_account.session` | | Recognised by | Tables `sessions` (with `dc_id`, `server_address`, `port`, `auth_key`) and `version` = 7 or 8 | | Requirements | Exactly one authorized session row; a closed, complete database | Close the program that created the file first. If `my_account.session-journal` or `my_account.session-wal` exists next to it, the database is not finalised: open and close the original client cleanly. Deleting those sidecar files can leave a broken copy. ### Pyrogram `.session` | | | | --- | --- | | What it is | The SQLite database Pyrogram-based tools create | | Recognised by | Table `sessions` with `dc_id`, `auth_key`, `test_mode`, `user_id`, `is_bot`; `version` = 2 or 3 | | Requirements | One authorized **user** session on the production network. Bot and test-DC sessions are rejected | The stored user ID is checked against Telegram during login. ### Session + JSON pair Accounts are often distributed as two files with the same name, for example `447700900123.session` and `447700900123.json`. Select **both** at once. - From the JSON, TgWitness uses `app_id`/`api_id` and `app_hash`/`api_hash`, so you usually do not have to type API credentials. - The connection profile uses `device_model` (alias `device`), `system_version` (alias `sdk`), `app_version`, `lang_code`, `system_lang_code` (alias `system_lang_pack`), `lang_pack` and optional `tz_offset` (seconds from UTC, -43200 to 50400). Supplied fields take priority over generated defaults and the panel/browser language. Conflicting aliases are rejected. The resolved profile is saved in the encrypted workspace credentials and reused after restart, including its app version. - `phone`, proxy settings and device tokens are **ignored**. `twoFA` is read only when **Create an independent authorization** is selected; direct import ignores it. - A JSON without a supported authorization field is only metadata. Add its session file or continue with phone or QR login. A JSON containing a supported session or Auth Key can authorize on its own; see [Account JSON](https://phishdestroy.io/tgwitness/docs/reference/accounts/#account-json). ### Telegram Desktop (TData) TData is the `tdata` folder of the Telegram Desktop application (the cross-platform app from desktop.telegram.org). | System | Default `tdata` location | | --- | --- | | Windows | `%APPDATA%\Telegram Desktop\tdata` (portable Telegram: next to `Telegram.exe`) | | Linux | `~/.local/share/TelegramDesktop/tdata` | | macOS | `~/Library/Application Support/Telegram Desktop/tdata` | To import it: > **Parallel session warning.** Direct TData import reuses Telegram Desktop's authorization key. Do not use that key in Desktop and TgWitness simultaneously. Telegram can invalidate the authorization with `AUTH_KEY_DUPLICATED`, leaving both copies unusable until a new login. > > > > Fully quit Desktop, including its tray process, and keep that copy closed while TgWitness uses the imported session. **Quit, do not log out or revoke the session:** revocation also invalidates the imported copy. If you need both clients running, select **Create an independent authorization** and keep Desktop closed until the new login succeeds, or sign in to TgWitness by phone or QR. A dedicated account is recommended, but does not make cloned keys safe to use in parallel. > > > > This also applies to imported `.session` files, StringSession text and Auth Key HEX. Other clients with their own independently created authorizations can remain signed in. See [Telegram's AUTH_KEY_DUPLICATED documentation](https://core.telegram.org/api/errors#406-not-acceptable). 1. Fully quit Telegram Desktop. 2. Create a ZIP containing **only** these two items from `tdata`: - `key_datas` - the 16-character file ending in `s` next to it, usually `D877F783D5D3EF8Cs` Zipping the whole folder with its media cache usually exceeds the limits (512 entries, 32 MiB unpacked). 3. Select the ZIP in **Files**. If Telegram Desktop has a **local passcode**, enter it under **Passcode or session text** first. This is not the 2FA password. Supported: one account per archive, modern `key_datas`/`key_data0`/`key_data1` storage, local passcode. Not supported: folders with several logged-in accounts, older Desktop layouts, password-protected ZIPs, and the separate native macOS app "Telegram for macOS". ### Telethon StringSession A single line of text, usually starting with `1` and about 350 characters long. Load it as a `.txt` or `.tgwitness-session` file (at most 4 KiB), or paste it under **Passcode or session text**. Only Telethon strings are accepted; Pyrogram and TDLib strings use different formats. ### Auth key and DC in one line Account lists often carry the raw authorization as `<512 hexadecimal characters>:`, for example `a1b2…ef:5`. Paste that line under **Passcode or session text**, load it as a text file, or put it in the `session` field of an [Account JSON](https://phishdestroy.io/tgwitness/docs/reference/accounts/#account-json). TgWitness maps DC 1–5 to the same production addresses as the `auth_key` + `dc_id` JSON import and reports the format as **Auth key HEX and DC**. Any other DC number or key length is rejected. ### Account JSON One JSON object, at most **64 KiB**, in a file ending in **`.json`**. | Field (aliases) | Meaning | | --- | --- | | `api_id` (`app_id`) | Application ID, a positive number | | `api_hash` (`app_hash`) | Application hash, 32 hexadecimal characters | | `string_session` (`session_string`, `session_str`; legacy `session`) | Telethon StringSession text, or `<512 hexadecimal characters>:`, not a file name | | `auth_key` (`auth_key_hex`) + `dc_id` | Complete 512-character Auth Key and DC 1–5 | | `user_id` (`id`) | Optional; checked against Telegram before the authorization is saved | | `device_model` (`device`) | Connection device description | | `system_version` (`sdk`) | Connection OS version | | `app_version` | Application version sent to Telegram | | `lang_code`, `system_lang_code` (`system_lang_pack`), `lang_pack` | Client language, system language and client language pack; an empty `lang_pack` is allowed | | `tz_offset` | Optional UTC offset in seconds, sent in `initConnection.params`; integer or decimal integer string | If both an alias and the main name are present, they must agree. Explicit Telethon session fields take priority over a generic `session` blob in another format. If both contain recognizable Telethon sessions, they must describe the same authorization. Without an explicit field, `session` must be a valid Telethon StringSession or an auth key and DC in `<512 hexadecimal characters>:` form. Examples: ``` { "app_id": 1234567, "app_hash": "0123456789abcdef0123456789abcdef" } ``` ``` { "api_id": 1234567, "api_hash": "0123456789abcdef0123456789abcdef", "auth_key": "REPLACE_WITH_ALL_512_HEXADECIMAL_CHARACTERS", "dc_id": 2, "user_id": 123456789 } ``` The first example only fills API credentials; sign in by phone or QR, or add a session file. Bulk lists (a JSON array of accounts) are not accepted. ## Identify what you have | You see | It is | Use | | --- | --- | --- | | `*.session`; opening it in a text editor shows `SQLite format 3` at the top | Telethon or Pyrogram SQLite | **Files** (detected automatically) | | A `tdata` folder containing `key_datas` | Telegram Desktop TData | ZIP two files, then **Files** | | One text line starting with `1`, ~350 characters | Telethon StringSession | **Files** | | One text line `512 characters 0-9a-f`, then `:` and a digit 1–5 | Auth key and DC | **Files**, box **Passcode or session text** | | `*.json` with `app_id`/`app_hash` | Companion metadata | **Files**, together with its session | | `*.json` with `auth_key` or `string_session` | Account JSON | **Files** | | 512 characters `0-9a-f` | Auth Key | **Auth key** | | 32 characters `0-9a-f` | API hash | **API ID + Hash** | | `td.binlog` or a `db.sqlite` from a TDLib app | TDLib storage | Not supported | | `123456789:AA…` | Bot token | Not supported | ## Unsupported formats | Format | Alternative | | --- | --- | | TDLib storage (`td.binlog`) and TDLib exports | Sign in by phone or QR | | Pyrogram session **strings** | Use the Pyrogram `.session` file, or phone/QR | | TData with several logged-in accounts | Log out the other accounts in Telegram Desktop, or use each account's own session file | | Bot tokens | Not supported: TgWitness observes as a user account | | CSV/JSON lists of many accounts | Import supported session files through **Accounts → Import accounts**, or sign in by phone/QR in separate workspaces | | Test-DC or bot sessions | Use a production user account | ## Multiple accounts Press **+** beside the account selector, or open **More tools → Account → Settings → Connection settings → Workspaces**, enter a label and sign in. - Any number of workspaces, including the main one. Each has its own session, proxy route, sources, capture policy, journal, signing key, checkpoints and exports. - Switching the displayed workspace does not pause the others. - A journal stays bound to the account that created it. Signing in as a different account requires another workspace, and one account cannot be assigned to two workspaces. - The main panel token controls all workspaces. [Issued access](https://phishdestroy.io/tgwitness/docs/reference/access/) can restrict other people to selected accounts and chats, with separate permissions and session limits. - **Accounts** renames a workspace and deletes an added one, with its session, journal, sources and signing key. The main workspace cannot be deleted from the panel. ### Bulk import and account groups Use **Accounts → Import accounts** to add several accounts, pair files by basename and see each login result. Each account gets its own workspace. A group keeps related accounts together without merging their sessions, keys or evidence. **Open group** on **Accounts** leads to its page at `/groups/`: - **Accounts:** each member's connection route, observation and last message, with **Start all** and **Pause all**. - **Needs attention:** accounts that were signed out, are unavailable or have a connection, intake, source or media problem; each name leads to its card. - **Chats several accounts see:** shared sources, the accounts observing them and interruptions in the available workspace-observation period (up to seven days). **Export with N accounts** splits a channel or supergroup export between them and signs one archive. - **Export group:** one ZIP with each account's signed export under `accounts/` and `manifest.json` listing their SHA-256 and key fingerprints, signed by the main workspace in `manifest.signature.json`. Verify each account archive on its own with `python -m tgwitness.verify` and that account's trusted fingerprint. Members share the group's settings; an account can keep its own values. See [shared settings](https://phishdestroy.io/tgwitness/docs/reference/settings/#account-groups), [the import and groups guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Accounts.md#import-accounts-and-share-settings) and [the MTProxy pool dashboard](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Proxies.md#pool-dashboard-and-custom-sources). ## Sign out **More tools → Account → Sign out of Telegram** (with observation paused) asks Telegram to end the session, so it also disappears from the account's **Settings → Devices**, and removes the session from the workspace vault. The journal, sources, settings and signing key stay, and the journal records the sign-out. The workspace still belongs to its account: only that account can connect to it again. If Telegram does not answer, the session is still removed here and the panel says so; end it in Telegram under **Settings → Devices**. ## When Telegram ends the session If Telegram bans, freezes or signs out the account, or ends the session from another device, the journal records the cause, the Telegram error, the route and the data centre. The account's health shows **Download the account loss report**: a signed JSON file with the journal records of the 24 hours before the loss, namely connections, routes, sessions, account notices and coverage gaps, each with its journal hash and signature. Check it with `python verify.py tgwitness-account-loss.json --fingerprint COLLECTOR_FP`; the evidence export holds the complete hash chain. A frozen account is also detected when it connects and while observing, and its sending and joining actions are turned off. ## Keeping account files safe - Treat every `.session`, TData ZIP, StringSession, Auth Key and account JSON like a password. TgWitness keeps the imported authorization in its encrypted vault; you can remove the original files afterwards. - Do not run the same authorization in two programs at once. Telegram may revoke it (`AUTH_KEY_DUPLICATED`), and both copies stop working. - An expired or revoked session cannot be revived by conversion. Sign in again. ## Troubleshooting | Message or symptom | What to do | | --- | --- | | *Cannot read this session. Close its original client…* | The SQLite file is open or unfinished (`-journal`/`-wal` sidecar). Close the original program cleanly and copy the file again. | | *Supported Telethon SQLite schemas: 7 and 8* / *Pyrogram … 2 and 3* | A very old or unknown library version created the file. Sign in by phone/QR instead. | | *Only authorized production user sessions are supported* | The Pyrogram file belongs to a bot or the test network. | | *TData archive exceeds 512 entries or 32 MiB* | ZIP only `key_datas` and `D877F783D5D3EF8Cs`, not the whole folder. | | *Cannot decrypt TData. Check the Desktop local passcode* | Enter the Telegram Desktop local passcode under **Passcode or session text**. | | *Import one TData account at a time* | Telegram Desktop had several accounts; see [Unsupported formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/#unsupported-formats). | | *Selected files describe different accounts or API credentials* | Select files of one account only. | | *JSON contains no supported API credentials or authorization* | Check the field names in [Account JSON](https://phishdestroy.io/tgwitness/docs/reference/accounts/#account-json). | | *API metadata only* | The JSON has no session. Add the `.session` file or use phone/QR. | | *Auth Key HEX must contain all 512 hexadecimal characters* | The key is truncated or contains `…`. | | Account ID does not match the imported account | The file's user ID differs from what Telegram reports; the file is for another account. | | Account already belongs to another workspace | Open that workspace instead of adding the account twice. | | Connected, but a private group is missing from the chat list in **More tools → Sources** | Check membership. The picker inspects the first 1,000 dialogs; raise the limit under **More tools → Parameters**. | | Proxy connection fails | Check the route and IP mode. Automatic MTProxy tries another working entry. Hide the address waits; Direct as a last resort can connect directly after its configured delay. See [routing modes](https://phishdestroy.io/tgwitness/docs/reference/connection/#ip-modes). | See also: [connection and security](https://phishdestroy.io/tgwitness/docs/reference/connection/) for proxies and encryption, and [how collection works](https://phishdestroy.io/tgwitness/docs/reference/collection/) for what is captured after sign-in. --- # TgWitness Access Tokens, Scopes & Permissions Canonical page: https://phishdestroy.io/tgwitness/docs/reference/access/ Configure scoped access to Telegram workspaces and chats in TgWitness. Review permissions, token expiry, IP restrictions, session limits and revocation. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Issue scoped access to accounts and chats, choose permissions, limit sessions and IP addresses, and withdraw access. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Getting started](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) ![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2) Give a reviewer access to one chat, an analyst permission to export a case, or an operator control of selected accounts. Each person gets their own token. The main panel token stays with the administrator. [Account setup](https://phishdestroy.io/tgwitness/docs/reference/accounts/) · [Connection routes](https://phishdestroy.io/tgwitness/docs/reference/connection/) · [Security model](https://phishdestroy.io/tgwitness/docs/reference/security/) ## Two scopes, two different jobs **Collection scope** decides what an account records: selected chats, a Telegram folder or the whole account. **Access scope** decides which of those recorded accounts and chats another person can see and use. Giving access does not join a Telegram chat, start collection or grant Telegram account permissions. An access can open selected workspaces, selected chats within them, all workspaces, or every account of an [account group](https://phishdestroy.io/tgwitness/docs/reference/accounts/#bulk-import-and-account-groups). **All workspaces, including ones added later** also covers future accounts. A group access also covers accounts added to that group later. Select workspaces explicitly when a case should stay limited to them. ## Give someone access 1. Sign in as the main administrator and open **More tools → Access**. 2. Under **Give someone access**, enter a name you will recognize in the log. 3. Choose the workspaces and, where needed, the individual chats. 4. Select what this person may do. **View** is always included. 5. Set the expiry, sign-in/session limits and allowed addresses as needed. 6. Press **Create access**. Copy the token now: it is shown only once. 7. Send the panel address and token privately. The recipient enters that token on the normal sign-in page; they do not need your main panel token or a Telegram session. Open the panel with the issued token in a separate browser session and check the visible chats and permitted actions before handing it over. Access names remain in encrypted local storage and are resolved by the administrator's panel. Names are omitted from new access and workspace-creation audit records; existing signed records keep their original fields. ## Choose the permissions For a text-only public demonstration, use **Public showcase** instead of ordinary reviewer access. It shows explicitly selected public channels, retained edits and deletions, and signed statistics, with author fields redacted and files closed at the API boundary. [Create and verify a showcase](https://phishdestroy.io/tgwitness/docs/reference/showcase/). | Permission | What it allows | | --- | --- | | `view` | Read permitted chats, captured messages, profiles, files and filtered journal records. Always included. | | `export` | Export permitted chat history and dossiers. Whole-workspace evidence exports require access to the whole workspace. | | `sources` | Manage sources, snapshots and profile capture. Chat-limited access can act only on allowed chats; account-wide source discovery and scope settings stay closed. | | `collect` | Start or stop a collector. Requires whole-workspace access because collection affects the account. | | `interact` | Perform supported Telegram interactions within the access scope. Chat-limited access cannot use account-wide link previews. | | `settings` | Change collection settings, timestamps, notifications, off-site copies and parameters. Requires whole-workspace access. | | `account` | Sign in or out of Telegram and manage connection routes. Requires whole-workspace access. | | `board.read` | Read Case Board notes only within the permitted workspace and chats. | | `board.write` | Add bookmarks, highlights, slices, comments and open/review statuses. Also needs `board.read`. | | `board.manage` | Manage collections, final team statuses and other participants' cards. Also needs board read/write. | Only the main administrator can download the off-site replica recovery key. Delegated `settings` or `account` access does not grant that key. Permissions and scope are checked together. Ticking a permission does not open other chats or unlock a workspace-wide operation for a chat-limited access. For a parallel export, the access must cover the exported chat in every selected account. An issued access cannot create new accesses, manage other people's sessions or open the administrator console. ### Three useful setups | Person | Scope | Permissions | | --- | --- | --- | | Reviewer | One case's recorded chats | `view` | | Analyst preparing a handover | The chats to investigate and export | `view`, `export`; add `interact` only if they should act through Telegram | | Collection operator | Selected whole workspaces | `view`, `sources`, `collect`; add `settings` or `account` only when needed | The Access form's starting presets also include Case Board: Reviewer can read, Analyst can read and write, and Operator can manage it. Presets remain editable, and existing grants are not automatically expanded. See [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/) for inherited chat scopes and export privacy. ## Limits and sessions | Setting | How it works | | --- | --- | | Parallel sessions | Limit simultaneous sessions to 1–100. At the limit, refuse the next sign-in or end the oldest session. | | Sign-ins allowed | Limit successful uses of the token to start sessions. Existing sessions are not ended just because the last allowed sign-in was used. | | Valid until | An absolute expiry for the access. Expired access cannot sign in or keep making requests. | | Minutes without activity | Session inactivity timeout, from 5 minutes to 30 days. Successful requests extend it; an open panel may keep itself active by polling. | | Allowed addresses | Accept specific IP addresses or CIDR subnets. Leave empty to allow any address unless first-sign-in binding is enabled. | | Bind to the first sign-in | The first successful sign-in fixes the permitted address for that access. | The IP is the client address seen by the application. Behind a reverse proxy or tunnel, check the address shown in **Open sessions** before relying on IP rules: several users may otherwise appear to share the proxy's address. ## Change or withdraw access Edit an entry under **Granted access** to change its scope, permissions or limits. Scope and permission changes are checked on subsequent requests, including requests from sessions that are already open. Revoking an access ends its sessions and makes the issued token unusable. **Open sessions** also lets the administrator end an individual session without revoking the whole access. Saved export copies retain their creator, workspace, chat scope and required permissions. An issued access can list or download its own copies only while those permissions still apply; copies containing Case Board also require `board.read`. The administrator can retrieve all copies. Older copies without this metadata and group bundles are administrator-only. Download tickets and prepared file responses recheck access after preparing the file, before sending its bytes. Each access, including the administrator, can hold ten pending download tickets per workspace; the workspace-wide limit is 1,000. Tickets expire after 120 seconds and are single-use. Revocation cannot recall files that someone already downloaded. Signing out, locking the panel or ending a session does not stop a running collector. ## What the administrator can see Reviewers and analysts receive collection progress without proxy endpoints, pool diagnostics, server paths or raw connection errors. Connection diagnostics require `account` permission over the whole workspace. Reading notification, off-site-copy and parameter settings requires `settings` permission. Full browser User-Agent strings are not retained in access sessions. An upgrade also removes them from the mutable session cache. The panel process log masks IP literals, URL credentials and labelled secrets. Local service logs and previously signed journal records are not rewritten. Access rules and signed sign-in records still use the client address. ### Replace the main key Use **More tools → Access → My limits → Reissue administrator key**, or run `tgwitness token rotate` from a managed installation while the panel is running. All existing browser sessions end, including sessions opened with colleague tokens. The requesting browser receives a new session; save the new administrator key before hiding it. Issued colleague tokens remain valid until separately revoked. An installation using `TGWITNESS_TOKEN` must change that environment setting and restart. ### Request and proxy boundaries The API admits up to 600 requests per minute per client and credential family: panel, archive/MCP or witness. Authentication cooldowns are separate for these families. Ten rejected authentications within a minute start an exponential cooldown, from one second up to five minutes. A failed attempt after the cooldown increases it; ten minutes without a failed attempt resets escalation. Rejections return HTTP 429 and `Retry-After`. Limits are in memory, shared across workspaces in one panel process; restart clears them. Live streams are limited to four per bearer token and 32 for the panel process. Opening a stream also consumes the API request budget. Request bodies have a 60-second receive deadline, reduced to 10 seconds for login, demo access, archive API and witness-head paths, or 8 seconds for MCP transport. Each application permits four unfinished bodies per client address, with overall limits of 32 and 64 MiB of reserved route allowances. Requests without bodies do not consume these slots. Oversized bodies return 413, timed-out bodies return 408, and exceeded client capacity returns 429 with `Retry-After: 1`. Exhausted overall body capacity returns 503 with `Retry-After`. Forwarded IP headers are ignored unless the actual TCP peer belongs to `TGWITNESS_TRUSTED_PROXIES` (comma-separated IPs or CIDRs). Set `TGWITNESS_PROXY_HEADER` to `x-forwarded-for` or `cf-connecting-ip`. XFF is walked from the nearest proxy toward the first untrusted peer. Malformed or duplicate trusted address metadata is rejected, so it cannot inherit an allowlisted proxy address. The managed quick tunnel trusts the local cloudflared connector; the own-domain setup trusts local Caddy. Direct deployments trust no proxy by default. If launching Uvicorn yourself, disable its proxy-header processing so this boundary receives the actual peer. `TGWITNESS_PANEL_ALLOWED_IPS` restricts all panel access, including the administrator, to listed IPs or CIDRs. The installer routing-identity probe stays public and returns no account data. Include the required local administrative route before enabling the allowlist. A managed installation's **START-HERE** guide includes the service configuration and recovery instructions. An API `ws` query selector must identify the workspace in the request path; unknown, mismatching and duplicate selectors are rejected with 404. Panel scripts and styles carry SHA-384 integrity metadata. An import map also covers locally imported JS modules in browsers that support import-map integrity. The dynamically generated language response is separate. These checks detect asset substitution relative to the delivered page; the page itself and its hashes come from the panel server, so protect that server and its delivery path. **Log since this start** combines process logs with journal activity from every workspace: sign-ins, refusals, route changes and operator actions. It is an in-memory console for the current process, not a permanent copy of every message. Frequent message events stay in the journal rather than filling the console. Issuing, changing and revoking access, and starting or ending sessions, also create signed `access.*` journal records. Tokens are not included in those records. Issued tokens and session credentials are retained as hashes in the encrypted vault. A pending QR sign-in belongs to the panel session that started it. Ending or revoking that session, or rotating the main panel token, cancels its pending QR client on the server. This also applies when the browser cannot send its own cancellation request. Token rotation also cancels QR sign-ins started directly with the main panel token. A QR request waiting for another operation checks access again before it starts. Completed Telegram authorizations and pending sign-ins started by another panel session are preserved. ****Main administrator and trust boundary**** The main panel token remains unrestricted. Browser sign-ins with it create sessions subject to the administrator's configured session limits. Scripts sending the main token directly retain full access and are not counted as browser sessions. This is application-level access control in one installation. All workspaces share the server process; this is not isolation from the host administrator. Keep the main token, Telegram sessions, signing keys and data directory private. A witness token is a separate checkpoint/health credential, not a panel access token. --- # Telegram Proxy Routing & Connection Security Canonical page: https://phishdestroy.io/tgwitness/docs/reference/connection/ Understand TgWitness proxy pools, IP modes, fallback policy and external-request routing. Review authentication and protection of stored connection secrets. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Authentication, automatic proxy pools, IP modes, fallback policy, external requests and secret storage. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Deployment and recovery](https://phishdestroy.io/tgwitness/docs/reference/deployment/) ![Deployment & recovery](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f) This document describes TgWitness 0.9.3 behavior and its limits. Authentication, source access, network connectivity and capture completeness are separate states. For sign-in steps, file formats, and multiple accounts, start with [accounts and session formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/). For event policies and restart behavior, see [how collection works](https://phishdestroy.io/tgwitness/docs/reference/collection/). ## Guided connection setup In **More tools → Account → Connection route**, the administrator can choose **This account**, **An account group** or **All accounts**, then select a route. **Review selection** lists the affected accounts. **Prepare and check** tests the proposed route without changing the saved one. **Apply checked connection** validates the preview, pauses observation if necessary, saves the route and resumes observation that was already running. It never starts collection in a previously idle account. History downloads remain paused and can be resumed separately. Pause active exports before switching. Group changes keep accounts with their own route by default. Clear that option only when the preview lists the changes you intend. Application reports each account's result; it is not an all-or-nothing transaction across databases. A failed switch restores that account's previous settings. A failure to resume is shown explicitly. Previews expire after ten minutes and changes to connection settings or group membership require a new check. Apply reuses a successful preflight result for up to 90 seconds when its route, mode and policy are unchanged. A managed tunnel must still have the same running process. Older results, changed tunnel processes and automatic MTProxy pool routes are checked again. The signed application record retains the original check time and records reuse and its age. Each preflight closes its temporary unauthenticated client; the collector connects using its own authorized session. | Route | What TgWitness manages | | --- | --- | | Direct | Connections from the host; an external host VPN is not detected or enforced. | | VPN | One full-tunnel WireGuard profile per account, carried by a local userspace SOCKS5 process. No host interface or driver is installed. | | My proxy | SOCKS5, HTTP CONNECT or MTProxy credentials. A URL can fill the SOCKS5/HTTP fields. Selecting several accounts shares this entered proxy. | | Public MTProto | The existing pool assigns Telegram routes. External requests are disabled until a separate suitable proxy is configured in the advanced settings. | | WARP | A separate local tunnel for each selected account, with WARP registration and a WireGuard profile kept in that account's vault. | The current-route check uses a fresh unauthenticated Telegram transport, not the account's session. It opens a transport connection through the route to the account's data center and makes one unauthenticated MTProto round trip (`req_pq_multi`); it creates no authorization key and uses no account. The reported latency is that connection time plus the round trip, and the check records both parts separately. For HTTP-capable routes it also requests Cloudflare's HTTPS trace through that route and displays its reported exit IP, country, WARP state and check time. WARP preparation fails unless the trace reports WARP active. These preflight checks report route connectivity and the observed exit. Review captured records through the archive's acquisition and verification results. A running local process alone is not a successful exit check. The panel keeps a moving average of the last five checks. A route is **slow** when the average exceeds 5 seconds or three checks in a row exceed it, and **unavailable** after two failed checks in a row; `network.slow_route` and `network.route_recovered` record the changes. For a slow WARP route, **Re-roll WARP** restarts the account's tunnel against other Cloudflare WARP endpoints, keeps the fastest and records `network.warp_rerolled` with the times before and after; **New WARP identity** registers a new WARP device and keeps it only when it is faster. The local proxy address, the Telegram account and its session stay the same; Telegram connections reconnect through the restarted tunnel. A slow WARP route is re-rolled automatically at most once every 30 minutes; when that does not help, further re-rolls wait for the operator. ### Portable WARP and WireGuard This is an **unofficial WARP integration** using [wgcf 2.3.1](https://github.com/ViRb3/wgcf/releases/tag/v2.3.1) and [wireproxy 1.1.3](https://github.com/windtf/wireproxy/releases/tag/v1.1.3). The administrator explicitly accepts setup before the first download or WARP registration. Those setup connections go directly to GitHub and Cloudflare and reveal the machine's IP. Ordinary account traffic keeps its existing route until application. Cloudflare chooses the exit address and country; separate tunnels can share an exit address. Country selection, periodic IP rotation and a host-wide VPN kill switch are not provided by this feature. Supported helper downloads: Linux and macOS x86-64/ARM64, and Windows x86-64. Artifacts are checked against SHA-256 hashes bundled in the reviewed source, and cached executables are checked again before launch. No helper is added to PATH, installed as a system service, or given a public listener. All files live under the workspace's `portable-routes/` directory and encrypted vault entries. The loopback SOCKS5 listener requires independently generated credentials. Private profiles and WARP account credentials are encrypted with the existing workspace vault. While running, the helper needs an owner-only plaintext config; it is removed on a normal stop. A host crash can leave this file behind in the owner-only data folder. This does not encrypt the disk or protect against its administrator. The supervisor closes the tunnel if the panel's parent pipe disappears. A failed tunnel never enables a direct fallback. Panel restart restores a selected tunnel; failed starts retry with a bounded delay. **Stop tunnel** also pauses observation and persists the stopped state. **Start tunnel** starts the tunnel; resume observation separately when ready. Uploaded WireGuard profiles must contain one Interface and one Peer, full IPv4 and IPv6 routes, and no hooks, includes, environment substitutions or extra listeners. Public endpoint addresses are resolved and pinned before startup. Use an external VPN or SOCKS5 gateway for OpenVPN/IPsec and private endpoints. ## Authentication methods **API ID and API hash identify an application; they do not replace account login.** They are optional in TgWitness. Precedence: a pair entered in the form, then one from an imported account JSON, then the pair saved in the workspace, then the built-in pool of 50 public pairs, tried in random order with automatic rotation when Telegram refuses one. Only the Telegram Desktop pair (2040) is sent with a matching Telegram Desktop client description. Your own pair from API Development Tools at [my.telegram.org](https://my.telegram.org) can be used with all of your accounts; each account still has its own authorization. | Method | Requirements | TgWitness support | | --- | --- | --- | | Phone, code, optional 2FA | Account access; API pair optional | Panel login | | Auth Key HEX + DC ID | Full 512-character key and DC 1–5 | Direct **Auth key** tab; optional User ID checked before authorization is saved | | Telethon StringSession | A valid session string | Panel login | | Telethon SQLite `.session` | Closed, consistent copy | Direct panel import of schemas 7/8; optional offline CLI | | Pyrogram SQLite `.session` | Closed production user session | Direct panel import of schemas 2/3 | | Telegram Desktop TData ZIP | One modern account; local passcode if protected | In-memory conversion with checksum/decryption checks | | Account JSON | Supported API/session/key fields | Metadata alone fills API credentials; a session/key or phone/QR login is still needed | | QR login | Confirmation from an authorized Telegram app | Local QR generation, expiry/retry, optional 2FA | | TDLib / Pyrogram StringSession | Other library-specific formats | Unsupported | | Bot token | A bot with its own access/update model | Not used by this collector | Telegram chooses code delivery, including whether to send SMS. An API hash cannot repair a revoked session or replace a forgotten 2FA password. TgWitness does not persist login codes or the Telegram 2FA password to disk. For a private source, the account must already have access. A group username is unnecessary. A proxy or session import grants neither membership nor administrator rights. The chat's settings decide whether members see history from before they joined. ## Import a Telethon session file Telethon SQLite, Pyrogram SQLite, and Telegram Desktop TData use different formats. The panel detects and converts the supported structures; renaming a file is not conversion. Select one session and its companion JSON under **Files**, press **Check files**, then **Connect account**. Up to four matching files and 8 MiB total are accepted. See [format limits](https://phishdestroy.io/tgwitness/docs/reference/accounts/) for TData/JSON details. There is no passcode recovery. Phone/2FA or QR login creates a separate authorization. The optional Telethon-only command-line path remains available: 1. Stop the client using the original session and make a consistent copy. The converter rejects files with an unfinished WAL/journal. Close the original client properly instead of deleting those files to bypass the check. 2. From the TgWitness environment, run: ``` python -m tgwitness.sessions account.session --out account.tgwitness-session ``` 1. Under **Add account → Files**, load the result or paste its string, and continue. 2. Check the displayed numeric account ID, select sources and start observation. **The converted file is an unencrypted account-access secret.** Keep it in protected storage and never commit it or send it to a third-party conversion service. TgWitness saves the authorized session in its encrypted vault. Copying a session does not create a separate authorization: do not run concurrent clients with cloned auth keys and assume independent update delivery. Conversion transfers authorization, not original messages, the entity cache or a durable update cursor. It does not fix update recovery across process restarts. ## MTProto, Telethon and proxies MTProto is Telegram's protocol. Telethon is the Python client library TgWitness uses. MTProxy is a Telegram transport proxy; SOCKS5 and HTTP CONNECT provide general tunnels. None replaces account authentication. Save the route for each workspace in **More tools → Account → Settings → Connection settings → Change connection route** before signing in. New workspaces default to **Automatic MTProxy · public lists** with **Hide the address**. Existing workspaces that explicitly used Direct retain a mode permitting it. Files are read over separate connections from the one that reads messages, as the official apps do. In the account's own data center they reuse the account's authorization key with a new MTProto session; for another data center one key is created and authorized while the account is connected and is kept only in memory. Every file connection uses the same route as the account. Their number per data center is limited by **Parameters → Performance → File connections per Telegram data center**; 0 reads files over the account's main connection only. At most five Telegram connections are set up at once across all accounts of an installation. ## IP modes The route chooses the connection. The IP mode, **IP protection** in the panel's Account section, determines when the server's address may be exposed. These controls do not install a VPN or route all machine traffic. | Mode | Telegram | External requests | | --- | --- | --- | | Hide the address (`hide`) | Use a proxy; wait if none works. No direct fallback. | Require SOCKS5/HTTP; refuse requests without an applicable proxy. | | Direct as a last resort (`fallback`) | Automatic MTProxy may use Direct after the configured delay, then return to a working proxy. | Prefer a configured external proxy or the account's SOCKS5/HTTP route; otherwise Direct is allowed. | | Server behind a tunnel or VPN (`tunnel`) | Direct routes and immediate automatic-pool fallback are permitted. | Direct is permitted when no applicable proxy is configured. | The tunnel or VPN mode assumes you manage that network separately. Without a working tunnel, destinations can see the server's own address. Select the mode according to your actual network, not the name of the option. ### Choose a route | Route | Settings | Boundary | | --- | --- | --- | | Automatic MTProxy | Built-in lists or an operator catalog | Maintains a working Telegram route; direct fallback depends on the IP mode | | Direct | Tunnel or VPN mode | Telethon uses the host's network route | | SOCKS5 | Host, port, optional username/password | python-socks, remote destination DNS enabled | | HTTP CONNECT | Host, port, optional username/password | Plain HTTP CONNECT; TLS to the proxy itself is not implemented | | MTProxy | Host, port, secret | Experimental Telethon transport; 32 hex digits or `dd` + 32 hex digits | Fake TLS `ee` secrets are rejected. Telethon 1.45's normalization can strip a prefix and domain, but that does not implement Fake TLS. Paste `tg://proxy?server=…&port=…&secret=…` or `https://t.me/proxy?server=…&port=…&secret=…` and choose **Fill fields from link**. This validates and fills the fields without connecting or saving; review and save the route separately. Manual fields remain available. See [Telegram proxy links](https://core.telegram.org/api/links#proxy-links). ### Public proxies supplied by your installation The built-in list combines seven sources: [SoliSpirit/mtproto](https://github.com/SoliSpirit/mtproto), [zakky8/mtproto-proxy-pro](https://github.com/zakky8/mtproto-proxy-pro), [kort0881/telegram-proxy-collector](https://github.com/kort0881/telegram-proxy-collector), [3yed-61/MTP-Collector](https://github.com/3yed-61/MTP-Collector), [Therealwh/MTPproxyLIST](https://github.com/Therealwh/MTPproxyLIST), [KhodeJav/telegram-proxy-collector](https://github.com/KhodeJav/telegram-proxy-collector) and [tgmtproxy/telegram-mtproto-proxy-list](https://github.com/tgmtproxy/telegram-mtproto-proxy-list). The bundled snapshot contains endpoint facts, source attribution and download dates. Listings are inputs; the connectivity checks below decide which proxies are used. **Automatic MTProxy** checks Telegram transport connectivity, keeps a working proxy and switches to another when it fails. Workspaces prefer different proxies when enough working entries are available; proxies can share an exit address. Failed proxies rest before another attempt. If none works, the IP mode determines whether collection must wait or may use a direct connection. Changing proxies does not change the account or erase its journal. Route choices and changes are recorded in the signed journal. While automatic routes are active, lists refresh hourly and transport checks run every ten minutes by default. These intervals are configurable. **Update public lists** requests a refresh; viewing the list alone does not change a saved manual route. **Telegram traffic and HTTPS requests use different routes.** List downloads use a separate HTTPS connection and the supplied external-request route. `TGWITNESS_PROXY_FEED_PROXY` explicitly overrides that route with an HTTP/SOCKS5 proxy; both collector Compose variants forward it. The background pool follows the main workspace. No Telegram session, API credentials, panel token or bot token is sent to feed providers. Provider names, snapshot dates and the download route appear under **Where the list comes from**. An MTProxy carries Telegram traffic only. Workspace HTTP operations such as timestamps, notifications, off-site copies and source checks use a separate SOCKS5/HTTP proxy when configured, then the account's SOCKS5/HTTP route. Without either, Hide the address refuses the request; the other modes permit Direct. External requests can be disabled. An explicitly configured feed-download proxy remains a separate operator override. The independent witness service keeps its own route. For operator-managed private services, the existing server environment setting `TGWITNESS_ALLOW_PRIVATE_DESTINATIONS=1` permits private destinations and keeps proxy-side hostname resolution. It cannot be enabled from the panel. Public-only mode rejects `.onion` destinations before querying the public resolver; Tor onion services require that explicit private-destination setting and a suitable proxy. This DNS behavior applies to external HTTP operations, not Telegram's transport. Cloudflare documents the [JSON DNS endpoint](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json/). ****Automatic pool parameters**** Under **More tools → Parameters → Automatic MTProxy**, configure the failure threshold, cooldown, planned rotation, proxy sharing and permitted fallback delay. | Control | Default | | --- | --- | | Disconnects before replacement | 3 within 10 minutes | | Proxies tried per connection attempt | 3 | | First / maximum rest after failure | 10 minutes / 6 hours | | Planned rotation | Disabled; switch on failure | | Accounts per proxy | 0: prefer separate entries, share when needed. Set 1 to wait for an exclusive entry. | | Delay before permitted Direct fallback | 10 minutes; Hide the address still refuses Direct | | Feed refresh / transport checks | 60 / 10 minutes; main workspace values apply to the shared pool | Different proxies can share an exit address. Telegram's limits apply on every route. To replace the public list with your own operator catalog, configure the override below. It disables external subscriptions entirely, including when its `proxies` array is empty. Copy [the empty catalog](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proxies.config.example) to `proxy-config/proxies.json` and add your deployed public endpoints: ``` {"format": "tgwitness-proxy-catalog-v1", "proxies": [ {"id": "project-eu", "label": "Project EU", "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"} ]} ``` The example values must be replaced. Up to 32 distinct entries are accepted. The authenticated listing returns labels/hosts/ports without shared secrets; selecting one saves its credentials into the workspace vault. Availability remains untested until an explicit transport test. A malformed catalog leaves manual configuration available. Native launch: set `TGWITNESS_PROXY_CATALOG` to the local JSON path. Docker: ``` docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build ``` The overlay mounts `proxy-config` read-only; files must be readable by container UID 10001. That directory is excluded from Git, Docker build context and source archives. This catalog configures the collecting accounts; [the witness bot](https://phishdestroy.io/tgwitness/docs/reference/witness/) uses its own HTTP/SOCKS5 route, not MTProxy. Direct fallback is governed by the IP mode above. Pause observation before changing a route. Saving disconnects old clients and cancels unfinished login; a new client uses the saved route. The account's journal/session binding remains. Settings replace the previous route: re-enter proxy credentials when editing it. Credentials are encrypted in `network.enc`. The API does not return the username, password or secret. Signed records contain the route type and whether credentials are present, excluding the endpoint and secrets. The operator can see the endpoint in the panel. Secret fields clear after saving, locking or switching workspaces. **Test Telegram connection**, also available before login, opens and closes a temporary unauthorized Telegram connection through the route. It does not contact an IP-check website. Success establishes transport connectivity, not group access, complete delivery or anonymity. The proxy applies to the Telegram client's connections, including Telegram DC media downloads. Browser, pip, SSH and manually invoked TSA tools have separate routes. The proxy hostname may be resolved locally. `rdns` affects destination hostnames; Telegram often supplies numeric DC IPs. SOCKS5 and plain HTTP CONNECT do not themselves encrypt proxy credentials or the client-to-proxy tunnel. MTProto separately protects Telegram traffic. Use an appropriate secure channel to the proxy on an untrusted network. Private groups are cloud chats protected by MTProto in transit; end-to-end Secret Chats are a separate chat type, recorded by the [Secret Chat module](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/). ## Encryption and signatures | Layer | Implemented | Operator responsibility | | --- | --- | --- | | Telegram traffic | Telethon MTProto | Platform trust, route and availability | | Web panel | Bearer token, loopback default, request limits | HTTPS or SSH tunnel for remote access | | Secrets | Fernet for API credentials, session, proxy credentials and signing private key | Protect the decryption key and running host | | Vault key | Local key, or external master key for a new installation | Separate protected storage and key backup | | Messages and attachments | Plaintext application storage | Encrypted disk/volume | | ZIP/JSONL/CSV/HTML | Integrity checks, no content encryption | Protect exported copies and transfers | | Provenance and time | Signed journal, process receipt, RFC 3161 tools | Trusted key, independent checkpoints/TSA and custody procedure | **Storage protection** in Account shows these states. The panel token is an access secret, not an encryption password. It grants administrator access; [issued tokens](https://phishdestroy.io/tgwitness/docs/reference/access/) can be scoped to accounts and chats. Workspaces share the host process and are not isolated tenants. BitLocker, LUKS, FileVault or a managed encrypted volume can protect storage under their respective threat models. An administrator of an unlocked running machine can still read data. Include SQLite WAL/SHM, media, temporary exports, swap, backups and browser downloads in storage planning. A Docker volume is not encrypted merely because it is a volume. ## External master key For a **new** installation, place the master key outside the data directory. This does not automatically migrate an existing local-key vault. Prepare a key directory accessible only to the service identity, then run: ``` python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key python -m tgwitness --data-dir /private/observations/new-case ``` PowerShell, using the installed project environment: ``` python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key $env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key' python -m tgwitness --data-dir E:\PrivateData\new-case ``` In Docker, mount the file read-only outside `/data`, for example at `/run/secrets/tgwitness-master.key`, and set the environment variable to that path. The service UID must be able to read it. Pass the path, not the key bytes, through environment/configuration files. Each workspace receives a random public salt and its own Fernet key derived through HKDF-SHA256. `vault.external.json` stores derivation metadata, not the master key. A missing/wrong key fails startup without silently replacing it. Retain both the salt metadata and master key for recovery. All workspaces derive from the same master key; its compromise affects the entire installation. The running process can decrypt secrets. This is not an HSM or password KDF. Arbitrary human passwords are not accepted in place of a random key. Keep the existing key for existing installations until a deliberate migration is implemented and verified. Deleting `vault.key` or replacing a master key can destroy access to sessions/signing keys. Keep encrypted backups and keys separately and test recovery in an isolated instance. --- # Deploy TgWitness with Docker, HTTPS & Backups Canonical page: https://phishdestroy.io/tgwitness/docs/reference/deployment/ Deploy a persistent TgWitness collection service with Docker or operating-system services. Configure secure panel access, backups, updates and recovery. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Run TgWitness as a service on Windows, Linux, macOS or Docker, behind HTTPS, with backups and updates. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Deployment & recovery](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f) **English** · [Русский](https://github.com/phishdestroy/TgWitness/blob/main/docs/ru/DEPLOYMENT.md) · [Українська](https://github.com/phishdestroy/TgWitness/blob/main/docs/uk/DEPLOYMENT.md) · [Español](https://github.com/phishdestroy/TgWitness/blob/main/docs/es/DEPLOYMENT.md) · [Português (Brasil)](https://github.com/phishdestroy/TgWitness/blob/main/docs/pt/DEPLOYMENT.md) · [Türkçe](https://github.com/phishdestroy/TgWitness/blob/main/docs/tr/DEPLOYMENT.md) · [العربية](https://github.com/phishdestroy/TgWitness/blob/main/docs/ar/DEPLOYMENT.md) · [فارسی](https://github.com/phishdestroy/TgWitness/blob/main/docs/fa/DEPLOYMENT.md) · [اردو](https://github.com/phishdestroy/TgWitness/blob/main/docs/ur/DEPLOYMENT.md) · [हिन्दी](https://github.com/phishdestroy/TgWitness/blob/main/docs/hi/DEPLOYMENT.md) · [Bahasa Indonesia](https://github.com/phishdestroy/TgWitness/blob/main/docs/id/DEPLOYMENT.md) · [Tiếng Việt](https://github.com/phishdestroy/TgWitness/blob/main/docs/vi/DEPLOYMENT.md) · [简体中文](https://github.com/phishdestroy/TgWitness/blob/main/docs/zh/DEPLOYMENT.md) ## Choose an installation For the portable package, extract `TgWitness--windows-amd64-portable.zip` from GitHub Releases. For the other methods, download and extract the source ZIP or clone the repository, then run the following from the project directory: | Installation | Start | Runs in the background? | | --- | --- | --- | | Windows portable package | `TgWitness.cmd` | No; keep the window open. | | Native Windows | `Start.cmd` | No; use the optional logon task for background use. | | Native Linux/macOS | `sh start.sh` | No; use systemd/launchd for background use. | | Docker on any supported host | `docker compose up -d --build --wait` | Yes, while the Docker daemon runs. | | Docker helper on Windows | `scripts\Docker.cmd` | Yes; the helper waits for web-server health. | | Docker helper on Linux/macOS | `sh scripts/docker-start.sh` | Yes; the helper waits for web-server health. | For a cloud server that a third party should be able to check — created through the provider's API, without SSH, reached only through a Cloudflare Tunnel — see [high-assurance deployment](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/). Native startup creates a private `.venv` and installs the pinned dependencies. Docker builds them inside the image, without requiring host Python. First-time setup needs Internet access. When no Python 3.11+ is found, `Start.cmd` asks before installing Python 3.12 for the current Windows user (winget, otherwise the python.org installer after checking its Python Software Foundation signature); it never requests administrator privileges. Docker and OS services remain prerequisites. Native and portable installations use `data/live` inside their folder. Docker uses the `tgwitness-data` named volume at `/data`. These are separate installations until you deliberately migrate the complete data directory. Do not expect a new Docker container to discover native accounts automatically. ## Installation requirements Native installation needs Python 3.11 or later with `venv` and `ensurepip`, Internet access for the first dependency installation, and a writable project directory for `.venv`. The bundled panel needs no Node.js or frontend build. Run the launcher from your normal OS account; administrator/root privileges are not required by TgWitness. - **Windows:** `Start.cmd` checks `py -3`, then `python`, then the default per-user and Program Files install folders, and requires version 3.11 or later. If none works, it offers the automatic per-user installation described above. `py -3 start.py` also works. The portable package needs no Python at all. - **Linux:** `start.sh` tries `python3.13`, `python3.12`, `python3.11`, `python3` and `python`, and prints the install command for apt, dnf, pacman, zypper, apk or Homebrew when none qualifies. Debian/Ubuntu installations may require the `python3-venv` package matching the selected interpreter. A distribution's older default Python must be replaced or supplemented with Python 3.11+. - **macOS:** install a current Python 3.11+ distribution; do not assume an OS-provided interpreter meets the requirement. Use `python3 start.py` from the project directory. - **Docker:** use Docker Engine/Desktop with Compose v2.20 or newer. Docker Desktop must use Linux containers on Windows. The container installs its own Python dependencies; the host does not need a separate Python installation. ## Local computer Use `Start.cmd` on Windows or `sh start.sh` on Linux/macOS. `scripts\Setup.cmd` or `sh start.sh --setup-only` prepares the environment. The launcher installs dependencies on first use; later launches reuse the environment. Internet access is needed for setup and Telegram collection, but browsing existing records and creating exports work offline. Run `python start.py --check` after setup to inspect local dependencies, Ed25519, storage, key configuration and the listening address without starting a collector. Use `--json` for structured output. Pass the intended `--data-dir`, `--host` and `--port`. The check does not install packages, create a journal or connect Telegram; it is not an integrity or coverage qualification. Startup separately verifies existing journals. `python start.py --help` also avoids installation. After using start.py, run auxiliary commands with `.venv\Scripts\python.exe` on Windows or `.venv/bin/python` on Linux/macOS, or activate that environment first. The `python -m ...` examples below assume the environment is active. ``` python -m tgwitness --data-dir /path/to/private/data --host 127.0.0.1 --port 8787 ``` Environment variables: TGWITNESS_DATA, TGWITNESS_HOST, TGWITNESS_PORT, TGWITNESS_TOKEN. TGWITNESS_VAULT_KEY_FILE selects external-key mode for a new installation; see [External master key](https://phishdestroy.io/tgwitness/docs/reference/security/#external-master-key). TGWITNESS_TOKEN, if supplied, must contain at least 24 characters; use a cryptographically random value. Without it, the app generates a 256-bit random token in panel-token.txt. The environment override does not rewrite that file. Restart to rotate credentials. Exactly one process may own a data directory. A cross-platform OS file lock prevents accidental concurrent writers. Use one Uvicorn worker. The panel can manage any number of workspaces, with additional workspace directories under profiles//. For separate service instances, use separate directories and ports. SQLite WAL files belong on local persistent storage, not a network filesystem. Do not share one volume between replicas. ## Windows portable package Each GitHub Release carries `TgWitness--windows-amd64-portable.zip` and its `.sha256`. It contains the official embeddable Python 3.12 runtime from python.org (checksum pinned in `tools/build_portable.py`), TgWitness and its pinned dependencies, and three launchers: | File | Purpose | | --- | --- | | `TgWitness.cmd` | Start the panel; extra options are passed through, e.g. `TgWitness.cmd --port 8790` | | `TgWitness-Demo.cmd` | Start the synthetic demo in `data\demo` | | `TgWitness-Check.cmd` | Run the readiness check without starting | The pinned Russian morphology dictionary and PDF color profiles are bundled for offline use. Packaging permits only their known file paths inside dependency `data` directories; unexpected files in those directories fail the build. Extract the whole archive to a writable folder such as `Documents\TgWitness`; do not run it from inside the ZIP or from Program Files. The runtime uses an isolated module path, so other Python installations and `PYTHONPATH` do not affect it. Data stays in the package's `data` folder. To update, stop TgWitness, extract the new version to a new folder and copy the `data` folder across. Build it yourself on 64-bit Windows with Python 3.12: ``` python tools/build_portable.py ``` ## Container ``` docker compose up -d --build --wait ``` This creates a named persistent volume for /data. The web port is mapped to 127.0.0.1:8787. The process runs as UID 10001 with dropped capabilities, a read-only root filesystem, and writable /data and /tmp. `--wait` checks web-server health before returning; Telegram authorization and delivery appear in the panel. The supplied helpers use a 180-second readiness timeout after building. Initial dependency downloads can take longer than that. Both base Compose files use the project name `tgwitness`, so extracting a new release into another directory does not silently select a new data volume. Keep only one deployment active for that project. For independent installations, use a unique `docker compose -p NAME ...` and a different host port, and retain both on updates. For an older deployment using a different project name, continue using its original name with `-p`; `docker compose ls` lists existing projects. Copy `deploy/env.example` to `.env` and change `TGWITNESS_PORT` to use a different loopback port. For example, `TGWITNESS_PORT=8788` exposes the panel at `http://127.0.0.1:8788`; the container still listens on 8787. `.env` is Git-ignored. Retrieve the initial token: ``` docker compose exec tgwitness cat /data/panel-token.txt ``` Useful commands: ``` docker compose ps docker compose logs --tail 100 -f docker compose stop docker compose up -d --wait ``` `restart: unless-stopped` restarts the collector after a crash or Docker daemon restart. On a Linux server, enable Docker at boot using your distribution's service manager, commonly `sudo systemctl enable --now docker`. On Windows/macOS, enable Docker Desktop's start-at-sign-in setting. Desktop sign-out, sleep, or a stopped Docker daemon can interrupt collection. An explicitly stopped container stays stopped until you start it again. The /tmp volume is capped at 512 MiB in the example configuration. Export construction uses each workspace's `temporary-exports/` on persistent /data instead. Reserve space there for simultaneous exports, journal/WAL growth, media and backups. The launcher uses deploy/constraints.txt to pin qualified runtime dependency versions. Docker and high-assurance servers install from deploy/requirements.lock and deploy/build.lock with pip --require-hashes: every package file must match a SHA-256 recorded in the commit, so a file replaced on PyPI or a mirror is refused. Packages that ship only source (jieba, pyaes) are built with the setuptools pinned in deploy/build.lock (`--no-build-isolation`) by the launcher, the Windows portable builder and the Dockerfile, so pip does not resolve a separate, unpinned build environment. The Python base image and operating-system packages still require independent release qualification. Do not use docker compose down -v unless you intend to destroy the journal and keys. Container health reports web-server availability, not successful Telegram capture. Inspect the panel's collector state, heartbeat, errors, and coverage events. ### Independent witness profile The optional `witness` service runs an [independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/) in its own container, with its own key and journal in the `witness-data` volume and only a read-only witness token for the collector. Create the token in the panel under **More tools → Extras → Independent witness**, add it with a bot token and channel to `.env`, then start the profile: ``` docker compose --profile witness up -d # deploy/compose/compose.image.yaml: same flag docker compose logs witness # witness key fingerprint ``` The service reaches the collector inside the Compose network at `http://tgwitness:8787` (`TGWITNESS_WITNESS_COLLECTOR` overrides it, for example `/profiles/` for another workspace). For a witness on a separate server, run by someone else, use `deploy/compose/compose.witness.yaml` there with `TGWITNESS_WITNESS_COLLECTOR` set to the collector's HTTPS address; that file contains only the witness. ## Install a published image Copy `deploy/env.example` to `.env`. Set `TGWITNESS_IMAGE` to the published version, using the **lowercase** repository path, for example: ``` TGWITNESS_IMAGE=ghcr.io/your-owner/your-repository:0.9.3 TGWITNESS_PORT=8787 ``` Run this file on its own, instead of `compose.yaml`: ``` docker compose --project-directory . -f deploy/compose/compose.image.yaml pull docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait docker compose --project-directory . -f deploy/compose/compose.image.yaml exec tgwitness cat /data/panel-token.txt ``` No source build, Python, or compiler is needed on the host. The release workflow targets Linux AMD64 and ARM64 containers, including Docker Desktop's Linux VM. Use a version tag or `ghcr.io/owner/repository@sha256:...` from the workflow summary. No moving `latest` tag or unattended application upgrade is configured. The image and source variants use the same data volume when their project name matches. ## Automatic HTTPS on a server Use a server with Docker, a domain you control, and persistent local storage. Point the domain's A/AAAA records at the server; publish AAAA only if IPv6 reaches it. Allow inbound TCP 80 and 443 and outbound DNS/HTTPS for certificate issuance. Other services must not already own these ports. Copy `deploy/env.example` to `.env` and set a hostname, without a scheme or path: ``` TGWITNESS_DOMAIN=watch.your-domain.org ``` Start the source build with the HTTPS overlay: ``` docker compose -f compose.yaml -f deploy/compose/compose.https.yaml up -d --build --wait docker compose -f compose.yaml -f deploy/compose/compose.https.yaml exec tgwitness cat /data/panel-token.txt ``` ``` docker compose --project-directory . -f deploy/compose/compose.image.yaml -f deploy/compose/compose.https.yaml up -d --wait ``` For a published image, use `deploy/compose/compose.image.yaml` as the first file instead. Keep both `-f` arguments for later status, logs, update, and stop commands. Caddy obtains and renews a certificate, redirects HTTP to HTTPS, and forwards requests to the collector on the private Compose network. Certificate state has its own persistent volume. The collector's direct host port remains loopback-only. The supplied Caddy configuration does not enable access logging. Open `https://watch.your-domain.org` and enter the panel token. Compose readiness covers the containers; certificate issuance and external reachability depend on DNS and the firewall. If HTTPS is not ready, inspect DNS, firewall rules, and: ``` docker compose -f compose.yaml -f deploy/compose/compose.https.yaml logs --tail 100 caddy ``` The supplied Caddy image follows its `2-alpine` tag. Pulling refreshes that image; pin a tested digest in your deployment if you need fixed infrastructure versions. ## Updates and backups Preserve the Compose project name and data volume across updates. First stop the collector and make a complete backup. For the default source-based deployment: ``` docker compose stop docker compose cp tgwitness:/data ../tgwitness-backup-before-update ``` Use a new backup destination each time, outside the repository, and protect it as account-access material. The example path is illustrative; use your private backup location. Copy the entire directory, including hidden files, all workspaces, keys, journals, and media. Back up an external vault master key separately if configured. An evidence ZIP is not a restorable application backup. For HTTPS, also preserve the Caddy volumes if you need to retain its certificate/account state. For a source deployment, obtain the new release files and run: ``` docker compose up -d --build --wait ``` For an image deployment, change `TGWITNESS_IMAGE` to the desired version, then run: ``` docker compose --project-directory . -f deploy/compose/compose.image.yaml pull docker compose --project-directory . -f deploy/compose/compose.image.yaml up -d --wait ``` Use your installation's Compose file(s) for the preceding stop/copy commands too. Keep `.env`, custom configuration, and the same project name. `down` keeps named volumes; **`down -v` deletes them**. Do not copy `.venv` between operating systems or Python versions. For native updates, stop TgWitness, back up its full data directory, replace source files, and run `python start.py --setup-only` before launch. Check panel access, account identity, observation state, and coverage after an update. After the restart TgWitness resumes the saved Telegram update position and requests the updates missed during the update. A rollback may require the pre-update backup if a future version changes storage formats. ## Remote server Keep the service bound to loopback and use an SSH tunnel, or terminate HTTPS at a reverse proxy. The base Compose file is local-only; the optional `deploy/compose/compose.https.yaml` overlay supplies Caddy for a configured domain. Keep the bearer token out of URLs and proxy logs. A reverse proxy should limit request size and connection rates. Do not expose plain HTTP to the Internet. Examples for systemd, a Windows logon task, a macOS user agent and Caddy are provided in [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md). Review/adapt their paths before installation. They are supplied templates, not locally executed platform qualifications. No background service or task is registered by the normal launcher. On Windows, a windowless `pythonw.exe` launch stores startup/server diagnostics in `logs/server.log` under the data directory (5 MiB per file, two rotated backups). Console launches retain console logging. HTTP access logging is disabled in both modes. Protect logs with the data directory and review them before sharing. ## Restart and gaps The last requested observation state is persisted. If observation was active, startup attempts to reconnect and resume selected sources. Manual pause clears that intention. A failed restart is recorded and shown in the panel. TgWitness stores Telegram's update position for the account and for each channel (pts, qts, seq and date) in the workspace vault and restores it at the next start. The client then requests the updates missed while the process was stopped, and the periodic recheck recovers missed messages and records saved ones that Telegram no longer returns. Dialogs are reloaded on start. Every startup records the preceding journal head, the offline boundary and the update position it resumed from. The monitor checks connectivity every 10 seconds and adds a heartbeat every minute (**More tools → Parameters → Liveness record every**). Disconnections and silent periods are recorded as coverage gaps with their reason. History snapshots are stored as separate current-history observations next to live records. The media queue is stored in each workspace's SQLite database. A message and its job are committed atomically. Interrupted running jobs are recovered for retry on start. Each download has a 120-second base timeout plus time at 256 KiB/s for its size, and a 1–2,000 MiB limit per attachment type; timeout, speed and retries are under **More tools → Parameters**. The collector skips files whose size is unknown. Pausing retains queued work. Retry uses the original observed file descriptor, never the latest version of a subsequently edited message. Temporary failures have bounded retries; media FloodWait pauses survive restart. Media recovery is separate from Telegram update recovery and cannot recreate vanished files. ## Backup, restore, and capacity `tgwitness backup FOLDER` copies the data directory while the panel keeps running: checkpoints first, then SQLite files through the online backup API, then keys, media and profiles, so no copied checkpoint is newer than the copied journal. `backup-manifest.json` lists every file's SHA-256 and the journal heads. To restore, stop TgWitness and replace the whole data directory with that folder. The next start records that the journal was restored from an older copy. That record compares the journal with the head kept in `TGWITNESS_STATE_DIR`, a folder outside the data directory: the `tgwitness-state` volume in Compose, `/var/lib/tgwitness-state` in the systemd units, and the user's local state folder otherwise. Without a writable state folder the restore is not detected and the log says so once. Without the command, stop the process before copying the **entire data directory**, including vault.key, signing.enc, credentials.enc, SQLite database/WAL files, media, token, checkpoints, and all profiles/ subdirectories. Restore the complete copy while the destination service is stopped. Missing vault keys or signing-key mismatch cause startup to fail; do not regenerate keys to force access. Keep secret backups encrypted and access-controlled. Evidence ZIPs are portable review artifacts, not application backups or Telegram-session backups. There is no automatic retention deletion. Plan disk space for all messages, raw metadata, media, temporary exports, and backups. Startup verification and export stream records instead of loading the whole journal. An export pins a read snapshot while new WAL writes can continue; long-running exports can retain WAL pages, so disk capacity still matters. ZIPs are capped at 4 GiB uncompressed to match the independent verifier's default; **More tools → Parameters → Largest signed ZIP** raises the cap, and such archives are verified with `verify.py --max-gib N`. Other formats have no event-count cap. Supported browsers stream response chunks to a user-selected file. Other browsers buffer at most 128 MiB and direct larger transfers to the authenticated CLI: ``` python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip ``` Use `--profile ID` from **Exports → Workspace ID** for another workspace, `--format zip|jsonl|csv|html`, `--url https://your-server` for a remote server, or `--max-mib` to change the 5 GiB transfer limit. Plain HTTP is allowed only for loopback. Tokens travel in headers, redirects are refused, existing files are not overwritten, and incomplete downloads are not published as finished files. If TGWITNESS_TOKEN overrides the generated token, use a separately protected file containing that active value: panel-token.txt is not rewritten by the override. The command's SHA-256 is only a transfer checksum; independently verify the signed ZIP. The panel displays queued/failed media, oldest pending media, free disk, Telegram request pauses, and sources whose access is unconfirmed. These diagnostics are not a complete end-to-end delivery monitor. Workspaces share a process; a noisy account can still affect others. Separate worker processes, retention/rotation, durable update recovery and full deployment qualification remain. Scoped panel access is documented in [access and permissions](https://phishdestroy.io/tgwitness/docs/reference/access/); independent checkpoints are covered by the [witness guide](https://phishdestroy.io/tgwitness/docs/reference/witness/). Detailed procedures: [connection/security](https://phishdestroy.io/tgwitness/docs/reference/connection/) and [operating modes](https://phishdestroy.io/tgwitness/docs/reference/operations/). --- # Phala Intel TDX: Attested Telegram Collection Canonical page: https://phishdestroy.io/tgwitness/docs/reference/high-assurance/ Deploy TgWitness on Phala or a conventional VM. Review Intel TDX quotes, OS measurements, collector identity and independent verification boundaries. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) A sealed 24/7 server on Hetzner or Phala Cloud, Gateway DNS and the checks a third party can repeat. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Deployment and recovery](https://phishdestroy.io/tgwitness/docs/reference/deployment/) ![Deployment & recovery](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f) High-assurance deployment adds independent checks of the collection environment to archive verification. The reviewer queries deployment and access records held by the cloud provider and Cloudflare, and an Intel TDX deployment adds hardware attestation of the collector's environment. Ordinary local and Docker use is unchanged. Nothing here runs unless you deploy with `python -m tgwitness.cloud`, and the collector reads its host only when the deployment sets `TGWITNESS_ASSURANCE`. Flow diagram · Operator → Server, firewall without inbound rules (provider API); Operator → Tunnel and DNS (Cloudflare API); Server, firewall without inbound rules → Tunnel and DNS (outbound only); Server, firewall without inbound rules → Signing key created on the server; Verifier, read-only tokens → Provider log and firewall; Verifier, read-only tokens → Tunnel connector address and ingress; Verifier, read-only tokens → Signed /api/assurance statement; Verifier, read-only tokens → Evidence ZIP · Operator · Verifier, read-only tokens · Server, firewall withoutinbound rules · Provider log and firewall · Tunnel connector addressand ingress · Signed /api/assurancestatement · Evidence ZIP · Tunnel and DNS · Signing key created on theserver · provider API · Cloudflare API · outbound only **Diagram as text** 1. Operator → Server, firewall without inbound rules (provider API) 2. Operator → Tunnel and DNS (Cloudflare API) 3. Server, firewall without inbound rules → Tunnel and DNS (outbound only) 4. Server, firewall without inbound rules → Signing key created on the server 5. Verifier, read-only tokens → Provider log and firewall 6. Verifier, read-only tokens → Tunnel connector address and ingress 7. Verifier, read-only tokens → Signed /api/assurance statement 8. Verifier, read-only tokens → Evidence ZIP **On this page** - [What a verifier can check](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#what-a-verifier-can-check) - [Providers](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#providers) - [Confidential VM on Phala Cloud (Intel TDX)](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx) - [Before you start](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#before-you-start) - [From the panel](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#from-the-panel) - [Quick tunnel without a domain](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#quick-tunnel-without-a-domain) - [Deploy](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#deploy) - [Debug deployment and lock](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#debug-deployment-and-lock) - [Remove a deployment](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#remove-a-deployment) - [Any server (self-attested)](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#any-server-self-attested) - [Verify](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#verify) - [Report for evidence handover](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#report-for-evidence-handover) - [Cloudflare as an outside witness](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#cloudflare-as-an-outside-witness) - [Reading the deployment result](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#reading-the-deployment-result) ## What a verifier can check | Claim | How it is checked | Kept by | | --- | --- | --- | | The server was created through the provider API at a known time | Server object and its creation in the provider's own log | Provider | | Nobody used the provider's access paths | Log of console requests, rescue, password reset, rebuild, ISO, images, backups | Provider | | Nothing could connect to it | The provider firewall has no inbound rules; SSH is masked from the first boot | Provider (firewall), host (SSH) | | The panel is reached only through the tunnel | Tunnel ingress forwards to the panel alone; the connector runs from the server's address | Cloudflare | | This exact software runs | The collector's signed source-tree hash equals a checkout of the deployed commit | Collector, checked against Git | | The signing key was created on that server | The key signs a statement naming the provider's server ID and the hash of the cloud-init it received | Collector, checked against the provider | | The journal belongs to that key and server | Every process start in the evidence ZIP carries the host measurement for that server | Evidence ZIP | | The Telegram key was created in the attested run | `account.authorized` records `key_origin: "created"` | Evidence ZIP | The collector records SSH state, sessions, login history and boot information in signed process-start and `host.state` records. On an ordinary VM these are local inventory records, which the reviewer compares with the provider's independent records. The Intel TDX deployment below additionally verifies hardware-backed measurements. An attested deployment does not collect on an imported session key. Sign in by phone or QR, or use the session file for an independent login: either way the Telegram authorization key is created inside the attested run, the journal records `key_origin: "created"`, and `python -m tgwitness.cloud verify` passes `account_key`. A journal with an imported key fails that check. ## Providers | `--provider` | Credentials | Verifier's read-only access | Provider log for the verifier | Kept for | | --- | --- | --- | --- | --- | | `hetzner` | `HCLOUD_TOKEN` | Read token of the same project | Server and firewall actions | While the resources exist | | `digitalocean` | `DIGITALOCEAN_TOKEN` | Read-only personal access token | Droplet actions | While the Droplet exists | | `linode` | `LINODE_TOKEN` | `linodes`, `firewall`, `events` read-only scopes | Account events, firewall rule versions | 90 days | | `vultr` | `VULTR_API_KEY` | User with read access and the `activity_logs` permission | Account activity log (method, path, actor) | 30 days, longer with an audit-log subscription | | `aws` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | `ec2:DescribeInstances`, `ec2:DescribeSecurityGroups`, `cloudtrail:LookupEvents` | CloudTrail event history | 90 days | | `phala` | `PHALA_CLOUD_API_KEY` | An API key of the same workspace | Application revisions and CVM operations: compose and environment changes, restarts, OS upgrades | While the application exists | | `generic` | none | none | none: **self-attested** | – | Use a dedicated project, team, account or sub-account for each case: the verifier's read-only access then shows only this deployment. Credentials are read from `--provider-token-file` or the variable above, never from the command line. For AWS the file holds `ACCESS_KEY_ID SECRET_ACCESS_KEY [SESSION_TOKEN]`; the region is `--location`. Every report states the scope of each provider's records. In short: Hetzner logs console requests; DigitalOcean's Recovery Console, Linode's Lish/Glish and Vultr's web console are not logged as such, so root is locked at the first boot and a console login would need a password reset or a boot change, which are logged. Vultr returns the console address to any key that can read the instance; neither the record nor the report stores it. ## Confidential VM on Phala Cloud (Intel TDX) With `--provider phala` the collector runs in an Intel TDX confidential virtual machine on [Phala Cloud](https://phala.com/), managed by dstack. The host and Phala's staff cannot read its memory, and the processor signs an attestation of what the machine booted. The verifier does not take Phala's word for it: `tgwitness.tdx` checks every attestation itself, up to the pinned Intel SGX Root CA, against Intel's revocation lists and Intel's signed platform data, and refuses machines that can be debugged or migrated. | Report entry | What it shows | | --- | --- | | `tdx_binding` | The attestation covers the signed statement of the collector and the random value of this request | | `tdx_quote` | Intel vouches for the attestation; it passes only when Intel rates the platform as up to date | | `tdx_compose_hash` | RTMR3, replayed from the dstack event log, measures the app-compose the collector reports | | `tdx_compose` | That compose is byte for byte the one the code of the deployed commit builds: source files pinned by hash, both images by digest, no other code | | `tdx_identity` | The attestation comes from the deployed application and instance, with keys from Phala's KMS and an encrypted disk | | `tdx_os` | MRTD and RTMR0-2 equal the values the verifier computes from the dstack OS image Dstack-TEE publishes, found by the OS image hash the CVM reports, and from the ACPI tables QEMU builds for the VM's shape: firmware, kernel, initrd, command line with the root file system hash, memory, vCPUs and devices. A development image fails | The OS image (about 180 MB, of which 21 MB are kept) is downloaded once from [Dstack-TEE/meta-dstack](https://github.com/Dstack-TEE/meta-dstack/releases) into `dstack-images` beside the record; `--tdx-image FOLDER` uses another folder or an unpacked image, `--tdx-image none` skips the comparison. The measurement follows `dstack-mr` and the `qemu-acpi` crate of Dstack-TEE/dstack. Private measurement regressions compare QEMU's own ACPI output and a retained Phala Cloud quote; live qualification also needs the published image. `--tdx-measurements` still compares MRTD and RTMR0-2 given as JSON instead. Every start of the collector recorded in the journal carries such an attestation, so `verify --evidence` checks each start and the OS image it booted. Phala's application revisions and the CVM's operations serve as the provider log: a compose changed after the deployment fails the report, and restarts are listed for review. In the panel choose **Confidential virtual machine · Phala Cloud** under **More tools → Extras → Server 24/7** and paste a Phala Cloud API key; the quick tunnel works as on Hetzner. From the command line: ``` python -m tgwitness.cloud deploy --provider phala --name case-1 --server-type tdx.small \ --ref v0.8.0 --repository https://github.com/phishdestroy/TgWitness --quick-tunnel \ --provider-token-file phala-key.txt python -m tgwitness.cloud verify --record deployments/case-1/deployment.json \ --provider-token-file phala-key.txt --cloud-init deployments/case-1/docker-compose.yaml \ --source CHECKOUT_OF_COMMIT --fingerprint COLLECTOR_FINGERPRINT --report certificate.md python -m tgwitness.cloud check-report --report certificate.pdf --verifier-fingerprint VERIFIER_KEY ``` `--tdx-collateral` reads Intel's certificates and revocation lists from a file instead of downloading them from Intel. Gateway DNS is not available here: Phala has no provider firewall for outgoing traffic. `verify --source` builds the reference installer from your checkout, which runs that checkout's code on this computer. For a deployment made from a repository other than the official one, `verify` refuses unless you also pass `--trust-source`; do so only for a checkout you have read. ### Offline check with verify.py A recipient without a Phala account checks the quotes with the standalone verifier, offline: ``` python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_FINGERPRINT python verify.py phala-tdx-attestation.json ``` For the quote of every `process.started` record in an evidence archive, and for the quote of a signed collector statement (also inside a deployment record or a published attestation record), `verify.py` checks the quote's ECDSA P-256 signature with its attestation key, the quoting enclave report's signature with the PCK certificate, that this report names the attestation key (SHA-256 of the key and the QE authentication data), that it comes from Intel's TDX quoting enclave in production mode, and the chain PCK certificate → Intel SGX PCK Platform or Processor CA → Intel SGX Root CA, whose SHA-256 is pinned in `verify.py`. It refuses debuggable or migratable TDs, checks that REPORTDATA is SHA-512 of the start record (journal key, run, source tree, host) or of the signed statement, and prints MRTD, RTMR0-3 and REPORTDATA. The collector also stores Intel's collateral (TCB Info, QE Identity, revocation lists and their issuer chains) with each quote when Intel's service answers. With it, `verify.py` checks Intel's signatures and revocation lists and computes the TCB status as of the recorded time, or as of the collateral's issue date when that is later. Without it the result reads "TCB status not checked (no collateral in the archive)". Which code the VM ran (the compose RTMR3 measures, the OS image behind MRTD and RTMR0-2), the provider log and Intel's current rating remain checks of `python -m tgwitness.cloud verify`; the offline check therefore marks the attested collection run as partial and does not by itself reach the `sealed` tier or the `attested` profile. ### Attestation certificate For a Phala deployment `verify --report certificate.md` also writes the certificate: a self-contained `certificate.html` and an A4 `certificate.pdf` with the verdict, the chain of trust from Intel's root to the collector key, a comparison with ordinary and high-assurance servers, the measurements next to the values computed from the published image, who vouches for each part, the Intel certificate chain, every check, the provider log, and how to repeat the verification. The JSON report stays the authoritative record; the pages render it. The report is sealed, in `certificate.seal.json` and the `.tsq`/`.tsr` files beside it: | Seal | What it adds | | --- | --- | | Qualified electronic time stamp, `http://tsa.belgium.be/connect` | RFC 3161 time stamp over the exact bytes of `certificate.json` from the Belgian federal government's qualified trust service provider (FPS Policy and Support, BOSA). Its unit is listed as a qualified time-stamping service, status granted, on Belgium's EU trusted list; the root (Belgium Root CA6) and the list's entries, as of the list issued on 20 October 2026, are pinned in `tgwitness/tsa_roots.py`. Under Regulation (EU) No 910/2014, article 41, such a time stamp is presumed accurate as to date and time and as to the integrity of the data in every EU member state | | RFC 3161 time stamp, FreeTSA | A second, independent time stamp | | Verifier signature | Ed25519 over a statement naming the report's SHA-256 and every time stamp, with the verifier's own key (`--sign-with FOLDER`, default `~/.tgwitness/verifier`); the PDF carries a signature by the same key | `--timestamp URL` (repeatable) chooses other authorities, `--timestamp none` none, `--sign-with none` leaves the seal unsigned. `check-report` checks the report's hash, the verifier signature, each time stamp to a trusted root and its qualified status, and the PDF's signature. The legal weight of a qualified time stamp outside the EU, and of the report as a whole, is for the court or authority that receives it; the seal shows when the report existed and that it has not changed. The attestation relies on Intel's TDX module and microcode and on the physical integrity of the memory bus. Whoever controls the application in Phala's account can deploy another compose; it appears as a new revision with a new compose hash. The host controls the machine's time source and network. Deploy, verify with `--evidence`, restarts, the OS image comparison, the sealed certificate and destroy have run on Phala Cloud itself; see [the 4 November 2026 run](https://phishdestroy.io/tgwitness/docs/reference/verification/#live-phala-cloud-deployment--4-november-2026). On 9 November a deployment collected from a live Telegram account; one run used a session key created inside the VM. See [the live account run](https://phishdestroy.io/tgwitness/docs/reference/verification/#phala-cloud-with-live-telegram-account--9-november-2026) and [the key created in the VM](https://phishdestroy.io/tgwitness/docs/reference/verification/#session-key-created-inside-the-tdx-vm--9-november-2026). ## Before you start 1. A Cloudflare zone, its account ID, and an API token with **Cloudflare Tunnel Edit**, **Zone Read** and **DNS Edit**, given with `--cloudflare-token-file` or `CLOUDFLARE_API_TOKEN`. For the verifier: **Cloudflare Tunnel Read**, **DNS Read** and, for the audit log, **Account Settings Read**. Without a domain, a [quick tunnel](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#quick-tunnel-without-a-domain) needs none of this. 2. Provider credentials with write access to a dedicated project; `lock` uses the same: - Hetzner: API token with Read & Write permission; - DigitalOcean: personal access token with write access; - Linode: personal access token with `linodes`, `firewall` and `events` read/write scopes; - Vultr: API key of a dedicated account or sub-account; - AWS: IAM credentials allowed `ec2:DescribeVpcs`, `ec2:DescribeImages`, `ec2:CreateSecurityGroup`, `ec2:AuthorizeSecurityGroupIngress`, `ec2:RunInstances`, `ec2:CreateTags`, `ec2:DescribeInstances`, `ec2:DescribeSecurityGroupRules` and `ec2:RevokeSecurityGroupIngress`. 3. The commit to run. A release tag is resolved once to its commit with `git ls-remote`; the server only ever receives the 40-character commit. ## From the panel On your own computer, **More tools → Extras → Server 24/7** runs the same `deploy` for Hetzner in three steps: choose Europe or the United States, paste a Hetzner token (Read & Write), then review the server type, monthly price, address and version the panel found with that token. Nothing is created before you confirm. The panel shows each step as `deploy` reports it, then the address, the panel token and the signing key fingerprint. Without a domain the server gets a [quick tunnel](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#quick-tunnel-without-a-domain); **Your servers → Find the current address** looks it up again after a restart. For a fixed address under your own domain, open **Optional · your own domain** and add a Cloudflare token (the prepared link selects Zone Read, DNS Edit and Cloudflare Tunnel Edit). The tokens travel with each request from the browser tab to TgWitness on the same computer and are not written anywhere; the deployment record, redacted cloud-init, panel token and, for a quick tunnel, the address key are kept in `deployments/NAME` inside the data directory. The panel offers this only to the main administrator on a direct loopback connection (`127.0.0.1`, no proxy or tunnel headers); a panel reached over a network shows the commands instead. The version defaults to the release tag of the running panel, resolved through the GitHub API. Location, server type and price come from Hetzner's API: `cpx22` where it is offered, otherwise the cheapest x86 type with at least 2 GB of memory. ## Quick tunnel without a domain `--quick-tunnel` replaces `--zone`, `--cloudflare-account` and `--panel-host`; no Cloudflare account or token is involved: ``` python -m tgwitness.cloud deploy --provider hetzner --name case-2026-11 --server-type cpx22 \ --ref 0123456789abcdef0123456789abcdef01234567 --quick-tunnel --provider-token-file hetzner.token ``` On the server, cloudflared opens a [quick tunnel](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) to the panel: a random `https://….trycloudflare.com` address that changes whenever cloudflared or the server restarts. A small service on the server posts each address to a random ntfy.sh topic, signed (HMAC-SHA256) with a key only the deployment directory holds (`address-key.txt`), and repeats it every three hours because ntfy.sh keeps posts for 12. `deploy` and **Find the current address** accept signed posts only, so a forged post cannot send you, and your panel token, to someone else's address. The topic is in the record and the published cloud-init: whoever has them can read the current address, which still asks for the panel token. The server keeps no inbound port either way. A verifier has no address key, and anyone who reads the topic can post to it. So the collector also posts the address itself, signed with its own Ed25519 key, and `verify` takes the newest post signed by the collector key in the deployment record; posts are ordered by the time ntfy.sh received them, not the time they claim. A collector from before this change signs nothing, and `verify` then takes the newest post and says so in the `statement` check; a forged post can only make that check fail, since the address must still answer with the collector's key. What it costs: no Cloudflare account keeps records of a quick tunnel, so `verify` reports the tunnel, connector and DNS check as unavailable and the result is at best `incomplete` (on Phala Cloud the check passes instead: the connector runs inside the measured compose); the provider records, firewall, signed statement, host measurements and installer comparison are checked as usual. The byte comparison with the reference installer needs a deployed commit that already knows `--quick-tunnel`; a 0.7.0 checkout builds the domain installer and reports the difference. Cloudflare offers quick tunnels for trials, allows 200 requests in flight and does not carry Server-Sent Events, so the panel's live updates (versions after 0.7.0) may not arrive through one and a view needs reloading; that part has not been tried. For a case that has to stand, use your own domain. ## Deploy Look at everything that will be sent first. `plan` makes no provider or Cloudflare request: ``` python -m tgwitness.cloud plan --provider hetzner --name case-2026-11 --server-type cpx22 \ --ref 0123456789abcdef0123456789abcdef01234567 --zone example.org \ --cloudflare-account CLOUDFLARE_ACCOUNT_ID --panel-host case.example.org ``` Then deploy with the same options and the credentials: ``` python -m tgwitness.cloud deploy --provider hetzner --name case-2026-11 --server-type cpx22 \ --ref 0123456789abcdef0123456789abcdef01234567 --zone example.org \ --cloudflare-account CLOUDFLARE_ACCOUNT_ID --panel-host case.example.org \ --witness-host case-witness.example.org \ --provider-token-file hetzner.token --cloudflare-token-file cloudflare.token ``` Server types to start with: `cpx22` (Hetzner), `s-1vcpu-2gb` (DigitalOcean), `g6-standard-1` (Linode), `vc2-1c-2gb` (Vultr), `t3.small` (AWS). `--location` and `--image` default to each provider's Ubuntu 24.04 in a European region. `--repository` takes the commit from another https Git repository, without credentials in the URL (default `https://github.com/phishdestroy/TgWitness.git`). `deploy` also accepts `--out` for another deployment directory (default `deployments/NAME`; a directory that already holds a deployment is refused) and `--wait`, the minutes to wait for the collector's signed statement: 1 to 240, default 20, or 60 for `generic`. The command: 1. creates a Cloudflare tunnel whose ingress forwards the panel hostname to the panel and, if given, the witness hostname to `/api/witness/head` and `/api/assurance` only; 2. creates proxied CNAME records for those hostnames, refusing names that already exist; 3. creates a provider firewall without inbound rules and a server behind it with no SSH key, no backups, no console agent, and cloud-init that masks SSH, locks root, installs `cloudflared`, fetches exactly the commit, checks it and starts TgWitness as a hardened systemd service; 4. waits for the collector's signed statement and checks that it names this server and the hash of this cloud-init. `deployments/case-2026-11/` then holds: | File | Contents | Share? | | --- | --- | --- | | `deployment.json` | IDs, hashes, the API calls made (method, path, status) and the first signed statement | Yes, with the verifier | | `cloud-init.redacted.yaml` | The exact cloud-init with its two secrets replaced by `REDACTED` | Yes | | `panel-token.txt` | The panel token | No | The provider's root password, the tunnel token and the panel token are never written to `deployment.json`. Publish the collector fingerprint printed at the end through a channel you do not control alone, for example a witness channel or a message to the recipient. Sign in to Telegram at `https://case.example.org` with the panel token, as in the [account guide](https://phishdestroy.io/tgwitness/docs/reference/accounts/). Panel actions are recorded in the signed journal; they are not SSH sessions. A [witness](https://phishdestroy.io/tgwitness/docs/reference/witness/) can poll `https://case-witness.example.org`. There is no SSH: if the bootstrap fails, the collector never answers. Delete the server and deploy again, or use a debug deployment to find the cause. ### Secrets in the user data The cloud-init carries two secrets: the panel token and the Cloudflare tunnel token. The signing key is not among them; it is created on the server. Hetzner, DigitalOcean and Linode do not return user data through their API. Vultr returns it to any key that can read the instance, and EC2 through `DescribeInstanceAttribute`. For AWS give the verifier only the three actions in the table, never `ec2:Describe*`. For Vultr, assume the verifier's key can read both tokens. A tunnel token lets someone run a second connector: `verify` reports any connector not on the server, and the collector's statements cannot be forged that way because each one signs a fresh challenge. With `--quick-tunnel` the second secret is the address key instead: whoever reads it can post a false address that the panel would accept. The collector's public statement leaves out the server's address and the sources of logins; both stay in the signed journal. ## Debug deployment and lock `--debug-ssh-key KEY --debug-ssh-from 198.51.100.4` keeps SSH for one key from one address or small network, at most a /24 for IPv4 or a /48 for IPv6. `KEY` is already registered with the provider: the name or ID of an SSH key in the Hetzner project, the ID or fingerprint of an SSH key in the DigitalOcean team, a Linode username whose profile SSH keys are added to root, the ID of an SSH key in the Vultr account, or the name of an EC2 key pair in the region. These options do not apply to `generic`. Such a deployment is recorded as `debug` and is **never** reported as high-assurance. When you are done, run `sudo tgwitness-lock` as the last command of the last SSH session, then: ``` python -m tgwitness.cloud lock --record deployments/case-2026-11/deployment.json --provider-token-file hetzner.token ``` The firewall loses every inbound rule. Reports then show when SSH was allowed and when it was closed; that window stays visible. ## Remove a deployment `destroy` deletes the server and its firewall, found by the deployment's label so that a deployment which failed half-way is removed as well, then the DNS records that point to its tunnel, and the tunnel. The server's journal and signing key are deleted with it: export the evidence first. The record stays, marked `removed`, with the API calls of the removal. ``` python -m tgwitness.cloud destroy --record deployments/case-2026-11/deployment.json --confirm case-2026-11 \ --provider-token-file hetzner.token --cloudflare-token-file cloudflare.token ``` Removal through the API is implemented for Hetzner. For other providers `destroy` stops before deleting anything and names the label to delete in the provider's console. A hand-installed server (`generic`) loses only its tunnel and DNS records. A quick tunnel deployment needs no Cloudflare token: its tunnel ends with the server, and its posts expire from ntfy.sh within 12 hours. ## Any server (self-attested) `--provider generic` is for a server bought or installed by hand. `deploy` creates the tunnel and DNS, writes `install.sh` (private) and `install.redacted.sh` (to publish), and waits. Copy `install.sh` to a freshly installed Ubuntu 24.04 server and run it there: ``` sudo bash install.sh ``` It records the host as it was (logins, accounts, `authorized_keys`, listening sockets, services, scheduled jobs, packages), installs the commit, enables a host firewall, deletes itself, masks SSH and ends the session. The report for such a server is at best **SELF-ATTESTED**: whoever ran the installer had root before it, and no provider record is available to the verifier. It is still better than an unexplained server: the inventory, the installer hash and every later login are signed. ## Verify The verifier needs `deployment.json`, the published installer, read-only credentials and, ideally, a checkout of the commit and an evidence ZIP: ``` git clone -c core.autocrlf=false https://github.com/phishdestroy/TgWitness.git checkout git -C checkout checkout 0123456789abcdef0123456789abcdef01234567 python -m tgwitness.cloud verify --record deployment.json \ --provider-token-file read-only.token --cloudflare-token-file cloudflare-read.token \ --fingerprint COLLECTOR_FINGERPRINT --cloud-init cloud-init.redacted.yaml \ --source checkout --evidence tgwitness-evidence.zip --report report.md ``` Every provider and Cloudflare value is requested by the verifier at that moment; the record supplies only the IDs to ask about. The exit code is 0 for **PASS**, 1 for **FAIL** and 2 for **REVIEW**, **INCOMPLETE** or **SELF-ATTESTED**. `--fingerprint` should come from an independent channel; without it the key is compared with the operator's record only. `python verify.py` still verifies the evidence ZIP itself, as in [Evidence](https://phishdestroy.io/tgwitness/docs/reference/evidence/). Provider actions are classified: creation and start within 30 minutes of creation pass; console, rescue, password reset, rebuild, ISO, images, snapshots, backups, Systems Manager, EC2 Instance Connect and firewall openings fail; power actions and anything not expected are marked for review. An unknown action never passes silently. ## Report for evidence handover `--report report.md` writes the Markdown report and `report.json` beside it: 1. result, collector key fingerprint, deployment, provider, commit, server, firewall, tunnel; 2. every check with its status and source (provider API, Cloudflare API, collector statement, evidence journal); 3. the provider log with each action's assessment and, where the provider records it, the actor; 4. the Cloudflare endpoints holding the tunnel's connections, configuration and audit log; 5. the signed collector statement; 6. what the report covers and what lies outside its scope; 7. commands to reproduce it, and the SHA-256 of every file it was given. Hand over the report, `report.json`, `deployment.json`, the published installer and the evidence ZIP. Produce the report early: provider logs are kept for limited periods. ## Cloudflare as an outside witness Everything here is optional. Without a Cloudflare account the server still runs, and two of these work today: | What | What it shows | In TgWitness | | --- | --- | --- | | Quick tunnel or your domain's tunnel | the panel is reached only through the tunnel | the server wizard, see above | | drand relay `drand.cloudflare.com` | records after a drand round are newer than it: the journal was written as it went | evidence mode, **More witnesses**, no account ([format](https://phishdestroy.io/tgwitness/docs/reference/evidence/#optional-records-in-evidence-mode-drand-and-telegram-devices)) | | Tunnel health notifications | when the tunnel was down, by email or webhook from Cloudflare | set them in the Cloudflare dashboard | | Gateway DNS (`--gateway-dns`, or **Cloudflare Gateway DNS** in the wizard) | every name the server looked up, answered by Cloudflare over TLS; the Hetzner firewall lets DNS reach nothing else; whether a Gateway policy could rewrite answers | Hetzner, free Zero Trust plan, no domain; `verify` checks the firewall, the location, logging, policies, the server's queries and the audit log; evidence mode copies the log into the journal | | Gateway with the Cloudflare One client on the server, an outbound firewall that allows only Cloudflare | every connection the server made, not just DNS | not built yet | | Access in front of the panel | who signed in to the panel and when | not built: needs your own domain | | SSH command logging | each command in a debug session | not built yet | Logpush, which would keep Cloudflare's own copy in R2, is an Enterprise feature: on the free plan Cloudflare answers `logpush is not enabled for this account`. Its Gateway log lasts 24 hours there, so evidence mode copies it into the signed journal (**Cloudflare Gateway's log of this server's DNS queries**, a read-only token with Account Analytics Read). `--gateway-location ID` (with `--gateway-dns`) uses an existing Gateway DNS location, given by its 32-character ID, instead of creating one; `destroy` leaves it in place. Without a Zero Trust plan an account has one DNS location. When Cloudflare refuses another, the server shares the existing one and its queries are told apart by its address; that filter needs Zero Trust PII Read as well, and `destroy` leaves a shared location. One log query spans at most three hours, so the copy and `verify` read the day in three-hour windows. Gateway DNS covers the system resolver. DNS over HTTPS on port 443 to another resolver, and connections to an address looked up nowhere (Telegram's data centres, for one), are not in its log. Cloudflare cannot see inside Telegram's encryption, other devices on the Telegram account (evidence mode's device list records them from Telegram's side) or the provider's hypervisor. ## Reading the deployment result For an ordinary VM, the provider controls the host infrastructure, and local inventory is checked alongside provider records. For Intel TDX, the verifier additionally checks the hardware quote, collector binding, compose and OS measurements. Read the individual results to see which checks passed or were unavailable. Historical firewall detail depends on the provider; Linode retains rule versions. The [validation record](https://phishdestroy.io/tgwitness/docs/reference/verification/) lists tested deployments and remaining live checks, and [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) connects these environment checks to archive acquisition and integrity. --- # TgWitness Panel: Chats, Journal & Exports Canonical page: https://phishdestroy.io/tgwitness/docs/reference/panel/ Navigate TgWitness chats, sources, the signed journal, exports and account controls. Review panel actions, capture status and optional investigation tools. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Every screen of the panel: chats, journal, sources, exports, Extras, protection modes and the code check. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Getting started](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) ![Getting started](https://phishdestroy.io/tgwitness/assets/chapter-start.svg?v=443547f9bcd2) [First setup and settings](https://phishdestroy.io/tgwitness/docs/reference/settings/) · [Accounts](https://phishdestroy.io/tgwitness/docs/reference/accounts/) · [Export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/) · [Case reports](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) What each screen does, what it writes to the signed journal and where the detailed guide is. The panel shows one workspace at a time: one Telegram account with its own sources, journal and signing key. The account selector in the top bar switches workspaces. The address carries the workspace (`?ws=…`); while the address, the selector and the loaded account disagree, actions stay blocked. Use [Compare collection methods](https://github.com/phishdestroy/TgWitness/blob/main/docs/COLLECTION-MODES.md) to choose between live observation, full history, fresh account/chat exports and saved-record handover. The Exports page includes the same comparison above its download controls. **On this page** - [Find your way](https://phishdestroy.io/tgwitness/docs/reference/panel/#find-your-way) - [Start here](https://phishdestroy.io/tgwitness/docs/reference/panel/#start-here) - [Chats](https://phishdestroy.io/tgwitness/docs/reference/panel/#chats) - [Journal](https://phishdestroy.io/tgwitness/docs/reference/panel/#journal) - [Sources](https://phishdestroy.io/tgwitness/docs/reference/panel/#sources) - [Exports](https://phishdestroy.io/tgwitness/docs/reference/panel/#exports) - [Settings, accounts and connection](https://phishdestroy.io/tgwitness/docs/reference/panel/#settings-accounts-and-connection) - [Extras](https://phishdestroy.io/tgwitness/docs/reference/panel/#extras) - [Protection modes](https://phishdestroy.io/tgwitness/docs/reference/panel/#protection-modes) - [More tools](https://phishdestroy.io/tgwitness/docs/reference/panel/#more-tools) ## Find your way The sidebar keeps six daily sections together: **Home**, **Chats**, **Journal**, **Exports**, **Accounts** and **Settings**. Sections that your access does not permit are omitted. **More tools** contains investigation and administration tools. Open **Appearance** at the bottom of the sidebar to change the language, theme, time zone or interface level: | Level | Sections in the sidebar | | --- | --- | | Simple | The daily sections | | Standard | Also Case Board, Sources, Access and Documentation under More tools | | Expert | Also System map, Network topology, Extras, Ask the archive, Parameters, Account, System log and Integrations under More tools | Section names stay the same at every level. A level only hides sections. A hidden feature keeps working, and the server checks every permission on its own. Level, language, theme and time zone are saved per operator and workspace; see [settings](https://phishdestroy.io/tgwitness/docs/reference/settings/). Use **Go to a section** at the top of the sidebar (Ctrl+K, or ⌘K on a Mac) to find a chat, a parameter or a journal record by `#number`. Arrow keys move, Enter opens, Esc closes. The top bar has: - **Notifications**: problems and chat changes worked out from the journal. **Mark all as read** clears the counter and **Notification rules** opens the rules. Delivery to Telegram, Discord or email is set up in [Extras → Notifications](https://phishdestroy.io/tgwitness/docs/reference/panel/#notifications). - A collection-status menu with the start/pause control, connection settings and health diagnostics for Telegram, event intake, sources and the attachment queue. On a narrow screen, open it with the activity icon. - **Lock**: closes the panel in this browser. Collection keeps running on the server. The version and protection mode are under **Appearance**; see [protection modes](https://phishdestroy.io/tgwitness/docs/reference/panel/#protection-modes). An installation opens **Home** after sign-in; an explicit link opens its requested screen. A chat-scoped reviewer opens **Chats**. The addresses `/home`, `/case-board`, `/pseudo-secret` and `/network-topology` also open their corresponding screens. Unknown page addresses return HTTP 404 with nearby page suggestions. The demo workspace contains fictional messages and never connects to Telegram. Actions that would change a real workspace are refused there. [System map](https://github.com/phishdestroy/TgWitness/blob/main/docs/SYSTEM-MAP.md) shows this installation's account routes, proxy state, socket endpoints, encrypted vaults, evidence services and observed network requests. Select an account to inspect its path. Available but disabled services stay visible. ## Start here The overview clears its account-specific chart and summary when you switch accounts or sign in again. Loading, failed reads and a period with no saved records have separate states. **Retry** repeats the failed read; if the server requests a wait, the next attempt time appears. A failed refresh keeps the last successful data for the same workspace and labels it with its last update time. Each connected account shows **Collector heartbeat** and **Last event received** separately. The first is collector activity; the second is the latest Telegram update received. A quiet source can leave the second time unchanged while the collector keeps running. Open the collection-status menu for connection, intake, source and attachment diagnostics. Choose a task. **Export my account** downloads what the account can read now. **Follow an investigation** records new messages, observed edits and deletion notices from the chats you choose. While observation is paused, Chats, Journal and Sources show the setup card: connect the account, choose sources, start observation. With the goal **Evidence for a case**, or in the Witnessed, Case preparation, GitHub-verified or Maximum [protection mode](https://phishdestroy.io/tgwitness/docs/reference/panel/#protection-modes), starting observation first reads Telegram's session list (not while **Strict: read only the chosen chats** is on). If other sessions are signed in, the panel names their number and offers **Start anyway** or **Open Sessions of this account**. Other goals and modes start without that question. The goal question stays on this page until you answer or skip it. A new workspace opens the [first setup](https://phishdestroy.io/tgwitness/docs/reference/settings/) instead. ## Chats Saved conversations, read-only by default. Chat rows show collection state, pending and failed file downloads, initial history loading and restrictions returned in Telegram's dialog metadata. A lost or unconfirmed access state does not identify a content ban. Open **Filters** to select these states or sort by the file queue; the selection stays in the URL when the page is reloaded. The **Retry** filter finds initial chat loads waiting after an error. Their badge shows the error type and, while collecting, the next attempt time. Home summarizes how many loads need another attempt. Paused collection retains the jobs until it resumes. In **Simple** mode Home also shows **Can be handed to a court: yes** or **no · missing: …**. Yes means timestamps are on with an RFC 3161 authority and that authority recently returned a timestamp that validated against its root certificate; each export asks for a new one for its last record. The line names the missing item otherwise. It does not check the signing key: the recipient confirms its fingerprint, received separately, and runs `verify.py` with `--tsa-ca` and the authority's root certificate. A Bitcoin proof, a witness post or an attested collection run can also meet the minimum there but are not counted here. Preserved-attachment journal entries show the observed type, name and byte size. New download outcomes also retain the media kind and duration when Telegram provides them. Older signed records stay unchanged; absent metadata is not reconstructed. - Search the list by name or ID. Several words match in any order, including a name and part of an ID together. The **+** button opens **Add a chat or channel** (adds or removes watched chats), **Open Telegram link** and **Pseudo-secret · Start chat**. **Open Telegram link** takes a username or invite link and saves a preview to the journal; a search for an @username or t.me link with no match offers the same. **Join / open and observe** then joins the chat and adds it to your sources; opening a bot sends it `/start`. - Pseudo-secret chats appear in the same list, green with a lock, and open in Pseudo-secret. When observation is off the list shows one **Observation off** line with **Start observation**. - The quick filters are tabs in one row: **All**, **Pseudo-secret**, **Priority**, **Changes** (saved edits or deletion notices), and **Needs attention** (lost or unconfirmed access, messages not found on recheck, failed media, history retries or Telegram restrictions). Tabs with nothing in them are hidden. Counts respect the search and type filter; a quick filter replaces the state filter. These choices stay in the URL for reloads and Back/Forward navigation. **Needs attention** does not label a message as deleted. Type, state and custom sorting remain visible as removable chips when **Filters** is collapsed. - Large lists show 80 matches at a time; **Show more** adds the next 80. The open chat and a focused row stay available when they match, even outside that batch. The counter shows displayed chats out of all matches. Search covers the entire list, including chats that have not been displayed yet. - From search, **↓** moves to the first result, **↑** to the last displayed result, and **Enter** opens the first match. Within the list, **↑/↓** and **Home/End** move focus; **Enter** opens the focused chat. **Escape** returns to search, where pressing it again clears the query. **Clear filters** resets the list without changing collection or the open conversation. - The chat header counts messages **deleted, text kept**, **deleted before saving** and **not found on recheck**. Each count is a button that shows only those messages; press it again to show all. **Deleted** and **Not found at recheck** on a message open a note with the time and what was observed. The chat list and notifications use the same definitions. A deleted message is red and keeps its saved text; an edited message keeps every saved version. - **Search saved messages** searches the complete retained chat, including earlier text versions. Deleted, edited, media and author filters also cover the complete retained chat. **Not found at recheck** is separate from received deletion notices. Search does not request messages from Telegram; use **Load history** to acquire more. A match in an earlier version opens the saved versions with their journal links. **Displayed version** identifies the record used for the message and its bookmark; a late history response cannot replace a newer live edit on screen. - Between messages the chat shows two kinds of gap markers. **Message numbers not observed** lists numbers the journal has no record for, in channels and supergroups only: other chats share one account-wide numbering, so a jump there says nothing about the chat. **Coverage gap** marks a period between a recorded interruption and the next recorded resumption, with the reason when the journal has one. The markers appear with all messages shown and hide while a message filter is on. - **Build report** above the messages opens the report studio with this chat selected. The same button in an author's person card selects the chat and that author. Both change only the draft; save it before exporting. - Pressing an author's name opens a person card beside the messages: saved profile, bio, profile photos, gifts, links, message counts and the activity timeline with its journal records, plus **Refresh profile** and **Build report**. **Close**, Esc or another chat closes the card; the chat keeps its position. **Rhythm** in the card counts the author's saved messages in this chat in UTC: active days, starts after 6 hours of silence, median time to reply to someone else within 24 hours, the longest run of consecutive messages, the share sent between 00:00 and 06:00 and a weekday × hour heatmap. - **Select** above the messages turns on message selection: press messages to mark them, Shift-press to mark a range, or use **Select shown**, then **Build report**. The report studio opens with **Selected messages** filled in. The report covers the message records of those messages (observations, edits, deletion notices) that pass the other filters; an author filter leaves out deletion notices, which carry no sender. Up to 1,000 messages can be selected; a chip in the studio removes one message, and whole chats can be added next to them. Missing message numbers are reported only for chats selected in full. - **Load history** brings the last 100, 250 or 500 messages into this view and the journal. Find it in **Chat actions**, alongside recording settings, read-only and secret-masking controls. The menu closes with Escape or a click outside it. Loading earlier messages keeps the current reading position. If the query or page changes while Telegram responds, the completed load updates the saved journal without replacing the newer view. A failed automatic load offers **Retry**. To load every enabled source, use [Sources → Full history](https://phishdestroy.io/tgwitness/docs/reference/panel/#sources). - **Export chat** downloads the whole visible history as a signed `chat.json` and `chat.html`. Several connected accounts can share the work: each downloads its own range of message numbers and signs its part, and the account that starts the export signs the archive. See [export one chat](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Chat-Export.md). - **People** lists everyone with saved messages in this chat. People profiles are off by default because they are personal data about third parties. When they are on for a chat, a profile shows name and username history, Telegram flags, avatar hashes, activity, who replies to whom, other observed chats, and mentioned wallets, phones, usernames and links. Every fact points to its record. **Export profiles** saves a signed file, optionally in a password ZIP; turning profiles off deletes the profile file. See [people profiles](https://phishdestroy.io/tgwitness/docs/reference/evidence/#people-profiles). - **Collect all authors** on the same tab asks Telegram for the profile, bio, profile photos, gifts and bio links of everyone with saved messages in the chat. In a channel or supergroup other connected accounts can share the work. Each chosen account is reserved for the collection, takes whole people and reaches an author through one of that author's saved messages. An account busy with another task is not touched and joins once it is free. An author it cannot reach goes back to the chat's own account. Progress shows the percentage, the time left and each account's share; **Pause** releases the accounts. Every saved record names the account that read it, and the journal records when each account joined and left. - **Save profile now** records a snapshot of the chat or bot profile: description, members, invite link, bot commands. ### Read-only, sending and secrets Two switches above the messages protect the account and the reader: - **Read-only** is on when a chat opens. Turn it off to send messages or press bot buttons. Each action asks **Send as @account?** or **Press this bot button as @account?**, tells you that chat members see it and that it goes into the signed journal. **Do not ask again for 10 minutes in this chat** skips the question for a while. Sending is off for the **Evidence for a case** goal, in the panel and in the API. - **Mask secrets** hides what looks like a password, a login code, an API key or hash, a bot token, a session string, a private key, a JWT or a payment card number (card numbers are checked with the Luhn sum). **Show** reveals one value; the reveal is recorded in the journal. Turning masking off for this browser is recorded too. Only the display changes: the original records and every export keep the full text. ### Save selected messages as images In a cloud chat, choose **Select**, mark the messages, then choose **Save as image**. To capture a whole chat, choose **Save chat as images** in the chat tools menu; it loads up to the latest 2,000 saved messages and says when older ones are left out. The preview offers **Light**, **Dark** and **Classic** styles; use Previous and Next for longer captures. **Download signed ZIP** saves every page as PNG together with `pages.sig.json` and `README.txt` ([signed chat images](https://phishdestroy.io/tgwitness/docs/reference/evidence/#signed-chat-images)). Up to 50 messages may be selected, and all of them must still be in the loaded chat window. The panel asks you to reduce an oversized selection instead of silently dropping messages. Every page ends with an authenticity block: the journal record numbers it shows, the chat, the render time, the workspace key fingerprint, the `verify.py` command for that page and a QR code with the chat, key and render time. Signing requires the export permission and adds an `export.image_attested` record to the journal. The image includes the saved text, author, message number, UTC time, reply number, attachment labels and saved edit/deletion status. It uses the latest saved text with the number of retained versions; attachment contents, inline buttons, reactions and earlier text versions are not rendered. A long message continues on the next page with its message number and part count. Each page identifies itself as rendered from saved messages. The PNG is a visual excerpt; use the archive and its verifier when handing over the signed records and attachments. Rendering happens in the browser without making a Telegram request; for signing, only each page's SHA-256 and record numbers are sent to the panel. The existing secret masker protects text, author names and attachment labels. The preview holds a snapshot until closed and clears on panel lock or a workspace/chat change. The signed journal and report selection remain unchanged. See [case reports](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) for complete report exports. ### Forward messages Turn off **Read-only** for the chat, then choose **Forward** under a message, or **Select**, mark up to 100 messages and choose **Forward**. Pick the destination by name: the list holds saved chats and the account's Telegram chats where it can post (groups, private chats, bots and channels it administers). The panel asks for confirmation, then forwards natively through Telegram with the account's message pace. The request and its result are signed journal records naming the source chat, message numbers and destination. Copies are saved in the destination only when that chat is observed. A chat that forbids forwarding returns a refusal and nothing is sent. ### Forward a chat to a channel or group The main administrator can open a saved cloud chat and choose **Forward chat** from its tools menu. Choose **New channel**, **New group**, or **Existing channel or group**. New destinations are private. For an existing destination, **Choose a chat** lists the account's groups and the channels it administers; search by name. The destination must allow this account to post. Forum destinations are not supported. Pause observation or another active account job and enable Telegram actions before previewing. Read-only accounts and the **Evidence for a case** goal block transfers. **Preview** reads the accessible Telegram history boundary and checks the destination. It does not create a destination or send messages. **Start** starts the transfer; the preview expires after ten minutes. One transfer can be active per workspace. The transfer reads Telegram history from oldest to newest, through the last message seen in the preview. It is not limited to the messages already saved in TgWitness. Messages arriving above that boundary are excluded. Native forwarding preserves Telegram's available author attribution and media without downloading and uploading copies. Albums within the boundary stay together. Notifications are silent. Replies, topic structure, reactions, edits and deleted or inaccessible messages are not reconstructed. Secret Chats are outside this workflow. Telegram's content protection and posting restrictions remain in force. The panel shows confirmed sends, skips, state and the next allowed attempt time. Service messages and individually protected messages are skipped with a recorded reason. Account message spacing and hourly limits apply to every message; an album waits until its reserved slots are due. FloodWait and slow-mode pauses update the account's shared RPC backoff. The account's existing pacing defaults remain unchanged. **Pause** stops between requests; **Cancel** stops remaining work without removing messages already sent or deleting a created destination. An in-flight request may finish before either action takes effect. Closing the dialog does not cancel a job. After a process restart, unfinished jobs require an explicit **Resume**. A lost or incomplete send response pauses the job for review: inspect the destination before resuming. A retry retains the stored Telegram random IDs and confirmed counts; this is not a guarantee of indefinite deduplication by Telegram. An unknown creation result cannot be resumed automatically: check Telegram and cancel the old job before starting a new transfer to the destination that was created, if any. If saving a job or its journal entry fails, the worker restores the last saved state and releases the account. A send or creation that may already have reached Telegram remains marked for review. Retry a failed start or resume after storage is available again; confirmed progress advances only with its journal entry. Signed `interaction.forward.*` journal entries record the boundary, destination, confirmed source/destination message IDs and skips. They document the transfer; they do not replace the original signed observations and exports. ## Journal Every record the workspace has signed, newest first. - **Overview** counts observed messages, recorded edits, deletion notices and selected sources. - **Event timeline** filters by event type (all, edits, deletions, reactions, membership, coverage), by text and by source. **Load earlier events** pages back. - Open a record to see its details, hash and payload. **Link to this record** is an address that opens the same record. Possible secrets are masked in this preview; exports keep the original. - The journal is append-only: nothing in the panel edits or deletes a record. Check it with **Exports → Verify journal** or `python -m tgwitness.verify`; see [export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/). ## Sources Which conversations this workspace records, and what it keeps from them. Changes apply to future activity; saved records stay. **Refresh chat list** reads the account's chats and folders. It does not download messages. ### Scope - **What this account records**: **Chosen chats** (only the chats you add), **Telegram folder** (one of the account's folders, including chats added to it later) or **Whole account** (every chat, and every new chat, group, private chat or bot as it appears). **Investigation mode** is for a dedicated account: it records everything the account sees, its own messages and button presses, and saves each new chat's profile and earlier visible messages straight away. The [dedicated account guide](https://phishdestroy.io/tgwitness/docs/dedicated-account/) explains why never to use your main account. - **Strict: read only the chosen chats** (Chosen chats only, off by default) stops reads of Telegram's service notifications, the session list and earlier messages of a chat being turned on, leaves the sensitive content setting alone and skips phone call updates. See [strict chosen chats](https://phishdestroy.io/tgwitness/docs/reference/collection/#strict-chosen-chats). - **Source types** limit folder and whole-account modes to channels, groups, private chats and bots. **Own actions** adds the account's own messages, edits and reply-keyboard presses. - **When a new chat or bot appears**: save its profile and up to the chosen number of its latest visible messages. - **Chosen chats** is marked as recommended. **Discard changes** returns the form to the saved scope until you press **Save scope**. [Pseudo-secret](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/) is the included Secret Chat interface, enabled per account after installing its protocol module with one button. Cloud observation and history use their own settings. Nothing is recorded while TgWitness is not running; after a restart it catches up only what Telegram still returns, and the report shows the gap. Chats beyond the chat list limit (1,000 dialogs unless changed in Parameters) are added when they next become active. Inline bot buttons pressed in another app are invisible; the bot's reply is recorded. ### Chats in scope Filter by status (**Enabled**, **Paused**, **Priority**, **Excluded**, **Unconfirmed access**, **Ignored**) and type, then act on a selection: enable, pause, mark or remove priority, exclude from scope or remove. The status badge only shows the state; actions are in each row's menu with a line on what they do. Pausing and excluding ask for confirmation, also in bulk. Removing a source asks for its name and deletes its people profiles; its saved records stay in the journal. A source the account's chat list does not show is **receiving updates, not in the chat list** while records keep arriving, otherwise **access unconfirmed**. **Available chats** adds chats with **Add selected** or **Add all matching**. ### Full history Loads the available history of every enabled source into Chats and the journal. Progress survives a restart; attachments follow your media settings. See [source history](https://phishdestroy.io/tgwitness/docs/reference/history/). ### Recording - **Choose which changes to preserve**: new messages, edits, deletion notices, visible reactions, joins and leaves. A preset changes the form; **Save recording settings** applies it. Turning a category back on does not recover missed events. - **Preserve media when available**: download attachments up to a size per file, set per type from 1 to 2,000 MiB, and limit video length in seconds (0 means no limit). Every download attempt gets a recorded outcome. - **Recheck**: priority chats every few minutes, other chats rarely, so the account stays clear of Telegram's FloodWait limits. 0 turns a group off. Mark priority chats with the star in the list; chats per pass and the pause between chats are in Parameters. See [collection](https://phishdestroy.io/tgwitness/docs/reference/collection/). - The save bar says whether these settings match the recommended ones. **Return to recommended** fills in the recommended values; **Save recording settings** applies them and **Discard changes** restores the saved ones. ## Exports **Downloads** prepares files; **Build report** chooses how reports look. | What | Use it for | Guide | | --- | --- | --- | | Account export | A fresh snapshot of what the account can read now | [Account export](https://phishdestroy.io/tgwitness/docs/reference/account-export/) | | Sharing copy | A minimized derivative of a finished account export | [Disclosure](https://phishdestroy.io/tgwitness/docs/reference/account-export/#prepare-a-disclosure-for-a-lawyer-or-another-recipient) | | Signed ZIP | Journal, report, attachments and verification tools at a fixed journal boundary | [Export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/) | | HTML, PDF, JSON report | A sealed readable report | [Case reports](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) | | JSONL, CSV | Original records with signatures; a formula-safe spreadsheet | [Export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/) | | Handover extract | Only the chats, period and people a recipient needs | [Evidence](https://phishdestroy.io/tgwitness/docs/reference/evidence/#investigation-handoff) | | Chat export | One chat as signed `chat.json` and `chat.html` | [Export one chat](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Chat-Export.md) | - **Encrypt the downloads above with a password** (12 characters or more) saves an AES-256 ZIP that 7-Zip or WinRAR opens. The signed file inside is unchanged. The password is not stored. - When the session key of this workspace was imported, the account export and chat export dialogs say so in one line: copies of that key can exist outside Telegram's session list. The same line offers **Create an independent authorization**, which opens the sign-in page with that option selected. See [accounts](https://phishdestroy.io/tgwitness/docs/reference/accounts/#create-an-independent-authorization). - A chat export that fails or is cancelled keeps the range it saved. **Capture or export one chat** then offers **Resume export** and **Start over**; see [export one chat](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Chat-Export.md). - While a chat export reads, **Download messages read so far** saves a ZIP whose pages are signed as they are written; the line under it counts the signed messages. - **Prepared exports** keeps up to 20 files within 2 GiB, plus the latest one, for repeat downloads, each with its SHA-256 for the recipient to compare. Each card names what the file holds: **Signed archive** (complete journal and its record count), **Report**, **Journal records** or **Handover extract**, the case title and ID, and the report selection it was built with (chats, chosen messages, dates). **Show** narrows the list to one kind when it holds more than one. - When the browser refuses its save dialog, the panel falls back to an ordinary download. - **Your signing identity** shows the key fingerprint. **Save checkpoint** and **Download signed run receipt** give you records to keep outside the collector. **Prepare timestamp request** builds an RFC 3161 request without contacting any service. ## Settings, accounts and connection - **Settings**: goal, connection, what to record and the interface. See [first setup and settings](https://phishdestroy.io/tgwitness/docs/reference/settings/). - **Accounts**: every workspace with its state, sources, events and attachment queue. Filter by **Needs attention**, **Collecting**, **Offline or paused** or **Not connected**, pause or resume a selection, import account files in bulk and manage groups. See [accounts](https://phishdestroy.io/tgwitness/docs/reference/accounts/). - **Account**: sign-in and the connection route of this account. Direct, a WireGuard profile, your own proxy, the public MTProto pool or WARP; prepare and check a route, then apply it to this account, a group or all accounts. See [connection and proxies](https://phishdestroy.io/tgwitness/docs/reference/connection/) and [proxies](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Proxies.md). **Account security → Sessions of this account** lists Telegram's sessions, ends one or all of them, and — for a key created in this workspace — offers **Make this the only session when Telegram allows it**, which repeats that action after the 24 hours Telegram requires and shows the two-step password it sets once. See [account security](https://phishdestroy.io/tgwitness/docs/reference/accounts/#create-an-independent-authorization). **Account security → Witness probe** uses a second workspace to check that this session receives updates live; see [witness probe](https://phishdestroy.io/tgwitness/docs/reference/accounts/#witness-probe). Bulk pause and resume keep the confirmed selection within the session where it was opened. Controls stay disabled while confirmation or execution is pending; changing workspaces or locking the panel cancels the remaining commands. After execution, the panel refreshes account states. A failed request is reported as a request failure, because the server may already have applied the command. Commands are not automatically repeated. ## Extras Optional: an account and sources are enough to start collecting. Only the option you choose opens its settings, and nothing is connected automatically. The **Protection level** card at the top shows the [protection mode](https://phishdestroy.io/tgwitness/docs/reference/panel/#protection-modes). | Card | What it adds | Guide | | --- | --- | --- | | Storage & disk space | Backups, moving older files to your cloud, an evidence copy that cannot be deleted | [Storage](https://phishdestroy.io/tgwitness/docs/reference/storage/) | | Goal & protection level | Suggested settings for your goal and two scales | [below](https://phishdestroy.io/tgwitness/docs/reference/panel/#goal-and-protection-level) | | Notifications | Problems, changed messages and a daily summary; your own control bot | [below](https://phishdestroy.io/tgwitness/docs/reference/panel/#notifications) | | Evidence & backups | Timestamps, more witnesses and an encrypted off-site copy | [below](https://phishdestroy.io/tgwitness/docs/reference/panel/#evidence-and-backups) | | Server 24/7 | A cloud server without SSH, created and deleted from the panel | [High assurance](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#from-the-panel) | | Independent witness | Signed checks posted to your Telegram channel or Discord | [Witness](https://phishdestroy.io/tgwitness/docs/reference/witness/) | | Code check | Compares the running program with a public GitHub commit | [below](https://phishdestroy.io/tgwitness/docs/reference/panel/#code-check) | ### Goal and protection level Four questions: 1. **What is it for?** A personal record, an investigation, or evidence for a case. 2. **How much will you observe?** A few chats (up to about 50), many chats (up to about 500) or whole accounts. This sets the chat list limit to 1,000, 3,000 or 20,000. 3. **Photos and files?** Text only, photos and short media (photos 20 MB, videos 100 MB), or everything (videos and documents up to 1 GB each). Everything with whole accounts also keeps 4 GiB of disk free. 4. **Where will it run?** This computer, or a server that is always on. The suggestion lists independent timestamps, drand and Telegram's device list, each with a line on what it adds. Timestamps start every 60, 30 or 10 minutes for a personal record, an investigation or evidence; drand and the device list need timestamps. **Apply** changes only these, the attachment policy and the two parameters above. Each change is a journal record, plus `setup.applied`. Notifications, an off-site copy, a server, Gateway DNS, the code check and a witness are offered as next steps with their own forms. Two scales are computed from what is set, not from the goal: | Scale | Points | | --- | --- | | Credibility | Signed journal 1, timestamps 3, drand 1, device list 1, code check that matches 1, witness polling 1, attested server 2, Gateway DNS log 1 | | Reliability | Always-on server 3, off-site copy 3, Object Lock 1, problem notifications 1 | 80% or more reads **maximum**, 50% **high**, 25% **moderate**, below that **basic**. Reliability currently counts an always-on server from the answer to question 4, before any server is checked. ### Notifications Notifications go through Apprise to Telegram, Discord, Slack, ntfy, email, Matrix and 100+ other services. Pick a service, fill in one or two fields and send a test, or paste Apprise addresses directly. - **Problems**: disk almost full, account signed out, collection, copy or timestamp errors, a new session signed in to the account with the device, application and country Telegram lists, a login code or new sign-in that Telegram reports during observation, and another session after **Make this the only session**. On a sealed server, an opened SSH port or a login is a problem too. - **Changes**: deleted, edited and missing messages in observed chats, grouped into one notification per check (every minute unless changed in Parameters). - **Completed tasks**: history, exports and storage copies. - **Watchlist hits**: matches from watchlists set to send an alert. - **Daily summary** at the chosen hour, server time. Notifications carry chat names and counts. Message excerpts are off by default; with them on, message text leaves this machine. **Your operator bot** is a bot of your own from @BotFather that answers `/status` and `/stats`, and optionally `/pause`, `/resume` and `/copy`. Only the listed chat and Telegram user IDs can use it; conversation text stays in the workspace. Use a separate bot if another application already receives its commands. See [notifications](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Notifications.md) and [operator bot](https://phishdestroy.io/tgwitness/docs/reference/storage/#operator-bot-and-completion-notices). ### Evidence and backups - **Independent timestamps** send only the SHA-256 of each signed checkpoint to RFC 3161 authorities and OpenTimestamps calendars, every 5 to 1,440 minutes. A recipient needs such third-party time for the minimum for evidence. **Anchor now** runs a pass. See [timestamps](https://phishdestroy.io/tgwitness/docs/reference/timestamp/). - **More witnesses**, each off until chosen: the newest drand round, Telegram's list of signed-in devices without IP addresses, and Cloudflare Gateway's log of the server's DNS queries. See [optional records](https://phishdestroy.io/tgwitness/docs/reference/evidence/#optional-records-in-evidence-mode-drand-and-telegram-devices). - **Encrypted backup** copies the journal, files, checkpoints and chat exports to S3-compatible storage (Wasabi, Amazon S3, Backblaze B2, Cloudflare R2, MinIO). Everything is encrypted on this machine first. **Download encryption key** and keep it apart: without it the copy cannot be read. Object Lock in Governance or Compliance mode keeps objects from deletion for a set number of days. See [off-site copy](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Off-site-Copy.md). ### Code check Checks whether the installed program matches a published version. 1. Enter a GitHub repository (the official one is filled in) and a tag, branch or commit. 2. **Check now** asks GitHub's API, through this workspace's route for outside requests, for that commit's file list. It compares the git blob ID of every measured program file with the commit. A Windows checkout with converted line endings still matches. 3. The result lists changed, extra and missing files (up to 50 of each) and is saved as a `source.checked` journal record. The result counts as current only while the running program files are unchanged: check again after an update. No token is needed and only public repositories work; chats and credentials are not uploaded. A match identifies the code on disk. It is not hardware attestation; for that, see [Phala Cloud](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx). ## Protection modes The switcher next to the version number shows the chosen mode and how many of the 18 protection layers are active, for example `🟠 Witnessed 9/18`. **Change mode** in **Extras → Protection level** opens the choice. A mode describes a target and lists what is still missing; recording, signing and saved settings are the same in every mode. | Mode | For | Adds | | --- | --- | --- | | 🟢 Easy | Watching a chat and keeping a copy | Chats, the journal and chat exports; signing runs in the background | | 🟡 Signed | Reports to a platform, a host or an abuse desk | Signed archive, journal check, checkpoints, handover extract | | 🟠 Witnessed | Cases where someone may claim the record was changed | An independent witness posting signed journal heads | | 🔴 Court-ready | Evidence for a lawyer, the police or a court | Timestamps, an encrypted off-site copy, case details in reports | | 🟣 GitHub-verified | Records whose software anyone must be able to check | Code check and GitHub Actions capture | | ⚫ Maximum | High-stakes cases against a well-funded adversary | A sealed 24/7 server, a hidden IP address, all 18 layers | The layers: every record signed and chained; a signed run receipt; attachments saved with SHA-256; signed checkpoints; rechecks; problem alerts; read-only witness access; a witness checking on schedule; RFC 3161 timestamps; OpenTimestamps proofs; a verified latest timestamp; an encrypted off-site copy; case details in reports; a matching code check; Telegram never seeing this machine's IP; outside requests through a proxy; Object Lock on the copy; a sealed server with provider records. A layer that is off has **Set up**, which opens its form. Choosing a lower mode asks for confirmation and deletes nothing. ## More tools **Extras → Independent capture**: connect a separate browser or AyuGram recorder, pin its signing key, select capture options, start/pause, take snapshots and download verified signed archives. Each recorder has its own manual login, route, journal and key. Both connections start disabled. See the English [Independent capture guide](https://github.com/phishdestroy/TgWitness/blob/main/docs/OPTIONAL-CAPTURE.md). - **Ask the archive**: search saved observations, review the sources, then decide whether to send them to an AI model. See [archive analysis](https://phishdestroy.io/tgwitness/docs/reference/analysis/) and [local OCR and transcription](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/). - **Parameters**: limits and pace of collection, rechecks, downloads, profiles, notifications and exports. Search by name, show **Only changed** values and prepare defaults as a draft with **Restore defaults…**. **Save parameters** applies the values from their next use, and each change is a journal record. - **Access**: separate tokens for reviewers, analysts and operators, limited to chosen workspaces, chats and rights. See [access](https://phishdestroy.io/tgwitness/docs/reference/access/). - **System log**: what this process did since it started (connections, proxy changes, sign-ins, refusals, settings changes) with IP addresses hidden. **Follow new lines** keeps the newest line in view. Messages stay in the journal only. - **Integrations**: the AI provider, [read-only MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/) connections and [signed webhooks](https://phishdestroy.io/tgwitness/docs/reference/webhooks/). - **Case Board**: private team notes, bookmarks and slices next to the evidence. See [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/). - **Documentation**: the [investigation mode](https://github.com/phishdestroy/TgWitness/blob/main/docs/INVESTIGATION-MODE.md) drawer. While a documented session is recording, it moves to the main sidebar. - **GitHub Actions capture** in Exports: one chat captured from your fork. See [sealed capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md). --- # Save Edited & Deleted Telegram Messages Canonical page: https://phishdestroy.io/tgwitness/docs/reference/collection/ See how TgWitness captures Telegram updates, keeps every edit and the text of deleted messages, and records scope, attachments, rechecks and coverage. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Observation scope, live updates, rechecks, attachments, own actions and what a gap means, record by record. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Collection](https://github.com/phishdestroy/TgWitness/blob/main/docs/COLLECTION-MODES.md) ![Collection](https://phishdestroy.io/tgwitness/assets/chapter-collect.svg?v=adb3306d1f69) TgWitness records what a connected Telegram account observes. Live monitoring preserves messages, captured edits, deletion notifications and attachments with their observation times and source context. History reads, rechecks and available admin-log records add separately identified observations to that record. **On this page** - [From login to a journal](https://phishdestroy.io/tgwitness/docs/reference/collection/#from-login-to-a-journal) - [Observation scope: chosen chats, a folder or the whole account](https://phishdestroy.io/tgwitness/docs/reference/collection/#observation-scope-chosen-chats-a-folder-or-the-whole-account) - [Scope and event selection](https://phishdestroy.io/tgwitness/docs/reference/collection/#scope-and-event-selection) - [Own actions](https://phishdestroy.io/tgwitness/docs/reference/collection/#own-actions) - [Investigation mode: joining teams and talking to bots](https://phishdestroy.io/tgwitness/docs/reference/collection/#investigation-mode-joining-teams-and-talking-to-bots) - [Recheck tiers](https://phishdestroy.io/tgwitness/docs/reference/collection/#recheck-tiers) - [Message history and attribution](https://phishdestroy.io/tgwitness/docs/reference/collection/#message-history-and-attribution) - [History snapshots](https://phishdestroy.io/tgwitness/docs/reference/collection/#history-snapshots) - [Attachment handling](https://phishdestroy.io/tgwitness/docs/reference/collection/#attachment-handling) - [Pause, lock, disconnect, and restart](https://phishdestroy.io/tgwitness/docs/reference/collection/#pause-lock-disconnect-and-restart) - [Account isolation and verification](https://phishdestroy.io/tgwitness/docs/reference/collection/#account-isolation-and-verification) ## From login to a journal For self-destructing photos and files, see [Self-destructing media](https://github.com/phishdestroy/TgWitness/blob/main/docs/EPHEMERAL-MEDIA.md). It explains the priority worker, saved and unavailable outcomes, and the limits of read-receipt blocking in the API collector. Flow diagram · Authorize a user account → Select accessible groups and channels; Select accessible groups and channels → Save event and attachment settings; Save event and attachment settings → Start observation; Start observation → Receive updates from the active client; Receive updates from the active client → Apply source and event policy; Apply source and event policy → Append a signed observation; Append a signed observation → Review or export the journal; Append a signed observation → Process any queued attachment; Process any queued attachment → Append the download outcome · Authorize a useraccount · Select accessiblegroups and channels · Save event andattachment settings · Start observation · Receive updates fromthe active client · Apply source and eventpolicy · Append a signedobservation · Review or export thejournal · Process any queuedattachment · Append the downloadoutcome **Diagram as text** 1. Authorize a user account → Select accessible groups and channels 2. Select accessible groups and channels → Save event and attachment settings 3. Save event and attachment settings → Start observation 4. Start observation → Receive updates from the active client 5. Receive updates from the active client → Apply source and event policy 6. Apply source and event policy → Append a signed observation 7. Append a signed observation → Review or export the journal 8. Append a signed observation → Process any queued attachment 9. Process any queued attachment → Append the download outcome Authorization, access to a source, a running collector, and complete delivery are different questions. A successful login does not grant access to every group. Delivery is tracked separately: coverage records, update-gap recovery and rechecks show what arrived. ## Observation scope: chosen chats, a folder or the whole account **More tools → Sources → Scope** decides which chats a workspace records. New setup starts with **Choose chats**. Existing saved choices are retained. Choosing **All chats** in the setup wizard asks for confirmation when the loaded list contains more than 50 chats; the size estimate remains a separate, sample-based operation. | Mode | Records | New chats | | --- | --- | --- | | Chosen chats (default) | Only the chats you add by hand | Never added automatically | | Telegram folder | Chats in one of the account's folders: chats included by name, plus the folder's categories (contacts, non-contacts, groups, channels, bots), minus its excluded chats and, if the folder says so, archived chats | Matching chats are added as soon as they become active; chats you add to the folder in Telegram are picked up within an hour | | Whole account | Every chat the account sees | Every new chat, group, private chat or bot is added the moment its first update arrives | - **Source types** (channels, groups, private chats, bots) narrow the folder and whole-account modes. Chosen chats can be of any type, including private chats and bots; source types never stop a chat you added by hand. A type turned off, an exclusion or a switch to chosen chats stops automatically added sources as soon as it is saved, before the source list is recalculated and also when Telegram cannot be reached: their new messages, history passes, new-chat history, peer settings and profile observations. - **Chats you add by hand** stay recorded in folder and whole-account modes even when they are outside the folder; only *Exclude*, *Remove* or a pause stops them. Chats the scope added (*auto*) follow the folder: one that leaves it is paused at the next recompute. - **Excluded chats** are never recorded, in any mode. In folder and whole-account modes, *Exclude* and *Remove* on a source put it on this list, so the scope does not add it again. Choosing the chat again by hand (in Sources, from Chats or under Settings → **Which chats?**) takes it off the list. The list holds up to 5,000 chats; past that, *Remove* is refused and the chat can be paused instead. - **Own actions** (on by default): messages this account sends, its edits and its reply-keyboard button presses. Turned off, outgoing messages and edits are skipped. - Switching to a folder or the whole account asks for confirmation: these modes record private chats and messages of third parties and belong on a dedicated account only. The confirmation and every scope change are signed `scope.changed` records. On an account set up as your main one, the scope form and Investigation refuse a folder or the whole account, as start does; only a one-time copy without recording may use them. - Chats added by the scope appear as sources marked *auto*, recorded as `scope.applied` (at start and hourly) or `source.discovered` (a new chat while observing). Switching back to chosen chats pauses every automatically added source at once, without reading the account's chat list again. An excluded chat stops being recorded as soon as the scope is saved, and its source is paused even when Telegram does not return the chat list. While observing, saving the scope applies it again, also when the values did not change. Scope of these modes: - **Secret Chats** use the included [Pseudo-secret integration](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/), with a protocol module installed from the panel and a per-account enable switch. Cloud history and Takeout use a separate acquisition path. - **Offline periods.** After a restart TgWitness resumes the saved update position, asks Telegram for missed updates and rechecks chats. Telegram keeps a bounded backlog, so after a long outage reports and `verify.py` list the remaining interval as a gap (see [coverage](https://phishdestroy.io/tgwitness/docs/reference/evidence/#coverage-continuity-gaps-and-unobserved-ids)). - Only the first 1,000 dialogs are listed at start (the limit is under **More tools → Parameters**); older chats are added when they next become active. The earlier history of an added chat is not fetched — take a history snapshot or a full chat export when you need it. - Folder conditions that change all the time (muted, read) are not applied: such chats stay observed. - **Inline (callback) bot buttons** pressed in another app are invisible to a second session; the bot's reply or edit is recorded. Reply-keyboard presses arrive as outgoing messages and are labeled `button_press`. - More chats mean more requests. Telegram restricts accounts for volume it considers excessive, which is one more reason to use dedicated accounts. ### Strict chosen chats **Strict: read only the chosen chats** appears under **Chosen chats** and is off by default. It is meant for a permission that covers the chosen chats only. While it is on: - Telegram's service notifications (777000) are not read: not when observation starts or stops and not every minute while observing. No `session.security_baseline` or `account.security_event` records are written. - The account's session list is not read: not when observation starts or stops (the panel's question about other sessions for **Evidence for a case** and the evidence protection modes is skipped too), not every two minutes while observing, not when a connection opens, and not by the connection check, whose *Current authorization* entry is shown as skipped. The two-step verification status used by the takeover check is not read either. So `account.sessions`, `session.concurrent_at_start` and `session.takeover_risk` are not written, and a session ended from another device is not reported as `session_revoked_externally`. - While this is the only session of the account (**Make this the only session** or its automatic version), the session list is still read every two minutes while observing and when a connection opens, so that `session.exclusive_ended` is recorded when another session appears. 777000 stays unread in that period, although the `session.exclusive_from` record says Telegram's sign-in notices keep being recorded. - Deletion notices are compared with a session check only if one ran in the last 10 minutes (while this is the only session, or after opening **Sessions of this account**). Otherwise, unless the last rights check shows that this account could not delete the message (never so in private chats and ordinary groups), they read: *Who deleted it is not known: this account itself, from another session or device, could also have deleted it.* - With a session key that was imported, nothing in the journal gives the time this session signed in until the session list is read (for example in **Sessions of this account**). Until then chat exports and **Automatic** account exports use the regular session instead of Takeout, with the reason `session_age_unknown`. - Turning a chat on does not read its earlier messages. Without the switch, each chat turned on (in Sources, in Chats, by joining from the panel or in the setup wizard) gets one `baseline` snapshot of its latest messages, up to **More tools → Parameters → Largest history snapshot** (500 by default), when observation next runs. A waiting snapshot that comes due while the switch is on is dropped. A chat joined from the panel does not get its latest messages read as a new chat either (the **When a new chat or bot appears** count, 100 by default), and opening a chosen chat with no saved messages in Chats does not load its last 100 messages by itself. **Load history** and snapshots you start yourself still read history. - The account's sensitive content setting is neither read nor changed. Without the switch, sign-in and each new connection turn it on when it is off and Telegram allows the change (`account.content_settings`); the setting belongs to the account and applies in every Telegram app. Content Telegram marks as sensitive may stay hidden. - Phone call updates are not recorded as `account.phone_call`. - Stopping observation writes only the session key fingerprint; it does not read the session list or 777000. It does not narrow what Telegram sends: updates of every chat still reach this session, and only the chosen chats are recorded. The account's chat list (up to **Chats read from the account's list**) and its folders are still read at start, and again when the scope is saved while observing, to find the chosen chats. Deletion notices without a chat (`deletion.unscoped`) are still recorded: they carry message IDs only and may belong to a chosen private chat or ordinary group. The frozen-account check (`help.getAppConfig`), the other connection checks, and features you turn on yourself (ending other sessions automatically, the witness probe, pseudo-secret chats, **Sessions of this account**, and Telegram's list of signed-in devices under **More witnesses**, which reads the session list at each timestamp pass and which setup ticks for the **Follow chats** and **Evidence for a case** goals) keep working. Turn it on before signing in; otherwise sign-in itself checks the current authorization and turns on sensitive content. Each change is a signed `scope.changed` record, and `observation.started` carries the value as `scope.strict`. Switching to a folder or the whole account turns it off. ## Scope and event selection Each workspace has its own sources. TgWitness does not join groups, accept invitations, or enumerate every member automatically. Sources must already be accessible to the account. At startup, the collector checks selected sources against the account's visible dialogs; the first 1,000 dialogs are inspected unless **More tools → Parameters → Chats read from the account's list** says otherwise. An absent source is marked **access unconfirmed**, not assumed to have removed you. | Setting | Collects | Effect when disabled | | --- | --- | --- | | New messages | Ordinary delivered messages | Later edits/deletions may have no earlier captured text to compare. | | Edits | Delivered edited message versions | Intermediate changes are not reconstructed later. | | Deletions | Scoped deletion notices and unscoped account-level notices | Deletion notices are not added to the journal. | | Reactions | Delivered reaction snapshots | Separate reaction updates are not added. | | Membership | Delivered membership service messages and participant updates | Those membership observations are not added. | Settings apply to all selected sources in the workspace. Save the form to apply changes; changes are recorded with signed before/after values. Disabling a category does not remove earlier records. Re-enabling it does not backfill missed updates. Operational records and other group service events remain separate from these switches. Membership service messages can create message records when membership is enabled even if ordinary new-message capture is disabled. Captured Telegram objects retain embedded metadata; a switch is not a redaction rule. **Deletions in private chats and ordinary groups** arrive as message IDs without a chat. These chats share one account-wide message ID sequence, so when a message with that ID was saved earlier, its chat is known: the deletion is recorded in that chat with `chat_resolution` explaining how. IDs never saved stay an **unscoped deletion** with an explicit unresolved chat. These are Telegram deletion notifications, preserved even when their chat cannot yet be correlated. The notification's schema contains IDs; the journal adds reception time and any saved message context, including `deleted_message_was_outgoing`. Available admin-log entries provide a separate source of the action, actor and source time. ## Own actions Messages sent by the observed account are labeled `outgoing`. An edit of an outgoing message notes that in private chats and groups only its author can edit it, while channel posts can be edited by other admins. When an outgoing message repeats the text of a button from the newest saved reply keyboard in that chat, it carries `button_press` with a link to the keyboard's record. Excluding own actions also applies to background rechecks and automatic new-chat history. Skipped outgoing messages advance the recheck position so they cannot block later incoming messages. Explicit panel actions and manually requested history snapshots remain recorded. ## Investigation mode: joining teams and talking to bots **More tools → Sources → Scope → Investigation mode** prepares the scope for a dedicated account that joins team chats, starts bots and writes to them: the whole account, every source type, own actions, and for every chat or bot that appears its profile and its latest 200 visible messages. Review the form and press **Save scope**; the switch to the whole account asks for the usual confirmation. - **Buttons.** Buttons under a message are kept with it and shown in **Chats**: links, web apps, login links, texts to copy, callback data, inline queries, requests for a phone number or location. Links are shown as text and never opened by the panel. When a bot changes only the buttons (a new payment link), that is a new version of the message, both from live updates and from rechecks. - **New chats and bots.** In folder and whole-account modes, **When a new chat or bot appears** saves, right after it appears: - its profile as a `source.profile` record: bot description and commands, the about text of a user, group or channel, members, linked chat and invite link when Telegram returns one; - its latest visible messages (up to 1,000) as a history snapshot marked `new_chat`: the earlier messages of a team chat just joined, or what a bot said before observation noticed the chat. Messages already saved live are not repeated. Newly selected chats use these settings when the scope is applied, including chats already present in the account's dialog list. Initial profile and history loading runs for up to three chats concurrently; work for the same chat stays in order. Each history/profile stage uses the configured operation timeout, so stalled requests release their worker. History is saved before the optional profile read; a profile failure does not prevent that history capture. Failed stages retry after 5 seconds, doubling to a maximum of 5 minutes without occupying a worker during the delay. Pending IDs, retry deadlines and completed stages are saved locally. A restart resumes only unfinished stages; a profile retry does not repeat a completed history read. Sources disabled before their turn are skipped. The overview shows active, pending and retrying chat loads separately from attachment downloads. A FloodWait pauses this work and it resumes afterwards; failures are recorded and live recording of the chat continues. This includes waits while resolving the new chat's identity: the pending profile/history task is retained for retry, and an existing longer account-wide wait is not shortened. The workers share this wait; concurrency does not bypass Telegram's request limits. - **Profiles on request.** **Chats → Profile → Save profile now** saves the current profile of any source; the newest one is shown above the messages. - **Chat state snapshots (preview).** State outside the message stream changes without a message: unpinning every message leaves no message-level trace, an administrator loses rights, a gift is hidden, converted, upgraded or refunded. While observing, every enabled source is read periodically and saved as a signed `chat.state` record: title, usernames, description, member and administrator counts, linked chat, slow mode, pinned message IDs (up to 100), administrators with their rights and titles, and gifts shown on channels and user profiles (up to 100). Each record lists the differences from the previous snapshot: changed fields with before and after, pinned messages added or removed, administrators and gifts added, changed or no longer listed. - A part Telegram refuses (for example the administrator list of a channel for a member who is not an administrator) is named in `errors`; its earlier value is kept and listed in `carried_forward`, never reported as removed. - A record whose only changes are counts, and a check that found no change, refer to the last full state with `state_seq` and cumulative `state_overrides`. A full state is written at least every seven days and whenever anything other than a count changes. - `parts_complete` marks capped lists. Additions require a complete earlier list, removals require a complete current list, and explicit empty values record clearing. - **More tools → Parameters → Chat state** sets the interval (12 hours by default, 0 turns snapshots off), the pause between sources, which parts are read, and whether checks that found no change are recorded. `FLOOD_WAIT` and `FLOOD_PREMIUM_WAIT` stop the remaining snapshot requests, preserve any longer account-wide deadline, and leave the interrupted chat eligible for another attempt after that wait. - **Not visible.** Inline (callback) buttons pressed in another Telegram app, the popup or link a bot answers such a press with, and invite links used in another app do not reach TgWitness. What the bot sends or edits afterwards is recorded. ### Act from the panel **Chats** now includes a mini-client using the selected workspace's Telegram account: - Write a plain-text message or choose **Reply** under a saved message. The returned outgoing message is recorded even when the scope excludes outgoing updates. - Press **Press button** under a current callback or text button. The server fetches the message again and refuses the action if the keyboard differs from the saved version. Callback receipts retain Telegram's popup text, alert flag and URL; the answer is also shown below the conversation. URLs remain selectable text and are not opened automatically. - Press **+** → **Open Telegram link**, enter `@username`, a public `https://t.me/name` link, `https://t.me/+invite` / `joinchat/invite`, or a bot link with `?start=parameter`, and press **Save preview**. The original link and Telegram's preview are signed before joining. **Join / open and observe** then joins the group/channel or opens the user/bot, adds the chat as an enabled source, and sends `/start` to a bot, including its start parameter. A join request awaiting administrator approval is recorded as pending, not as membership. Turn on **Start observation** to capture incoming replies live. Panel actions work while observation is paused; the panel then saves their direct responses, and live observation captures the rest of the conversation. Newly added sources use the configured profile/history intake when observation is running. When a source is paused, enable it in **More tools → Sources** before sending or pressing its buttons. `interaction.preview`, `interaction.requested` and `interaction.result` are ordinary signed journal events included in evidence exports. Requests identify the account, message/button or preview record and whether observation was running. Receipts distinguish success, rejection, approval pending and an unknown outcome. An interrupted request may have reached Telegram: check the chat before starting a new action. Reusing a request ID retrieves its saved receipt without repeating the action, including after restart. The panel retains the ID after an ambiguous response for the same action during the current page session. It also retains that ID when refreshing the view fails after a successful action: the receipt stays visible, and clicking again retrieves it. Callback and join RPCs have one application attempt; retryable reads keep their configured retry policy. Switching chats immediately clears the draft and reply target and disables sending until the new conversation loads. This mini-client handles text and callback buttons. Mini application buttons get **Open mini app**, which records the application in an isolated browser ([Mini applications](https://github.com/phishdestroy/TgWitness/blob/main/docs/MINI-APPS.md)). Login, phone and location requests, payments, inline queries and attachments still require a Telegram client; their saved button metadata remains visible. The new controls use English text. ## Recheck tiers Rechecks ask Telegram again for missed messages, edits and messages it no longer returns. Sources marked with a star are **priority** sources, rechecked every 15 minutes by default; all other sources every 6 hours. Chosen chats start as priority sources, chats added by a folder or the whole account as regular ones. At most 30 sources are rechecked per pass and the rest wait for the next minute; after a reconnect, priority sources go first. Both intervals are set under **More tools → Sources → Recording → Recheck** (0 turns a tier off) and are recorded as `recheck.changed`. Missed messages are fetched upward from where the previous pass stopped, at most **More tools → Parameters → Missed messages recovered per chat and pass** (1,000 by default). After a long stop the recheck therefore fills the whole gap, even when live messages newer than the gap were saved first. A chat that is still catching up is rechecked again on the next minute instead of waiting for its tier interval; `recheck.completed` shows `continues_after` until it is done. Comparisons include message text, entities, keyboards (including removal), and attachment content/identity. Changing file access hashes or file references alone does not create an edit, nor does what Telegram fills in on its own: a link preview loading, story views, paid media unlocked by this account, an invoice's receipt. Each saved version in Chats links to its full journal record, including media metadata. ## Message history and attribution Suppose the collector observes “Meeting at 10:00,” later sees “Meeting at 11:00,” and then receives a deletion notice. It appends three distinct observations. The original text remains, the edit is a separate version, and the notice records that a deletion was observed. If collection began after the first version disappeared, that text is unavailable. If several edits occurred while the process was offline, only subsequently observed versions can be saved. A deletion notice cannot recover content never captured. The record combines several sources: | Source | Preserved information | | --- | --- | | Live message or edit update | Message ID, sender metadata, captured version, reception time and supplied Telegram message/edit date. | | Live deletion notification | Reported message IDs, reception time, raw notification and links to previously saved content. | | Available admin log | Action, actor, source date and supplied message content, read by an account with the required rights. | | Panel interaction | The requested action and its recorded outcome under the selected account. | | Recheck | Telegram's current response compared with the previously saved message. | `observed_at` is the time the record was written on the collector clock and increases with `seq`. Records written while handling a live update also carry `received_at`, the time the update reached the collector, and `processing_delay_ms`, the time from reception to writing; updates held while observation starts are processed in arrival order before later ones. `source_at` retains a source date where that event supplies one. Telegram clock-offset observations, clock-discontinuity records and [external time checks](https://phishdestroy.io/tgwitness/docs/reference/timestamp/) provide the associated timing context. An ordinary message notification's fields describe that notification; admin-log and interaction records retain their own attribution. ## History snapshots A snapshot requests the latest visible messages from an enabled source, up to 500 per request. Results are labeled as history observations. Manual snapshots run alongside observation. Repeated observations are kept as separate records. Turning a source on also takes one `baseline` snapshot of it, unless [strict chosen chats](https://phishdestroy.io/tgwitness/docs/reference/collection/#strict-chosen-chats) is on. Snapshots stop if the source is disabled during the read. Replies must belong to the requested chat and contain strictly decreasing positive message IDs below the requested boundary. An invalid reply interrupts the snapshot before that message is saved; already preserved messages remain in the signed journal with the interruption record. Snapshots follow the attachment policy but remain separate from live-event switches. They do not reconstruct deleted messages or missed intermediate versions. You can request one while paused; any attachments it queues wait until observation starts and the download worker runs. The **History** run is a separate exclusive task: it reads selected sources and downloads their queued attachments sequentially without starting monitoring. Pause releases the account; resume continues the saved run. For date, language and reply filters across several idle accounts, see [Distributed chat export](https://github.com/phishdestroy/TgWitness/blob/main/docs/DISTRIBUTED-EXPORT.md). ## Attachment handling Attachment download is on by default and pauses below 1 GiB of free disk. The collector commits the message observation and download job together. The job retains the original media descriptor and size policy, so a later edited attachment is not silently substituted. Downloads run after message capture. A completed download creates a `media.saved` record with its SHA-256 and byte count. Skipped, failed, retried, and interrupted work has separate outcomes; a file counts as preserved when its `media.saved` record exists. The completed file must also match the byte count in the original observed attachment descriptor. A short or unexpectedly long response is not recorded as preserved media. The file and its folder entry are flushed to disk before `media.saved` is written. When the previous collector process ended without an orderly stop, the next start reads every file recorded as saved during that run. A file that is missing or whose bytes differ from the recorded SHA-256 gets a `media.missing_after_restart` record, its download is queued again, and differing bytes are moved to `media-damaged/`. Files moved to off-site storage are not read. Within one workspace, concurrent queued jobs for the same attachment representation wait for the active transfer, then recheck its saved bytes before reuse. Each job keeps its own signed outcome and reference to the earlier saved-file record. Cancelling a waiting job does not cancel the active transfer; if that transfer fails or is cancelled, the next job can try again. Different attachments can download concurrently. Jobs with the same account, representation, expected size and capture action stay queued while one matching job is running. They do not occupy download slots, so other files can start even when the queue begins with many copies of one slow file. Completing an attempt wakes the queue. Priority lanes, saved retry delays and history ownership still apply; each observation receives its own outcome. Chat exports also share an active transfer for repeated file representations within the same export directory. Each message retains its attachment reference, and reuse requires a fresh size and SHA-256 check. Different files can be checked in parallel without holding a common transfer lock. Temporary download and copy paths are unique to each operation; cancellation waits for any active local file reader before cleanup. The export file index serializes only metadata access, not file hashing or downloads. Server-hash reads for different attachments also run concurrently, sharing the client's three file-request slots with byte downloads. Repeated reads of the same representation reuse only a complete cached result. File reads leave the ordinary request queue free; saved FloodWait deadlines are checked again when a request gets a slot. Limits are set **per type**: photos, videos, GIFs and animations, round video messages, voice messages, music and audio, stickers, and files. Each type can be turned off and has its own size limit from 1 to 2,000 MiB; new workspaces start with 20 MiB for photos, 100 MiB for videos, 50 MiB for files, audio and round videos, 20 MiB for voice and GIFs and 5 MiB for stickers. New workspaces leave GIFs and stickers off until turned on. Workspaces with policies saved before per-type limits keep all types enabled and retain their single limit for every type. *Maximum file size* sets every type at once. A type turned off produces a `media.skipped` record; unknown-size or oversized files are not downloaded. Large files get extra download time based on their size and a baseline speed of 256 KiB/s. Jobs survive restart, but expired references, lost access, or deleted files can still prevent recovery. Waiting jobs keep the limit saved with them, so a raised limit applies to new files only. Turning a type off or lowering its limit also skips the waiting files it excludes, each with a `media.skipped` record; turning downloads off pauses the queue until they are turned on again. ## Pause, lock, disconnect, and restart | Action or condition | Effect | | --- | --- | | Switch workspace | Changes the panel view; other collectors keep their state. | | Lock the panel or close a tab | Leaves the server and observation running. | | Pause observation | Stops that collector and preserves queued attachment work. | | Disable a source | Stops future scoped capture; queued media jobs for it wait while it is disabled. | | Remove a source | Forgets it as a source and deletes its people profiles; records already saved stay in the append-only journal. Its attachments still waiting are recorded as failed (`source_removed`). In folder and whole-account modes it is also excluded. | | Change the connection route | Requires a pause, closes old clients, and cancels unfinished login. | | Stop the Python process | Stops all workspaces; no observations are made while it is offline. | | Restart after active observation | Attempts to resume the saved scope using the saved session. A manual pause clears that intent. | The collector records detected disconnects, retries, errors, starts/stops, and heartbeats. Short interruptions can be missed by periodic connectivity checks. After a restart, missed updates are requested from the saved update position and observed chats are rechecked periodically; see [evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/#durable-collection-and-process-receipts-02). A snapshot adds the current state as context, and the gap stays recorded. ## Account isolation and verification Each workspace has its own journal, authorization, signing key, policy, and queue. Only its active client can contribute live observations. Rejected, pending, superseded, and connection-test clients cannot write live updates into its journal. Different accounts can observe the same group, but their journals remain separate. Each event includes the previous hash and an Ed25519 signature. Exports cover the whole workspace journal through a fixed sequence number. Panel filters do not filter the export; collection may continue beyond its boundary while it is being prepared. **Verify journal** checks the event chain and signatures through the displayed boundary. Its result is cleared when the workspace changes, and the panel identifies new records added after the check. ZIP export also verifies collected media. Retain fingerprints and checkpoints independently. See the [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) for acquisition checks in each mode, and [daily operations](https://phishdestroy.io/tgwitness/docs/reference/operations/) for routine collection. --- # Record Telegram Secret Chats in TgWitness Canonical page: https://phishdestroy.io/tgwitness/docs/reference/secret-chats/ Record Telegram Secret Chats that TgWitness creates or accepts: install the protocol extra, enable it per account and keep messages and timers in the journal. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Install the Secret Chat protocol extra, enable it per account and record the chats TgWitness creates or accepts. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) The published application includes the Secret Chat backend, collector integration, API routes and **Pseudo-secret** interface. The protocol library is a separate module: open **Pseudo-secret** and press **Install and turn on**. Automatic incoming acceptance stays off until you turn it on. ## Protocol module | | | | --- | --- | | Module | `kiaro-telethon-secret-chat` 0.2.0 | | Author | KiaroSama | | License | GPL-3.0-or-later; its `LICENSE` and `NOTICE` stay inside the saved archive | | Source | [KiaroSama/Telethon-Secret-Chat](https://github.com/KiaroSama/Telethon-Secret-Chat) at commit `d87bf037b90060383c7b704d8a06ebb98c621c6f` | | Check | SHA-256 `c80feb9b5bc28201677c140d20930fbd730d7efdebb8ca789a19040c3f00ce5c` over the list of package files and their own SHA-256 values | **Install and turn on** is available to the main administrator. TgWitness downloads the source archive of that commit from GitHub through the workspace's route for requests outside Telegram, compares every file of the package with the value fixed in the TgWitness release, saves the archive as `modules/telethon-secret-chat-.zip` in the data directory and loads the code from memory. No restart is needed. The check runs again at every start; an archive that differs is not loaded and the page says so. A changed, missing or added package file fails the check. The module is a separate work under its own license. TgWitness does not ship it: each installation downloads it from its author's repository. **Details** on the page shows the loaded module, its author, license, commit and SHA-256. A host without access to GitHub can install the same commit into the Python environment instead; the panel then uses that copy: ``` python -m pip install ".[secret-chats]" ``` TgWitness becomes an endpoint for the chats it creates or accepts. It records messages, available attachments, timer changes and deletion notices in the signed journal. Previously saved content remains available after a later deletion notice. ## Package availability On 8 November 2026, the published installer package was checked at source [`b35f8e18f3d1`](https://github.com/phishdestroy/TgWitness/commit/b35f8e18f3d13c329af12e0036f50e0c8f340a2c), release `b35f8e18f3d1-1ff85ec98bb2`, version 0.9.1 preview. The [immutable wheel](https://get.destroy.tools/releases/b35f8e18f3d1-1ff85ec98bb2/tgwitness-0.9.1-py3-none-any.whl) and its dependency lock passed SHA-256 and RSA release-signature verification. The packaged backend and interface matched that source revision byte for byte. The package also contains the API registration and collector hooks. That package did not contain the protocol library, and it is not in the dependency lock. The `secret-chats` extra in [pyproject.toml](https://github.com/phishdestroy/TgWitness/blob/main/pyproject.toml) pins the same commit as the panel button. This package inspection establishes which files and dependency declarations ship. The [validation record](https://phishdestroy.io/tgwitness/docs/reference/verification/) identifies the separate runtime checks. The earlier 6 November guide described a development snapshot; it no longer describes the package above. ## Use the interface Open **Pseudo-secret**, install the module if the page offers it, turn it on for the account and connect it. Incoming requests wait for acceptance unless automatic acceptance is enabled. Starting, accepting, sending and closing use the account's interaction permissions and read-only protection. | Action | Preserved result | | --- | --- | | Start a chat by username or user ID | Outgoing request; the peer accepts it on their device. | | Accept a request | TgWitness becomes the receiving endpoint. | | Send or receive a message | `secret_chat.message` with its direction, content and supplied timer. | | Receive a file | Decrypted bytes stored by SHA-256 and a `secret_chat.file` receipt; included in the evidence export. | | Receive a timer or deletion notice | A separate action record alongside retained messages and files. | | Review the chat | Conversation, file receipts, notices and key visualization. | Existing Secret Chats on another device retain their device-specific keys. An imported cloud session does not transfer those keys. Secret-chat key material and counters use the workspace vault; preserved messages and decrypted files use the normal workspace storage protections. ## Find saved messages Use **Search messages** inside an open chat to find a literal phrase, ignoring case. **Previous** and **Next**, or Enter and Shift+Enter in the search field, move between matching messages. The counter counts messages; the first matching phrase in each message is highlighted. Escape clears the search. Search keeps the surrounding conversation, saved files and deletion notices visible. It searches the records already loaded in the panel. When earlier records remain, the panel says so; **Load older records** extends the history and updates the search results while keeping the current message in place. Each chat keeps its search while you switch within the same workspace. Locking the panel or changing workspaces clears those searches. Search terms stay in the page's memory and are not stored in browser storage or sent as API queries. Searching does not send Telegram messages or typing/read notices. The existing visibility settings still govern opening a chat and other actions. **Build report** keeps the selected chat's report scope; a display search does not silently restrict the exported records. Preview the report's selection before downloading it. ## Persistence and interaction controls The integrated implementation uses durable journal lookup for duplicate detection, keeps attachment jobs pending after a failed download, and routes closing through the same interaction guard as other remote actions. These replace the three paths reported in the historical 6 November development-snapshot audit. Decrypted messages whose journal write fails are held in the vault for retry. Attachment size and free-disk checks defer downloads while keeping their jobs. The module reuses the account's existing connection. Read and typing notices are sent only as chosen under [What the other side sees](https://github.com/phishdestroy/TgWitness/blob/main/docs/INVESTIGATION-MODE.md#what-the-other-side-sees); screenshot notifications are never sent. See [secret_chats.py](https://github.com/phishdestroy/TgWitness/blob/main/tgwitness/secret_chats.py), [API routes](https://github.com/phishdestroy/TgWitness/blob/main/tgwitness/api/secret_chats.py) and [access policy](https://github.com/phishdestroy/TgWitness/blob/main/tgwitness/access.py). The [historical audit](https://github.com/phishdestroy/TgWitness/blob/main/website/validation/audit/REPORT.md) retains its original snapshot findings. Current availability and implementation should be read from the package revision above and the [current capabilities](https://github.com/phishdestroy/TgWitness/blob/main/docs/STATUS.md). ## Interface demonstration The website scenario uses fictional requests, messages and files to demonstrate the panel workflow. It is an interface example; protocol and acquisition checks have their own dated results in the validation record. --- # Telegram History Backfill & Signed Progress Canonical page: https://phishdestroy.io/tgwitness/docs/reference/history/ Load visible Telegram history from enabled sources, pause or resume backfill and inspect signed progress. Previously missed edits and deletions stay unknown. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Load past messages from enabled sources, pause and resume, and verify a signed progress report. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Collection](https://github.com/phishdestroy/TgWitness/blob/main/docs/COLLECTION-MODES.md) ![Collection](https://phishdestroy.io/tgwitness/assets/chapter-collect.svg?v=adb3306d1f69) In **More tools → Sources → Chats in scope**, review the enabled chats, choose Standard API or Takeout export, then choose **Load full history**. The run fixes that list of sources and reads their available past messages into Chats and the signed observation journal. Media uses the existing attachment settings and durable download queue. This is separate from the per-chat signed JSON/HTML export. For account-wide collection, select **Whole account** and save the scope. History refreshes all accessible dialogs, including archived chats, before signing its source list. This discovery does not use the selected-chat picker's list limit. Chats discovered later are observed and receive their configured initial snapshot; another full run can load their earlier history. Keep **Keep observation on during and after history loading** enabled to record new messages, edits and deletion notices while history loads. One history run or export uses the acquisition slot; live observation runs alongside it. Choose one to three concurrent chats, one to five attachment workers and whether to preserve available Recent Actions and compare previously saved versions. Takeout may require approval in Telegram and a server-specified wait. These options remain fixed on resume. See [Backfill behavior and evidence contract](https://github.com/phishdestroy/TgWitness/blob/main/docs/BACKFILL.md) for transport, retry and trust details. ## Pause, restart and partial results - **Pause history** stops reading. **Continue history** resumes from the last committed message in each source; restarting the app also leaves the run paused until resumed. Resuming requires the same idle Telegram account. - The message observation, attachment job and cursor commit in one transaction. A resumed run does not repeat its already committed observations. Live capture or a separate, explicitly started run may independently observe the same message. - Each source (each Telegram split range in Takeout) fixes an upper message ID on its first read. Newer messages belong to live observation, not to that source's remaining historical pages. - Inaccessible sources and sources disabled during acquisition remain visible as failed or skipped. Other sources continue; the overall result is incomplete. - Telegram shows a chat's admin log only to its administrators. For an ordinary member the admin-log read is recorded as `history.admin_log.unavailable` with `reason: not_admin` and does not make the history incomplete; an admin-log read that fails for an administrator does. - FloodWait delays respect the saved account backoff. Transient failures retry up to five times; exhaustion and low disk space pause with the cursor intact. - **End this history run** preserves saved observations. It does not remove them or cancel standard-API attachment jobs. Ending Takeout marks its remaining Takeout files as skipped; pausing keeps them resumable. A new run reads enabled sources anew. History completion describes history reads only. Attachments may remain pending, fail, or be excluded by the configured policy. Check media receipts in the journal and the attachment queue; only a completed receipt with preserved bytes constitutes a saved attachment. The history operation is an explicit snapshot request and is separate from switches that select categories of future live events. ## Transfer and verify Save the **signed progress report**, then use **Export evidence** to download the journal and saved attachments. A later evidence export may include additional records; the report binds its counters to the journal prefix at the time it was created. Run the verifier from a trusted checkout of this version: ``` python tgwitness/verify.py tgwitness-history-report.json --evidence evidence.zip --fingerprint TRUSTED_FINGERPRINT ``` Keep the expected signing-key fingerprint independently. The verifier checks the report signature, the evidence archive, the report checkpoint, source plan, account and counts of saved/unavailable messages. New runs also bind source progress and options to signed cursor events. Without `--evidence`, it checks only the signed report and its internal consistency. Legacy progress fields and attachment summaries remain signed collector statements. The evidence verifier checks archived media bytes. Read verified history together with its acquisition intervals, coverage and available Recent Actions. This workflow reads currently accessible history; [live monitoring](https://phishdestroy.io/tgwitness/docs/reference/collection/#message-history-and-attribution) preserves versions and notifications as they arrive, while [Secret Chats](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/) use the enabled endpoint integration. For verification, use the retained checkpoints, witness records and applicable acquisition attestations described in the [verification modes](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope). The acquisition cursor is local workspace state. Restoring an evidence ZIP alone does not restore a pending acquisition job or Telegram session. Keep the workspace backup if continuation of the original job is required. --- # Operate TgWitness: Monitoring, Export & Recovery Canonical page: https://phishdestroy.io/tgwitness/docs/reference/operations/ Manage Telegram collection, notifications and exports in TgWitness. Review daily checks, backup procedures, recovery and capacity planning for each workspace. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Daily operation of the panel: modes, monitoring categories, parameters, notifications, exports, backup and capacity. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Deployment and recovery](https://phishdestroy.io/tgwitness/docs/reference/deployment/) ![Deployment & recovery](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f) For your first connection, use [accounts and session formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/). For an explanation of saved versions, event policies, and gaps, see [how collection works](https://phishdestroy.io/tgwitness/docs/reference/collection/). This guide covers daily operation and recovery. A managed installation includes **START-HERE.html** and **START-HERE.txt** beside its launcher, with the repository link and commands tailored to its installation path. Run `tgwitness guide --print` over SSH, or `tgwitness paths` to locate the actual data directory. A root systemd install stores private state under `/var/lib/tgwitness-…`; `/opt/tgwitness` holds the program. For a managed temporary Cloudflare tunnel, `tgwitness tunnel off` closes public access while the local panel and collection keep running. `tgwitness tunnel on` enables it; `tgwitness tunnel restart` creates a new tunnel connection. Use `tgwitness open` to see its current address. An explicit off setting survives service restarts. `tgwitness stop` stops both the panel and collection. **On this page** - [Operator workflow](https://phishdestroy.io/tgwitness/docs/reference/operations/#operator-workflow) - [Share work without sharing the main key](https://phishdestroy.io/tgwitness/docs/reference/operations/#share-work-without-sharing-the-main-key) - [Runtime modes](https://phishdestroy.io/tgwitness/docs/reference/operations/#runtime-modes) - [Monitoring categories](https://phishdestroy.io/tgwitness/docs/reference/operations/#monitoring-categories) - [Notifications](https://phishdestroy.io/tgwitness/docs/reference/operations/#notifications) - [Panel layout](https://phishdestroy.io/tgwitness/docs/reference/operations/#panel-layout) - [Deployment environments](https://phishdestroy.io/tgwitness/docs/reference/operations/#deployment-environments) - [Startup checks and exports](https://phishdestroy.io/tgwitness/docs/reference/operations/#startup-checks-and-exports) - [Backup, restore and interruptions](https://phishdestroy.io/tgwitness/docs/reference/operations/#backup-restore-and-interruptions) - [Capacity and retention](https://phishdestroy.io/tgwitness/docs/reference/operations/#capacity-and-retention) ## Operator workflow Flow diagram · Choose storage and key protection → Open the panel with its token; Open the panel with its token → Select a workspace; Select a workspace → Configure Direct or proxy route; Configure Direct or proxy route → Enter phone or choose files / QR; Enter phone or choose files / QR → Check account identity and select accessible groups; Check account identity and select accessible groups → Save event and attachment policies, then start observation; Save event and attachment policies, then start observation → Monitor errors, access, queues and disk; Monitor errors, access, queues and disk → Retain independent checkpoints; Retain independent checkpoints → Export and verify material · Choose storage and keyprotection · Open the panel withits token · Select a workspace · Configure Direct orproxy route · Enter phone or choosefiles / QR · Check account identityand select accessiblegroups · Save event andattachment policies,then start observation · Monitor errors,access, queues anddisk · Retain independentcheckpoints · Export and verifymaterial **Diagram as text** 1. Choose storage and key protection → Open the panel with its token 2. Open the panel with its token → Select a workspace 3. Select a workspace → Configure Direct or proxy route 4. Configure Direct or proxy route → Enter phone or choose files / QR 5. Enter phone or choose files / QR → Check account identity and select accessible groups 6. Check account identity and select accessible groups → Save event and attachment policies, then start observation 7. Save event and attachment policies, then start observation → Monitor errors, access, queues and disk 8. Monitor errors, access, queues and disk → Retain independent checkpoints 9. Retain independent checkpoints → Export and verify material Authorization, transport connectivity, access to a group and completeness of delivery are different properties. A green connection status does not imply all events have been captured. ## Share work without sharing the main key Open **More tools → Access** to give a reviewer or analyst their own token. Choose the accounts and chats they can open, then allow viewing, export or operational actions. An operator who starts/stops collection needs whole-workspace access; a reviewer can be limited to a single chat. Session limits, expiry and IP rules are separate from Telegram account authorization. See [access and permissions](https://phishdestroy.io/tgwitness/docs/reference/access/). Use **Open sessions** to end a connection or revoke the access to end all of its sessions. The administrator console combines current-process activity across workspaces. Session closure leaves collection running. ## Runtime modes | Mode | Action | Behavior | | --- | --- | --- | | Demo | scripts\Demo.cmd or `--demo` | Synthetic data; real account connections disabled | | Observation | Start observation | Record delivered updates for selected sources | | History snapshot | Chats → Chat actions → Load history | Up to 500 current messages; no reconstruction of all past changes | | Pause | Pause observation | Stop collection while retaining data and queued jobs | | Review/handoff | Exports | ZIP, JSONL/CSV/HTML, checkpoint, process receipt and timestamp request | | Multiple accounts | Workspaces or the top **+** button | Any number of separate workspaces in one process | Local demo access opens automatically without manual token entry. It uses a process-lifetime capability valid only for direct loopback access to an isolated synthetic demo; the main panel token is not disclosed. Real workspaces and remote or proxied demo access retain token authentication. Demo entry grants no Telegram authorization. ## Monitoring categories ![Per-account monitoring settings with synthetic source data](https://phishdestroy.io/tgwitness/assets/sources.png?v=761b8bfa296c) In **More tools → Sources → Recording → Choose which changes to preserve**, select new messages, edits, deletion notices, reaction updates and membership events independently. The default retains all categories. **Messages, edits & deletions** keeps the original context while disabling separate reaction/member updates. **All visible activity** restores all five. Presets change the form; press **Save recording settings** to apply. The saved policy applies to all selected sources in that workspace. Other workspaces retain their own settings. Each actual change records signed before/after values; the current policy is also included in process receipts and observation start records. Disabling a category does not delete earlier observations. Re-enabling does not retrieve missed changes. There is no per-group category override in this version. Keep new messages enabled when prior content matters: a deletion notice cannot recover text that was never captured. Operational/coverage records and other group service events are always retained. Explicit history snapshots are separate from live-category selection and may include service messages. These switches do not redact reaction/member metadata embedded in an otherwise captured Telegram object. A history snapshot may queue attachments while paused. Start observation to process them. Queued does not mean downloaded. An unavailable original file is not replaced with a newer edited version; outcomes are recorded separately. **Lock** clears browser access and secret fields but leaves collection running. Closing a tab also leaves the process running. Stopping the Python process or service stops collection regardless of the browser state. An additional workspace can be deleted once a signed ZIP or ASiC-E container covering its journal and its Case Board notes has been downloaded in full. Preparing the archive is not enough: a record outside setup events or a note added after the download keeps **Delete** unavailable. When the panel receives the file itself, it counts the export only after it has received every byte, and then reports the size to `POST /api/exports/{id}/received`; a download that breaks off is not counted. With a browser save picker (File System Access) the panel reports it after the file is written and closed. Without one, the panel hands the received file to the browser's downloads and cannot see whether the browser kept it, for example when its save dialog is cancelled; the panel then says that the download started, not that the file was saved. A file the browser downloads on its own (an export larger than the panel's browser buffer) and a download by another HTTP client are counted when the server has sent the whole response. The operating system and a reverse proxy buffer several megabytes of a response, so for these downloads the server cannot see a break near the end. Unless the panel said the file was saved, check the downloaded file before deleting. A group export counts for its accounts when it is downloaded right after it is prepared; downloading it again from **Prepared exports** does not. Before deleting, the panel shows the format, size, preparation time and SHA-256 of the last downloaded signed archive and asks to confirm that this archive is saved outside the workspace. The server refuses `DELETE /api/profiles/{id}` without `kept_copy` set to that SHA-256 (or to `confirmed` for an archive downloaded before the fingerprint was recorded). Deleting an additional workspace stops its collector and removes its local data. If a locked file or filesystem error interrupts removal, the panel reports the failure and keeps the workspace listed as unavailable (`DeletionPending`). Close programs holding its files and retry **Delete**. Restarting TgWitness leaves that workspace stopped and does not recreate its partially removed journal or keys. A successful deletion is recorded only after the directory has been removed; separately exported or backed-up copies remain under their own retention policy. ## Notifications Open **Settings → Notifications and off-site copy → Notification destinations**, or **More tools → Extras → Notifications → Configure**. TgWitness uses Apprise to send alerts to Matrix, Telegram, Discord, Slack, ntfy, email and other supported services. You can add several destinations to one workspace. 1. Enter one Apprise destination URL per line. Use the [service catalogue and URL formats](https://appriseit.com/services/) for your service. 2. Turn on **Send notifications**, then choose problem alerts, changes in observed chats and a daily summary. The summary hour uses the server's time. 3. Turn on **Include short excerpts** if you want saved text from deleted and edited messages in the alerts. 4. Press **Save notifications**, then **Send test** to check delivery. For your own receiver, use Apprise's [JSON webhook](https://appriseit.com/services/json/). For example, `jsons://notify.example.org/tgwitness` sends JSON over HTTPS to that endpoint. This is a fictional example; replace it with your own destination. Destinations and settings belong to the selected workspace. Change notifications cover its observed sources, including newly added chats. The bell in the top bar also lists recent problems and chat changes. In the demo, the notification controls are visible but sending is disabled. Configure delivery in a real workspace. Notifications use that workspace's Direct, SOCKS5 or HTTP route; MTProxy cannot carry them. Non-HTTP destinations such as SMTP require a direct route. ## Panel layout ![Connection workspace using synthetic data](https://phishdestroy.io/tgwitness/assets/connection.png?v=c8781089fe29) **Journal** shows observations, search and filters. An edit opens captured versions; a deletion opens prior content if available. Unknown attribution remains explicit. Counts are available under **Overview**; acquisition details stay in the local guide. Open an edited message to compare its versions with **Inline diff** or **Side by side**; **Raw** shows the saved fields. Changes to hidden links and bot buttons appear separately. Open an attachment preview to inspect saved images, audio or video; the download button keeps the preserved original available. **Live** updates the journal and chats as records arrive. Pause it while reviewing, or use the new-events button when ready; collection keeps running. **Ctrl/Cmd+K** finds panel actions and searches the journal. **More tools → Sources** contains the observation scope (chosen chats, a Telegram folder or the whole account), accessible chats of every type, selected sources with priority stars, attachment and recheck settings and history snapshots. Private sources are selected by dialog/ID without a public link. Access status describes the most recent check, not permanent permissions. Filter sources, select their checkboxes, then enable, pause or mark them as priority together. In the available-chat list, **Add selected** uses your selection; **Add all matching** uses the current search and type filter. **Chats → People** lists everyone with saved messages; with people profiles switched on for the chat, a click opens that person's profile with links to the journal records. **More tools → Extras → Independent witness** creates read-only witness tokens, shows when each witness last checked and gives the commands and options to run one ([independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/)). **More tools → Parameters** holds every limit and pace of the workspace that is not on another page: how many dialogs are read, how often the chat list is re-read, heartbeat and checkpoint intervals, the startup buffer, how rechecks spread their requests (first delay, chats per pass, pause between chats, messages recovered and re-requested), disk reserve, timeouts and retries of downloads, what people profiles look for (including your own regular expressions), size and pace of notifications, snapshot, ZIP and browser-download limits, and Telegram client timeouts and retries. Each field shows its range and default; changed fields are marked and can be restored one by one or all together. Every change is recorded as `parameters.changed` with the values before and after, and observation start records name the values in force. Values apply from their next use; client timeouts and retries from the next connection. Recheck intervals, attachment types and sizes, evidence and off-site copy intervals stay on their own pages and take any value in their range, not only presets. The bell in the top bar lists recent problems and changes in observed chats; unread ones are counted until marked as read. Changes are grouped per chat and hour ("12 deleted, 1 edited, 0 not found"), and problems such as a sign-out or a full disk stay in the list however busy the chats are. **More tools → Account** starts on the phone-number field. **Continue** leads directly to code entry, asking for API credentials only when missing. QR and file import are alternative tabs. Saved API credentials are reused only within their own workspace. The entry screen has no sidebar, statistics, or setup paragraphs. The **Settings** icon opens API, proxy, storage, and additional-account controls. A new workspace opens [first setup](https://phishdestroy.io/tgwitness/docs/reference/settings/); after sign-in, a workspace with saved sources and records opens **Chats**. Changing the route requires paused observation and cancels unfinished login. An existing journal cannot be silently rebound to a different Telegram account. **Exports** checks journal integrity and produces portable files. Its workspace ID can be passed to the download CLI. Every export pins a full journal prefix; later events enter a subsequent export. Search filters do not change the package scope. Detailed signing and coverage information is under **Verification and evidence**. The panel reports collector state, queued/failed media, oldest pending media, free disk, request pauses and sources whose access is unconfirmed under **Collector health**. These details are collapsed initially and hidden on Account. A setup card shows the next step: connect an account, choose sources, or start observation. The account list is a load-time snapshot; the selected workspace refreshes periodically. This is not a multi-process SLA monitor. The UI uses local assets and text rendering for source content. Desktop and narrow Chromium layouts are tested. ## Deployment environments | Environment | Installation | Verification status | | --- | --- | --- | | Windows PC/server | Python 3.11+, scripts\Setup.cmd/Start.cmd, private data directory | Locally checked on Windows/Python 3.12 | | Linux server/VPS | Python venv, dedicated service user, HTTPS/SSH | Code, CI and systemd example provided; not executed on this host | | macOS | Python venv, foreground process or user agent | launchd example provided; separate installation check needed | | Docker/Compose | Persistent volume, one worker | Definition and CI runtime check provided; Docker unavailable locally | | Phone browser | Connect to the protected panel on a running server | Narrow Chromium layout tested; collector does not run on iOS/Android | Portability means no mandatory cloud service or frontend build. Each target still needs compatible Python/crypto dependencies, local disk and network access. See [DEPLOYMENT.md](https://phishdestroy.io/tgwitness/docs/reference/deployment/) and [service templates](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md). Workspaces share CPU, memory and an event loop. For process isolation, use distinct instances, ports, data directories and account authorizations. There is no unified panel across separate instances. Never point several workers at one database. ## Startup checks and exports Run `python start.py --check` before starting a prepared environment. Add `--json` for machine-readable checks or pass the intended `--data-dir`, `--host` and `--port`. The command checks prerequisites without Telegram login or creating a journal. Journal verification runs during application startup, and capture readiness shows in the panel. An occupied port may simply be an existing instance. Browsers supporting the File System Access API save exports through a writable stream. Other browsers buffer at most 128 MiB. Use the streaming CLI for larger exports or browsers without file streaming: ``` python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip ``` Add `--profile ID` from Exports for a child workspace. Use `--url https://server` for remote access. Plain HTTP is accepted only for loopback destinations. The token is read from a file and sent in a header, not printed or put in a URL. Redirects are refused. Existing destinations are not overwritten. Failed transfers remove their temporary part file. The reported SHA-256 is a transfer checksum; verify the signed ZIP separately with a trusted fingerprint/checkpoint. ## Backup, restore and interruptions 1. Pause observation and stop the process cleanly. 2. Copy the entire data directory: databases, WAL/SHM if present, media, `credentials.enc`, `signing.enc`, `network.enc`, vault keys/metadata, token, checkpoints and every `profiles/` directory. 3. For external-key mode, separately preserve the master key and retain each `vault.external.json`. Generating a new key cannot recover the old secrets. 4. Restore while the destination is stopped; configure the original key, restrict access, and verify integrity before resuming. 5. Record downtime and verification results. The downtime stays a recorded gap; a history snapshot adds the state after it. Evidence ZIPs exclude sessions/private keys and are not full service backups. `tgwitness backup FOLDER` makes the same copy while the panel keeps running and leaves out the search index, which rebuilds itself; see [Updates and backups](https://phishdestroy.io/tgwitness/docs/reference/deployment/#updates-and-backups). Four things are protected differently: | What | Protection | | --- | --- | | Export files without a password (the default) | Signed, so changes are detectable; set a password to encrypt the export | | Export files with a password | If you set a password, the finished export goes unchanged into a WinZip AES-256 ZIP that 7-Zip and WinRAR open; the password is not stored ([evidence handling](https://phishdestroy.io/tgwitness/docs/reference/evidence/)) | | The journal database and saved attachments on disk | An encrypted disk or volume and folder permissions | | Telegram sessions and signing keys | Encrypted in the data directory (`credentials.enc`, `signing.enc`, `network.enc`) | A full service backup is the stopped data directory described above, not an export. Use protected storage and a deliberate transfer mechanism for both. Temporary server exports live in each workspace's `temporary-exports/`; completed responses are cleaned up, and interrupted export files are removed on the next startup while that workspace's instance lock is held. After a connection-restored event, the collector requests missed updates from the saved update position. Persistent media jobs and the Telegram update position survive restart; see [evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/#durable-collection-and-process-receipts-02). ## Capacity and retention Default limits, all changeable under **More tools → Parameters**: the first 1,000 dialogs, 500 messages per snapshot, 4 GiB uncompressed signed ZIP content (larger archives need `verify.py --max-gib N`) and a 128 MiB browser fallback. Attachments take 1–2,000 MiB per type under **More tools → Sources → Recording → Attachments**. The download CLI defaults to 5 GiB transferred. Available disk can be a lower limit. Reserve space for journals, media, WAL, temporary exports and backups. Exports use the data volume rather than Compose's 512 MiB `/tmp`. Measure events/second, queue age, media bytes and disk latency rather than counting groups alone. Live delivery is measured on the running collector. There is no automatic retention deletion. Removing a journal tail invalidates its relationship to retained checkpoints. Priority rechecks already exist: starred sources are rechecked every 15 minutes by default, others every 6 hours (see [recheck tiers](https://phishdestroy.io/tgwitness/docs/reference/collection/#recheck-tiers)). Password-protected exports exist as described above. Scoped access is documented in [access and permissions](https://phishdestroy.io/tgwitness/docs/reference/access/). See [READINESS.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/READINESS.md), [LIVE_ACCEPTANCE.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md) and [VERIFICATION.md](https://phishdestroy.io/tgwitness/docs/reference/verification/). --- # Telegram Investigation Mode & Account Scope Canonical page: https://phishdestroy.io/tgwitness/docs/reference/investigation/ Configure whole-account Telegram investigation across channels, groups, private chats and bots. Preserve observations and prepare a verifiable case package. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Whole-account investigations across channels, groups, private chats and bots, from scope to a verified case package. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Investigation](https://phishdestroy.io/tgwitness/assets/chapter-investigate.svg?v=48c1be9d2a52) Follow a case across channels, groups, private chats and bots, from initial acquisition to a cited timeline and verifiable handoff. The interactive website version is at `/docs/cases/`; [preview instructions](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/PUBLISHING.md#preview-the-website-locally). **On this page** - [Worked case: a destination changes across four conversations](https://phishdestroy.io/tgwitness/docs/reference/investigation/#worked-case-a-destination-changes-across-four-conversations) - [1. Define the case and collect the whole account](https://phishdestroy.io/tgwitness/docs/reference/investigation/#1-define-the-case-and-collect-the-whole-account) - [2. Inventory every source and acquire historical context](https://phishdestroy.io/tgwitness/docs/reference/investigation/#2-inventory-every-source-and-acquire-historical-context) - [3. Preserve the evolving case and deliberate interactions](https://phishdestroy.io/tgwitness/docs/reference/investigation/#3-preserve-the-evolving-case-and-deliberate-interactions) - [4. Connect observations across chats](https://phishdestroy.io/tgwitness/docs/reference/investigation/#4-connect-observations-across-chats) - [5. Build the cross-chat timeline](https://phishdestroy.io/tgwitness/docs/reference/investigation/#5-build-the-cross-chat-timeline) - [6. Add account perspectives without losing their origin](https://phishdestroy.io/tgwitness/docs/reference/investigation/#6-add-account-perspectives-without-losing-their-origin) - [7. Assemble and verify the case handoff](https://phishdestroy.io/tgwitness/docs/reference/investigation/#7-assemble-and-verify-the-case-handoff) - [Adapt the investigation](https://phishdestroy.io/tgwitness/docs/reference/investigation/#adapt-the-investigation) ## Worked case: a destination changes across four conversations An announcement points to a bot. An operations group discusses a new payment destination, and the bot's keyboard displays it. The announcement is edited, a private follow-up repeats the destination, and a group message disappears. The questions are: what was observed before and after the change, which Telegram accounts posted each item, where the destination appeared, which attachment bytes were preserved, and what intervals remain unknown? All names, IDs, times and journal references in this example are fictional. The workflow uses current features; the case map is an illustration, not an automatic graph generated by the application. Flow diagram · Channels → Workspace journal; Groups → Workspace journal; Private chats → Workspace journal; Bots → Workspace journal; Workspace journal → Search all sources; Workspace journal → People profiles with record references; Workspace journal → Saved versions and attachment receipts; Search all sources → Analyst timeline and source register; People profiles with record references → Analyst timeline and source register; Saved versions and attachment receipts → Analyst timeline and source register; Workspace journal → Signed evidence ZIP; Analyst timeline and source register → Case handoff with separately verified artifacts; Signed evidence ZIP → Case handoff with separately verified artifacts · Channels · Groups · Private chats · Bots · Workspace journal · Search all sources · People profiles withrecord references · Saved versions andattachment receipts · Signed evidence ZIP · Analyst timeline andsource register · Case handoff withseparately verifiedartifacts **Diagram as text** 1. Channels → Workspace journal 2. Groups → Workspace journal 3. Private chats → Workspace journal 4. Bots → Workspace journal 5. Workspace journal → Search all sources 6. Workspace journal → People profiles with record references 7. Workspace journal → Saved versions and attachment receipts 8. Search all sources → Analyst timeline and source register 9. People profiles with record references → Analyst timeline and source register 10. Saved versions and attachment receipts → Analyst timeline and source register 11. Workspace journal → Signed evidence ZIP 12. Analyst timeline and source register → Case handoff with separately verified artifacts 13. Signed evidence ZIP → Case handoff with separately verified artifacts ## 1. Define the case and collect the whole account 1. Connect the collecting account in its own workspace. In [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/) or your case register, record the case reference, account ID, workspace and observation start. Retain the trusted signing-key fingerprint independently. 2. For a dedicated collecting account, open **More tools → Sources → Scope → Investigation mode**. The preset selects **Whole account**, channels/groups/private chats/bots, own actions, source profiles and the latest 200 visible messages for newly discovered sources. Review it, press **Save scope**, and complete the scope confirmation. Main accounts use selected chats or a folder; whole-account collection is available to accounts marked for investigation. 3. **Load chats** and compare the sources with the account's dialog list. Check exclusions. **More tools → Parameters → Chats read from the account's list** defaults to 1,000 and allows up to 20,000. Sources beyond the list limit are added when they become active. Record what was actually enumerated. 4. In **More tools → Sources → Recording**, select **All visible activity** and save the monitoring settings. Review attachment types/limits and free disk space. 5. Start observation. Validate a controlled new message, edit and deletion, then retain the test references and any failures. Whole-account scope records account-visible activity within the saved settings, in the chats the account has joined. Secret Chats are recorded by the [Secret Chat module](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/), and existing conversations are backfilled through [History](https://phishdestroy.io/tgwitness/docs/reference/history/). See [collection scope](https://phishdestroy.io/tgwitness/docs/reference/collection/#observation-scope-chosen-chats-a-folder-or-the-whole-account). ## 2. Inventory every source and acquire historical context Keep a source register with one row per chat: | Field | Record | | --- | --- | | Identity | Workspace, account ID, numeric chat ID, title and type | | Visibility | Membership/role, access confirmed or unconfirmed, exclusions | | Live capture | Start time, selected event types and later policy changes | | Journal history | Snapshot requested/completed, limit, time and record references | | Full history | Signed per-chat export filename, boundary and completion/failure | | Attachments | Completed media receipts, hashes, sizes and skipped/failed outcomes | | Coverage | Outages, incomplete intake, FloodWait, unavailable messages and other gaps | Use the right acquisition for each source: - **Load full history** in **More tools → Sources → Chats in scope** loads available past messages from enabled sources into the workspace journal. It supports pause/resume and a signed progress report. See [history acquisition](https://phishdestroy.io/tgwitness/docs/reference/history/). - **History snapshot** saves recent visible messages into the observation journal. Its default maximum is 500; **More tools → Parameters → Largest history snapshot** can raise that to 10,000. These are current history observations, not reconstructed edits. - **Exports → Capture or export one chat → Export full chat**, or **Chats → Export chat**, fetches the currently visible history of one chat into a separate signed `chat.json` / `chat.html` bundle. Repeat for the case's sources and retain each result. - **When a new chat or bot appears** can save its profile and up to 1,000 recent messages; Investigation mode selects 200. Existing chats do not receive that intake retroactively when the mode is enabled. - **Download visible attachments** preserves bytes under the configured policy. Require a completed `media.saved` receipt with SHA-256 and byte count. A queued job, thumbnail or filename is not the preserved attachment. A full chat export does **not** populate the journal or people profiles with all its messages. Use **Load full history** or bounded journal snapshots for history you need to analyze inside TgWitness. Review the enabled source list before starting a history run. Neither route recovers material Telegram no longer returns. ## 3. Preserve the evolving case and deliberate interactions Star active case chats as priority sources. Review recheck intervals, continued catch-up and media outcomes. Keep the collector observing while using the account. Use **Chats → Profile → Save profile now** to retain source metadata such as descriptions and bot commands. This is separate from people profiles derived from saved messages. Where the case involves following a source or interacting with a bot: 1. **Open Telegram link → Save preview** records the supplied link and returned preview before an action. 2. **Join / open and observe** performs the join/open, and sends a bot's start parameter when supplied. A join request awaiting approval is recorded as pending. 3. Panel-issued text replies and supported button presses retain `interaction.requested` and `interaction.result`. Callback receipts can retain returned popup text, alert state and URL. Those are real account actions. Callback presses in another Telegram app are not visible to the collector, although resulting messages or edits may be. The mini-client does not perform web-app, payment, phone or location workflows. For exact behavior, see [panel interactions](https://phishdestroy.io/tgwitness/docs/reference/collection/#act-from-the-panel). ## 4. Connect observations across chats In **Journal**, select **All sources** and search recorded content. Open matching records and retain the workspace, chat, message ID, sequence and record hash. In a relevant chat, open **People → Turn on profiles** and inspect a person: - Names/usernames observed over time and the numeric Telegram ID. - Reply relationships with source-record references. - **Also in…** other chats in this workspace journal where that ID wrote. - Activity, edits/deletions and mentioned wallets, phones, usernames and links. - Saved avatar metadata and similar cached avatars, with their separate origin. Open the cited records before using a derived profile in a finding. Profiles cover people with saved messages, not every member of the group. **More tools → Parameters → Records cited per fact** limits the reference list, not the underlying activity count. Mentions and avatar similarity are leads; ownership and identity rest on numeric IDs and attributed senders. The signed dossier separates encoder hints from forwarded and reused files into `clients.forwarded` and `clients.reused`. Such files do not contribute to `clients.observed` or the `media_timing.pre_existing` list. A reused file means the same Telegram document ID was observed in a different message earlier in this journal, within the reader's permitted chats. Its first observed record is cited; another observation or edit of the same message is not a reuse. The dossier's `paid_reactions` section retains the latest available Stars leaderboard for each listed message, with source records and anonymous flags. These are snapshot counts, not sums of additional payments or a complete list of people who reacted. A snapshot without a leaderboard supplies no replacement list. The section reports omitted messages when its display limit is reached. Watchlists and indicator exports inspect button labels, URLs, copy text, inline queries and callback bytes that decode as valid UTF-8. Invalid or oversized callback encodings are skipped by text extraction; the original bytes remain in the saved record. Existing watchlists need a rescan to inspect older records with these additional fields. Inspection does not press the button. In the worked example: | Link | Records | Supported observation | | --- | --- | --- | | Same sender account | Group #146 and private follow-up #205 | Both supply Telegram sender ID 71001 | | Same destination | #146, bot keyboard #173, channel edit #188, private message #205 | All contain `pay.example.invalid/new`; a repeated destination links the material | | Same saved file | Completed media receipts #151 and #209 | The full SHA-256 values agree for the preserved bytes | | Channel attribution | #101 and #188 | Do not attribute a channel post to user 71001 without an attributed sender | Compare attachment hashes and their associated message references, and keep account timelines grouped by the Telegram IDs supplied in those records. Keep the team's working notes on [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/): bookmark the records you rely on, such as #146, #188 and #205, highlight the exact destination string, and save a slice of every recorded action between two records or in a time range. Notes and statuses retain the team's review in their own signed history, separately identifiable from the source observations. ## 5. Build the cross-chat timeline Use saved versions in **Chats** and their **Journal record #…** links. In **Journal**, combine **All sources** with **Edits**, **Deletions** and **Coverage**. Keep both `source_at`, where supplied, and `observed_at`. | Illustrative observation time | Reference | Observation | | --- | --- | --- | | 09:00 | Channel #101 | Original destination captured | | 09:12 | Group #146; media #151 | New destination posted; file download completed | | 09:16 | Bot #173 | Keyboard points to the new destination | | 09:20 | Channel #188 | Announcement edited; both saved versions remain | | 09:24 | Private #205; media #209 | Same sender ID repeats destination; same file bytes preserved | | 09:28 | Group #231 | Deletion notice received; deleter and exact deletion time unknown | Other records occur between these example references. Sequence numbers order observations; history snapshots can contain older source dates and arrive later than live events. Distinguish snapshots, recovered messages, deletion notices and missing-on-recheck outcomes. Mark coverage gaps as unknown intervals. Later history acquisition does not retroactively establish uninterrupted observation. ## 6. Add account perspectives without losing their origin Use a separate workspace for every distinct account and repeat its inventory. Keep account ID, role, signing-key fingerprint and source references with every comparison. Message numbers are not global identifiers across chats/accounts. Case Board keeps source-linked notes and collections within each workspace. The group screen reviews account status together and can bundle separate workspace exports. Correlate those sources in your case notes or analysis tools; each journal retains its own origin and signing key. A global search or merged cross-workspace timeline is not generated. Multi-account export of one channel/supergroup acquires that chat's history using the eligible accounts. For longer work, retain boundaries with an [independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/). Use controlled delivery checks to qualify each account's capture path and visibility. ## Media recurrence and forwarding sources Evidence reports compare Telegram document IDs and SHA-256 hashes from saved-file records separately. They show distinct messages, chats and the first and last retained occurrence, with an expandable observation timeline in HTML. Repeated snapshots or edits of the same message do not increase an occurrence count for the same key. A different file in an edited message retains its own occurrence. "First observed" follows journal sequence within the report selection. It does not claim the earliest publication on Telegram. Document IDs identify Telegram documents; SHA-256 compares saved bytes. Matching 64-bit dHashes of different saved images are shown as visual leads; this comparison uses equal hashes, not a nearest-neighbor search. Image bytes must match their saved SHA-256 before dHash analysis; files over 64 MiB and images over 40 million pixels are skipped. Forward-source summaries count distinct destination messages. Header peer IDs, hidden names, post-author signatures and Saved Messages context stay separate. People-profile JSON includes each sender's sources; channel posts also appear in the chat-level summary. A named source without a peer ID is a text grouping, not an identified person. Imported-chat headers remain marked as imported. Non-compact evidence ZIPs include `media-repeats.json`, `forward-sources.json` and `observed-sources.gexf`, protected by the archive manifest. The GEXF 1.3 graph has typed `forwarded_from` and `recommended` edges. Arrows run from the observed chat to the referenced peer. Recommendation weights count retained recommendation observations; forward weights count distinct messages. Hidden names and imported headers do not create identity edges. No graph operation resolves profiles or calls Telegram. Edge metadata includes source sequences and hashes. The summaries follow the report's selection; the evidence ZIP still contains the complete signed journal. A selection containing only message events compares document IDs; saved-byte and image comparisons require saved-file events in the selected stream. The current cloud-message selection excludes `media.saved`. Limits are explicit: 200,000 retained key/message occurrences per analysis, 100,000 media keys, 20 report groups, 100 chronology references per group and 1,000 exported graph edges. When a comparison cap is reached, results show omitted occurrences and counts become lower bounds. Chronology and graph display limits are reported separately. Compact ZIPs omit these derived summaries. The signed source records remain unchanged. ## 7. Assemble and verify the case handoff Keep these together in an analyst-assembled case directory: | Material | Purpose | | --- | --- | | Case notes and source register | Question, collection policy, access/role, findings, alternate explanations and gaps | | Timeline | Both times and workspace/chat/message/sequence references for each entry | | Case Board export and slices, if used | Source-linked bookmarks, quotes, team notes, collections, revision history and selected records checked against the evidence ZIP | | Signed evidence ZIP per workspace | Complete recorded journal, manifest and included preserved media; panel filters do not narrow the journal export | | Separately signed people-profile files | Derived references checked against the matching workspace evidence | | Signed full chat exports | Current visible-history acquisition, separate from the observation journal | | Trusted fingerprints, TSA root certificates and earlier checkpoints | Key identity, external time of the last record and retained journal boundaries | | Witness artifacts, if configured | Separate journal, signed posts and witness fingerprint | | Verification results and delivered-file hashes | What was checked, which bytes were transferred and to whom | From a trusted installation, with filenames and each workspace's actual fingerprint: ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint retained-checkpoint.json --require evidence python -m tgwitness.verify profiles-operations.json --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --evidence evidence.zip python -m tgwitness.verify history-channel.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 python -m tgwitness.verify board-slice.json --evidence evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 ``` `--require evidence` exits with code 2 unless the fingerprint matches and external time from a third party covers the last record; the checkpoint is a supporting check. Retain the actual verification results and original artifacts. Export workspace notes from Case Board alongside the cited source material. Assemble cross-workspace findings in the top-level case directory; each TgWitness artifact has its own signature and verification procedure. ## Adapt the investigation | Case | Trace | Deliver | | --- | --- | --- | | Bot-driven order/payment dispute | Entry announcement → saved link preview → bot start parameter → message and keyboard versions → panel callback receipts → private/group follow-up | Observed offer/response timeline and verified sources; payment confirmation comes from the payment record | | Removed messages after an incident | All affected chats → saved originals/edits → deletion or missing-on-recheck outcomes → preserved media → coverage and other account perspectives | Preserved versions and explicit unknown intervals; no invented deletion actor | | A participant changes names across chats | Numeric sender ID → name/username history → replies → other observed chats → cited destinations/files | A Telegram-account activity timeline with links to its source records | [Collection reference](https://phishdestroy.io/tgwitness/docs/reference/collection/) · [People-profile verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/#people-profiles) · [Evidence handoff](https://phishdestroy.io/tgwitness/docs/reference/evidence/#investigation-handoff) · [Completed validation](https://phishdestroy.io/tgwitness/docs/reference/verification/) --- # TgWitness Features & Telegram Collection Scope Canonical page: https://phishdestroy.io/tgwitness/docs/reference/features/ Review implemented TgWitness collection, multi-account workflows and signed exports, with the platform support and qualification of each feature. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) The current collection model, multi-account workflows, exports and operational boundaries of TgWitness. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Project reference](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Project reference](https://phishdestroy.io/tgwitness/assets/chapter-project.svg?v=f8e31208f561) TgWitness preserves Telegram conversations accessible to connected accounts, records observed changes and prepares verifiable exports. This reference describes the collection model, current workflows and their boundaries. **On this page** - [Standalone application](https://phishdestroy.io/tgwitness/docs/reference/features/#standalone-application) - [Shared investigations](https://phishdestroy.io/tgwitness/docs/reference/features/#shared-investigations) - [Archive tools](https://phishdestroy.io/tgwitness/docs/reference/features/#archive-tools) - [Optional extras](https://phishdestroy.io/tgwitness/docs/reference/features/#optional-extras) - [Protocol and private sources](https://phishdestroy.io/tgwitness/docs/reference/features/#protocol-and-private-sources) - [Multiple accounts](https://phishdestroy.io/tgwitness/docs/reference/features/#multiple-accounts) - [Capture and attribution](https://phishdestroy.io/tgwitness/docs/reference/features/#capture-and-attribution) - [Capacity and Telegram limits](https://phishdestroy.io/tgwitness/docs/reference/features/#capacity-and-telegram-limits) - [Reliability and recovery](https://phishdestroy.io/tgwitness/docs/reference/features/#reliability-and-recovery) - [Evidence model](https://phishdestroy.io/tgwitness/docs/reference/features/#evidence-model) - [Export, deployment and handoff](https://phishdestroy.io/tgwitness/docs/reference/features/#export-deployment-and-handoff) - [Stable release criteria](https://phishdestroy.io/tgwitness/docs/reference/features/#stable-release-criteria) ## Standalone application TgWitness has its own installation, data directory, and release lifecycle. The bundled web interface handles setup and review; exported records can be used independently. The operator connects their accounts, chooses sources visible to each, and obtains a saved observation journal. The panel exposes content, saved changes, observation provenance and known gaps. Another investigator can verify the exported material. The panel distinguishes account authorization, access to a source, collector activity and recorded coverage. Review those states together when assessing an interval with few messages or a connection problem. ## Shared investigations An administrator can issue [access tokens](https://phishdestroy.io/tgwitness/docs/reference/access/) scoped to workspaces and individual chats, with per-action permissions, IP restrictions, expiry, sign-in limits and session control. A read-only reviewer can inspect a case without receiving Telegram authorization or the main panel key. Chat-limited access stays separate from account-wide settings and full-journal exports. Automatic MTProxy maintains working Telegram routes from four public sources or an operator catalog. [IP modes](https://phishdestroy.io/tgwitness/docs/reference/connection/#ip-modes) determine whether failure must wait for another proxy or may use an explicitly permitted direct route. External HTTP requests have a separate route and off switch. ## Archive tools [History acquisition](https://phishdestroy.io/tgwitness/docs/reference/history/), [archive search and analysis](https://phishdestroy.io/tgwitness/docs/reference/analysis/), [read-only MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/), [local OCR/transcription](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/) and [outgoing webhooks](https://phishdestroy.io/tgwitness/docs/reference/webhooks/) have been included since 0.7.1. Analytical reports and recognized text stay separate from captured events. [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/) adds source-linked bookmarks, quotes, notes and collections within a workspace. The [report constructor](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) selects material, sections and one of eight designs for supported HTML/PDF exports. ## Optional extras Everyday setup is account → sources → observation. **More tools → Extras** is a separate destination for independent capture, storage, goal and protection level, notifications, evidence and backups, an always-on server, a Telegram witness bot and a code check. Each states its availability and requirements before showing settings. Choosing a card opens instructions; it does not enroll or start a service. Bot setup has three steps: create read-only access, choose publication settings, and launch on the witness host. Network and publication options, existing connections and verification commands are disclosed on demand. Downloaded configuration is distinct from a running witness. Switching extras retains the draft; account changes and locking clear the temporary token and form. The built-in guide includes launch instructions. [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md), opened from Exports, launches a pinned collector from your fork, captures one chat and produces an encrypted handoff with workflow provenance. ## Protocol and private sources **MTProto is Telegram's protocol; Telethon is the Python library TgWitness uses to speak MTProto.** They are not alternative connection methods. Collection uses MTProto; the optional witness publishes signed checks through the Bot API. Each workspace has its own authorized client and account update stream. TgWitness selects observations from configured sources and makes separate explicit requests for functions such as history snapshots and media downloads. A private source needs no public username. Telegram peer type and numeric ID are the identifiers; titles and usernames can change. Access depends on existing membership and permissions. TgWitness does not automatically join sources or bypass join approval. An access hash from another account is not a universal access token. The collection model must account for pre-join hidden history, participant/admin roles, session revocation, removal or changed permissions, group-to-supergroup migration, topics/forums, linked discussions, channel identities and unavailable attachments. Not every combination has been qualified live. Source visibility is checked at collector start. Missing a source from the bounded dialog result means **access unconfirmed**, not proven removal. One unavailable source does not prevent observing other accessible sources. Never put invitation links or real sessions in public fixtures. ## Multiple accounts The panel supports any number of **workspaces**, each with its own: - Authorization, encrypted vault and connection route. - SQLite journal and Ed25519 signing identity. - Selected sources, media queue and capture settings. - Observation state, errors, checkpoints and exports. Switching the displayed workspace does not stop another collector. Duplicate account authorization across workspaces is rejected. A journal already bound to one Telegram account cannot be reassigned to another; reconnecting the same account is allowed. This preserves account identity and the relevant message-ID scope. The application sets no fixed workspace count. Each workspace runs its own collector tasks for connection monitoring, media downloads, rechecks and new-chat intake within a shared Python process and event loop. Throughput depends on the workload. For process isolation, use separate installations, ports and data directories. Assign each account sources it can access. Different accounts may observe the same group, but their observations remain separate and retain their origin. Two accounts on one operator-controlled machine are not two independent witnesses. **Export group** bundles the separately signed workspace ZIPs with a signed file list containing their workspace IDs, hashes and signing-key fingerprints. Each journal retains its own boundary. Build a combined cross-workspace timeline in case notes or analysis tools, retaining those source references. ## Capture and attribution Sources provides per-account switches for new messages, edits, deletions, reactions and membership. Presets retain either all categories or messages/edits/deletions. The policy applies to the workspace's selected groups, survives restart, and is signed with before/after changes. Defaults preserve all categories. Turning a category off does not remove old records; turning it back on does not reconstruct missed events. Operational records, other group service events and explicit history snapshots are separate. Captured Telegram objects may retain embedded metadata regardless of the separate-update switches. There are no per-group category overrides yet. | Material | Captured now | Boundary | | --- | --- | --- | | Message | Text, peer/message IDs, sender metadata, replies and original update envelope | Preserved as an account-visible observation signed by the collector | | Edit | New observed version, earlier captured versions, reception time and supplied edit date | Message updates and available admin-log entries retain their respective attribution fields | | Deletion | Telegram notification, reception time and previously captured content | Actor and source action time are retained when supplied by a separate admin-log record | | Account-level deletion notice | Original notice; resolved records include the saved chat and correlation method | Requires exactly one previously saved private-chat or ordinary-group match in scope; other IDs stay `deletion.unscoped`. Channel and supergroup IDs are excluded from this correlation | | Reaction | Delivered counters and visible recent identities | A complete available reactor list requires separate queries; channels may hide identities | | Membership | Service messages and delivered participant updates | Visibility depends on role and chat type; membership is reported from delivered events | | Admin actions | Relevant delivered updates and an admin-log snapshot in channel/supergroup chat exports | The export reads the log when available to the exporting admin account | | Attachment | Original version descriptor, downloaded bytes/SHA-256 and attempt outcomes | The original version stays; a later version is never substituted | | History | Explicit snapshot of current visible messages | Live recording keeps earlier versions and deletion notices | | Collector process | Start/stop, heartbeat, errors, settings, scope and signed run receipt | Local inventory; GitHub and TDX add [independent environment checks](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) | The interface names the account supplied in the source event and retains observed names and usernames. When the event omits its actor, the report leaves that field unspecified. ## Capacity and Telegram limits Capacity is sized per deployment. It depends on peak events per second, attachment volume and sizes, additional RPCs, active accounts, disk latency/free space, network conditions, Telegram limits, acceptable lag and queue depth. Telegram distinguishes passive delivery from active short polling. Its update documentation describes additional `updates.getChannelDifference` calls for open channels/supergroups and recommends at most **ten simultaneously short-polled sources**. This applies to short polling; the number of selected groups is set separately. | Mode | Purpose | Status | | --- | --- | --- | | Standard observation | Record delivered updates from selected sources | Implemented | | Priority rechecks | Starred sources use their own configurable interval and take precedence in each bounded recheck pass | Implemented with history and message queries | The priority star controls these rechecks. Additional `updates.getChannelDifference` short polling is not exposed as a separate user mode. Arbitrary high-frequency polling, ignoring FloodWait or assuming linear capacity from extra accounts is not a valid sizing model. Default limits are the first 1,000 listed dialogs, up to 500 messages per history snapshot, 1–2,000 MiB per collected file by type, and 4 GiB uncompressed signed ZIP content; each is changed per workspace, file sizes under **More tools → Sources → Recording** and the others under **More tools → Parameters**. Exports have no fixed event-count cap. Browser fallback is bounded to 128 MiB by default; the streaming CLI has a configurable transfer limit, 5 GiB by default. ## Reliability and recovery Implemented behavior includes SQLite WAL/synchronous transactions; atomic message and media-job writes; persistent jobs and retry delays; original-version descriptors; bounded retries; persisted media FloodWait; media downloads outside the text event's network wait; stable-prefix exports while later writes continue; atomic settings and audit records; preservation of working authorization after failed replacement login; isolation of a damaged additional workspace; explicit reconnect attempts; distinct authorization-loss reporting; and wall-clock change detection using a monotonic clock. Account and channel pts/qts/seq are saved and resumed after a restart, and observed chats are rechecked periodically; see [evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/#durable-collection-and-process-receipts-02). Saving the position periodically is not an atomic, lossless acknowledgement of journal acceptance. Every process start records the previous head and offline boundary. Current history is not treated as gap repair. Telegram's difference retention is finite; `differenceTooLong` cannot reconstruct all vanished content. Irrecoverable gaps must remain explicit even if a later history snapshot succeeds. ## Evidence model Each event records a sequence, local UTC observation time, source time when supplied, kind, source, actor when supplied, original payload, previous hash and signature. Message observations also retain collector account/run context. The signed process receipt contains a random run ID; TgWitness/Python/OS/dependency versions; source-file SHA-256 values and aggregate fingerprint; initial account, scope and settings; UTC/monotonic readings; and the preceding journal head. Settings changes, start/stop and errors enter the same journal. Checkpoints are retained at startup, every five minutes while observing (changeable), and on orderly stop. A retained local checkpoint can detect rollback to an earlier journal prefix. | Mechanism | What it establishes | | --- | --- | | File SHA-256 | Bytes match a known digest | | Event hash chain | Record ordering/linkage relative to a known boundary | | Ed25519 | Signature under a particular key | | Independently retained checkpoint | Later material agrees with the retained boundary | | Program-file measurement | Collector self-report about measured files | | Valid independent TSA response | Existence of particular bytes by the TSA time under explicit trust assumptions | RFC 3161 request preparation and response verification are implemented without OpenSSL. Evidence mode also submits checkpoint hashes to configured timestamp services. Retain and verify the authority's response to establish an independent time anchor. See [TIMESTAMP.md](https://phishdestroy.io/tgwitness/docs/reference/timestamp/). Retain checkpoints independently, control access to signing keys, keep transfer records and verify exports with trusted software. The [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) explains how those checks complement one another and which trust assumptions apply. ## Export, deployment and handoff A signed ZIP contains original JSONL, CSV, HTML, preserved attachments, hashes, a signed manifest and a convenience verifier. It covers one workspace and a fixed full journal prefix. Panel search filters do not silently remove records. Secret keys, tokens and Telegram sessions are excluded; original observations can still contain personal information and Telegram metadata. Retain the ZIP digest, trusted fingerprint, checkpoint, process receipt and handoff record separately. Use a verifier from a trusted installation, rather than trusting executable code solely because it appears in the examined ZIP. The browser interface ships locally without Node.js, CDNs or external fonts. One operator token controls the installation. Remote access needs HTTPS or an SSH tunnel. Native Python and container definitions are supplied, with service examples under [deploy/](https://github.com/phishdestroy/TgWitness/blob/main/deploy/README.md); executed platform checks are listed separately. The default workspace uses the data root; additional workspaces use `profiles//`. Backup requires a stopped process and the complete data/key set. Evidence ZIPs are not application backups. Secrets can use an external master key for a new data directory; journal/media encryption is provided by the operator's disk/volume. See [CONNECTION-SECURITY.md](https://phishdestroy.io/tgwitness/docs/reference/connection/) and [OPERATIONS.md](https://phishdestroy.io/tgwitness/docs/reference/operations/). ## Stable release criteria Before a stable release, qualify: 1. Real private groups, supergroups, forums and channels with member/admin roles and hidden/visible history, including login/2FA, revocation and access loss. 2. Controlled edits, deletions, reactions, membership and media against known actions. 3. Process/host crashes, disk failures/full disk, expired file references, FloodWait, network loss, corrupted files and database rollback. 4. Sustained multi-account use with measured lag, queues, memory and disk, including quiet and noisy sources together. 5. Interruption between MTProto state advancement and journal acceptance. 6. Clean installation on the intended OS/container matrix and verified backup restore. 7. Independent review of security, signatures and attribution/evidence claims. Scoped panel access is described in [access and permissions](https://phishdestroy.io/tgwitness/docs/reference/access/). Since version 0.6, TgWitness supports the bounded single-account TData and account-file import described in [ACCOUNTS.md](https://phishdestroy.io/tgwitness/docs/reference/accounts/). Review Telegram API terms before publication. Research references and platform findings are in [RESEARCH.md](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/RESEARCH.md). --- # Case Board: Source-Linked Telegram Annotations Canonical page: https://phishdestroy.io/tgwitness/docs/reference/case-board/ Review Case Board bookmarks, highlights, action slices and discussions. Understand scoped access, annotation revisions and links to original Telegram records. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Bookmarks, exact highlights, action slices, discussions, scoped access and the signed annotation history used by Case Board. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Investigation](https://phishdestroy.io/tgwitness/docs/reference/investigation/) ![Investigation](https://phishdestroy.io/tgwitness/assets/chapter-investigate.svg?v=48c1be9d2a52) Case Board gives an investigation team a shared working view of saved material. Bookmark an observation, highlight an exact passage, save a range of actions, and discuss it with colleagues. Cards retain their source references and signed revision history. Team annotations stay in the workspace, separately identifiable from the original Telegram observations. [Evidence model](https://phishdestroy.io/tgwitness/docs/reference/evidence/) · [Access](https://phishdestroy.io/tgwitness/docs/reference/access/) · [Reports](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) ![Synthetic investigation feed](https://phishdestroy.io/tgwitness/assets/case-board.png?v=da27ef9c5b51) **On this page** - [Work with a case](https://phishdestroy.io/tgwitness/docs/reference/case-board/#work-with-a-case) - [Permissions](https://phishdestroy.io/tgwitness/docs/reference/case-board/#permissions) - [Stored contracts](https://phishdestroy.io/tgwitness/docs/reference/case-board/#stored-contracts) - [API and exports](https://phishdestroy.io/tgwitness/docs/reference/case-board/#api-and-exports) - [Operating limits](https://phishdestroy.io/tgwitness/docs/reference/case-board/#operating-limits) ## Work with a case Open **More tools → Case Board** in Standard or Expert mode. The language follows the panel. Use **To board** beside a journal record or saved chat message, or focus it and press **B**. The bookmark is added to Inbox in one click. Edit its title, labels and note, or move it to a collection. A changed card appends a signed revision; removing it preserves the history. For a first case, choose a collection and add the records that answer one question. Use comments to review the interpretation, then **Presentation** to walk through the cards and source context. Choose Case Board material separately in [Report studio](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) when preparing the deliverable. Saving a slice does not automatically configure a report's data filters. Select text inside a saved chat message to reveal **Highlight → board**. Select its colour and add a note. The server checks the exact quote and saved version, including emoji, RTL text and combining marks. The interface does not map a selection through masked or transformed text. Shift-click two records in one chat for **Slice between**, use **Slice by time**, or save the journal's current chat, period and event-kind filters. A saved slice has its own authoritative predicate: opening it in Journal also applies multiple chats, message-number limits and actor filters. **Show records added since bookmark** isolates the later additions. Changing Journal filters exits the slice. From People, **Slice this person’s actions** uses the recorded actor ID; it does not assume that the message author edited, deleted or reacted to a message. The slice dialog previews counts before allowing creation. `all` includes every recorded kind, including snapshots, edits, deletions, reactions, membership/service updates, own actions, buttons, media outcomes, recovered messages and future event kinds. The selection describes saved observations. Unknown-chat deletion notices are separate context, available only to a whole-workspace access, never attributed to one of the chosen chats. Collections have a declared chat scope. An empty scope means the whole workspace. A collection cannot contain cards outside its scope; a chat-limited participant cannot read a broader collection. Inbox is a virtual collection for unassigned cards. Search and filters cover visible cards only; threads and mentions inherit the parent card's access. Removed comments have a tombstone in the discussion. No viewer history is recorded. **Presentation** opens all cards in the chosen collection, with Card, Source context and Team comments views and keyboard Previous/Next controls. It provides no editing controls. The ordinary feed is paginated; presentation loads its list in pages and retrieves one card's detail at a time. ## Permissions All operations require `view`, workspace/chat scope and `board.read`. `board.write` adds cards, comments, moves and open/review statuses. `board.manage` permits collection management, confirmed/dismissed statuses, revisions/removal of someone else's card. A status is a team decision, not a cryptographic verification result. Access form presets: Reviewer = read; Analyst = read/write; Operator = read/write/manage, in addition to their existing permissions. Existing grants do not silently acquire new rights. The main administrator has all rights, and posts as **Main administrator**. Use named grants for attribution. Mentions list only current accesses able to read the complete parent card. A grant for chat A cannot obtain a card or slice for A+B, even by guessing its ID or supplying a false `target.chat_id`. Target metadata is resolved from the signed event hash on the server. Collections, discussion counts, related cards and live notifications are filtered before response. Exports require `export` as well as `board.read`; an existing exporter without board access gets the ordinary evidence archive without team notes. SSE rechecks current grants before each batch. ## Stored contracts Like observations, annotations are written transactionally to an append-only SQLite table in the workspace. `annotations.jsonl` is its exact canonical export from the same read snapshot as `events.jsonl`. There is no second competing annotation store and no `board.activity` journal event. Each line has exactly: ``` { "seq": 1, "at": "2026-11-02T14:00:00.000+00:00", "access_id": "admin", "access_label": "Main administrator", "kind": "board.bookmark", "payload": {"id": "32 lowercase hex digits", "target": {"event_hash": "64 lowercase hex digits"}}, "previous_hash": "64 zeroes for the first record", "hash": "SHA-256 described below", "signature": "base64 Ed25519 signature" } ``` The abbreviated example above illustrates the envelope; actual payloads include their model defaults and server-resolved target fields. API request schemas are under [`tgwitness/schemas`](https://github.com/phishdestroy/TgWitness/blob/main/tgwitness/schemas/board-bookmark.json), generated from the runtime Pydantic models by `python tools/build_board_schemas.py`. Extra request fields are rejected. IDs are generated server-side when omitted. Authorship, time, snapshot and signature cannot be supplied by the caller. Named grant IDs follow Access's existing 16-hex format; card IDs are 32 hex. Canonical JSON is UTF-8, sorted object keys, no whitespace between tokens, unescaped Unicode, and no NaN/infinities. The annotation hash is SHA-256 of the canonical object containing `format: "tgwitness-annotations-v1"` and all seven envelope fields through `previous_hash`. This format tag separates its hash domain from observations. The signature is Ed25519 over the 32 raw hash bytes. Sequence starts at 1. Revisions retain the card ID and name the preceding annotation hash in `supersedes`; they cannot change chat scope. Moves, statuses and removal are separate records. The SQLite table rejects UPDATE and DELETE. `case-board.json` contains `{statement, signature}`. The canonical statement is signed by the workspace key and contains `format: "tgwitness-case-board-v1"`, `public_key`, `created_at`, `journal_head`, `meaning`, and `state`. State is deterministic replay: `annotations_head`, an ordered `items` array (collections, cards, comments including tombstones), and `status_history`. Items retain their last annotation hash, sequence, author and time, as well as the original creator and creation time across revisions. Replay checks revisions, parents, collection references and duplicate action IDs. `manifest.json` and new checkpoints also bind `annotations_head`. Retain a checkpoint independently to detect truncation or rewriting with a copied signing key. ### Text versions `range.start` is a zero-based Unicode code-point offset, `length` is a positive code-point count, and `quote` must equal the exact substring of `payload.text` or `payload.caption` at the target event. No NFC/NFKC, case folding or grapheme normalization is applied. Python string slices and JavaScript `Array.from(text)` implement the same indexing. Combining marks and ZWJ emoji may occupy several code points. `range.version` is the target event hash, not the current message version or Telegram's UTF-16 entity offset. Later edits never relocate a highlight automatically. ### Slice identity and time `query` accepts exactly one `chat_id` or nonempty `chat_ids`, optional inclusive `from`/`to`, inclusive message-ID bounds (one chat only), `kinds: "all"` or exact/prefix wildcard kinds, explicit `actors`, `search`, `hide_system`, and `include_unscoped`. Journal kind groups expand to their exact predicates. Search uses the journal's NFC/case-folded payload search without altering signed source text. Dates require a timezone and normalize to UTC. Dates filter **observed_at**. Telegram's `source_at` is displayed separately. A deletion without a source timestamp has no invented deletion time. A late record observed outside a time interval does not enter it; a message-ID slice can include a later deletion for those message IDs. `snapshot` fixes creation time, the journal sequence/hash boundary, matching count, first/last sequence and `result_hash`. The latter is SHA-256 of the UTF-8 canonical JSON array of matching event hashes sorted lexicographically, including `[]` for an empty slice. It also carries exact kind counts and a 24-bin observation-time miniature. A slice stores a query, not duplicate source records. At export, `board/slices/.json` lists current hashes and added/removed sequences. The verifier reconstructs the original result at the creation boundary, then the current result. Added records are reported as a change fact. Removing an original event breaks the immutable evidence chain; it is not silently accepted as an ordinary removal from a slice. Reaction snapshots have incomplete recent-actor lists. The explorer compares adjacent snapshots of the same chat/message, including a predecessor outside the slice, and reports aggregate count deltas **between observations**. Missing recent actors are not claimed to have removed a reaction. The first snapshot has no inferred earlier state. Actor observations remain attributed to the snapshot in which they were supplied, not to an invented action time. ## API and exports `GET /api/board` accepts collection/chat/author/label/state/from/to/q/kind/comments, offset/limit and newest/oldest order. `GET /api/board/card/{id}` returns a card, source preview, thread, status history and related cards. The participants subroute returns eligible mention choices. `POST /api/board/{bookmark|highlight|slice|collection|comment|status|move|remove}` appends a record. `POST /api/board/slice-preview` calculates a query. Slice records are paged at `GET /api/board/slice/{id}/records`; recomputation always uses the current stable read snapshot. Live `/api/stream` emits payload-free `board` notifications, separately from journal cursors. `GET /api/board/export` returns a signed document. Chat-limited access receives a clearly labelled signed **disclosure**, never another chat's annotations or the full chain. Full evidence ZIPs carry `annotations.jsonl`, signed `case-board.json` and slice JSON appendices. HTML/PDF/JSON report settings select no board, bookmarks/slices without discussion, or cards with comments. The section explicitly separates team opinions from observations. Report data filters restrict the readable notes too; full signed source files in the evidence ZIP remain complete. `GET /api/board/slice/{id}/export` produces a signed `tgwitness-board-selection-v1` JSON excerpt; `?format=csv` produces a convenient table without a standalone signature. Keep the JSON and ZIP: ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_KEY_SHA256 --board python -m tgwitness.verify board-slice.json --evidence evidence.zip --fingerprint TRUSTED_KEY_SHA256 python -m tgwitness.verify case-board.json --evidence evidence.zip --fingerprint TRUSTED_KEY_SHA256 ``` The selection check authenticates the signed statement, exact source records and completeness of its query at the specified boundary. The evidence ZIP may be newer but must contain that prefix. A dangling target is reported explicitly. A different original slice snapshot, changed annotation, mismatched replay state or changed source fails. Old archives without annotations retain their existing verification behavior. Handover defaults to **Do not include**. Explicit inclusion projects cards through the already minimized records, omits inaccessible/omitted targets, withholds highlights whose source text was minimized, cleans team text with the same mention/contact rules, and optionally replaces investigator labels with R01, R02… in metadata and known occurrences in notes. No original `annotations.jsonl` is disclosed. The signed `tgwitness-case-board-handover-v1` sidecar and report contain the same minimized material. Slice counts describe disclosed records only, with original snapshot/query actor details withheld. Free-text names not known to the minimizer still require review, as they do in ordinary handovers. The derivative carries its own signature; the original annotations keep theirs in the full archive. ## Operating limits Parameters include soft limits of 10,000 cards and 50,000 comments, a slice page of up to 5,000 records, and media-preview control. Soft limits warn without deleting history. Feed pages are at most 200 cards. Standalone JSON slice excerpts are capped at 64 MiB; narrow the query or use the signed ZIP for larger material. The standalone verifier caps annotations replay at 256 MiB. No external comment notifications are enabled or implemented by Case Board. The feature's automated acceptance uses fictional data and a simulated Telegram transport to check storage, access, rendering and exports. See [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) for the scope of the evidence checks. --- # Telegram Archive Analysis & Source Citations Canonical page: https://phishdestroy.io/tgwitness/docs/reference/analysis/ Analyze saved Telegram messages with source-linked reports. Review AI inputs, citations and the distinction between captured observations and interpretation. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Search saved messages, review AI inputs and keep analytical reports with their source references. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Investigation](https://phishdestroy.io/tgwitness/docs/reference/investigation/) ![Investigation](https://phishdestroy.io/tgwitness/assets/chapter-investigate.svg?v=48c1be9d2a52) [Workflow guide](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) Use **Journal** for local search without AI; [full-text search](https://phishdestroy.io/tgwitness/docs/reference/search/) (preview) matches word forms, phrases, domains and @usernames. For **More tools → Ask the archive**, first enable and configure a provider in **More tools → Integrations**. The workspace selector chooses the account; the form chooses chats and the observation period. Retrieval runs locally. An exact phrase or domain narrows retrieval; a message ID requests saved versions. Review the excerpts and open their journal records or context. There is no vector database or automatic Telegram action. ## Providers and consent AI starts disabled in every workspace. Only the main administrator can configure the model, endpoint, encrypted API key, context/output limits, timeout and daily request budget. The key is never returned to the browser. Keep a blank key field to retain the current key, or explicitly remove it. Ollama uses its documented [`/api/chat` endpoint](https://docs.ollama.com/api/chat) with non-streaming JSON output. Its default address is `http://127.0.0.1:11434` on the TgWitness server. The operator can change it using `TGWITNESS_AI_LOCAL_ENDPOINT`; this is not a model-controlled address. Install the selected model yourself. TgWitness does not download it automatically. The compatible provider expects a base URL ending in `/v1` and the [Chat Completions protocol](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create): `messages`, JSON response mode, `max_completion_tokens`, and `choices[0].message.content`. Services lacking these fields are not supported. Connection testing sends synthetic text and counts toward the request budget. Every request uses the workspace's configured outside route. A blocked route or Telegram-only MTProxy is an error; there is no direct retry. A deliberately configured local Ollama address permits a private destination. A loopback AI endpoint requires the workspace's Direct outside route; proxy routes are rejected before transmission. For other private services the existing server-level private destination opt-in applies. The preview shows the endpoint and outside route, including the proxy host when applicable. Changing that route requires a new preview. Before generation, **Data sent to the model** shows the request: question, checked excerpts, event kinds, observation times and coverage markers. Telegram sessions, raw fields, provider keys, attachment bytes and the full journal are not part of that context. Uncheck unwanted sources, then explicitly approve processing. External providers may retain submitted content under their own policies. Local execution means the endpoint is local; a separately configured service follows its own configuration. There are at most two concurrent provider requests globally and one per workspace. A preview expires after ten minutes and can generate one answer. The provider's reported token counts are shown; a cost estimate appears only when both input and output tariffs have been configured. Failed attempts also consume the daily request budget. No automatic retries spend additional budget. ## Sources and limits Retrieval uses the [full-text index](https://phishdestroy.io/tgwitness/docs/reference/search/#ask-the-archive-and-mcp) when it is complete: the best matches across the selected chats, with word forms. Questions about recent changes or one message's versions, and searches while the index is building, use a bounded lexical search of the newest records. The preview names the method. Retrieval returns up to 24 sources; long texts are cut around their match. Truncated excerpts and incomplete result sets are marked. The period refers to **observation time**, not a claim that Telegram history is complete. Workspace-wide coverage events are withheld from chat-scoped access. Missing data is described as not found in the available archive. The model receives no tools. Its source IDs are resolved against the selected records, hashes are rechecked, and quoted strings must occur in those records. Unknown IDs, changed quotes and uncited claims reject the answer. The application creates links; model-generated URLs are not used as citations. These checks establish source existence and quote accuracy. Review inferences against the records before relying on them. ## Reports Save a reviewed answer as a separate analytical report. It includes the model summary, observed chronology, extracted links and handles, edit/deletion records, coverage limits, and source event hashes. The provider, model, endpoint, time and prompt-template version accompany it. No identities are automatically merged. Analyst revisions and notes are stored separately from the model summary. Reports live in encrypted derived files, with an index outside the signed event stream; the original events and media do not change. Only the owner or administrator can open a report, and source access is checked again. Download also requires export permission. Version 1 does not sign reports or imply that model conclusions are verified evidence. Limits: 100 reports per workspace and 100 analyst revisions per report. For manual OCR and transcripts, see [media processing](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/). For client access, see [MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/). --- # Telegram Archive Full-Text Search Canonical page: https://phishdestroy.io/tgwitness/docs/reference/search/ Search captured Telegram messages by word forms, exact phrases, domains and usernames. Review ranking and how the index stays tied to the signed journal. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Find saved messages by word forms, exact phrases, domains and @usernames, best matches first, with the index bound to the signed journal. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Investigation](https://phishdestroy.io/tgwitness/docs/reference/investigation/) ![Investigation](https://phishdestroy.io/tgwitness/assets/chapter-investigate.svg?v=48c1be9d2a52) [Archive analysis](https://phishdestroy.io/tgwitness/docs/reference/analysis/) · [Local OCR and transcription](https://phishdestroy.io/tgwitness/docs/reference/media-analysis/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) **Preview.** In **Journal**, choose **Best match · word forms** next to the search field. Results are ranked with BM25 and match other forms of the same word: *перевод* finds *переводом* and *переводы*, *transfer* finds *transfers*, a Chinese phrase is found without spaces. **Newest first · exact text** keeps the previous substring search over the whole record. The index is derived data. It is rebuilt from the signed journal, is never signed itself and never enters an export. The original records do not change. **On this page** - [Search syntax](https://phishdestroy.io/tgwitness/docs/reference/search/#search-syntax) - [Languages](https://phishdestroy.io/tgwitness/docs/reference/search/#languages) - [Where the index lives](https://phishdestroy.io/tgwitness/docs/reference/search/#where-the-index-lives) - [Results and the signed journal](https://phishdestroy.io/tgwitness/docs/reference/search/#results-and-the-signed-journal) - [Recognized text](https://phishdestroy.io/tgwitness/docs/reference/search/#recognized-text) - [Access](https://phishdestroy.io/tgwitness/docs/reference/search/#access) - [Ask the archive and MCP](https://phishdestroy.io/tgwitness/docs/reference/search/#ask-the-archive-and-mcp) - [Dependencies](https://phishdestroy.io/tgwitness/docs/reference/search/#dependencies) - [Benchmark](https://phishdestroy.io/tgwitness/docs/reference/search/#benchmark) ## Search syntax | Write | Finds | | --- | --- | | `перевод карта` | Records containing both words, in any form | | `"переводом на карту"` | The exact phrase, in this order | | `бонус OR подарок` | Either word | | `перевод -казино` | Records without the excluded word | | `example.com` | The domain and its subdomains, also in hidden links and button URLs | | `@username`, `t.me/username` | Mentions and links of the account, and messages it sent | | `#tag` | The hashtag | | `+79991234567`, a wallet address, an e-mail address | The same value in text or links | | `from:@username`, `from:123456` | Messages from that sender | | `chat:-1001234567890` | One chat; it can only narrow your own access | | `id:42` | Saved versions of message 42 | | `since:2026-01-01 until:2026-01-31` | Observation period; a date without a time covers the whole day | | `kind:edited` | Only edits (`new`, `snapshot`, `edited`, `recovered`) | | `source:ocr`, `source:transcription`, `source:all` | Recognized text instead of, or with, messages | Prepositions and other function words are ignored when other words are present. Look-alike letters mixed into a word (a Latin *a* inside a Cyrillic word), fullwidth and decorative Unicode letters and invisible characters are normalized. ## Languages The language is detected per record from its script and letters: | Script | Matching | | --- | --- | | Cyrillic | Russian and Ukrainian lemmas with [pymorphy3](https://github.com/no-plagiarism/pymorphy3). Without the optional Ukrainian dictionary a light Ukrainian stemmer is used | | Latin | English Snowball stemmer; diacritics are ignored | | Chinese, Japanese, Korean, Thai, Lao, Khmer, Myanmar | Overlapping character pairs: any phrase is found without spaces. Chinese queries are split into words with jieba | | Other scripts | Exact words | The Ukrainian dictionary (`pymorphy3-dicts-uk`) is distributed under GPL-3.0, so it is not installed by default. Install it with `pip install "tgwitness[uk-dictionary]"`; the index notices the new analyzer and rebuilds itself. ## Where the index lives | Mode | Storage | Use | | --- | --- | --- | | On disk (default) | `search/fulltext.sqlite3` in the workspace directory | Large archives; survives restarts | | In memory only | Nothing on disk; rebuilt at every start | No derived copy of message text on disk | | Off | No index; **Newest first · exact text** remains | Minimal installations | The main administrator chooses the mode under **Journal → Filters → Search index** for each workspace. `TGWITNESS_FULLTEXT=disk|memory|off` sets the default for workspaces without their own choice. Switching to memory or off deletes the file. The index file has the same protection as the journal: it sits in the private data directory. Backups and off-site copies leave it out. New records are indexed in the background within seconds; a search also indexes a short backlog first, so a record saved a moment ago is found. An existing journal is indexed after the update without blocking the panel; until then, results cover the indexed records and the journal shows the progress. **Rebuild index** starts again from the first record. ``` python -m tgwitness index status --data-dir data/live python -m tgwitness index rebuild --data-dir data/live --json ``` `rebuild` needs the panel to be stopped (exit code 3 otherwise). With `--json`, standard output carries only the result; progress goes to standard error. ## Results and the signed journal The index stores the sequence number and hash of the last journal record it covers and checks them against the journal when it opens. A replaced, restored or edited journal causes a rebuild. Every response reports this position, and every hit is read back from the signed journal by its sequence number: the index decides which records to show and in what order, never their content. Chat access is applied to the journal's own chat field, not to index content. ## Recognized text OCR and transcripts stay in their encrypted artifacts. Their index exists only in memory and is rebuilt when a recognition job completes. A hit appears on its `media.saved` record, labelled as machine recognition with the engine, model and an excerpt; it is never presented as text sent in Telegram. The same index serves **Search recognized text**, which still also matches plain substrings. ## Access Chat-scoped access finds only records from its chats, including recognized text of their attachments. `chat:` and other filters can only narrow that set. Index status shown to scoped access omits journal totals. Only the main administrator can change the mode or rebuild the index. ## Ask the archive and MCP **More tools → Ask the archive** retrieves its sources from this index when it is complete: the best matches across the selected chats, with a saved text counted once. Up to 24 sources are sent; long texts are cut around their match and marked as truncated. Questions about recent changes, saved versions of one message, and searches while the index is still building use the previous chronological retrieval. The preview shows which method was used. MCP clients can call `search_messages` with `ranked=true` and page with `next_offset`. Scoped connections receive only their chats. Ranked pagination covers at most the first 1,000 results, regardless of page size. Narrow the query, chat or period to inspect further matches. Newest-first searches order messages, OCR and transcription results before selecting each page. ## Dependencies | Package | Licence | Why | | --- | --- | --- | | pymorphy3, pymorphy3-dicts-ru, DAWG2-Python | MIT | Russian and Ukrainian lemmas; dictionaries are loaded locally | | snowballstemmer | BSD-3-Clause | English stems, pure Python | | jieba | MIT | Chinese query segmentation, pure Python (source distribution only) | | pymorphy3-dicts-uk (optional) | GPL-3.0 | Full Ukrainian dictionary | SQLite FTS5 with the `unicode61` tokenizer is required; it is part of the SQLite in current Python builds. Without it, best-match search reports that it is unavailable. ## Benchmark `python tools/bench_fulltext.py --messages 1000000 --work ` creates a deterministic signed journal of mixed Russian, Ukrainian, English, Chinese and Japanese messages with links and handles in 200 chats, builds the index and times typical searches (50 results, median of 7 runs). Measured on Windows 11, Intel Core i9-13900K, 128 GB RAM, Python 3.12.10, SQLite 3.49.1, data on an exFAT drive, analyzer `fulltext-v1+pymorphy3-ru+light-uk+snowball-en`: | Measure | Result | | --- | --- | | Signed journal | 1,000,000 messages, 1.50 GiB, written in 19 minutes | | Index build from the journal | 71 s, about 14,141 messages per second | | Index file | 58 MiB, 3.8% of the journal | | Search right after a new record | 8 ms median, 9 ms p95 | | Previous substring search, same journal | `перевод` 3.2 s, `银行转账` 2.6 s, `verify-account.example` 2.6 s | | Search | Matching records | Best match, median | p95 | Newest first, median | | --- | --- | --- | --- | --- | | Common word, word forms: `перевод` | 134,403 | 82 ms | 85 ms | 7 ms | | Two words: `оплата карта` | 28,996 | 43 ms | 43 ms | 14 ms | | Rare word: `розыгрыш подарок` | 28,881 | 42 ms | 47 ms | 13 ms | | Exact phrase: `"переказ коштів на картку"` | not counted | 35 ms | 36 ms | 6 ms | | Domain with subdomains: `verify-account.example` | 12,435 | 17 ms | 17 ms | 3 ms | | @username: `@support_desk_bot` | 10,331 | 15 ms | 16 ms | 3 ms | | Chinese without spaces: `银行转账` | 17,691 | 23 ms | 24 ms | 3 ms | | Japanese: `リンク` | 16,603 | 23 ms | 25 ms | 3 ms | | English stem: `withdrawal` | 27,775 | 26 ms | 26 ms | 2 ms | | OR and exclusion: `бонус OR подарок -казино` | 268,034 | 190 ms | 193 ms | 19 ms | | Chat filter: `chat:-1000000000007 перевод` | 652 | 9 ms | 9 ms | 6 ms | | Period filter: `since:2026-01-01 until:2026-01-31 выплата` | 115,732 | 155 ms | 156 ms | 81 ms | An exact phrase is checked literally on candidates in rank order until the page is full, so its total is not counted. Times grow with the number of matching records; narrowing the chat or period makes broad searches faster. The synthetic corpus repeats a small vocabulary, so common words match far more records than in real chats. --- # Telegram Archive MCP Server: Read-Only Access Canonical page: https://phishdestroy.io/tgwitness/docs/reference/mcp/ Connect an MCP client to saved Telegram records through scoped, expiring access. Review supported tools, transports and the read-only archive boundary. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Connect an MCP client to selected workspaces and chats with expiring, revocable access. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Archive integrations](https://phishdestroy.io/tgwitness/docs/reference/cli/) ![Archive integrations](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074) Connect an analyst client to selected workspaces and chats. TgWitness serves **Streamable HTTP at `/mcp` in the panel process**. Each connection has its own token, expiry and permitted tools. MCP cannot send Telegram messages, change settings or modify the signed journal. The same connections work with the [command line](https://phishdestroy.io/tgwitness/docs/reference/cli/). [Workflow guide](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) **On this page** - [Install and check](https://phishdestroy.io/tgwitness/docs/reference/mcp/#install-and-check) - [Issue a connection](https://phishdestroy.io/tgwitness/docs/reference/mcp/#issue-a-connection) - [Connect your client](https://phishdestroy.io/tgwitness/docs/reference/mcp/#connect-your-client) - [Cloudflare Tunnel](https://phishdestroy.io/tgwitness/docs/reference/mcp/#cloudflare-tunnel) - [Tools and boundaries](https://phishdestroy.io/tgwitness/docs/reference/mcp/#tools-and-boundaries) ## Install and check Use the Python environment that runs the panel. From a source checkout: ``` # Windows PowerShell & .\.venv\Scripts\python.exe -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]' & .\.venv\Scripts\python.exe start.py --check ``` ``` # Linux / macOS .venv/bin/python -m pip install -c deploy/constraints-mcp.txt -e '.[mcp]' .venv/bin/python start.py --check ``` Restart the panel with its usual data directory and launch arguments after installation. Readiness should include `[PASS] mcp: streamable-http available`. **More tools → Integrations → MCP** shows the runtime status and an installation command using that server's actual Python executable. **Re-check** refreshes this status without reloading the page; it does not install packages or restart the server. The MCP extra uses the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk). `deploy/constraints-mcp.txt` pins the tested SDK and dependencies. ## Issue a connection 1. Enter a label and choose the workspaces and chats the client may read. 2. Select tools individually or use a preset. Only implemented tools are offered. 3. Choose 1, 7, 30 or 90 days, or a custom expiry between one minute and 90 days. 4. Press **Create connection**. The token appears once beside the client config. 5. Copy the token and config, then run **Check connection**. It initializes MCP and lists permitted tools; **no messages are read**. The result shows protocol version, tool names, count and elapsed time. 6. Press **Done** when the credential is saved. Polling preserves the form and the shown-once card. Locking the panel clears displayed secrets. The list shows recent use, last tool, address and requests in the last minute. **Revoke** ends access. **Rotate token** revokes the old credential and issues a replacement with the same scope, tools and expiry; copy the replacement once. Panel login tokens and Telegram credentials do not work as MCP tokens. ## Connect your client Select the client in the panel and copy its generated configuration. Configs use secret references or explicit placeholders; the token is copied separately. | Client | Configuration | Connection | | --- | --- | --- | | Claude Code | `.mcp.json` | HTTP, `type: "http"`, bearer header | | Claude Desktop | `claude_desktop_config.json` | Local stdio bridge | | Cursor | `.cursor/mcp.json` | HTTP with an environment-variable header | | VS Code Local | `.vscode/mcp.json` | HTTP with a password `promptString` input | | Windsurf | `mcp_config.json` | HTTP with a bearer-header placeholder | | Other clients | URL and Authorization header | Streamable HTTP | TgWitness uses bearer tokens, without OAuth discovery. Use the local stdio bridge for clients whose remote connector requires OAuth. For VS Code, input variables apply to the **Local** harness and are not forwarded to Copilot sessions. Configuration references: [Claude Code](https://code.claude.com/docs/en/mcp), [Cursor](https://prod.cursor.com/docs/mcp), [VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). The canonical entry point for a local bridge is: ``` python -m tgwitness.mcp_server --url https://your-panel.example/mcp ``` Use the client's local Python with the MCP extra installed. Set `TGWITNESS_MCP_TOKEN` in its protected environment. Keep credentials out of command arguments and URLs. `tgwitness-mcp` is the same entry point. The old `tgwitness.mcp_bridge` module and `TGWITNESS_ARCHIVE_TOKEN` name remain compatibility paths with a warning; new configs use `mcp_server` and `TGWITNESS_MCP_TOKEN`. ## Cloudflare Tunnel Forward the panel's `/mcp` route and preserve the bearer header. Opening MCP settings as an administrator registers the panel's current origin for this run. For a stable address available immediately after restart, configure `TGWITNESS_PUBLIC_URL` with the panel's HTTPS origin before starting the panel. Arbitrary Host and forwarded headers do not register a trusted address. Host and Origin checks reject unrelated browser origins. Responses use `Cache-Control: no-store`; authorization values are never logged. A `*.trycloudflare.com` address is temporary. When a tunnel restart changes the hostname, update the configured public URL and each client's MCP URL. Use a stable hostname for saved client configurations. ## Tools and boundaries | Tool | Reads | | --- | --- | | `list_workspaces` | Granted workspaces | | `list_chats` | Granted chats | | `search_messages` | Saved message text within the selected period; `ranked=true` uses [full-text search](https://phishdestroy.io/tgwitness/docs/reference/search/) (word forms, best matches first, `next_offset` paging) | | `get_message_versions` | Captured versions and deletion observations | | `get_message_context` | Nearby captured message IDs | | `get_journal_event` | One sanitized record with its source reference | | `get_capture_status` | Collection state, permitted coverage records and `gap_summary`: message numbers never observed, per channel or supergroup and for the account-wide sequence ([details](https://phishdestroy.io/tgwitness/docs/reference/evidence/#missing-message-numbers-gap_summary)); choose a chat to see its listed gaps | | `get_activity_stats` | Messages by UTC hour and weekday, peak days, edit and deletion shares, senders, domains and `@handles`, with coverage ([details](https://phishdestroy.io/tgwitness/docs/reference/cli/#activity-statistics)) | | `get_messages_by_date` | Saved messages of one calendar day in a named IANA time zone (`Europe/Kyiv`, `UTC`), by the time Telegram reports; `from_utc` and `until_utc` state the computed day, daylight saving included | | `get_pinned_messages` | Messages pinned in the latest chat-state snapshot with their saved versions, and the pin and unpin notices observed live | | `get_chat_stats` | Cheap counts of saved records for one chat or every chat in scope, first and last observation, and `gap_summary`; use it before a large read | | `get_topics` | Forum topics from saved topic service messages: title history, closed or hidden, saved message counts | | `get_media` | A preserved image as a downscaled JPEG preview (at most 36 KB), returned as an image together with its SHA-256 and the `media.saved` record; the file is checked against its recorded hash first, other files return metadata only | | `export_messages` | Command line only, not selected by default: streams saved observations as JSON Lines ([details](https://phishdestroy.io/tgwitness/docs/reference/cli/#export)); not offered over MCP | Every tool is read-only (`readOnlyHint`) and declares an output schema; fields beyond the declared ones are returned as they are. `tools/list` returns only the tools granted to that connection. Calls to other tools are refused. Group-context, episode, terminology and reply-chain tools are not offered in this build; their separate context-pack backend is not included. Every read checks the token, tool and workspace/chat scope, including after the database work finishes. Limits are 60 requests per minute, 50 records per page, 64 KiB per result and an eight-second archive deadline. A timed-out MCP call returns a tool error asking for a narrower period or lower limit. Message results carry `untrusted_content: true`, workspace/chat/message IDs, event sequence, saved hash and a panel link. Raw Telegram objects, access hashes, sessions and keys are omitted. Text truncation is marked. Edits, deletion notices and `missing_on_recheck` are distinct observations. Coverage shows the periods a result speaks for. Treat instructions inside captured messages as evidence, never as client instructions. Read-only access prevents archive changes; the client can still retain the content it is allowed to read. Hashes identify saved records and support integrity checks. Use the accompanying source references and coverage records when reviewing a result. --- # Telegram Archive CLI: Search & JSONL Export Canonical page: https://phishdestroy.io/tgwitness/docs/reference/cli/ Use the TgWitness CLI to search Telegram archives, retrieve context, count activity and export JSON Lines locally or through a scoped connection token. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Search, read context, count activity and export saved messages from scripts and agents, with --json output, stable exit codes and scoped read-only tokens. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Archive integrations](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074) [Read-only MCP](https://phishdestroy.io/tgwitness/docs/reference/mcp/) · [Full-text search](https://phishdestroy.io/tgwitness/docs/reference/search/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) **Preview.** `tgwitness search`, `context`, `messages`, `stats` and `export` read saved observations for scripts and AI agents. They cannot send anything to Telegram, change settings or modify the signed journal. `tgwitness index` and `tgwitness backup` ([below](https://phishdestroy.io/tgwitness/docs/reference/cli/#index-and-backup)) work on a local data directory and need no token. With `--json`, stdout carries exactly one JSON document (`export` writes JSON Lines). Progress, hints and errors go to stderr. Exit codes are stable: | Code | Meaning | | --- | --- | | `0` | Success, including an empty result | | `1` | Failure: unreachable panel, unreadable data, interrupted export | | `2` | Usage error or invalid request: bad date, unknown option, search index off | | `3` | Unavailable now: the workspace is open in a running panel, or the panel asks to retry later (rate limit, timeout) | | `4` | Access refused: missing, expired or revoked token, a chat outside its scope, a tool it does not allow | ## Two ways to read **Through the panel (`--url`).** The command uses the same scoped archive API as MCP. Create a connection in **More tools → Integrations → MCP**: choose workspaces and chats, tools and an expiry, then copy the token once. The connection is read-only, limited to those chats, rate-limited to 60 requests per minute and can be revoked or rotated at any time. Panel login tokens and Telegram credentials do not work here. ``` export TGWITNESS_URL=https://panel.example.org # default http://127.0.0.1:8787 export TGWITNESS_MCP_TOKEN=tgw_mcp_... # or --token-file path tgwitness search 'перевод карта' --json ``` A remote panel needs HTTPS; plain HTTP is accepted only for `127.0.0.1`, `localhost` and `::1`. Proxy environment variables are ignored and redirects are refused, so the token reaches only the address you give. **Directly from a stopped workspace (`--data-dir`).** Reads the data directory with full local access, without a token. Use it on a copy of a data directory or while collection is stopped. Signed records are never changed; like the panel, opening a workspace may bring its derived indexes up to date. When the panel has the workspace open, the command exits with code `3`; read through the panel instead. Without `--data-dir`, `TGWITNESS_DATA`, `./data/live` or the data directory of the installation running the command is used. `--workspace ID` selects a workspace (default `default`). `tgwitness messages --workspaces` lists the ones you can read. ## Commands | Command | Result | | --- | --- | | `tgwitness search QUERY [--chat ID] [--since] [--until] [--any] [--limit N] [--offset N]` | Best matches first, with word forms, exact phrases in quotes, domains and `@username` ([syntax](https://phishdestroy.io/tgwitness/docs/reference/search/#search-syntax)) | | `tgwitness search QUERY --exact [--before SEQ]` | Exact text, newest first, without the index | | `tgwitness context CHAT_ID MESSAGE_ID [--limit N] [--before SEQ]` | Saved messages within ten message IDs on either side | | `tgwitness messages [--limit N] [--offset N]` | Chats you can read | | `tgwitness messages CHAT_ID [--since] [--until] [--limit N] [--before SEQ]` | Saved messages of the chat, newest first | | `tgwitness messages CHAT_ID --message ID` | Every saved version and deletion record of one message | | `tgwitness stats [--chat ID] [--sender ID] [--since] [--until] [--top N]` | Activity statistics, below | | `tgwitness export [--chat ID] [--since] [--until] [--output FILE]` | Saved observations as JSON Lines in journal order | Dates are `2026-10-01` (UTC midnight) or ISO times with a timezone, `2026-10-01T09:00+03:00`. For `search`, `messages` and `export` they select observation time. Pages hold up to 50 records: follow `next_offset` (`--offset`) for ranked search and `next_before` (`--before`) elsewhere. Ranked search stops at 1,000 results. The final page may be shorter than `--limit`. When more observations match, the last page says so (`truncated: true` with `--json`); narrow the query, chat or period. Every message result carries `untrusted_content: true`, the workspace, chat and message IDs, the journal sequence, the saved record hash and a panel link. Edits, deletion notices and `missing_on_recheck` are separate records. Coverage in `stats` shows the periods a search result speaks for. ### Activity statistics `stats` counts saved observations for one chat, one sender, or every chat in scope: - messages by UTC hour and by weekday (Monday first), busiest hours and days; - edited, deleted and `missing_on_recheck` shares; - senders with message counts and first and last message times; - the most frequent domains and `@handles`, counted once per message across its saved versions; - coverage: `coverage.gap` records and, for access to the whole workspace, periods without a connected collector heartbeat (`collector_liveness`). The period selects **message time reported by Telegram**. Hour and weekday counts help estimate a sender's time zone. Figures are computed on request from the journal and are not stored. Each result names the journal head it covers when your access spans the workspace. Reading stops after five seconds through the panel, or `--timeout` seconds locally (default 30); then `complete` is false and `partial` names the first record that was not read. Only the most recent records are counted in that case. ### Export `export` writes one JSON object per saved observation (new messages, snapshots, edits, recovered messages, deletion notices, `missing_on_recheck` and saved media records) in journal order. Each line has the same fields as other results, with the full text. With `--output`, the file is written under a `.partial` name and renamed only after the panel's completion record; an interrupted export leaves no file and exits with code `1`. `--output` never overwrites an existing file. With `--output` and `--json`, stdout carries a summary: record count, last journal sequence and, for whole-workspace access, the journal head. An export through the panel needs a connection that allows **Export messages (command line only)**; it is not selected by default. This file is a working copy; for a verifiable handover use the signed export in **Exports**, which `python -m tgwitness.verify` checks. The panel rechecks access before emitting each record, including the completion record. Revoked or expired access leaves an incomplete export. Lazy page reads share the archive worker limit with other queries and have a bounded wait. ### Index and backup These two commands read the data directory directly and take no token or `--url`. | Command | Result | | --- | --- | | `tgwitness index status [--workspace ID] [--data-dir DIR] [--json]` | Search index state of one workspace or, by default, every workspace: mode, `ready`, `building` or `not built`, indexed and journal head sequence. Works while the panel runs | | `tgwitness index rebuild [--workspace ID] [--data-dir DIR] [--json]` | Rebuilds the index from the first journal record. Rewrites only the derived index, never the signed journal. Exits with code `3` while the panel has the workspace open. Nothing is built when the workspace keeps its index in memory or has search off | | `tgwitness backup FOLDER [--data-dir DIR] [--json]` | Copies the whole data directory into a new or empty folder outside it while the panel keeps running, and writes `backup-manifest.json` with every file's SHA-256 and the journal heads | `index` accepts `--workspace default` or a workspace ID; the default is `all`. The backup skips temporary exports, SQLite sidecar files and lock files. The folder holds the Telegram session and signing keys, so keep it as private as the data directory. [Backup, restore, and capacity](https://phishdestroy.io/tgwitness/docs/reference/deployment/#backup-restore-and-capacity) describes restoring and what the next start records. ## Agent skill [`.agents/skills/tgwitness-cli/SKILL.md`](https://github.com/phishdestroy/TgWitness/blob/main/.agents/skills/tgwitness-cli/SKILL.md) tells an agent how to use these commands, how to cite records and how to treat captured text. Agents that read `.agents/skills` load it from a repository checkout. For Claude Code, copy the `tgwitness-cli` folder to `.claude/skills/` in your project or `~/.claude/skills/`. ## MCP and the command line Both use the same connections, scope checks and limits. MCP results are limited to one 64 KiB page, so MCP offers no bulk export; the command line streams it. `get_activity_stats` is available to both. --- # Telegram Media OCR & Audio Transcription Canonical page: https://phishdestroy.io/tgwitness/docs/reference/media-analysis/ Extract text from captured Telegram images and audio with local OCR and transcription workers. Keep derived text linked to the original media and record. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Recognize captured images and audio with a local worker; keep derived text linked to its source file. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Investigation](https://phishdestroy.io/tgwitness/docs/reference/investigation/) ![Investigation](https://phishdestroy.io/tgwitness/assets/chapter-investigate.svg?v=48c1be9d2a52) [Workflow guide](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) Open a `media.saved` journal record, choose **Recognize attachment**, then select OCR or transcription under **More tools → Ask the archive** (named **Machine recognition** while archive AI is off). Processing is manual and local. There is no cloud media mode or automatic upload. Original attachment bytes and `media_sha256` remain unchanged; recognized text is explicitly marked as machine recognition and stored separately with the source hash, engine/model version, language, parameters and completion time. Transcripts retain returned timestamps. Search these results using **Search recognized text** and the OCR/transcript filter, or choose recognized text as the source of a **Journal** best-match search. Both match word forms through an [in-memory index](https://phishdestroy.io/tgwitness/docs/reference/search/#recognized-text). This is a separate derived-data search; it does not silently turn machine recognition into original Telegram text or add it to signed events. ## Set up the optional worker Version 1 requires a Linux host with a local Docker daemon. Windows installations can run TgWitness inside a Linux VM/WSL environment with its own local daemon. The panel never decodes an untrusted attachment itself. ``` docker build -f deploy/media-worker/Dockerfile -t tgwitness-media:local . export TGWITNESS_MEDIA_IMAGE=tgwitness-media:local ``` Set these variables in the TgWitness service environment and restart it. The daemon socket defaults to `/var/run/docker.sock`; rootless deployments can set `TGWITNESS_DOCKER_SOCKET`. The worker explicitly uses that Unix socket rather than a remote Docker context. Do not expose a Docker API to panel users or mount its socket inside the recognition container. For transcription, separately install a CTranslate2-compatible Whisper model, then set `TGWITNESS_WHISPER_MODEL_DIR` to its directory. The worker loads it with `local_files_only=True`; the selected model and input are mounted read-only. See the engine's [model-loading documentation](https://github.com/SYSTRAN/faster-whisper). The supplied OCR image includes English and Russian trained data. Build another language into your image when needed; language codes follow [Tesseract's CLI](https://tesseract-ocr.github.io/tessdoc/Command-Line-Usage.html). No model is fetched while processing. Build/download setup may use the network; each actual recognition container has networking disabled. Install the image before enabling it; runtime uses `--pull=never`. ## Bounds and recovery The container runs as an unprivileged user with a read-only root, dropped capabilities, `no-new-privileges`, one CPU, 2 GiB memory, a PID limit and a bounded temporary filesystem. Only a verified copy of the selected file and an optional model directory are mounted. The collector's database, vault and session are not mounted. The [Docker runtime flags](https://docs.docker.com/reference/cli/docker/container/run/) enforce these limits; this remains a container boundary, not a hardware enclave. Files are limited to 50 MiB, images to 20 million pixels, audio to 30 minutes with a known duration, and processing to five minutes. One worker runs at a time, with at most 20 queued/running jobs and 100 retained jobs per workspace. Cancel stops the container; retry creates a new job linked to the prior attempt. Interrupted jobs are marked after restart. Processing can fail when a model cannot fit the configured limits; it does not silently run without isolation. --- # Telegram Evidence Webhooks: HMAC & Delivery Canonical page: https://phishdestroy.io/tgwitness/docs/reference/webhooks/ Send scoped TgWitness events to HTTPS integrations with HMAC signatures. Configure retries and inspect webhook delivery without exposing unrelated records. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Send scoped events to HTTPS receivers with HMAC signatures, retries and delivery status. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Archive integrations](https://phishdestroy.io/tgwitness/docs/reference/cli/) ![Archive integrations](https://phishdestroy.io/tgwitness/assets/chapter-integrations.svg?v=367d9d210074) [Workflow guide](https://phishdestroy.io/tgwitness/docs/archive/) · [Wiki](https://github.com/phishdestroy/TgWitness/blob/main/docs/wiki/Archive-and-Integrations.md) Open **More tools → Integrations → Outgoing webhooks** in the selected workspace. Add an HTTPS receiver, choose collector/media/export events, and optionally select chats for new observations and changes. Message text is off by default. Enabling excerpts adds at most 1,000 characters to message-change events; raw Telegram fields and credentials are never sent. Copy the HMAC secret once into the receiver's protected configuration. It is encrypted in TgWitness's vault and cannot be retrieved from the panel. Remove and recreate a destination to rotate it. **Send synthetic test** queues a test with no chat content; refresh delivery status to see its outcome. Delivery extends the existing notification loop alongside Apprise. It uses the workspace's outside route and existing private-destination restrictions. There is no direct fallback or redirect following. URLs must not contain credentials, query strings or fragments; private addresses require the server-level network opt-in, not a setting a panel user can bypass. ## Payload and signature Schema: [`tgwitness.webhook/1`](https://github.com/phishdestroy/TgWitness/blob/main/integrations/webhook.schema.json). Every payload contains `event_id`, `timestamp`, `workspace`, `type`, `synthetic`, and counters. Journal-based events include their sequence and hash. Full-export completion and synthetic tests are delivery events, with no invented signed journal reference. Telegram deletion notices and `missing_on_recheck` remain distinct types. The `X-TgWitness-Signature` header is `t=UNIX_SECONDS,v1=HEX_HMAC_SHA256`. Compute HMAC over the exact bytes `timestamp + "." + raw_request_body`, using the displayed secret as UTF-8 bytes. Compare signatures in constant time before parsing or acting on the body. Reject timestamps more than five minutes from your clock. The timestamp is refreshed on each delivery attempt. Use `event_id` as an idempotency key in durable storage, with an atomic unique constraint before side effects. A valid signature alone does not prevent a recent request from being replayed. Keep processed IDs for at least the entire retry window; retain them longer if the receiver can reprocess stored events. ## Retries Deliveries are queued durably before HTTP requests. They use at-least-once semantics: a lost acknowledgement or restart may deliver an event again with the same ID. There are eight attempts with exponential backoff, starting at 15 seconds and capped at one hour. Success requires a 2xx response. A job that exhausts its retries stays visible with its error for review. The queue holds 1,000 deliveries. When full, scanning journal events pauses and resumes after space is available. A full-export completion that cannot be queued sets a visible queue error. Up to five deliveries are attempted per notification pass, and the latest 100 attempt records are retained. Removing a destination also removes its pending deliveries. ## n8n example Import [the example workflow](https://github.com/phishdestroy/TgWitness/blob/main/integrations/n8n-tgwitness.json). It is inactive and contains no secrets or downstream actions. Set `TGWITNESS_WEBHOOK_SECRET` in the n8n worker environment, allow that environment access, and allow the `crypto` builtin for the Code node. The example uses the Webhook node's raw-body option, checks signature/freshness, and acknowledges validated events. This matches the node's [documented implementation](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Webhook/Webhook.node.ts). Before adding SIEM writes or notifications, add durable idempotency storage keyed by `event_id`. Restrict n8n workflow editing and execution-log retention according to the data you elected to send. TgWitness adds no inbound commands. --- # Publish Captured Telegram Channel Evidence Canonical page: https://phishdestroy.io/tgwitness/docs/reference/showcase/ Share selected saved public-channel messages through scoped showcase links. Review expiry, revocation, signed snapshots and the scope of the published material. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Publish saved messages of selected public channels and signed snapshots through expiring, revocable links. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Deployment and recovery](https://phishdestroy.io/tgwitness/docs/reference/deployment/) ![Deployment & recovery](https://phishdestroy.io/tgwitness/assets/chapter-operate.svg?v=7039a376d47f) **More tools → Access → Public showcase** creates a separate, read-only page using the existing access-token system. It reads the installation's saved observations. It does not start a collector, sign in to Telegram or acquire a channel for a visitor. ## Publish a page 1. Save a source profile for each public channel you want to show. A channel must have a public username in its latest saved profile; groups and private chats are not eligible. 2. Open **More tools → Access → Public showcase** (or `/showcase-manage.html`) as the administrator. 3. Select channels across up to 16 workspaces, enter the public page title, and choose a link lifetime of 1, 7 or 30 days. Internal workspace labels are not published. Up to 64 channels can be included. 4. Review the selected channels' text for publication, then click **Preview selected records**. The preview uses the same server-side projection as the visitor page. 5. Click **Create showcase link**. Copy the link while it is visible. Open it in a separate browser to review the recipient's page before distributing it. The link contains an access token in its URL fragment. The page removes the fragment before making API requests and exchanges it for a browser session. Anyone holding the link can open the selected material until expiry or revocation. New links allow 100 concurrent sessions, each lasting at most one hour. Existing Access controls can also enforce address restrictions and sign-in limits through the grant API. Normal reviewer access is a different mode and still includes the original permitted messages and files. ## What visitors see | Visible | Kept private | | --- | --- | | Selected public channel titles, usernames and profile observation dates | Account identities, internal workspace labels and unselected sources | | Captured text and each saved edit | Structured sender IDs, names, usernames, phone numbers and profile values | | Deletion observations with the previously saved text, if available | Attachments, avatars, thumbnails, filenames and original payloads | | Markers saying an author/profile or attachment was recorded | Forwarding and reply metadata, network routes, IP addresses and credentials | | Selected-channel event counts, current collection switches, heartbeat and checkpoint interval | Collection controls and ordinary evidence-export APIs | | Signing fingerprint, journal checkpoint and consistency proof | Signing keys and Telegram sessions | **Public message text is not automatically anonymized.** A name, mention, phone number or link written into the message remains part of that text. `Redacted` applies to the structured author/profile fields. Review the actual selected content before publishing it, including preserved edits and deletions. Eligibility reflects the **latest saved source profile**, not a live Telegram lookup. If a subsequent profile no longer has a public channel username, new requests exclude the channel. Refresh source profiles when public visibility changes. Readers may already have saved material they previously received. The original signed records stay unchanged. The displayed projection is signed separately and carries hashes referencing its original records. The projection signature authenticates the displayed statement, and the referenced original records keep their own signatures. ## Check signatures and continuity Expand **Fingerprint & signed checkpoint** and download a snapshot. After a page refresh, the download includes the preceding browser snapshot and a Merkle consistency proof between their journal boundaries. Automatic refresh is once a minute while the page is visible and showing its first page of observations. With TgWitness installed, verify the downloaded file offline: ``` python -m tgwitness.showcase_verify showcase.json --fingerprint TRUSTED_COLLECTOR_SHA256 ``` The fingerprint must come from a separately trusted reference. To compare against a snapshot you retained yourself, use `--previous earlier.json`; this overrides the previous snapshot carried inside the download. The current proof must begin at that retained boundary. Authenticated clients can request that proof using `GET /api/showcase/{workspace_id}?challenge=<32-hex-random>&from_count=`. A shorter journal returns HTTP 409 instead of silently resetting the boundary. The signed checkpoint commits to the **whole collector journal**, including its record count and opaque head hash. Displayed message counts apply only to the selected public channels. The page never lists the other journal's contents. These are event counts, not unique-message counts. The settings describe the current configuration, not every earlier recording interval. Signature and consistency verification can detect changes relative to a retained boundary. Recount the reported events from the corresponding archive and review the acquisition intervals and retained witness checkpoints together. Use the [evidence verifier](https://github.com/phishdestroy/TgWitness/blob/main/docs/TRUST.md), [independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/) and [tested-scale record](https://phishdestroy.io/tgwitness/docs/reference/verification/). Synthetic installations are visibly labelled as synthetic. ## Revoke or host the page Use **Revoke** in the showcase manager or the existing **Access** section to close the link and end all its sessions. The visitor clears displayed records when a request detects that access has ended. Expiry and permissions are checked on every request. Showcase grants cannot be converted to ordinary panel access in place; create a new grant to change modes. Serve the page through the installation's existing HTTPS address. Publishing a link does not open a new port, create a tunnel or change DNS. The HTML and API remain on the user's installation. A showcase visitor cannot use the ordinary message, profile, media, export or management APIs with this access. --- # Evidence Verification: SHA-256 & Ed25519 Canonical page: https://phishdestroy.io/tgwitness/docs/reference/how-it-works/ Study the TgWitness evidence chain: canonical records, SHA-256 hashes, Ed25519 signatures, checkpoints and witnesses, with the verifier's exact formulas. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Hash chain, signatures, checkpoints and witnesses explained with the exact formulas the verifier uses. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Evidence and verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/) ![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c) TgWitness preserves what a collecting account observed, links those observations into a signed journal and lets another person verify an export against a trusted key, external time from a third party and an earlier retained checkpoint. The [local documentation website](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/PUBLISHING.md#preview-the-website-locally) adds interactive examples at `/docs/concepts/`, a checkpoint decision explorer at `/docs/witness/`, and walkthroughs for [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/), [report design](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) and [handover extracts](https://phishdestroy.io/tgwitness/docs/reference/evidence/#handover-extract). All example messages, counts and delays are fictional. Hashes in the chain sandbox are calculated with SHA-256 in the browser. Nothing is sent to Telegram. **On this page** - [A message changes; observations accumulate](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#a-message-changes-observations-accumulate) - [What a hash covers](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#what-a-hash-covers) - [What an earlier checkpoint adds](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#what-an-earlier-checkpoint-adds) - [Where a witness belongs](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#where-a-witness-belongs) - [Test delivery against known actions](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#test-delivery-against-known-actions) - [Pick a workflow](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#pick-a-workflow) ## A message changes; observations accumulate Sequence diagram · Telegram → Collector: New message: Meet at 10:00; Collector → Signed journal: Append message.new; Telegram → Collector: Edit: Meet at 11:00; Collector → Signed journal: Append message.edited; Telegram → Collector: Deletion notice; Collector → Signed journal: Append message.deleted; Note on Signed journal: Original + edit + deletion observation remain · Telegram · Collector · Signed journal · New message: Meet at 10:00 · Append message.new · Edit: Meet at 11:00 · Append message.edited · Deletion notice · Append message.deleted · Original + edit + deletion observation remain **Diagram as text** 1. Telegram → Collector: New message: Meet at 10:00 2. Collector → Signed journal: Append message.new 3. Telegram → Collector: Edit: Meet at 11:00 4. Collector → Signed journal: Append message.edited 5. Telegram → Collector: Deletion notice 6. Collector → Signed journal: Append message.deleted 7. Note on Signed journal: Original + edit + deletion observation remain This simplified sequence assumes Telegram delivered each update and the selected account could see it. Operational events also share the journal. A deletion notice does not supply the deleter or an exact deletion time. Repeated deliveries are separate observations; there is no journal-wide duplicate suppression. ## What a hash covers ![Observe, encode, hash and sign: each new event includes the preceding hash.](https://phishdestroy.io/tgwitness/assets/evidence-chain-animated.svg?v=368c25a3be9c) Read the formula from the inside out: **C** turns the nine fields into exact bytes; **SHA-256** produces their digest; **hex** is how that digest is stored. The previous hash is already inside the event. **unhex** turns the stored hash back into the 32 bytes that Ed25519 signs. [Static chain diagram](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-chain-static.svg) Let C(ei) be the canonical UTF-8 JSON of the nine event fields. The first `previous_hash` is 64 zero characters. Each later record includes the preceding record's hexadecimal hash: hi = hex(SHA256(C(ei))) σi = Ed25519.Sign(sk,unhex(hi)) The signature covers the 32 raw digest bytes. The hash input contains exactly `seq`, `observed_at`, `source_at`, `kind`, `chat_id`, `message_id`, `actor_id`, `payload` and `previous_hash`. Object keys are sorted; whitespace and ASCII escaping are omitted; NaN and infinity are rejected. See the [exact encoding](https://phishdestroy.io/tgwitness/docs/reference/evidence/#event-canonicalization). Flow diagram · 64 zero characters → Record 1 / hash h1; Record 1 / hash h1 → Record 2 includes h1 / hash h2; Record 2 includes h1 / hash h2 → Record 3 includes h2 / hash h3; Record 3 includes h2 / hash h3 → Signed checkpoint: count 3, head h3 (retain elsewhere) · 64 zero characters · Record 1 / hash h1 · Record 2 includes h1 /hash h2 · Record 3 includes h2 /hash h3 · Signed checkpoint:count 3, head h3 · retain elsewhere **Diagram as text** 1. 64 zero characters → Record 1 / hash h1 2. Record 1 / hash h1 → Record 2 includes h1 / hash h2 3. Record 2 includes h1 / hash h2 → Record 3 includes h2 / hash h3 4. Record 3 includes h2 / hash h3 → Signed checkpoint: count 3, head h3 (retain elsewhere) | Change to the supplied journal | What detects it | | --- | --- | | Alter record 2 while leaving its saved hash | Recomputed event hash differs; its signature no longer covers the changed event | | Rebuild the altered record and every later hash | The original signatures fail; a retained checkpoint at the affected boundary also disagrees | | Remove the tail but keep the remaining prefix intact | An earlier retained checkpoint beyond the supplied prefix reveals that the export is too short | | Re-sign a replacement journal with another key | A separately trusted key fingerprint rejects the replacement identity | ![Changing a saved field changes its digest; rebuilding hashes does not restore the original signatures.](https://phishdestroy.io/tgwitness/assets/evidence-tamper-animated.svg?v=5ca92399bea5) **Try the logic on record 2:** change `Meet at 11:00` to `Meet at 12:00` in the saved event. Its recomputed hash no longer matches. Recalculating the later chain can repair its links, but cannot make the original signatures cover the new digests. An observed Telegram edit, by contrast, becomes a new journal record. [Static change diagram](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-tamper-static.svg) Hash links alone do not prevent someone from recalculating a replacement chain. Trust comes from checking signatures under an independently trusted key, external time from a third party that fixes the journal head, and references retained outside the collector. ## What an earlier checkpoint adds ![Retain count 3 and head h3; a later export of 4 records is checked at position 3.](https://phishdestroy.io/tgwitness/assets/evidence-checkpoint-animated.svg?v=e68f4e7be4b9) **The reference stays still while the journal grows.** If the checkpoint says “3 records, head h3”, a four-record export can pass by matching h3 at position 3. Its newest head is h4, which is expected to differ. An export of only two records fails. [Static checkpoint diagram](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-checkpoint-static.svg) After verifying the checkpoint signature, require: Nexport ≥ Ncheckpoint and hexport[Ncheckpoint] = Hcheckpoint An export may extend beyond a checkpoint. It must agree at the retained boundary. The collector key signs the checkpoint, so the collector could sign another one. It binds the records only if the recipient obtained it before the archive, through another channel; the minimum for evidence also needs external time from a third party. The real verifier also checks every event's sequence, previous link, hash and signature. Comparing only the final stored head would miss an altered interior record whose saved hash was not updated. ## Where a witness belongs Flow diagram · Collector / account session / key A → Read-only checkpoint endpoint; Witness / pinned collector key / own key B → Separate signed witness journal; Witness / pinned collector key / own key B → Read-only checkpoint endpoint (Request a check); Read-only checkpoint endpoint → Witness / pinned collector key / own key B (Signed answer); Witness / pinned collector key / own key B → Channel with signed TGW1 posts (Bot API / own token) · Host A · Host B · Collector / accountsession / key A · Read-only checkpointendpoint · Witness / pinned collectorkey / own key B · Separate signed witnessjournal · Channel with signed TGW1posts · Request a check · Signed answer · Bot API / own token **Diagram as text** 1. Collector / account session / key A → Read-only checkpoint endpoint 2. Witness / pinned collector key / own key B → Separate signed witness journal 3. Witness / pinned collector key / own key B → Read-only checkpoint endpoint (Request a check) 4. Read-only checkpoint endpoint → Witness / pinned collector key / own key B (Signed answer) 5. Witness / pinned collector key / own key B → Channel with signed TGW1 posts (Bot API / own token) The witness records rollback, a different head at the same count, changed keys, invalid answers and missing responses. To confirm that every earlier record is unchanged, compare the export with retained checkpoints. A witness on another host avoids sharing the collector's host outage; a separate operator gives additional independence. The verifier checks that the witness key differs from the collector key; the custodian's key-control record shows who holds it. Telegram dates each post in a public channel, and `verify.py --channel https://t.me/s/…` reads those dates as external time. The witness attests to the collector's reported journal state. Use a controlled delivery test to measure which Telegram actions reached a collecting account. See [witness setup](https://phishdestroy.io/tgwitness/docs/reference/witness/). ## Test delivery against known actions Use a controlled group, distinct collecting accounts and a fresh marker. Send, edit and delete deliberately, checking capture between stages. Define the expected actions and a cutoff before inspecting the results. R = |observed∩expected| / |expected| Δ t = treceipt - taction Only matched expected actions count; duplicate receipts do not increase the numerator. The denominator must be nonzero. A missing receipt has no measured delay. Document clock uncertainty; use your own controlled deletion action time, because Telegram does not provide the exact deletion time. A result such as 5/6 (83.3%) describes the test actions, not the completeness of all Telegram traffic. ## Pick a workflow The [complete investigation walkthrough](https://phishdestroy.io/tgwitness/docs/reference/investigation/) follows an incident across a channel, group, bot and private chat: 1. On a dedicated collecting account, enable whole-account Investigation mode and inventory accessible chats. Use selected chats or a folder for a main account. 2. Acquire journal snapshots, per-chat full history and preserved attachments. 3. Keep live changes and any deliberate panel interactions with their receipts. 4. Follow numeric sender IDs, reply relationships, repeated destinations and file hashes through cited records and people profiles. 5. Add source-linked notes and collections in Case Board. Reconstruct a cross-chat timeline with both timestamps and explicit gaps. 6. Compare other account workspaces while keeping their origins and keys separate. 7. Assemble and verify the signed journals, profiles and history exports with case notes. The website's `/docs/cases/` guide includes an interactive case map and variants for bot disputes, removed messages and participants changing names. Case Board keeps notes and collections within a workspace. Group exports collect separate workspace packages; cross-workspace correlation and a combined timeline remain analyst work. [Completed validation and remaining work](https://phishdestroy.io/tgwitness/docs/reference/verification/) · [Export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/#investigation-handoff) · [Start with one account](https://phishdestroy.io/tgwitness/docs/reference/quickstart/) --- # Telegram Report Formats & Signed PDF Verification Canonical page: https://phishdestroy.io/tgwitness/docs/reference/case-reports/ Configure Telegram evidence reports, filters, layouts and contents. Review report revisions, included assessments and verification of HTML and signed PDF. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Report filters, eight designs, contents presets, saved change histories and the assessment included in signed exports. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Investigation](https://phishdestroy.io/tgwitness/docs/reference/investigation/) ![Investigation](https://phishdestroy.io/tgwitness/assets/chapter-investigate.svg?v=48c1be9d2a52) Turn selected observations into a readable account of the case: its question, scope, saved changes, charts, findings and source references. Each report gives the recipient a way to check the delivered material and inspect its collection coverage. The **Basis of trust** section appears in journal, handover, chat, account and sharing reports. Journal and handover PDFs use the same assessment as their signed `report.json`. ZIP manifests carry `case_assessment` in the signed manifest. This assessment travels with the exported material. The original observations retain their existing signatures. ## Document formats and reading order ### Report studio Open **Exports → Configure and preview**. Work through **Data → Design & contents → Preview**: 1. Use the whole workspace or choose chats, authors, inclusive UTC observation dates and event types. Load the catalog to search chats and authors, or enter their Telegram IDs. Author filters match recorded sender IDs; a deletion notice without a sender does not match an author filter. 2. Pick a page design, then choose charts, participant labels, the transcript and your written findings. Changing the design keeps these choices. 3. Build the preview. It shows actual counts, activity, participants, sample records, saved changes and missing message-number ranges. Changing a choice marks the preview out of date. Save before downloading HTML, signed PDF, signed JSON or the evidence ZIP. The data preview counts the complete stable journal prefix, not an initial sample. Only displayed sample rows and long lists are bounded; their omitted counts are shown. A later export takes a fresh stable snapshot, so ongoing collection may increase the figures. Scope, counts and source identity are included in the signed report. Opening or previewing the form does not save it. **Jurisdiction guidance.** Under Document details, open **Jurisdiction guidance · optional** to choose a jurisdiction and civil/commercial or criminal procedure. The appendix carries the legal basis, source links, preparation notes and research status. Local-language summaries and explanations of collection safeguards are optional. No jurisdiction is selected by default. These choices belong to the workspace, and are excluded from saved layout configurations and implicit sharing-copy defaults. See [defaults, supported reports and research limits](https://github.com/phishdestroy/TgWitness/blob/main/docs/JURISDICTION_GUIDANCE.md). **Choose the recipient's copy.** Charts and the transcript use the selected records. Integrity, custody and coverage describe the full source journal. The evidence ZIP contains its original records and attachments. Use [a minimized handover](https://phishdestroy.io/tgwitness/docs/reference/evidence/#handover-extract) when a recipient should receive only selected, permitted data. ### Read edits, deletions and missing IDs An edit shows the saved **Before** and **After** text and highlights the changed words. A deletion shows the last version saved before the notice. If no earlier content was captured, the report says so. When you select only edits or deletions, the preceding versions remain available as explicitly labelled context outside the filters. Unrelated messages are not added to these histories. **Unobserved message IDs** are gaps between known numbers in the chosen chats and date-derived ID span. Every known source record is checked before declaring a number unobserved: filtering out another author, an event type or a date cannot create a false gap. Neighboring saved messages are labelled as context. A missing number marks an unobserved position; deletion notices and unsuccessful rechecks are reported as their own event types. ### Choose a design Nine page designs are available for journal and single-chat HTML and signed PDF reports. They use the same records and calculations, with different covers, typography, chapter headings, tables and spacing. | Design | Reading style | | --- | --- | | Classic | A traditional dossier with a dark cover and numbered sections. | | Editorial | A framed serif title page, wide margins and a narrow chapter rail. | | Briefing | A compact cover with a navy spine, short headings and close-set tables. | | Analytics | A survey-style cover, modular chart plates and monospaced figures. | | Technical | A ruled register, numbered reference rail and precise comparison tables. | | Overview | A panoramic cover, generous spacing and prominent summary figures. | | Reading series | A section rail and grouped chapters for findings, scope, changes and the observation journal. | | Ledger & margin | Numbered chapters with a wide margin, exact chart tables and a separate message transcript. | | Profile overview | Key figures, observed profiles and searchable sections with links to chat records. | The design is saved per workspace and recorded in the signed export manifest. HTML works offline, supports light and dark themes, and adapts to narrow screens and right-to-left languages. Native PDFs use bundled fonts; the Editorial design includes Noto Serif under its bundled SIL Open Font License. Reading series and Ledger & margin also apply to account overviews, account chats and sharing copies. Chinese, Japanese and Korean PDFs additionally need a suitable font on the server, such as Noto Sans CJK, installed system-wide or placed in `TGWITNESS_FONT_DIR`. When it is unavailable, the ZIP keeps the HTML and JSON reports. These two designs include a readable journal without JavaScript. For large exports this view contains up to 500 whole records within an 8 MiB input budget; the report labels the limit and links to the complete viewer and source records. The account directory and relationship index describe that same reading sample, not all participants. Full-journal charts keep their separately stated scope. ### Choose the contents | Contents preset | Included by default | | --- | --- | | Case dossier (recommended) | Activity, observation times, participants, chats and the record transcript. | | Briefing | An activity overview without participant rankings or the transcript. | | Activity review | Activity, observation times, participants, chats and composition, with source references and exact figures. | | Custom report | Your own combination of charts, transcript and previews. | Changing a preset keeps your design, case details and written analysis. Integrity checks, coverage, reading notes and verification instructions remain in every design. Source records in the ZIP stay unchanged when a chart or transcript is hidden. The optional **Examination notes** contain the question, method, findings and conclusion written by the report's author. Cite the source file and record numbers in the findings. The signature preserves these authored statements alongside the report; source observations and the author's interpretation remain identifiable. Minimized handovers omit these private notes and full-journal charts. Chart and examination choices apply to journal reports. Select activity over time, the UTC weekday/hour heatmap, participant rankings, chat rankings and record composition. Choose 5–30 ranked groups and neutral participant aliases or account IDs. Unknown senders and the remaining participants are separate rows. Aliases affect charts only; source records still contain their identities. The design preview updates from the unsaved draft using production cover, examination and chart components, limited to matches within the first 50,000 source records. The data preview below calculates the complete selection. It is explicitly unsigned and does not persist edits. Cover and Charts buttons switch its section. This is not a complete PDF preview. **Save report settings** applies the choices to future exports; existing signed files are immutable. PDF uses the chosen cover, typography, chapter layout and the same selected aggregates as HTML and signed JSON. Trust assessment, coverage and verification instructions stay present. Hiding charts or the readable transcript does not remove authoritative source rows from the ZIP. Disabled chart series are omitted from the analytical JSON; use a minimized export to restrict disclosure of source records. Data-selection filters apply to journal reports; account and sharing exports retain their own acquisition and disclosure scope. A selection can name whole chats, authors, UTC dates, record types and individual messages. Messages picked in a chat with **Select** arrive as **Selected messages**; the report then covers the message records of those messages and of any chat selected in full, and lists the chosen message numbers under **Selected data**. Missing message numbers and their neighbouring records are reported only for chats selected in full. **Add message numbers** under the chat list adds messages without opening the chat: one line per chat with the chat ID, a colon and the message numbers, or `t.me/c/…` links to single messages. Shared design/chart preferences are frozen into new chat/account exports and account sharing previews. Account/sharing language and privacy settings remain independent; private case and examination notes are not copied into these exports. Account and sharing reports remain HTML protected by their signed archive manifest. Journal, minimized journal handover and single-chat kits also provide signed PDFs. ### What the charts count Journal activity and heatmaps count new, historical, recovered, edited, deleted and missing-on-recheck **observations**, by collector observation time in UTC. Heartbeats and attachment receipts are excluded. Participant rankings count only new, historical and recovered message observations: a sender is not declared to be the editor or deleter. Repeated observations can describe the same Telegram message. Journal analytics retain counts by kind, first/last record references and the source `events.jsonl` SHA-256. Figures include exact values in HTML and PDF. Daily buckets switch to months beyond 366 recorded days; graphs combine these into at most 36 equal-width intervals. More than 100,000 distinct identifiers or 1,200 months marks the affected chart unavailable, while exact overall counts remain available. Snapshot and account-sharing charts count only included non-service message rows, using their recorded message time. Sharing aggregates are calculated after redaction and filtering. These charts use at most 90 equal-width UTC date intervals and retain up to 10,000 grouping values; excess counts are explicitly declared and reconciled. The last interval may be shorter. Unknown or naive dates do not enter time charts. An empty interval means no included observations; consult coverage for gaps. These charts describe saved activity. Unknown senders remain a separate category, and each check is reported individually. When included, `analytics.json` is protected by the archive's signed file hashes. Journal `report.json` embeds the same selected aggregate. Signature verification detects changed bytes. To check the figures, recompute journal aggregates with `report_analytics.Analytics` and `selected`, or snapshot aggregates with `snapshot_analytics.collect` and `project`. ### Anomaly indicators **Preview.** Evidence reports add an **Anomaly indicators** section computed by registered processors (`tgwitness/metrics/`, one file per metric). The report names every processor that ran with its version, and prints its method under its table, so the computation can be repeated from `events.jsonl` with `tgwitness.metrics.run`. | Processor | What it shows | | --- | --- | | `first_time_posters_over_time` v1 | First-time posters and messages per UTC day. A flag requires at least five first-time posters and three times their median, with message volume at most 1.5 times its median. The baseline uses at least seven observed days within the previous 14 calendar days, after seven days of warm-up. | | `service_vs_message_ratio` v1 | Distinct saved message numbers per chat and the share used by service messages. It describes a numbering; it does not explain a particular missing number. | | `join_leave_per_month` v1 | Joins, departures and removals or bans per month, one per person, chat, change and day. | | `pinned_per_month` v1 | Pin service messages, unpin notices, and pinned messages added or removed between chat-state snapshots, per month. | **More tools → Parameters → Report metrics** selects processors and the number of displayed rows, including in filtered reports. Daily and monthly tables show recent rows, service-share tables rank chats by saved message count. Totals cover every row. From a source checkout, build all nine designs listed above from the same fictional journal: ``` python tools/build_report_styles.py --output test-results/report-styles ``` Open the resulting `index.html` to compare complete HTML reports, signed PDFs and ZIPs. Every design uses the same source journal. Use a new output directory for each run so previously signed examples are preserved. ![Fictional HTML dossier](https://phishdestroy.io/tgwitness/assets/dossier-en.png?v=62db26820986) The HTML opens with a case cover and key figures. The numbered evidence map links to each finding, its supporting facts, limits and independent review. Searchable records and stable record references remain available in the offline viewer. The design adapts to narrow screens, both themes and browsers without JavaScript. The signed PDF has a dedicated A4 cover, report reference and QR, an executive summary, an evidence map, numbered findings and document bookmarks. Its page headers and footers identify the report. A QR identifies the material; it is not an independent verification result. Browser printouts are separate from this cryptographically signed PDF. The observation timeline places recorded observation periods and interruptions on the same UTC axis. Empty space is not inferred coverage; the detailed tables retain the exact intervals. The ZIP contains the readable reports, signed JSON, source records and verification instructions. Generate a fresh, fictional English/Russian/German dossier with the development environment installed: ``` python tools/build_dossier_example.py --output test-results/my-new-dossier ``` Each language directory contains `report.html`, `report.pdf`, `report.json` and `dossier.zip`. Existing sample directories are never overwritten. No Telegram account, external timestamp service or network connection is used to create it. ![First three pages of the fictional signed PDF](https://phishdestroy.io/tgwitness/assets/dossier-pdf.png?v=30a8d283dcc2) ## Reading a concrete case For a journal of 1,200 entries with a validated timestamp at entry 1,000, the report identifies 200 later entries outside that timestamp's bound. The timestamp fixes an upper bound on when the checkpoint existed; each message keeps its own send time from Telegram. If three other timestamp files fail validation or cannot be validated, they are counted separately and cannot supply a positive conclusion. A usable timestamp must satisfy all of these checks: its imprint matches the checkpoint, its signature chains to a trusted TSA root at the stamped time, and the checkpoint's signature, key, count and head match the exact journal prefix. Merely parsing a timestamp or having an OTS receipt is insufficient. The reader must independently choose the trusted TSA root and repeat verification. OTS needs its own Bitcoin confirmation check. | Report status | Meaning | | --- | --- | | Checked during export | The exporter performed the stated check; independent repetition is still needed. | | Recorded; review required | The underlying observation or operator statement is recorded; it is not independent confirmation. | | Not included in this copy | The copy has no supporting artifact for this claim. It does not say none exists elsewhere. | | Not independently checked | The report does not supply an independent verification result. | | Incomplete or unavailable | Material or a required check is missing, incomplete or unsuccessful. | Review each check separately, alongside the recorded collection coverage. ## What a strong configuration must preserve 1. Before relying on collection, retain the collector's key fingerprint through a separate trusted channel. Compare that reference with the export's signing key. 2. Retain independently timestamped checkpoints and, where used, a witness journal outside the collector's administrative control. Compare them against the exported journal to check its earlier boundaries. 3. Record acquisition scope, gaps, filters, limits and changes in collection. Explain missing periods relevant to the actual claim, keeping unobserved message IDs, deletion notices and unsuccessful rechecks distinct. 4. Preserve original ZIPs and their hashes. Record each holder, transfer, date and purpose. Retain the attributed operator statements and case notes with them. 5. For confidential VMs, preserve and independently verify the quote, challenge, Intel certificate chain, measurements, exact source and key-handling conditions. Keep the attestation verification result with the reviewed artifacts. See [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) for the checks of acquisition, archive integrity, time and collection coverage in each mode. ## Recipient review Use a trusted installation of TgWitness and an independently obtained fingerprint: ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca tsa-root.pem python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/WITNESS_CHANNEL --require-witness python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --check-drand ``` The second and third commands can meet the minimum for evidence: a checked timestamp, or the dates Telegram set on the witness posts, gives external time for the last record. The witness ZIP must come from an independently trusted source; preserve its key and provenance too. Retain the commands, tool version, outputs, reviewed input hashes and unresolved questions. Beacon verification is a separate online check; the report renderer never contacts a service merely to display a report. For a dispute over a particular message, cite the archive reference, authoritative file and record reference, then describe the relevant time bound, coverage gaps, selection and corroborating material. For a sharing copy, also review the recorded transformation and its references to the source archive. Private filters and identity mappings stay outside its public assessment. Verification of the signed PDF detects changes to covered bytes. Keep the original digital file and verification result alongside any screenshots or printed reading copies. --- # Telegram Account Export: Scope & Signed Archives Canonical page: https://phishdestroy.io/tgwitness/docs/reference/account-export/ Export the Telegram history an account can currently access. Review chat scope, resumable jobs, signed archives and minimized evidence sharing copies. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Export what an account can read now: scope, resumable jobs, a signed archive and minimized sharing copies. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Evidence and verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/) ![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c) An account export reserves the account's acquisition slot. Live observation can continue while the archive is discovered, downloaded, verified and packaged. Pause another history or export job before starting a competing acquisition. Pausing the archive leaves observation running, and pausing observation retains the archive job. Exports on different accounts can run at the same time. A Takeout-only job waiting for approval releases its account, so a separate regular-session export can start while approval is pending. An active acquisition still reserves that account. As the installation administrator, choose **Home → Export my account**, or **Exports → Telegram account → Configure account export**. Sign in if needed, review the scope, and explicitly start the export. Continuous observation is not required. **Saved observations** is a separate export of the existing journal; its ZIP includes all sources regardless of journal filters. Every workspace has its own jobs, signing identity and storage. Issued panel access, including an unrestricted ordinary export grant, cannot open these account-wide routes. Sender and text filters expand under **Filter by sender or message text**. **Account data & connection method** contains optional account categories and the Takeout/regular-session choice; its summary shows the active choices even when closed. Closing these sections keeps their settings. Export and report drafts remain in the current panel session while changing views; they are not saved through a browser reload. Existing jobs remain reachable from either export choice. This workflow exports data currently accessible to the connected account. The default **Automatic** method starts with [Telegram Takeout](https://core.telegram.org/api/takeout), which returns the accessible history in its current state, including left channels, saved contacts and other account data. If Telegram imposes a waiting period before Takeout starts, Automatic continues at once with the regular session; the journal records `account_export.transport` and the signed inventory names the method used and lists the change as an omission. **Telegram Takeout session only** waits for the approval instead, and **Regular session only** never asks for Takeout. Secret Chats are recorded live by the [Secret Chat module](https://phishdestroy.io/tgwitness/docs/reference/secret-chats/), and edits by live observation. The regular session has different coverage and records unsupported categories. **Home → Export everything** starts an export with every chat kind, every attachment type, the profile, contacts, profile photos, stories, session metadata and other account data, in all formats: the signed TgWitness archive with Telegram Desktop JSON and HTML views. **Choose what to export** opens the form below with the same defaults. Takeout is the official export API also used by Telegram Desktop. TgWitness can write Desktop-compatible JSON directly from its own acquisition; importing someone else's archive is not required. Chat and message IDs are available through both transports. Export speed and Takeout's approval delay depend on Telegram's limits for the account, whether a chat is public or forwardable. Measure the same scope and media settings before comparing speed. For up to 20 explicitly selected chat IDs, regular-API export resolves those peers directly before considering the account's complete dialog inventory. A readable public channel can therefore be exported without joining it, even when it is absent from the dialog list. Uncached peers fall back to the ordinary inventory. The archive filter remains enforced: if Telegram does not return a dialog and archived chats are excluded, the unknown archive status is recorded as an omission. Takeout keeps its split-range inventory procedure. Neither path joins chats or changes forwarding permissions. In Desktop-compatible JSON, channels that Telegram marks `left` appear under `left_chats`, including readable public channels the account has not joined. Both `FLOOD_WAIT` and `FLOOD_PREMIUM_WAIT` pause requests for the full server-requested period. The account's deadline is persisted across reconnects and restarts; a shorter later wait cannot shorten it. Retries are bounded, cancellation preserves sealed pages, and API credentials are not rotated to bypass a rate limit. No Premium purchase is made. ## Choose what is collected | Setting | Meaning | | --- | --- | | Purpose | Record why this acquisition is needed. Do not put unnecessary names or sensitive case details here. | | Report language | Choose the language of the readable report's labels. Original message text remains unchanged; untranslated template labels use English. The language is fixed with the signed job options. | | Chat kinds / chat IDs | All selected kinds, or just the listed chats; Saved Messages belongs to private chats. Archived chats are separately selectable. | | Dates | UTC. The panel's From and Through calendar dates are both included. The API uses inclusive `from_utc` and exclusive `to_utc`; the panel sends the start of the day after Through. An empty bound leaves that side unrestricted. | | Sender IDs | Only messages by the listed senders; an empty list includes all senders. | | Text contains | Case-insensitive literal phrases, matched with OR. Sender/date/own-message conditions combine with AND. | | Own messages | Keep only outgoing messages. | | Media types | Select attachment categories, or clear all to avoid downloading message files. | | File / total media limits | Per-file MiB and total downloaded-media GiB. Text, receipts, readable reports and ZIP overhead require additional disk space. | | Account categories | Profile, contacts, profile photos, stories, session metadata and other Takeout data have separate controls. | The **Minimize collection** preset disables files and account metadata. Sender/content filters apply before retained message pages and media downloads. Telegram still transmits API history pages containing messages needed to evaluate those filters: filtering is not a promise that unselected messages never enter process memory. Other ongoing observation in the workspace has its own scope and retention settings. Profile-photo history, stories, session metadata and other account data are selected by default. Disable them, and the profile and contacts, when the case needs messages only. If attachments or metadata are unnecessary, excluding them during acquisition avoids retaining another private copy in this export. Photo payloads use the still-image variant identified in their metadata and hash manifests, including photos with an animated avatar variant. That animation is not substituted for the selected still image. A shorter or longer payload than the observed size is recorded as a failed attachment, and a changed representation during file-reference renewal is rejected. These failures leave the archive partial while retaining the message records. Independent verification also rejects saved attachments whose signed length contradicts their observed size or representation, including in older archives. If a dedicated media connection fails temporarily, attachment reads use the standard file connection. After one minute, the dedicated route is retried in the background while downloads continue. This recovery keeps the configured connection limit and applies separately to each data center. Telegram flood waits and authorization failures still propagate. ## Message numbers and activity map Every account archive contains `message-gaps.json` and `map.html`. Channels and supergroups number their messages per chat, so each absent number between the first and last exported message is a message of that chat. Private chats, bots and basic groups share one number sequence for the whole account: an absent number there belonged to some chat. Its chat is proven when an exported reply or pin points at the number; otherwise it is estimated from which chats were active in the time between the neighbouring messages, and the remainder is attributed to chats not in the export. Each run carries its time window, neighbours, the shares per chat and a confidence label. A limited scope (filters, unselected chats) is stated, because absent numbers then include messages outside the selection. `map.html` shows a calendar, chats over time and weekday-by-hour grids for messages and for absent numbers, with tables of every chat and the largest runs. Chat pages show their own calendar, participants over time for groups, and a mark in the transcript where messages are absent. `verify.py` recomputes `message-gaps.json` from the signed pages and rejects a changed file. The activity map lists the largest channel and supergroup gaps, including their number ranges and neighbouring message times. Open a range to jump to its marked position in the paginated transcript. These marks record absent numbers between saved neighbours; deletion events, their times and message texts come only from saved records. Wide tables scroll within their cards on small screens. Long transcripts include a page index with message-date ranges and a calendar. Choose a month to open its first record in captured page order. Month counts use recorded message dates in UTC; undated records remain in the transcript. Page navigation includes the first, last and nearby pages, and opens the message section directly. The index works offline without JavaScript. ## Resume, coverage and verification Each job freezes its options and account identity. Inventory and captured pages are signed; page receipts record hashes, cursors, times, attachment outcomes and their preceding receipt. Only committed pages advance progress. Restart/resume checks those records before continuing. A changed account, changed signed page or inconsistent receipt chain is rejected. Options cannot be edited halfway through an acquisition: start another job for another scope. Pause releases the running account operation. Restarting the application leaves unfinished work available for explicit resume. An expired Takeout session requires an explicit resume; changing Telegram split ranges can require a new acquisition. Resume retains previous observations, so a long-running export is not one atomic snapshot. Other account-changing operations and conflicting exports are blocked during acquisition. Wait for packaging to finish before deleting a workspace. Resume shows **Verifying saved export data…** immediately and checks saved content in the background before contacting Telegram. The panel remains available during verification. Pause waits for the verification worker to finish safely before releasing the account; it also works when pressed immediately after starting or resuming. On slow storage that wait can be long. Failed integrity checks leave a failed job with an explanation and retain its files. If Telegram ends the account's authorization during inventory, history or attachment acquisition, the job pauses without marking the unfinished page complete. Reconnect the same account and resume to continue from the last saved page. Unavailable message placeholders advance the history cursor but do not end the read: older available messages are still requested, and a placeholder is not presented as a captured message or a confirmed deletion. The panel distinguishes a completed selected scope from a partial archive, and records omissions and failed reads. How the report shows coverage, gaps and missing message numbers: [Coverage and missing material](https://github.com/phishdestroy/TgWitness/blob/main/docs/COVERAGE.md). Deliberately excluded files are different from failed or unavailable files. Inspect coverage even when integrity verification succeeds. No local reader can prove Telegram returned every message that ever existed. Finished ZIPs remain available for repeated and HTTP-range downloads. An account archive contains `manifest.json`, `manifest.sig`, signed `job.json`, `inventory.json`, `receipts/`, authoritative `data/*.jsonl`, selected `media/`, readable HTML and a verifier. Pin the collector fingerprint through an independent channel, then verify using a trusted installation. The panel saves the archive as `tgwitness-account-export-EXPORT_ID.zip`; a sealed capture carries it inside its evidence archive as `account-export.zip`. Use the name of the file you have: ``` python -m tgwitness.verify tgwitness-account-export-EXPORT_ID.zip --fingerprint TRUSTED_SHA256 ``` For archives whose expanded contents exceed 4 GiB, set an explicit adequate `--max-gib`. The panel verifies its authenticated, completed local archives using their declared expanded size and published ZIP digest; the external CLI keeps its independent size limit. Verify before opening the readable HTML. The archive's bundled verifier is convenient, but a verifier obtained independently avoids trusting executable code delivered with the evidence. The Ed25519 signature and SHA-256 hashes detect changes after the collector committed the relevant bytes. Review that result together with the recorded collection scope, acquisition intervals, external timestamp receipts and the provenance checks available for the selected deployment. Later observations are recorded separately, preserving earlier captured versions. ## Prepare a disclosure for a lawyer or another recipient After downloading a finished export, keep the original ZIP and open `index.html` from an extracted copy. The report explains its scope, available coverage and limits. Its record references combine the archive reference, document path and record number, so a recipient can locate the same entry in the HTML or printout. For a worked example, [open the fictional report](https://phishdestroy.github.io/TgWitness/demo/report/). From a finished account export, choose **Prepare a sharing copy**. This builds a separate signed derivative. The source ZIP remains unchanged and private; do not send it together with a minimized derivative unless the recipient is authorized to receive its full contents. Choose its report language separately. Changing the language or any selection setting requires another preview before creation. 1. Enter the disclosure purpose and select dates, sender IDs and literal text criteria. 2. Choose whether to keep identities, reveal only listed participants, or pseudonymize everyone. In either pseudonymized mode chat IDs/titles and message IDs are also replaced. Pseudonyms are stable inside one disclosure and change between independently prepared disclosures. 3. Keep message text, omit it entirely, or add literal names/phrases to mask. In private modes the tool also masks known hidden sender names and alternate usernames, whole-token sender IDs, direct-chat names, links, email addresses and phone-like strings. Known-name matching handles Unicode case folding, including `Straße`/`STRASSE`. Generic group/channel titles are not automatically removed from message text. If the known-identity masking limit is exceeded, narrow the source export or omit text; the tool refuses to silently skip later names. These are best-effort rules, not general anonymization. 4. Leave files excluded unless the recipient needs them. Included originals retain their pixels, audio, text and metadata. They are **not** anonymized by the tool. 5. Preview the counts, warnings and sample transformed messages, then explicitly confirm creation. Samples are limited to 12 messages and 2,000 text characters each. This is a sample, not a full review of the result. Changing settings requires another preview. A preview expires after 15 minutes and is bound to that administrator session and exact original ZIP; it cannot be reused after creation. A new preview invalidates the previous one for the same job and session. 6. Inspect the complete resulting `index.html` and `messages.jsonl` locally before handing it over. If it reveals unnecessary information, create a new disclosure with stronger exclusions. Do not edit the signed ZIP in place. ### Messages left out by the selection **Preview.** A disclosure does not look complete when it is not. Inside every chat that keeps at least one disclosed message, messages the selection left out appear as markers, `[withheld by selection — rule: sender]` (or `text`, `period`). Choose **Messages left out by the selection**: one marker for each run of consecutive withheld messages (default) or one for each message. Markers carry only the rule and a count, never text, sender, date or files. Chats with nothing disclosed are left out entirely, so the package does not reveal that they exist. Disclosed replies say what they answer: a message included in this copy, a message withheld by the selection, or a message that is not in the source export (deleted before the export or never exported; the export cannot tell which). A withheld message that a disclosed reply answers always gets its own marker, so the reply points at a record that explains why it is empty. These three states are distinct from deletions and collection gaps, which belong to the source export. In `messages.jsonl` (format `tgwitness-account-disclosure-v2`) each message has `state`: `disclosed`, or `withheld` with `rules` and `count`. A disclosed reply has `reply_to` with the target `id` and `state` (`disclosed`, `withheld`, `not_in_source`). The manifest counts disclosed messages, chats, media and `withheld` messages. `verify.py` rejects a marker that carries content and a reply that points at a record missing from the package; version 1 packages verify as before. The minimized format omits structured account profiles, contacts, avatars, sessions, stories, raw Telegram objects, forwarding headers, reply quotations, contact cards and location metadata. It excludes the original JSONL files, private filter settings, pseudonym key and identity map. Selected text, explicitly retained identities and included files can still contain the same names, IDs or phrases used in those filters; they need separate review. The private policy and pseudonym key are retained encrypted in the local vault for the job; deleting the job clears its associated private disclosure records. The public policy records filter counts rather than filter values. The stated purpose is public in the manifest and HTML: explicit private criteria and, in pseudonymized modes, known hidden identities are masked there too, including when message text is omitted. Keep the purpose free of unnecessary personal details; unknown identifying context can remain. Its manifest binds the derivative files, public policy and original ZIP's hash. Verification can establish integrity and, if the source is supplied locally, matching source linkage. The panel saves the sharing copy as `tgwitness-disclosure-DISCLOSURE_ID.zip`: ``` python -m tgwitness.verify tgwitness-disclosure-DISCLOSURE_ID.zip --fingerprint TRUSTED_SHA256 python -m tgwitness.verify tgwitness-disclosure-DISCLOSURE_ID.zip --fingerprint TRUSTED_SHA256 --evidence tgwitness-account-export-EXPORT_ID.zip ``` Source linkage shows which archive and collector key the disclosure came from. The disclosure carries only the selected content; review the selection and the removal of identifying details against the original export. ## Sharing and hosted capture Select the messages and files the recipient needs, review the complete sharing copy, and retain the source separately. Record the delivered ZIP's hash so the recipient can identify and verify that exact copy. Pseudonymization replaces the selected identifiers; included text and original files remain part of the review. GitHub Actions supports full-account and selected-chat exports through Takeout or the regular API, plus a one-chat event journal. The [hosted capture guide](https://phishdestroy.io/tgwitness/docs/capture/) explains settings verification and the 120-minute limit. To verify a sharing copy derived from hosted capture, check its source hash against the original archive and verify that archive's attestation with the [mode-specific checks](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope). [Evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/) · [Case reports](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) --- # Telegram Evidence Archive Format & Verification Canonical page: https://phishdestroy.io/tgwitness/docs/reference/evidence/ Inspect signed Telegram evidence ZIP contents: records, manifest, attachments and receipts. Verify file hashes and signatures with an independently trusted key. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Contents of the signed ZIP, record kinds, process receipts, people profiles, off-site copies and offline verification. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) ![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c) TgWitness preserves account-visible Telegram observations in a signed journal. Recipients can verify the saved records, attachments and reports against a trusted collector key, check external time from a third party for the last record, and compare the journal with a checkpoint they retained earlier. This page describes the formats, the checks and the material to keep for handover. Recipients can start with **VERIFY.cmd** on Windows: it asks for the original ZIP and independently obtained key fingerprint, displays an explained result, and saves a separate verification transcript. See [verification launchers and the portable runtime](https://github.com/phishdestroy/TgWitness/blob/main/docs/VERIFICATION_LAUNCHER.md) for setup and trust limits. **On this page** - [What is signed](https://phishdestroy.io/tgwitness/docs/reference/evidence/#what-is-signed) - [Comparing chat exports](https://phishdestroy.io/tgwitness/docs/reference/evidence/#comparing-chat-exports) - [Investigation handoff](https://phishdestroy.io/tgwitness/docs/reference/evidence/#investigation-handoff) - [Handover extract](https://phishdestroy.io/tgwitness/docs/reference/evidence/#handover-extract) - [Readable reports](https://phishdestroy.io/tgwitness/docs/reference/evidence/#readable-reports) - [Event canonicalization](https://phishdestroy.io/tgwitness/docs/reference/evidence/#event-canonicalization) - [Actor semantics](https://phishdestroy.io/tgwitness/docs/reference/evidence/#actor-semantics) - [Coverage: continuity, gaps and unobserved IDs](https://phishdestroy.io/tgwitness/docs/reference/evidence/#coverage-continuity-gaps-and-unobserved-ids) - [Producer](https://phishdestroy.io/tgwitness/docs/reference/evidence/#producer) - [People profiles](https://phishdestroy.io/tgwitness/docs/reference/evidence/#people-profiles) - [Independent witness](https://phishdestroy.io/tgwitness/docs/reference/evidence/#independent-witness) - [Manifest and checkpoints](https://phishdestroy.io/tgwitness/docs/reference/evidence/#manifest-and-checkpoints) - [Verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) - [Attachments](https://phishdestroy.io/tgwitness/docs/reference/evidence/#attachments) - [Durable collection and process receipts (0.2)](https://phishdestroy.io/tgwitness/docs/reference/evidence/#durable-collection-and-process-receipts-02) - [RFC 3161 preparation and response verification (0.2)](https://phishdestroy.io/tgwitness/docs/reference/evidence/#rfc-3161-preparation-and-response-verification-02) - [Optional records in evidence mode: drand and Telegram devices](https://phishdestroy.io/tgwitness/docs/reference/evidence/#optional-records-in-evidence-mode-drand-and-telegram-devices) ## What is signed | Material | Protection | What to retain | | --- | --- | --- | | Every journal observation, including operational events | SHA-256 chain and an Ed25519 signature per event | Original `events.jsonl`, the trusted key fingerprint, and a retained checkpoint | | Evidence ZIP contents | `manifest.sig` signs the canonical manifest, which lists hashes of the content files | The complete ZIP, including its manifest and signature | | Preserved attachments | SHA-256 and byte count in a signed `media.saved` event; file hash in the signed ZIP manifest | The original bytes inside the verified ZIP | | Checkpoint | Ed25519 signature over journal length, head hash, public key, and creation time | An independent copy retained before a disputed change | | Run receipt | Signed record of the collector version, source-file hashes and start settings, also included in `process.started` | The receipt, associated journal and the environment evidence for the selected verification mode | | Readable reports: `report.html` and its parts, `report.json`, `report.pdf`, `chat.pdf` | An Ed25519 seal per file over its content; the PDF also carries a standard PDF signature (see [Readable reports](https://phishdestroy.io/tgwitness/docs/reference/evidence/#readable-reports)) | The file as received and the trusted key fingerprint; the ZIP it describes | | Standalone CSV | No standalone cryptographic signature; event hashes alone are insufficient | Use the exact copy inside the verified ZIP for integrity checking | | Screenshots, printouts, or PDF produced by a browser | No TgWitness signature on the derivative | Keep the original verified package and document how the derivative was made | The collector verifies journal signatures before generating every export format. Readable HTML and PDF reports carry their own seals; standalone CSV is checked as part of a signed ZIP. Keep the ZIP to retain the attachment bytes and manifest, and a separate checkpoint to check the journal against an earlier boundary. ## Formats and verification paths The acquisition mode and the output format answer different questions. The mode supplies collection and environment evidence; each format preserves or presents part of that record with the checks below. | Output | Verification and use | | --- | --- | | Evidence ZIP | Canonical events, signed manifest, coverage, custody entries, attachments and available external receipts; check the archive and its selected acquisition mode. | | ASiC-E container | The evidence ZIP as an ETSI ASiC-E container (EN 319 162-1) with a `mimetype` entry and `META-INF/ASiCManifest.xml`, CAdES-signed with the workspace's own certificate at level B-B, or B-T when timestamping is on. Validators such as EU DSS check format and integrity and, as the certificate is self-issued, report no trust anchor. EU DSS 6.3 with default settings refuses a container of more than 1000 files ("Too many files detected"). `verify.py` checks the Ed25519 manifest and every listed file, the SHA-256 values in `META-INF/ASiCManifest.xml` and in an added `ASiCManifestNNN.xml` or `ASiCEvidenceRecordManifest.xml`, and fails on a `META-INF/` entry none of them covers. It does not check the CAdES signatures and says so. | | HTML and JSON reports | Individually sealed views with source references, also listed in the ZIP manifest. Their recorded counts summarize journal event kinds. | | PDF reports | Ed25519 seal plus a PAdES baseline PDF signature over the byte range: B-B, or B-T with a signature time stamp when timestamping is on. The TgWitness verifier uses the trusted Ed25519 key; a viewer's certificate-trust display is a separate check. | | CSV | A spreadsheet view covered by the ZIP manifest. Formula escaping protects spreadsheet use; original signed text remains in the journal. | | JSONL | Signed event records, including attachment references. The evidence ZIP additionally carries the preserved attachment bytes. | | Chat export and Desktop-compatible views | History acquisition and available admin-log records, with the requested rendering and signed archive. Live monitoring's saved versions are a separate acquisition path. | | Media and hash-only records | Saved bytes are checked against their SHA-256 and message reference. Hash-only acquisition preserves the available hash metadata for later comparison with file bytes. | | STIX/MISP and people profiles | Source-linked extracted observations, account IDs and analytical matches. Profile signatures and record hashes can be checked against the original evidence; avatar-cache provenance is labeled separately. | | Handover extract | Signed disclosure rules, unchanged records and marked minimized records retaining original hashes/signatures. Use the retained original for a comparison requiring withheld fields. | | Witness and time receipts | Earlier journal boundaries, continuity and the individual verified time claims. They accompany the acquisition and archive checks. | | Password-protected delivery | Protects the enclosed package during transfer. `.tgwpw` uses AES-GCM authenticated encryption, including an authenticated final record; the enclosed journal keeps its signatures and acquisition receipts. | A printout or screen capture is a presentation of the signed material. Its report ID, key fingerprint and QR reference help locate the original file for verification. Custody declarations record the supplied examiner and transfer information; verifier results and acquisition receipts are retained as separate evidence. ### External signatures A signature can also come from a key TgWitness never holds, such as an investigator's qualified electronic signature or an organisation's seal. On **Exports**, **External signature** on a prepared export without a password hands out the bytes to sign: a new `META-INF/ASiCManifestNNN.xml` listing every file with its SHA-256 for an ASiC-E container, or the export's `manifest.json` for a ZIP. The signer returns a CMS (CAdES) `.p7s`, detached or with the content embedded. TgWitness checks that the signature covers exactly those bytes and verifies with the signer's certificate (RSA PKCS#1 v1.5, RSASSA-PSS, ECDSA, Ed25519, Ed448). The chain is checked only against root certificates the operator supplies; revocation, trusted lists and qualified status are not checked. The panel shows one state per signature: waiting for a signature, attached and not checked, verified, algorithm not supported, signature invalid, signed bytes do not match, or certificate not chained to a supplied root. Changing the export after the bytes were handed out sets all its signatures to "signed bytes do not match". **Download with signatures** adds the signatures and their manifests under `META-INF` in an ASiC-E container. For a ZIP, it puts the unchanged ZIP, the `.p7s` files and `SIGNATURES.txt` into an outer ZIP. Invalid signatures and signatures over other bytes are left out. A signature with an algorithm TgWitness cannot check is included; the panel shows its state, as does `SIGNATURES.txt` for a ZIP. ### Signed chat images **Download signed ZIP** in the image preview saves PNG pages, `pages.sig.json` and `README.txt`. Each page ends with the journal record numbers it shows, the chat, the render time, the workspace key fingerprint and the command that checks it. The panel sends only each page's SHA-256 and record numbers; the server confirms that the records belong to the chat, signs the statement (`tgwitness-image-attestation-v1`) with the workspace key and journals the signing as `export.image_attested`. ``` python verify.py page-01.png page-02.png pages.sig.json python verify.py page-*.png pages.sig.json --fingerprint TRUSTED_SHA256 --evidence evidence.zip ``` The verifier checks the signature, matches every PNG to a signed page and reports the key fingerprint. `--fingerprint` compares the signer with a fingerprint obtained from the sender independently. `--evidence` reads a signed evidence ZIP of the same workspace and requires every record of the images to be present with the same hash. A changed pixel, a changed statement or another key fails the check. The images show saved records in TgWitness's own layout; they do not show what Telegram displayed to anyone. ## Comparing chat exports Verify and compare two signed chat-export ZIPs with independently retained signer fingerprints: ``` python -m tgwitness.verify first.zip --compare second.zip \ --fingerprint FIRST_TRUSTED_KEY_SHA256 --compare-fingerprint SECOND_TRUSTED_KEY_SHA256 ``` `--require` and `--require-tier` are refused together with `--compare`; check the required profile of each archive with its own verification. When both archives record the same numeric account and chat IDs, records are paired by message ID. **Unchanged** means equality of the complete saved JSON record: full text, author, dates, reply target, nested metadata and unknown fields are all included. JSON object key order does not matter; absent fields, nulls, value types and array order do. The 300-character preview is only for display. Changed entries name the differing top-level `changed_fields`, including changes invisible in that preview. Duplicate message IDs are rejected instead of overwriting one another during matching. A difference can be a changed display name, view count, collection annotation or other observation metadata. Telegram edits appear as their own edit events, and each archive's verification shows whether that archive is intact. Unparsed records remain in the comparison and are compared by their saved representation. For different or missing account/chat identities, the tool finds candidate correspondences using sender, complete text, file hash, media type and a five-second time tolerance, and reports them as **Matched** rather than **Unchanged**. Unparsed records remain unmatched. Differences in paired records are listed in `changed`, including in content mode. With `--json`, `matched` counts candidate pairs and `unchanged` counts pairs whose complete saved records are equal. The existing `changed_fields` and integer `unchanged` output remain compatible with earlier comparison results. Archive format and signature verification are unchanged. ## Investigation handoff 1. Record the case reference, operator, numeric Telegram account ID, selected sources, collection policy, and collection period in your case notes. TgWitness preserves observations and supports source-linked notes and collections in [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/). Keep transfer and custody records with your case materials. Check the intended collection setup with the [live acceptance procedure](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/LIVE_ACCEPTANCE.md). 2. Retain the workspace's public-key fingerprint independently before relying on its exports. Keep evidence mode on (the default) so checkpoints receive RFC 3161 and OpenTimestamps receipts. Save signed checkpoints outside the collector during collection. Record interruptions and the limits of the account's visibility. 3. Export a **signed ZIP** and retain the signed run receipt. Use a checkpoint at or before the exported journal boundary. A later checkpoint can correctly reject an earlier export as too short. Exports include the full workspace journal, regardless of panel filters; review the material before sharing it. 4. Have the recipient verify the ZIP with a trusted copy of the verifier, the independently supplied fingerprint and the timestamp authority's root certificate obtained separately. From a trusted checkout with its Python environment active: ``` python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint retained-checkpoint.json --require evidence ``` The fingerprint and a checked timestamp of the last record meet the minimum for evidence; `--require evidence` exits with code 2 otherwise. The checkpoint is a supporting check, because it is signed with the collector key. Successful output reports `key_pinned: true` and `checkpoint_checked: true` when both inputs are supplied and accepted. Preserve the verification result. ``` For a handover requiring the final exported record to be witnessed, use `--witness witness.zip --witness-fingerprint TRUSTED_WITNESS_SHA256 --require-witness`. This refuses an export with an unwitnessed tail. Add `--channel https://t.me/s/WITNESS_CHANNEL` to read the dates Telegram set on the witness posts as external time. See the [witness handover procedure](WITNESS.md#require-a-witnessed-export-boundary). ``` 1. Record the archive's SHA-256, export boundary, transfer date, sender, and recipient in your custody record. Keep the original package intact and work from copies. Share evidence files rather than the application's private data directory, which also contains account sessions and signing secrets. For transfer, choose a password-protected AES-256 ZIP or the stronger `.tgwpw` container. ZIP uses WinZip's low-cost password derivation; use a long random passphrase. `.tgwpw` uses scrypt and AES-256-GCM and opens with the standalone verifier's `unseal-password` command. The password is not stored and only protects confidentiality; the recipient decrypts the archive and verifies the signed export inside, which is unchanged. 2. To timestamp a checkpoint outside evidence mode, follow the [RFC 3161 procedure](https://phishdestroy.io/tgwitness/docs/reference/timestamp/) and retain the request, checkpoint, trusted CA information, and verified authority response. Preparing a request alone does not obtain a timestamp. For `.tgwpw`, use an independently obtained verifier and choose a new output file with the original extension: `python verify.py unseal-password export.tgwpw --out evidence.zip`. The command prompts for the password; `--password-stdin` reads one line for automation. It never overwrites an existing file and publishes plaintext only after all records authenticate. Run normal signature verification on the decrypted file afterwards. The container uses scrypt (`N=131072`, `r=8`, `p=1`, 16-byte salt; about 128 MiB RAM) and AES-256-GCM with 1 MiB records and an authenticated final record. An encrypted metadata record stores the inner filename, so downloaded containers can be renamed. Successful verification establishes integrity relative to the trusted collector key and retained boundary. See [verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope) for the trust assumptions and [validation results](https://phishdestroy.io/tgwitness/docs/reference/verification/) for the checks performed. ## Handover extract A signed ZIP carries the whole workspace journal. When a court, a lawyer or an abuse desk needs only some chats, a period or certain people, **Exports → Handover extract** prepares a minimised copy (`tgwitness-handover-v1`) according to the selected disclosure rules. The operator states the purpose and chooses the chats, an optional period (UTC), the people the extract is about, what happens to everyone else (shown, replaced by pseudonyms P01, P02… or left out), which message texts stay, which attachments and profile photos are included, and whether phone numbers and e-mail addresses in texts are masked. The purpose and these rules are in the signed manifest and in the report; the journal records `handover.exported` with the access that prepared it and the file's SHA-256, not the contents. `verify.py` checks an extract in two ways. A record shown unchanged is verified in full: its content against its hash, its Ed25519 signature and its link to an included predecessor. A minimised record keeps the original hash and signature, so the signature still verifies, but the withheld fields cannot be recomputed from it; the record names what was withheld and the report marks it. Account-wide service records (starts and stops, coverage gaps, connection, network and storage notices, scope and settings changes) keep only the fields listed for their kind: chat lists in them are cut to the chosen chats and their totals recounted, and a live-probe gap in a chat outside the selection loses that chat, its message numbers and the witness account; in a chosen probe chat the witness account is replaced by its pseudonym unless everyone is shown or it is one of the chosen people. The manifest names the journal length and head with the collector's signature over that head, and counts the records left out; `coverage.json` describes the chosen chats. New extracts also carry `proofs.jsonl`: for every included record and for the journal head, the Merkle path from the record's original hash to the journal root named in the signed manifest. `verify.py` checks each path, so every record is shown to belong to the same journal of that length and head, without the full journal; an extract of 100 messages checks in about a second whatever the journal size. `--range=CHAT:FROM-TO` additionally confirms that messages FROM to TO of a chat are in the extract and reports how many records it checked for them. Names inside file names are not detected. Review the final files before sharing: free text, file names and selected attachments can still identify people. Keep the full signed ZIP: the extract is a disclosure, not a replacement. ## Readable reports Signed evidence, handover and chat ZIPs carry readable HTML and JSON reports, plus PDF when the required fonts are available, in the selected report language. Each report is sealed with the workspace's Ed25519 key and can be verified separately: `python -m tgwitness.verify FILE --fingerprint KEY [--evidence ZIP]`. - `report.html` / `chat.html`: the seal statement (`tgwitness-report-seal-v1`) closes the file and signs the SHA-256 of every byte before it. Long journals and chats are split into parts of a configurable size (Report settings, 500 to 100,000 records; 5,000 by default): `records/records-0001.html` or `messages/messages-0001.html`, each sealed with its number, range and the total, and listed with its SHA-256 in the signed manifest. Runs of collector heartbeats are shown as one line unless Report settings list them one by one. - `report.json` (`tgwitness-report-json-v1`, keys `format`, `report`, `seal`): the seal signs the SHA-256 of the canonical JSON of `report`, so the facts can be read by case systems and scripts and a selection for data protection can be made from them while the signed file stays whole. - `report.pdf` / `chat.pdf`: a formal document for printing and filing, signed twice over the same bytes, the whole file except the signature value (`/ByteRange`). The standard PDF signature is PAdES baseline (ETSI EN 319 142-1, `/SubFilter /ETSI.CAdES.detached`: CMS with SHA-256 and ECDSA P-256, signing-certificate-v2, no CMS signing time; the claimed time is `/M`) at level B-B, or B-T with an RFC 3161 signature time stamp in the CMS when timestamping is on and a timestamp authority answers over the route for requests outside Telegram. It uses a self-issued document-signing certificate kept in the workspace vault; its subject serial number is the Ed25519 key fingerprint. The Ed25519 seal travels inside the CMS as the unsigned attribute `2.25.240684792623320047764573196045913242332` and names the certificate's SHA-256 with `"content": "pdf-byte-range"`, so the Ed25519 key vouches for the certificate. The certificate is not qualified: a PDF reader shows the signature as valid and the signer as unknown or untrusted until the certificate is trusted; compare the Ed25519 fingerprint instead. Chinese, Japanese and Korean PDFs need a font on the server (or in `TGWITNESS_FONT_DIR`); without one the ZIP carries the HTML and JSON reports only. - `report.en.html`, `report.en.pdf` / `chat.en.html`, `chat.en.pdf`: the English original of the same report when the report language is not English, sealed and signed in the same way and named under `report.original` in the signed manifest. The report in the selected language opens with a recommendation to file the English original with a certified or sworn translation; see [Translating reports for court](https://phishdestroy.io/tgwitness/docs/reference/translation/). In a channel or supergroup Telegram numbers messages 1, 2, 3… in order. A chat export lists the first and last number, how many are present and every run of absent numbers in `message-ids.json`, the manifest and the `chat.json` header, and marks each gap where it falls in the transcript. `verify.py` recounts them from `chat.json`. An absent number is a message Telegram did not return (deleted before the export, or not visible to the account); in private chats and basic groups numbers are shared by all of the account's chats and gaps are not counted. After reading the history, the export asks Telegram for every absent number again, by number (`channels.getMessages`, up to 10,000 numbers including the 1,000 below the first message, spread evenly over all gaps when there are more). The result is in `message-ids.json` and the report. An empty answer records that the number is unavailable to this account at recheck time; it leaves the cause unspecified. A message returned on recheck is added to the export and marked `found_on_recheck`. When the observing workspace saw messages of the chat deleted, missing on recheck or edited, the chat export adds `journal-changes.jsonl`: those journal records, every saved version and the notice, each with the hash and Ed25519 signature it received in the journal. `verify.py` recomputes each record's hash, checks its signature against the export key and compares the count with the signed manifest; the evidence export holds the complete hash chain. The report lists these messages under **Deletions and earlier versions**. Every report opens with **In brief**: one paragraph, then what the material shows and what the record includes. The page's own seal stamp turns amber when the browser has checked the seal's signature, not the page: a browser does not give a page its own bytes. It turns green only when the reader drops the file into the check at the end of the page and every byte matches, and only if the page shown is that file; otherwise it turns red. Each report names the program exactly: the git commit when the collector runs from a checkout or the installer sets `TGWITNESS_COMMIT`, and the SHA-256 of its source files (`source_tree_sha256`, the canonical JSON of path → SHA-256 of every `.py`, `.js`, `.css`, `.html` and `.svg` file in the package), which a checkout of that commit reproduces unless files were changed. The Telegram client is named with its library, API layer and data centre. When observation starts and when a chat export begins and ends, the collector asks Telegram for its time (`updates.getState`, whole seconds) and records Telegram's time minus the collector's clock, with the uncertainty from the round trip; the reports show these measurements under Chain of custody. A chat export also records when it read the history, apart from the dates of the messages. ### Offline report viewer and archive guide Extract the complete ZIP before opening `chat.html` or `report.html`. The viewer provides search, filters, participants, indicators, record details and JSON/CSV selections without a server. Keep `viewer/` and `media/` next to the report. Selections are derivatives: use `verify.py SELECTION.json --evidence ARCHIVE.zip` to compare them with the signed archive. The verifier checks the report ID, signing key, archive boundary and every selected item; edited, missing and duplicate items fail. Selection notes and creation time remain unsigned metadata. Message-number gaps are shown only for a complete, unfiltered ascending chat feed. Hiding a category or failing to load a data chunk must not turn an omitted row into evidence of a missing message. Search highlights operate on plain text before HTML escaping, preserving literal markup. The browser checks manifest signatures, the report ID and key, and all listed file hashes. It rejects ambiguous or malformed ZIP structures, duplicate names and unsafe paths, and caps files at 256 MiB and declared total contents at 4 GiB. Use the standalone verifier for larger archives. This browser check complements the verifier's checks of journal chains and data semantics. `README.txt` contains a start guide, an aligned file inventory, verification instructions and data format notes in the report language, followed by a complete English guide. `SHA256SUMS` covers the files listed within it, excluding itself, `manifest.json` and `manifest.sig`; the signed manifest also covers `SHA256SUMS`. Keep the original ZIP unchanged and save working files outside the extracted folder. PDF reports include section bookmarks and case/report identification on later pages. ### The chat at export time A chat export records what Telegram said about the chat when the export began: Telegram's own labels (`scam`, `fake`, `restricted` with its reasons, `verified`), usernames, description, member and admin counts, the linked discussion, content protection, whether new members see earlier messages and from which message on this account sees the history (`available_min_id`), the date of message 1 when it is the chat's creation, and the SHA-256 of the chat photo (saved in `media/`). It records the exporting account's place in the chat: role, join date, who invited it and, for an admin, its rights. A request Telegram refuses is named instead. When the exporting account is an admin, the export reads the chat's admin log (Telegram keeps about 48 hours) into `admin-log.json`: deletions and edits with the supplied content, acting account and source action date. These entries complement the live journal's captured versions and deletion reception records. ### Indicators The reports list, and the archive carries as `indicators.csv`, `indicators.stix.json` (STIX 2.1) and `indicators.misp.json` (MISP event), what an abuse desk can act on in the recorded messages: links and domains (also hidden behind text, in buttons and in link previews), cryptocurrency addresses, Telegram usernames and invite links, phone numbers, e-mail addresses and saved pictures. Bitcoin, Litecoin, Dogecoin and TRON addresses are listed only when their base58 checksum holds, segwit addresses when their bech32 or bech32m checksum holds and TON addresses when their CRC holds; EVM and Solana addresses are marked as not checked. Pictures carry SHA-256 and a perceptual hash (dHash, 64 bits) that recompressed or resized copies keep nearly unchanged. Reports write indicators so that they do not open by accident (`hxxps[://]example[.]com`); the files keep the values as they were. Every indicator is marked unknown and not for automatic detection (STIX `indicator_types: unknown`, MISP `to_ids: false`, distribution to the own organisation): being listed says that a message contained it, not that it is malicious. A link whose text shows a different address than it opens is marked in the report. The PDF reports end with an examiner's declaration to sign by hand, a checklist for a notary or court expert, and a QR code (also on the first page) with the report ID, the key fingerprint and the SHA-256 of the authoritative data, so that a printout leads back to its archive. ## Event canonicalization The hash input consists of exactly these fields: ``` seq, observed_at, source_at, kind, chat_id, message_id, actor_id, payload, previous_hash ``` Serialize using Python-compatible JSON with UTF-8, sorted object keys, no ASCII escaping, no insignificant whitespace, and no NaN/infinity: ``` json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False).encode("utf-8") ``` SHA-256 of those bytes becomes the event hash. The signature is Ed25519 over the 32 raw hash bytes, then base64 encoded. The first previous_hash is 64 zeroes. Sequence numbers start at 1 and increase by 1. All events, including operational events, share one chain. There is no duplicate-delivery suppression: repeated observations are distinct receipts, not a claim of distinct Telegram actions. Raw Telegram dates are ISO strings; binary fields become objects containing bytes_base64. Message text, entities, media descriptors, reply metadata, reactions, and service actions are retained in raw message metadata when supplied. A live message also keeps the Telegram update that delivered it in `transport_update`; when that update carries the same message as `raw`, its `message` field is `{"same_as": "raw"}` instead of a second copy. `observed_at` is the collector's UTC time of writing the record; `source_at` is the date supplied by that Telegram event. Records written while handling a live update add `payload.received_at`, the UTC time the update reached the collector, and `payload.processing_delay_ms`. Live edits retain the supplied edit date, history snapshots retain the message date with a current observation time, and an ordinary deletion notification records reception time with a null source date. Admin-log entries retain their supplied action date separately. Reception order and source event order are distinct timelines, with clock observations and external receipts available for comparison. ## Actor semantics Attribution follows the event source. `message.new.actor_id` and `message.edited.payload.sender_id` retain the message sender. Ordinary `message.deleted` notifications carry message IDs and have a null actor field; available admin-log entries carry their supplied action, actor and date. Membership service messages retain sender and action type, raw participant updates retain the supplied `actor_id`, and reaction snapshots preserve their supplied counts and visible identities. Read these records together with the captured versions and [panel interaction receipts](https://phishdestroy.io/tgwitness/docs/reference/collection/#own-actions). Deletion notifications for private chats and ordinary groups contain only message IDs. Those chats share one account-wide ID sequence, so an ID identifies a single message of this account. When a message with that ID was saved earlier in this journal, the deletion is recorded in that chat as message.deleted with payload.chat_resolution naming the method. IDs that were never saved are kept as `deletion.unscoped`: an actual deletion notification whose chat has not been correlated. This is distinct from `message.missing_on_recheck`, which records an unavailable query result, and from a gap in saved message IDs. Channels and supergroups number messages per chat and are never matched this way. When the deleted message was sent by the observed account, payload.deleted_message_was_outgoing is true; the deleter is still not supplied. An unscoped notice keeps its own label because the matching chat may be outside the current observation scope or have no unique match. Recheck absence remains a separate observation from a deletion notification in report counts, filters and labels. A later recovery clears the current missing state while preserving the earlier unsuccessful check in the signed history; deletion notices stay a separate event type. Multiple IDs resolved to the same chat from one notification are grouped as `deletion.batch`, regardless of their count, with the message IDs exactly as Telegram sent them and how many of them this account had sent. Telegram's notification lists the messages; the chat's admin log names the acting administrator where the account can read it. The link (`message.deletion_attributed`) is made whichever arrives first: a poll that saw the admin log entry before the deletion notice is matched when the notice is recorded. ## Coverage: continuity, gaps and unobserved IDs Every signed ZIP carries `coverage.json`, the HTML report opens with the same summary, and `verify.py` recomputes it from `events.jsonl` instead of trusting the file: - **Continuously observed from X to Y.** A period starts with `observation.started` and ends at a pause, a stop, a lost Telegram connection, a sign-out, a process start without an orderly stop, or more than three minutes without any record while observing (heartbeats are written every minute, so silence means the process stopped, froze or the computer slept). When the heartbeat interval is changed in **More tools → Parameters**, each heartbeat records it and the allowed silence becomes three intervals, never less than three minutes. - **Gaps** list the time between periods with the reason. A gap still open at the last record is marked `not_resumed_by_last_record`. - **Message IDs not observed.** For channels and supergroups, which number messages per chat, the IDs missing between observed ones are listed as ranges. They are reported as *not observed* — deleted, never delivered, or outside the saved history — never as deleted. Private chats and ordinary groups share an account-wide sequence, so gaps inside one such chat mean nothing and are not listed there. - Chat-level gap notices (for example Telegram asking for difference recovery in one channel) are counted as notes; they do not interrupt global coverage. - **Session records.** Windows in which Telegram's update counter grew while no update reached this session (`updates_diverted`), this session left Telegram's session list while its connection kept working (`session_revoked_externally`), or a witness probe's answer arrived only from history (`probe_ack_missed_live`) are listed separately. The verifier also reports where the Telegram session key came from, other sessions signed in when observation started, sessions added during observation, Telegram security notices (777000), other sessions ended from the workspace, only-session periods, witness probe counts and phone call updates. See [accounts](https://phishdestroy.io/tgwitness/docs/reference/accounts/#witness-probe). While [strict chosen chats](https://phishdestroy.io/tgwitness/docs/reference/collection/#strict-chosen-chats) is on (`scope.strict` in `observation.started`), the session list (except while this is the only session, or when **Telegram devices** is on), security notices and phone call updates are not collected, so their absence says nothing, and a deletion is matched to a session check only if one ran in the 10 minutes before it. ### Update sequence (`pts`) Telegram numbers message-related updates with `pts`: one sequence for the account (private chats and basic groups together) and one for each channel or supergroup. The collector records each stretch it received without a hole as a `coverage.sequence` record: the first and last `pts`, the number of updates of each type, and whether they were pushed live or returned by `getDifference` or `getChannelDifference`. A break is a `coverage.gap` record, and `coverage.gap_closed` names the `pts` from which the sequence is whole again. An unbroken stretch shows that every update Telegram numbered in that sequence between its first and last `pts` reached this collector's Telegram client. It says nothing about content Telegram never sent to this account, about the time before the first recorded `pts`, or about stretches the collector did not write down. A `pts` advance that no recorded stretch or difference covers is shown as a break. `GET /api/continuity` answers for an interval (`since`, `until`, `chat_id`) whether each sequence is unbroken and lists the breaks with their reasons. `verify.py` prints the same from the records of an archive under **Sequence continuity**. ### Missing message numbers (`gap_summary`) For a reader's guide to this section and to observation periods and gaps, see [Coverage and missing material](https://github.com/phishdestroy/TgWitness/blob/main/docs/COVERAGE.md). **Preview.** `coverage.json` → `gap_summary` measures the numbers Telegram assigned and this collector never saw. Telegram numbers messages once per channel or supergroup, and once per account across private chats, bots and ordinary groups. A number between two observed messages is either observed or missing; a contiguous range is a positive statement that every message numbered in it was observed. A gap names no actor and no reason. | Field | Meaning | | --- | --- | | `status` | `on`, or `off` when turned off in **More tools → Parameters → Gap analysis** | | `parameters` | The parameters that produced the result, so it can be repeated | | `chats[]` | One entry per channel or supergroup, each numbered on its own | | `account` | The account-wide sequence of private chats, bots and ordinary groups | | `status` (per sequence) | `applicable`, or `not_applicable` with `reason` | | `observed_from`, `observed_to`, `span` | First and last observed number and the size of the range | | `observed`, `observed_without_content` | Observed numbers; those known only from a deletion or recheck record | | `missing`, `density`, `gap_ranges`, `largest_gap` | Numbers never observed, their share of the range, how many runs, the longest run | | `clusters[]` | Listed gaps: `low`, `high`, `missing`, and the neighbouring observed numbers `after` / `before` with their observation times | | `service_estimate` | Only when enabled: how many missing numbers would be service messages at their observed share. Never subtracted from `missing` | Validity is derived from the journal, never assumed: - **Channels and supergroups** are measured per chat, also in an export of chosen chats. Records chosen by sender make the measurement `not_applicable`. - **The account-wide sequence** is measured only from the first to the last message that arrived while whole-account collection was on and kept private chats, bots, ordinary groups and the account's own messages, with no such chat excluded (`scope.changed`). Numbers named by `deletion.unscoped` count as observed without content. An export or handover of chosen chats cannot measure it. If whole-account collection was switched off and on, a note says that numbers used meanwhile appear as gaps. - Service messages are journal records with their own numbers, so they close their gaps themselves; the optional estimate is only context. `verify.py` recomputes `gap_summary` from `events.jsonl` with the parameters in the signed `coverage.json` member (defaults for older archives) and prints the account-wide line in its coverage summary. The archive's `get_capture_status` (MCP and the command line) returns the same measurement for the chats an access may read; the account-wide sequence only to access covering the whole workspace. Repeated observations of one service message count once, and the account service estimate uses only numbers inside the measured range. An applied scope must explicitly preserve the account's own messages before account-wide measurement is enabled; the measurement starts from records that carry that information. The measured range covers running observation, and resuming it is noted. The live archive query has a time budget, including its database scan, and marks an unfinished measurement as partial. Telegram documents the [separate message ID sequences](https://core.telegram.org/api/updates#message-id-sequences). These numbers describe observations; deletion notices, rechecks and the admin log record why a number is absent where Telegram reports it. When Telegram stops accepting the account, the `coverage.gap` record that ends observation carries `cause` (`account_banned`, `account_frozen`, `account_deleted`, `session_duplicated`, `session_revoked`, `session_expired`, `session_ended` or `not_authorized`) and the Telegram error; `verify.py` names the cause where the period ends. Coverage combines recorded observation periods, interruptions and message outcomes. Assess it together with the selected chats, period and attachment policy; recheck results and recorded gaps show how completely the account's updates were observed. ## Producer The signed manifest of evidence ZIPs, chat exports, witness journals and the statement of people-profile files contain `producer`: software, version, project (PhishDestroy), homepage and source repository. The HTML report and verifier display this signed producer record. Source-file hashes identify the recorded source tree for comparison with a trusted checkout. Execution provenance is checked separately by [GitHub acquisition attestation](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) or [Intel TDX measurements](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/), where enabled. Archives made before the producer field existed remain supported and are identified as legacy records. Each `observation.started` record also names the Telegram client that observed: its `api_id` (never the hash), whether that is a built-in public pair or the operator's own application, the client description sent in Telegram's connection request, and the kind of connection route with the IP mode (no proxy address or secret). The report and `custody.json` list every distinct client and route with when they were recorded, and the times no listed proxy answered and Telegram saw the server's address. Journals recorded before this say so. ## People profiles A profile file (`tgwitness-dossier-v1`, JSON) is built on request from records already in the journal for one chat; nothing is fetched from Telegram and profile contents are never written to the journal (switching profiles on and off is recorded as `dossier.changed`). For every person with a saved message it lists name and username history, Telegram flags (bot, scam, fake, premium, verified, restricted, deleted) as seen at saving time, profile photo IDs, SHA-256 and perceptual hash (pHash, compatible with `imagehash.phash`) of the avatar from the local avatar cache with similar avatars, activity (first and last message, counts, edited and deleted shares, messages by UTC hour), who replies to whom, other chats in this journal where the person wrote, and mentioned wallets (BTC, EVM, TRON, TON, LTC, DOGE, XMR, SOL; Base58Check addresses are checksum-validated), phone numbers, usernames and links, including links hidden behind text. Every fact lists the journal records (`seq`) it comes from, and `record_hashes` holds the hash of each referenced record. The statement is signed with the workspace key: ``` python verify.py tgwitness-dossier-CHAT.json --fingerprint TRUSTED_SHA256 --evidence tgwitness-evidence.zip ``` checks the signature, verifies the evidence export itself (signature, hash chain and files) and that every referenced record exists unchanged in that export of the same workspace. Avatar hashes are labeled as coming from the local cache (not journal records). Mentions are pattern matches and leads to check. Profiles are switched on per chat, can be exported as an AES-256 ZIP with a password, and are deleted when switched off or when the chat is removed from sources. ## Independent witness A witness journal (`tgwitness-witness-v1`) and its channel posts are checked against an evidence export with `verify.py --witness … --channel …`; see [independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/). With a public `https://t.me/s/…` or `https://telegram.me/s/…` address the verifier reads each post's date from Telegram, and the earliest such date of a post at the export head is external time for the last record. Dates from any other source are supplied metadata. ## Manifest and checkpoints manifest.json includes the format, export time, public key, fingerprint, journal length, head hash, scope, producer, limitations, and SHA-256 of every content member other than `manifest.json` and `manifest.sig` themselves. manifest.sig is the base64 Ed25519 signature over canonical manifest JSON. The verifier rejects unexpected/missing members, duplicate names, corrupt files, broken sequence/chain, invalid signatures, and mismatch with a provided checkpoint. It never extracts archive paths. It limits total declared uncompressed size to 4 GiB; `--max-gib N` allows larger archives made with a raised **More tools → Parameters** limit. A large archive is checked by several processes at once: members are hashed in parallel, and after the first 5,000 records the content hash and signature of each record are checked by worker processes while the main process follows the chain, the coverage and the bindings in order. `--jobs N` sets the number of processes; the default `auto` uses one per CPU, at most 16, and `--jobs 1` keeps everything in one process. The answer is the same either way, and a change is refused with the same message. Hashes at the positions named by retained checkpoints and timestamp anchors are kept during that single pass, so each anchor is compared without reading the journal again. On a 32-thread computer a 10.8 GB archive with 400,000 records took 58.9 s in one process, 15.2 s with 4 and 8.4 s with 16; one pass over the records in order then sets the limit. Run verification from your installed TgWitness version or a reviewed checkout. The copy included in an archive supports portable use; check that copy against your trusted installation before executing it. A checkpoint signs a statement containing the public key, journal length, head hash, and creation time. It also carries the newest drand round the workspace has fetched (`drand_anchor`): the collector asks a drand relay through the workspace's outside route before each periodic checkpoint, so Hide IP, proxies and a turned-off outside route apply, and making the checkpoint itself never connects out. The verifier can check that a later archive contains the same prefix. With `--checkpoint` and `--check-drand` it confirms that round with the drand relays and reports that the checkpoint was signed no earlier than the round's time; the round does not change the assurance tier. Retain the checkpoint outside the collector, so later verification compares the archive with a reference held separately from it. The collector key signs it, so it binds the records up to it only if the recipient obtained it before the archive, through another channel; on its own it does not meet the minimum for evidence. ## Reading a verification result The verifier reports archive integrity, signer pinning and assurance checks separately. A valid signature shows that the bytes have not changed since they were signed. The operator gives the key fingerprint to the recipient through a separate channel. Without `--fingerprint`, an intact archive passes its signature and format checks with `signer_pinned: false`, and the final line starts with `EVIDENCE: minimum not met · missing: confirmed signer key`. For an automated local-archive policy that requires a pinned signer and the minimum for evidence: ``` python -m tgwitness.verify evidence.zip --strict --json --fingerprint TRUSTED_KEY_SHA256 --tsa-ca TSA-ROOT.pem --require evidence ``` Use a fingerprint retained through the recipient's trusted channel. A trusted witness can also pin the collector through a consistent witnessed journal; supply `--witness`, `--witness-fingerprint` and `--require-witness`. `--strict` exits with status 2 for an unpinned signer; an unmet `--require-tier` or `--require evidence` also exits with status 2. `--require evidence` needs `--fingerprint` and external time from a third party covering the last record. Read `signer_pinned`, `requirements_met` and the assurance results, not the exit code alone. [Sealed acquisition](https://github.com/phishdestroy/TgWitness/blob/main/docs/TRUST.md#sealed-evidence) instead uses its attestation verifier and approved policy to authenticate the acquisition digest. ## Verification scope Verification checks the archive and the collection mode used to produce it. Choose the mode whose trust boundary matches the case, then retain its verification inputs. | Collection mode | What the verifier checks | Verification inputs and trust boundary | | --- | --- | --- | | Local workspace | Record signatures, hash chain, manifest and attachment bytes | Collector fingerprint retained by the recipient and external time from a third party: verified RFC 3161 or OpenTimestamps receipts, or witness posts read from t.me. Retained checkpoints and witness records are supporting checks | | Local workspace with an independent witness | The archive checks plus agreement with an earlier journal prefix retained by the witness | Witness fingerprint and records; the custodian's key-control record shows who holds the witness key. With `--channel https://t.me/s/…`, the dates Telegram set on the posts give external time | | [GitHub Actions capture](https://github.com/phishdestroy/TgWitness/blob/main/docs/SEALED-ACTIONS.md) | GitHub attestation of the archive digest, approved workflow and collector commits, hosted runner, fresh session/key origin and internal archive integrity | Trusted verifier policy, caller repository and GitHub attestation bundle; collection runs under the pinned workflow | | [Cloud deployment](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/) | Provider lifecycle and access records, firewall and Cloudflare state, plus the collector's signed run record | Read-only queries to the provider and Cloudflare; availability of individual checks depends on the provider | | [Intel TDX confidential VM](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#confidential-vm-on-phala-cloud-intel-tdx) | Quote signature and platform status, binding to the collector statement, compose and OS measurements | Intel trust chain and expected deployment measurements; retain the results of every required TDX check | In sealed acquisition, the approved collector receives data through an authenticated Telegram connection inside the verified environment. Attestation binds the archive to that execution, so verification covers acquisition as well as later file integrity. This relies on the approved code and the platform trust chain listed above. GitHub capture verification requires a session created inside the run and rejects imported-session captures. The run receipt records the collector version, file hashes and startup settings. GitHub provenance and TDX measurements provide the environment checks; the [validation record](https://phishdestroy.io/tgwitness/docs/reference/verification/) identifies tested configurations. ### Where the messages come from Telegram delivers messages to every client, official apps included, inside an MTProto session. The session's authorization key is negotiated against Telegram's pinned server key, and every update arrives encrypted and integrity-checked under that key. The collector receives messages through the account's authenticated session and signs each observation into the journal as it arrives, with the chat, message and sender identifiers and the date Telegram set on each message. In GitHub Actions capture and Intel TDX deployments, attestation also binds that session and signing key to the approved collector execution. The journal records where the authorization key came from. Signing in by phone or QR, or an independent login from a session file, writes `account.authorized` with `key_origin: "created"`; collecting on an imported `.session`, TData or JSON key writes `imported`. An imported key also exists wherever it came from. Attested deployments refuse imported keys. The Telegram origin of a record rests on the account's authenticated connection, the connection and capture records in the journal, captured MTProto frames matched to journal entries ([`tgwitness/forensics/`](https://github.com/phishdestroy/TgWitness/tree/main/tgwitness/forensics)), the Telegram date of each message and, for attested capture, the verified execution environment. Archive signatures preserve that record for later checking. Retained checkpoints fix earlier journal boundaries, coverage records show collection outcomes, and verified external timestamps place the committed bytes in time. For a local workspace, the recipient supplies trusted collector or witness inputs. For sealed acquisition, the trusted policy and attestation bind the archive digest to the approved collector execution. These are different verification paths; report the checks completed for the selected path. ## Attachments Files are addressed by SHA-256 under media/. A media.saved event links a hash and byte length to a specific message event. Raw filenames are metadata, never local paths. Media bytes are downloaded asynchronously, so immediate deletion may prevent capture. Disabled collection, oversize/unknown-size files, download failures, and interrupted downloads are visible as outcomes. A process crash can leave unreferenced partial files; they are not included in exports. The ZIP exporter verifies stored media against their names. JSONL, CSV, and HTML exports verify event signatures but do not carry media bytes. Derivative reports are conveniences; events.jsonl is the authoritative event representation. A full chat export saves attachments within the workspace's attachment settings into media/, named by SHA-256. Each message record in chat.json names its file (`file`, `file_sha256`) or the reason it is absent (`file_status`), together with what the reader saw around the text: links behind the text, forward origin, bot buttons, signature, views and the auto-delete timer. `verify.py` checks that every named file is in the signed manifest under that hash. ## Durable collection and process receipts (0.2) A media job and its message event commit in one transaction. The job stores the original TL message descriptor; the signed observation binds its SHA-256, account, and size policy. Recovery verifies that binding before downloading. It never fetches the current message and silently substitutes a newer attachment. Interrupted jobs are retried, while permanent failure remains an explicit outcome. Each workspace has its own journal and signing identity. A process.started event includes a run ID, local clocks, dependency versions, source-file hashes, initial account/scope, and capture settings. Heartbeats include the run ID, monotonic time, and queue state. The run receipt can also be downloaded as a separately signed statement. For verification of the execution environment, pair it with the GitHub attestation or TDX checks described in [Verification scope](https://phishdestroy.io/tgwitness/docs/reference/evidence/#verification-scope). Automatic checkpoints are retained locally on startup, every five minutes while observing (**More tools → Parameters → Signed checkpoint every**), and on orderly stop. Startup verification and export compare the journal against the latest retained local checkpoint. This can detect a database rollback when the checkpoint survives. Independent retention keeps that reference available outside the workspace; a verified external timestamp additionally anchors it in time. After a restart the saved Telegram update position is resumed (`catch_up_from` in `observation.started`) and missed updates are requested. The saved position covers only updates whose handling has finished, so updates still waiting when the connection closed or the process stopped are requested again. A periodic recheck records `message.recovered` for missed messages and `message.missing_on_recheck` when Telegram no longer returns a saved message; the latter is not a deletion notice and names no deleter or time. ### Off-site copy and restore (S3) The off-site copy (**Settings → Notifications and off-site copy → Off-site copy**, or **More tools → Extras → Evidence & backups**; off by default) uploads journal segments, preserved files, checkpoints with their timestamps and finished chat exports to S3-compatible storage, encrypted with AES-256-GCM before upload under a key kept in the workspace vault; Object Lock retention applies when the bucket supports it. Without the downloaded key the copy cannot be read. Restore and verify with `python -m tgwitness.replica restore --key-file KEY.json --out DIR`. Restore requires an empty ordinary directory. Downloads and decrypted objects stay in private temporary storage until the entire journal and every retained checkpoint verify. Unsafe object paths, inconsistent segment ranges and journals shorter than a checkpoint are rejected; failed verification publishes no restored files. Retention checks compare the returned Object Lock mode and date with the deadline sent at upload (one second of rounding tolerance). An expired, invalid or shortened deadline does not count as verified. The status reports the sampled object whose retention was read back for that upload pass. Missing or corrupt local media is reported as the pass's error and keeps the media cursor before it, so the file is tried again next pass; the files, checkpoints and exports after it are still copied. Restore checks all preserved-media references against decrypted hashes and recorded sizes. Identical overlapping journal segments from interrupted uploads are deduplicated; conflicting overlaps are rejected. Checkpoints created during an upload are deferred until their covered journal records have been copied, so a completed pass does not publish a checkpoint ahead of its journal. ### Streaming export snapshots Streaming exports use a stable SQLite read snapshot. Its head may be older than the current live journal when download completes. A checkpoint created after that snapshot can correctly report that the archive is shorter; compare with a checkpoint at or before the exported prefix, not an arbitrary later checkpoint. ## RFC 3161 preparation and response verification (0.2) Evidence mode sends only the SHA-256 of each signed checkpoint to the listed RFC 3161 authorities and OpenTimestamps calendars, over the workspace route and never over MTProxy. Timestamps are on by default in every setup goal; **Evidence for a case** also records drand. Answers are kept in `checkpoints/anchors/`, exported as `.tsr` and `.ots` files under `anchors/`, and checked by `verify.py` (`--tsa-ca` checks the TSA signature; confirm OpenTimestamps proofs with `ots upgrade` and `ots verify`). An RFC 3161 authority that fails twice in a row waits before the next attempt: one interval, then two, four and so on up to six hours, or as long as its `Retry-After` asks, up to a day. A pass that finds only waiting authorities writes no record; otherwise `anchor.completed` lists them under `deferred` with `retry_at`. Until they answer again, the panel shows timestamps as **Degraded**. The panel prepares a request archive containing canonical checkpoint.json bytes, a SHA-256 message imprint and random nonce in timestamp.tsq, checksums, and instructions. No network request is made; the token the authority returns for this request is the timestamp. `python -m tgwitness.anchor verify` checks the reply against the checkpoint bytes and the original request without OpenSSL. A trusted CA file is required explicitly; included certificates are not automatically trusted. Request checking is optional at the CLI, so retain and supply --request to check the nonce. The result states whether it was checked. The collector checkpoint signature and journal must still be verified separately with the trusted collector fingerprint. Verification checks the response signature, checkpoint bytes and, when supplied, the original request under the specified CA trust. For time stamps obtained in evidence mode, `verify.py` also checks the stored OCSP or CRL evidence ([signing certificate revocation](https://phishdestroy.io/tgwitness/docs/reference/timestamp/#signing-certificate-revocation)). See the [procedure](https://phishdestroy.io/tgwitness/docs/reference/timestamp/) and [validation results](https://phishdestroy.io/tgwitness/docs/reference/verification/). ## Optional records in evidence mode: drand and Telegram devices Two more records can run on the same passes as the timestamps. Both take effect only while evidence mode is on. **Evidence for a case** turns drand on; otherwise both start off. Switch them under More tools → Extras → Evidence & backups → **More witnesses · optional**, or `"drand": true` and `"devices": true` in `POST /api/evidence`. One failing does not stop the other or the timestamps; the panel shows the latest result of each under the form. **drand** (`beacon.drand`). Each pass writes the newest round of drand quicknet, the public randomness of the League of Entropy (a round every 3 seconds), into the journal: `chain`, `round`, `randomness`, `signature`, `round_time` and the `relay` that answered. A verified unpredictable round supplies a lower time reference for the subsequent hash-linked material. A verified timestamp on a later checkpoint supplies an upper time reference. These checks bound the linked material. The collector asks `drand.cloudflare.com` first, then the relays of Protocol Labs, through the workspace route, one request per pass. `verify.py` checks that each randomness is the SHA-256 of its signature and that the round time is right, and reports the rounds, the longest stretch without one and how far behind drand the collector's clock was. `--check-drand` compares the rounds with a Cloudflare relay and a Protocol Labs relay, all of them or a random sample of 100 in a long journal; a round that differs fails the verification. **Telegram devices** (`account.devices`). Each pass reads the account's sessions with `account.getAuthorizations`, the list Telegram shows in Settings → Devices, and records it: in full when it changed since the previous pass, with the `added` and `removed` session hashes, otherwise only its count and SHA-256. Device model, platform, app and version, creation and last activity, country and region are kept; IP addresses are not, because evidence exports leave your hands. The collector's own session is active all the time, so only other sessions' activity counts as a change. `verify.py` reports how often the list was recorded and each new and ended session. It reads the list only while observation runs. What they show: drand places the records in order against public time, and the device list is Telegram's statement through the collector, signed by the collector like every other record. **Cloudflare Gateway log** (`cloudflare.gateway_dns`). For a server that resolves through Cloudflare Gateway ([Gateway DNS](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/#cloudflare-as-an-outside-witness)), each pass copies what Gateway logged since the previous copy: one record per window of at most three hours with `from`, `until`, the `location_id`, the server's `address` when one is set, and the `queries` as `[at, name, type, rcode, decision, colo]`, also when there were none. Set it under **Cloudflare Gateway log**: account, location, optional address and a read-only token (Account Analytics Read; Zero Trust PII Read to keep one address of a shared location). The panel checks them with one request before saving; the token stays encrypted and never enters the journal. `verify.py` lists the windows, the names looked up most and any time no copy covers; a record whose count does not match its queries fails. A window that holds more than one page of queries in a single second keeps that page and says the rest is missing. The copy is Cloudflare's answer through the collector, signed by the collector; within 24 hours anyone with a read-only token can compare it with Cloudflare. --- # Certified Translation of Telegram Evidence Reports Canonical page: https://phishdestroy.io/tgwitness/docs/reference/translation/ File the English original of a TgWitness report with a certified or sworn translation. Find the sealed original in the archive and the terms translators keep. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Which file is the original, what to file with a certified translation and the terms translators keep. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Evidence and verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/) ![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c) TgWitness writes reports in 25 languages. English is the original. The other languages are machine translations with terminology review for some of them; they help the operator read the report and are not certified translations. ## What to file File the English original with a certified or sworn translation into the court language. A sworn translator knows the local terminology and the formal requirements for court documents. When the report language is not English, the evidence, chat and handover ZIPs also contain the English original of the same report: `report.en.html` and `report.en.pdf`, or `chat.en.html` and `chat.en.pdf` for a chat export. They are sealed and signed with the same key as the report in the selected language and listed with their SHA-256 in the signed manifest, which names them under `report.original`. A report exported in English is itself the original. The report in the selected language opens with the same recommendation and names the English file. Before translating, check the original against the archive: ``` python -m tgwitness.verify report.en.html --fingerprint KEY --evidence tgwitness-evidence.zip ``` `README.txt` in each archive ends with a **For translators** section that names the original files and repeats the terms below. The [narrative and expert protocol](https://github.com/phishdestroy/TgWitness/blob/main/docs/NARRATIVE.md) print the same recommendation. ## What stays literal - File names, commands, hashes, key fingerprints, Telegram IDs, message numbers and URLs. - Times: UTC in ISO 8601, as written. Do not convert them to a local time zone. - Captured messages: quote them in their original language and give the translation separately, marked as a translation. ## Terms | Term | Meaning | Not to be rendered as | | --- | --- | --- | | journal | The signed, hash-chained sequence of records kept by the collector | Diary, periodical, magazine | | record | One signed entry of the journal; use one word for it throughout | Note, article | | observation | What the collector received at a recorded time | A finding about the truth of the content | | collector | The TgWitness process that observed through the operator's own Telegram account | Collection of items | | data collection | Receiving and recording updates from Telegram | Collection, set, compilation | | deletion notice | Telegram's notice that a message was deleted; it does not show who deleted it | A proven deletion by a named person | | missing on recheck | Telegram no longer returned the message when it was checked again: deleted, or no longer visible to this account | Deleted | | absent message number | A number with no message in the export: deleted earlier or never visible to this account | Missing message, lost message | | gap | A period without observation | Evidence that nothing happened | | earlier version | The text before an edit; both versions are kept | Correction, falsification | | checkpoint | A signed summary of the journal up to a record number | Control point in a physical sense | | timestamp service (TSA) | An independent RFC 3161 time-stamping service | Authority, government body, certificate authority | | timestamp receipt | The answer of a timestamp service, or an OpenTimestamps receipt, showing that a checkpoint existed by a time | Evidence, proof of the facts | | seal | The Ed25519 signature embedded in a report file | Stamp of an official | | signing key fingerprint | The SHA-256 of the public key, obtained through a separate trusted channel | Biometric fingerprint | | witness | An independent party or service that keeps or confirms checkpoints | A person testifying in court | | handover extract | Part of a journal prepared for another party, with other people's data minimised | Complete export | | minimised record | A record whose withheld fields are named and replaced by their hash | Deleted or redacted record | --- # Independent Evidence Witness & Journal Continuity Canonical page: https://phishdestroy.io/tgwitness/docs/reference/witness/ Configure a TgWitness witness with its own key and Telegram bot. Verify journal continuity against signed checkpoints retained outside the collector. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) Run a witness with its own key and bot, publish signed checkpoints to a channel and check exports against it. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Evidence and verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/) ![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c) [Export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/) · [High assurance](https://phishdestroy.io/tgwitness/docs/reference/high-assurance/) · [Panel guide](https://phishdestroy.io/tgwitness/docs/reference/panel/#extras) A witness retains signed checkpoints separately from the collector. It checks the collector's signature and journal continuity, signs the result with its own key, and publishes it to a Telegram channel. Run it on a separate server with read-only access to the collector's witness endpoint. The technical result includes retained journal prefixes, challenge responses, signature checks, Merkle inclusion/consistency checks and signed continuity outcomes. For a witness operated by another custodian, retain the custodian and key-control record with its fingerprint. Separate keys and separate custody describe different parts of the setup. The verifier reports that a second key retained the journal head and up to which record; the custodian's key-control record shows who holds that key. The witness journal is a supporting check; the minimum for evidence is third-party time. The channel posts add external time: Telegram dates each public post, and the verifier reads those dates itself. Flow diagram · Collector → Witness (signed checkpoint: record count + head hash); Witness → Witness journal, own key; Witness → Telegram channel (signed post via its own bot); Evidence ZIP → verify.py; Witness journal, own key → verify.py; Telegram channel → verify.py (t.me/s page read live, or Desktop export) · Collector · Witness · Witness journal, own key · Telegram channel · Evidence ZIP · verify.py · signed checkpoint: record · count + head hash · signed post via its own bot · t.me/s page read live, or · Desktop export **Diagram as text** 1. Collector → Witness (signed checkpoint: record count + head hash) 2. Witness → Witness journal, own key 3. Witness → Telegram channel (signed post via its own bot) 4. Evidence ZIP → verify.py 5. Witness journal, own key → verify.py 6. Telegram channel → verify.py (t.me/s page read live, or Desktop export) **On this page** - [What the witness holds](https://phishdestroy.io/tgwitness/docs/reference/witness/#what-the-witness-holds) - [What it checks and records](https://phishdestroy.io/tgwitness/docs/reference/witness/#what-it-checks-and-records) - [Run a witness](https://phishdestroy.io/tgwitness/docs/reference/witness/#run-a-witness) - [Public proof page for several workspaces](https://phishdestroy.io/tgwitness/docs/reference/witness/#public-proof-page-for-several-workspaces) - [Verify](https://phishdestroy.io/tgwitness/docs/reference/witness/#verify) ## What the witness holds | The witness has | The witness never has | | --- | --- | | A read-only **witness token** for one workspace | The collector's Telegram session or API credentials | | Its own Ed25519 key and journal | The collector's vault, signing key or panel token | | Its own Telegram bot token | Message content: the head is a record count and a hash | The token is created in **More tools → Extras → Independent witness**, shown once and stored only as a SHA-256. It opens exactly one endpoint, `GET /api/witness/head`, which returns a freshly signed checkpoint plus signed content-free collection counters and operational health. It cannot open the panel, read message content or change settings, and the panel token is not accepted there. Revoke a token on the same page. The collector records when a new witness key starts checking (`witness.seen`) and shows the last check per token; a witness that has not checked within 2.5 intervals is marked overdue. New witnesses send a random challenge on each poll; the capture statement echoes it under the collector signature. Counters are bound to the exact checkpoint and are included in signed witness posts. Legacy heads remain accepted by the standalone witness. Journal growth alone is never counted as a new message. ## What it checks and records Every interval (10 minutes by default) the witness: 1. fetches the head itself (the collector cannot push or skip it); 2. verifies the collector's signature, the pinned collector key (`--collector-fingerprint`, or the first key seen), a nondecreasing count and an unchanged head at an unchanged count. Merkle inclusion and consistency proofs verify that a growing journal extends the retained checkpoint. Once continuity proofs have been used, removing them is rejected; 3. appends a signed record to its own journal: `witness.anchor` with status `ok`, `key_changed`, `rollback` (fewer records than before), `fork` (same length, different head) or `invalid` (the answer failed verification), or `witness.no_response` when the collector did not answer; 4. posts the result to the channel, signed, including "no answer" while the witness is running and can reach the Bot API. The post ID is recorded (`witness.posted`), a failed post too (`witness.post_failed`). A post looks like this; the last line carries the signed statement: ``` TgWitness witness #42 · journal head Collector 3fa9c2d1e0b4a7f6: 18234 records Head 9b1f…c07e 2026-10-28T19:40:00.123+00:00 TGW1.eyJhdCI6…. ``` ## Run a witness You need a Telegram bot (create one with @BotFather), a channel where that bot is an administrator, and the collector's address reachable from the witness — over HTTPS outside a private network (see the HTTPS profile in [deployment](https://phishdestroy.io/tgwitness/docs/reference/deployment/)). Open **More tools → Extras → Independent witness → Configure** in the panel. Three steps cover read-only access, your channel and interval, then launching the witness. Publication policy, optional HTTP/SOCKS5 proxy and custom Bot API address are under **Advanced settings**. The form downloads `witness.json` with this workspace's collector key pinned. Download the newly created read-only token with **Save access file** as `witness-token.txt`; place it and a `bot-token.txt` created on the witness host beside that JSON. The collector never receives the bot token. Downloading does not start a service or publish a message. No hosted project witness is implicitly enrolled. ``` python -m tgwitness.witness run --config witness.json --check-config python -m tgwitness.witness run --config witness.json python -m tgwitness.witness fingerprint --config witness.json ``` The first command checks configuration and secret files without network requests or key creation. Paths in JSON are relative to that file; CLI/environment paths are relative to the working directory. Retain the witness fingerprint outside its host. The collector's last-poll indicator confirms a request only; publication is reported by Proof or checked in the witness journal and channel. If the panel stays behind an SSH tunnel, expose only the scoped witness endpoint on a separate HTTPS hostname with [this Caddy example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.witness.example). The default workspace then uses `https://witness.example.org`, other workspaces use `https://witness.example.org/profiles/ID`. Tokens are still required; the panel and its other API routes are not forwarded by that virtual host. Choose `all` for regularly published checkpoints. A five-minute interval means about 288 posts per workspace per day. `changes`/`problems` deliberately leave some checks unpublished. MTProxy is for the collector's Telegram client. Witness HTTP polling and Telegram's HTTPS Bot API use their own direct/HTTP/SOCKS5 route ([Bot API](https://core.telegram.org/bots/api)). **Next to the collector, with Docker** (same host — independent process and key, but the same operator): put the values in `.env` and start the profile. ``` TGWITNESS_WITNESS_TOKEN=tgww_... TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC... TGWITNESS_WITNESS_CHANNEL=@your_witness_channel # another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/ docker compose --profile witness up -d docker compose logs witness # prints the witness key fingerprint ``` With a published image use `docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d`. **On someone else's server** (separate custody): copy the repository there, set `TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org` plus the three values above in `.env`, then ``` docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d ``` or without Docker: ``` python -m tgwitness.witness run --collector https://your-collector.example.org \ --token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel ``` ### Publish to Discord A witness can post to a Discord channel instead of Telegram. In Discord, open **Edit Channel → Integrations → Webhooks**, create a webhook and copy its URL. In the panel, choose **Discord webhook · your channel** in step 2. On the witness host, save the URL as `discord-webhook.txt` next to `witness.json`; it never reaches the collector. ``` python -m tgwitness.witness run --collector https://your-collector.example.org \ --token-file witness-token.txt --discord-webhook-file discord-webhook.txt ``` A witness has one publisher: a Telegram channel or a Discord webhook, not both. Posts carry the same signed statement and cannot ping anyone. A post longer than Discord's 2,000 characters is replaced by a short line with the full check attached as `witness-check.txt`. Each post ID is recorded as `witness.posted`. `verify.py --channel` reads Telegram channels only, so for Discord keep the witness journal: it holds every check. Discord posts give the verifier no external time. ### Options | Option | Environment | Default | Meaning | | --- | --- | --- | --- | | `--interval` | `TGWITNESS_WITNESS_INTERVAL` | 10 | Minutes between checks, 1–1440 | | `--timeout` | `_TIMEOUT` | 30 | Seconds to wait for the collector and the Bot API, 5–600 | | `--post` | `_POST` | `all` | `all`: every check; `changes`: a new head or a problem; `problems`: only problems and missing answers | | `--title` | `_TITLE` | `TgWitness witness` | First words of every channel post | | `--collector-fingerprint` | `_COLLECTOR_FINGERPRINT` | – | Pin the collector key instead of trusting the first answer | | `--proxy` | `_PROXY` | direct | `socks5://host:port` or `http://host:port` | | `--bot-api` | `_BOT_API` | `https://api.telegram.org` | Bot API address, e.g. a local Bot API server | | `--data-dir` | `_DATA` | `witness-data` | Witness key and journal | | `--config` | `_CONFIG` | – | JSON file with any of the options above | The collector address, tokens and channel come from `--collector`, `--token` or `--token-file`, `--bot-token` or `--bot-token-file`, `--discord-webhook-file` and `--channel`, or `_COLLECTOR`, `_TOKEN`, `_TOKEN_FILE`, `_BOT_TOKEN`, `_BOT_TOKEN_FILE`, `_DISCORD_WEBHOOK_FILE` and `_CHANNEL`, which keeps secrets out of the process list. A config file uses the option names with underscores, plus `texts`, which replaces the words of the channel posts: ``` {"collector": "https://your-collector.example.org", "token_file": "witness-token.txt", "bot_token_file": "bot-token.txt", "channel": "@your_witness_channel", "interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness", "texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}} ``` `texts` keys: `ok`, `key_changed`, `rollback`, `fork`, `invalid`, `no_response`, `collector`, `records`, `head`. The command line wins over the environment, the environment over the file. Unknown options or text keys stop the witness with a message instead of being ignored. Wording never affects verification: verify.py checks the signed token at the end of every post. With `--post changes` or `problems`, checks that were not posted are still in the witness journal and `verify.py` lists them as never posted; the start record names the policy. Every check still appears in the journal, so fewer posts mean fewer times dated by Telegram, not fewer checks. Without a channel the witness still keeps its journal. Keep the witness key fingerprint (`python -m tgwitness.witness fingerprint`) somewhere else. ## Public proof page for several workspaces `python -m tgwitness.proof` witnesses up to 32 workspaces at once and serves a read-only page with the latest signed check of each. Every workspace gets its own witness key and journal under the data folder and a pinned collector key; posting to a Telegram channel is optional per workspace. Start from [proof.config.example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/proof.config.example): | Field | Meaning | | --- | --- | | `title` | Page title, 1–100 characters | | `data_dir` | Witness keys and journals, relative to the file; default `proof-data` | | `interval`, `timeout` | Minutes between checks (1–1440, default 5); seconds to wait (5–600, default 20) | | `workspaces[].id`, `label` | Short lowercase alias and the name shown | | `workspaces[].collector` | Collector address; other workspaces end in `/profiles/` | | `workspaces[].collector_fingerprint` | Required, different for each workspace | | `workspaces[].token_file` | File with that workspace's read-only witness token | | `workspaces[].channel`, `bot_token_file` | Optional, together: post each check to a channel | | `workspaces[].proxy`, `bot_api` | Optional route and Bot API address | ``` python -m tgwitness.proof --config proof.json --check-config python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790 ``` The first command validates the file and the token files without opening a connection. The page answers only GET and HEAD: - `/` shows every workspace; a workspace without a check for 2.5 intervals is marked stale. - `/api/proof` returns the same as JSON. - `/api/proof/` downloads the latest signed statement (`tgwitness-public-proof-v1`): witness record number and hash, status, pinned collector key, checkpoint, collection counters and whether the channel post succeeded, signed by that workspace's witness key. - `/healthz` answers 503 when a workspace's monitor has stopped. Give the page its own hostname, as in [Caddyfile.proof.example](https://github.com/phishdestroy/TgWitness/blob/main/deploy/Caddyfile.proof.example). For verification, export a workspace's witness journal with `python -m tgwitness.witness export --data-dir proof-data/ --out witness.zip` and use it as described below. ## Verify On the witness side, export its journal: ``` python -m tgwitness.witness export --out witness.zip # Docker (add -f deploy/compose/compose.witness.yaml on a witness server): docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip docker compose cp witness:/witness/witness.zip . ``` Then, anywhere, with the collector's signed ZIP and the address of the public channel: ``` python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \ --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel ``` `--channel` also accepts a Telegram Desktop export (*Export chat history* → JSON gives `result.json`) or a saved copy of the page; these check the post content but give no external time. `verify.py` checks the witness journal (chain and signatures), then that **every head the witness saw is part of the exported journal**: the record at that count must have exactly that hash. A head that does not match fails verification — the journal was changed after the witness saw it. It also reports heads seen after the export, anomalies the witness recorded, answers that failed, periods whose matching checkpoints are present in this export ("Witnessed from X to Y") and gaps. Later checkpoints do not extend those periods. The result includes the last matched record number and the number of trailing records without a matching checkpoint. Only answers signed by the export's own key count: an export signed by a key the witness never saw is reported as not witnessed, and without `--fingerprint` its signer stays unpinned. With `--channel` every signed post must match the witness journal record by record: changed posts fail verification, missing posts are listed. Matching the token authenticates the content; the date is outside the signed token. With a live `https://t.me/s/…` or `https://telegram.me/s/…` address the verifier reads each post's date from the page at verification time. Telegram sets that date; dates of edited posts are not used. The earliest such date of a post at the export head is external time for the last record, which meets that condition of the minimum for evidence. Dates from any other source, such as a supplied `result.json`, a saved page or another web address, are supplied metadata, not independent time; the result names where its post dates came from (`post_date_verification`). ### Require a witnessed export boundary For a handover that must include a witnessed final record, add `--require-witness`: ``` python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \ --witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness ``` This requires the independently retained witness fingerprint, a key other than the collector key, and a matching checkpoint at the exact end of this export. A checkpoint covering only an earlier prefix is insufficient. Pause collection, let the witness observe the final state, and export before further journal writes; if the journal changes, retain another checkpoint and export that state. A later checkpoint alone cannot verify a shorter export's final hash. When `--channel` is also supplied, missing claimed posts or an empty match set fail this strict check. Without the flag, ordinary integrity checks still report unwitnessed records without rejecting an otherwise intact archive. Keep the witness journal and its pinned key separately. Online checks verify continuity between checkpoints; offline verification compares every retained checkpoint with the export. Legacy heads without continuity proofs retain the offline comparison and are reported without online continuity verification. The report lists witness downtime and failed publications by interval. ### Daily seals and unavailable timestamp calendars The witness seals the previous UTC day's journal boundary and submits the hash of that signed seal to OpenTimestamps. A calendar submission is pending evidence; only independently checked Bitcoin commitments receive confirmation in the verifier. If all calendars fail, the signed seal and unsuccessful attempt remain in the journal. The hourly maintenance pass retries that original record, including after a restart or a change of date. It scans at most 32 seals, submits at most two missing submissions and spends at most 60 seconds on retries per pass. A persistent cursor rotates through older seals. Retained submissions follow the existing proof-upgrade path. A retry does not rewrite the seal, change its original date or claim that the calendar received it earlier. A later Bitcoin commitment remains a later external confirmation. Missing proofs remain `none`; pending proofs remain `pending` until the verifier checks them independently. --- # RFC 3161 Timestamps for Telegram Evidence Canonical page: https://phishdestroy.io/tgwitness/docs/reference/timestamp/ Timestamp signed Telegram journal checkpoints with RFC 3161. Review what reaches the time authority and how to verify the returned timestamp response. [Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/) [Documentation index](https://phishdestroy.io/tgwitness/llms.txt) RFC 3161 timestamps for signed checkpoints: what is sent to the authority and how a response is verified. [TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Evidence and verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/) ![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c) TgWitness prepares RFC 3161 requests and verifies timestamp authority (TSA) responses. This manual procedure neither selects a TSA nor submits data; evidence mode does both on a schedule ([evidence format](https://phishdestroy.io/tgwitness/docs/reference/evidence/#rfc-3161-preparation-and-response-verification-02)). A prepared request is **not yet a timestamp proof**. ## What the proof binds Flow diagram · Account observations → SHA-256 chain and Ed25519 signatures; SHA-256 chain and Ed25519 signatures → Signed checkpoint; Signed checkpoint → Exact-byte hash and random nonce; Exact-byte hash and random nonce → RFC 3161 request; RFC 3161 request → Independent TSA; Independent TSA → Signed TSA response; Signed checkpoint → Verify data, nonce and explicit CA trust; Signed TSA response → Verify data, nonce and explicit CA trust · Account observations · SHA-256 chain andEd25519 signatures · Signed checkpoint · Exact-byte hash andrandom nonce · RFC 3161 request · Independent TSA · Signed TSA response · Verify data, nonce andexplicit CA trust **Diagram as text** 1. Account observations → SHA-256 chain and Ed25519 signatures 2. SHA-256 chain and Ed25519 signatures → Signed checkpoint 3. Signed checkpoint → Exact-byte hash and random nonce 4. Exact-byte hash and random nonce → RFC 3161 request 5. RFC 3161 request → Independent TSA 6. Independent TSA → Signed TSA response 7. Signed checkpoint → Verify data, nonce and explicit CA trust 8. Signed TSA response → Verify data, nonce and explicit CA trust The collector signature binds records to its key. A trusted TSA response can establish that a particular checkpoint existed by the TSA's stated time. The checkpoint can then bind the journal prefix. This upper time bound applies to that committed prefix; individual Telegram actions retain their recorded event times. ## Procedure The journal verifier reports backward steps and unparseable `observed_at` values in `chronology` when present, and includes a warning in its command output. It preserves the signed timestamps and still checks their signatures. A backward step can come from a clock correction, so review it with the host's clock records. Independent time comes from verified external timestamps, witness posts read from their public t.me page and drand rounds; `--strict` governs signer pinning and supported formats. Recorded drand values receive structural and hash self-consistency checks offline. `--check-drand` compares selected recorded rounds with HTTPS relay responses; the result states how many rounds were compared and which relays answered, and the compared rounds supply the authenticated lower time bound. 1. Retain the collector key fingerprint through a separate trusted channel; it identifies the collector independently of the examined ZIP. 2. In **Exports → Prepare timestamp request**, download the selected workspace's request ZIP. Extract `checkpoint.json`, `timestamp.tsq`, `SHA256SUMS` and `README.txt`. Do not change the checkpoint bytes. 3. Choose a TSA appropriate to the investigation. Submit `timestamp.tsq` using its documented method, with `application/timestamp-query` for an HTTP service. Save the original binary reply as `timestamp.tsr`, the endpoint, retrieval time and request outcome. The request contains a hash and nonce rather than messages; network metadata still reveals the request. 4. Obtain the trusted root certificate independently of the reply, plus any intermediates required. A certificate in the reply does not become trusted merely because it is included there. 5. From a trusted TgWitness installation, verify: ``` python -m tgwitness.anchor verify --checkpoint checkpoint.json --request timestamp.tsq --response timestamp.tsr --ca trusted-tsa-root.pem ``` Add `--intermediates tsa-intermediates.pem` if needed. OpenSSL is not needed: the signature, the signing certificate reference and the chain are checked in Python with the `cryptography` library, the same code `verify.py --tsa-ca` uses. `openssl ts -verify` remains an independent second check for an expert who wants one. 1. Export a signed journal ZIP after the checkpoint so it includes that prefix. Verify using the independently known fingerprint: ``` python tgwitness/verify.py evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json ``` This shows that the export contains the timestamped prefix. `verify.py` reads timestamp receipts only from the ZIP, where evidence mode stores them; the manual reply is checked in step 5 and covers the records up to this checkpoint. 1. Preserve the ZIP, checkpoint, request, reply, certificate chain, verification results and handoff record outside the collector. Repeat verification at receipt. To prepare a request from a saved checkpoint: ``` python -m tgwitness.anchor prepare checkpoint.json --out timestamp-request.zip ``` Preparation canonicalizes JSON and includes the matching checkpoint in the archive. Use the **checkpoint bytes from that archive** for TSA verification, even if the input file had different whitespace. ## Verification boundaries | Check | Current behavior | | --- | --- | | Data | SHA-256 of the exact checkpoint bytes must match the response | | Request | With `--request`, the original query and nonce are verified | | TSA signature | The signature, the signing certificate and its chain to the explicit CA are checked at the stamped time | | Collector signature | Separately verified by the journal verifier with a pinned key | | Revocation | Evidence mode stores OCSP/CRL evidence that `verify.py` checks | | Scheduled submission | Evidence mode, turned on by every setup goal | `--request` is technically optional, but omitting it prevents verification of the original nonce. For this full procedure, the result's `request_checked` must be true. Each certificate in the chain must be valid at the stamped time, and the signing certificate must be for time stamping only. The TSA response anchors the submitted checkpoint bytes to its stated time. Review that result with the acquisition records and environment verification for the selected mode. Evidence mode includes the Belgian government's qualified TSA (`http://tsa.belgium.be/connect`; RFC 3161 replies are signed, so plain HTTP does not weaken them). With that provider's root passed to `--tsa-ca`, `verify.py` reports a qualified eIDAS time stamp and its time stamping unit; Regulation (EU) No 910/2014, article 41(2), presumes the accuracy of its time and the integrity of the bound data. ### Signing certificate revocation Right after each reply, evidence mode fetches revocation evidence for the TSA signing certificate: an OCSP response from the certificate's AIA OCSP address, otherwise the CRL from its distribution point (at most 4 MiB). It is stored next to the reply as `checkpoint-N..ocsp` or `.crl` and exported with it. A failed fetch never holds back the time stamp; the `anchor.completed` record lists it as `unavailable` with the reason. `verify.py` checks the OCSP response signature (by the issuer, or by a responder certificate the issuer gave the OCSP signing purpose), the certificate ID and the status, and that the answer was issued at or after genTime or was still current then (nextUpdate). For a CRL it checks the issuer's signature, the same time window and that the serial number is not listed. It then reports `signing certificate not revoked as of