Documentation / 14
Secure Telegram Sessions & Evidence Storage
What leaves your machine, what each secret opens, and what the protections cover versus what's on you.
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.
- TelegramAlways · 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 copyOptional · 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.
- NotificationsOptional · off by default
Problems and change counts with chat titles. Message excerpts are sent only if you turn them on.
- Timestamp authorityOptional · off by default
Only the SHA-256 of a signed checkpoint and a random nonce. No messages, no chat names.
- WitnessOptional · 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.
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 with permissions, expiry and session limits.
Harden an installation
- Use a dedicated Telegram account, never your main one.
- Keep the panel on 127.0.0.1. Remote access only via HTTPS (bundled Caddy) or an SSH tunnel.
- Encrypt the disk with the data directory.
- Restrict the data directory to the service account (0700 on Unix, folder permissions on Windows).
- Keep the vault key elsewhere on servers: set
TGWITNESS_VAULT_KEY_FILEbefore the first start. - Save the fingerprint and checkpoints on another system, run a witness on another host.
- Never upload
data/, sessions,panel-token.txtor vault keys to GitHub or a chat. - Do not log
Authorizationheaders 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.