TgWitness / Documentation

What has been tested →

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.

127.0.0.1panel address by default
256-bitrandom panel token
0CDNs, analytics or remote fonts
Ed25519signature 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
Panel127.0.0.1:8787 · bearer token
Collectorone Telegram client per workspace
DATA DIRECTORY
JournalSQLite · hash-chained · signed
Mediafiles named by SHA-256
VaultFernet · session, API pair, signing key, proxy
  • 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.

Optional destinations are configured per workspace.

What each secret unlocks

SecretWhere it is keptWhat it unlocksIf it leaks
Panel tokenpanel-token.txt in the data directory; the browser keeps it per tabEverything in every workspaceStop TgWitness, delete panel-token.txt, start again: you get a new one
Telegram sessionVault, encrypted (credentials.enc)The Telegram account itselfEnd the session in Telegram under Settings → Devices
Signing keyVault, encrypted (signing.enc)Signing records under your fingerprintCheckpoints kept elsewhere, a witness and timestamps still show what existed before
Vault keyvault.key next to the data, or an external master keyThe vaultAssume the session and signing key leaked too
Witness tokenOn the witness hostRead-only: checkpoints and healthDelete it on the Witness page, make a new one
Off-site copy keyVault; download it once for recoveryThe off-site copyAnyone 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

  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.