TgWitnessDocumentation / 10
Keep it secure
Know the routes for Telegram, public proxy lists and optional external services. Know what each secret unlocks, what the protections cover and what they leave to you.
Where everything lives
The collector, its panel and every saved record stay on the computer or server you run it on. Telegram is the only destination by default; each other one 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 for the tab only | Everything in every workspace: read and export, change scope, sign in accounts | Stop TgWitness, delete panel-token.txt, start it again: a new token is created |
| 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 that verify under your fingerprint | Checkpoints kept elsewhere, a witness and timestamps show what existed before |
| Vault key | vault.key beside the data, or an external master key for a new data directory | Decrypting the vault | Treat the session and signing key as leaked too |
| Witness token | On the witness host | Read-only: signed checkpoints and health | Delete it on the Witness page; create a new one |
| Off-site copy key | Vault; download it once for recovery | Decrypting the off-site copy | Whoever also holds the stored objects can decrypt them: treat that copy as exposed |
What the protections cover
Covered
- A changed, removed or reordered record in an export: the hash chain or a signature no longer verifies.
- A journal cut back or rebuilt after a checkpoint was kept elsewhere: the retained checkpoint no longer matches.
- Guessing the panel token: 256 random bits, compared in constant time; after 15 failures a minute an address is refused.
- Hostile chat content: text is inserted as text, never as HTML; attachments download as files; the panel loads nothing from other sites.
- A copied data directory with an external vault key: sessions and signing keys stay encrypted without the master key.
Left to you
- The main panel token has full control. Give other people scoped access to the accounts, chats and actions they need; keep the main key private.
- An administrator of the machine can read everything and rewrite and re-sign the journal. Keep the fingerprint and checkpoints on another system.
- Message text and media are not encrypted by TgWitness. Use disk encryption and strict permissions.
- Plain HTTP beyond localhost shows the token on the network. Use HTTPS or an SSH tunnel.
- Signatures prove what was recorded was not changed, not that every Telegram event was recorded.
Share access to a case with permissions, expiry and session limits. A witness token remains a separate credential.
Harden an installation
- Use a dedicated Telegram account — never your main one. The panel token and the session give full control of it.
- Keep the panel on 127.0.0.1. Reach it remotely only through HTTPS (the bundled Caddy configuration) or an SSH tunnel.
- Encrypt the disk that holds the data directory: message text and media are stored as they arrived.
- Restrict the data directory to the service account. New directories get mode 0700 on Unix; on Windows, set the folder's permissions.
- Keep the vault master key elsewhere on servers: set
TGWITNESS_VAULT_KEY_FILEbefore creating the data directory. - Save the signing-key fingerprint and checkpoints on another system, and add 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. The token only opens the panel. Stop TgWitness, delete panel-token.txt from the data directory and start it again; the journal, sessions and keys are untouched. With TGWITNESS_TOKEN set, the environment value is used instead of the file.
Why are messages not encrypted at rest?
The collector must read them to search, compare versions and export. Encrypting them with a key on the same machine would add little against someone who can read that machine. Disk encryption protects a stopped or stolen disk; strict permissions protect a running one.
Report a vulnerability
Use Security → Report a vulnerability in the GitHub repository. Include the version, the impact and a minimal synthetic reproduction. Never send credentials, account directories or real evidence archives. If private reporting is unavailable, open an issue asking for a private channel without exploit details.