# One journal. Four collection modes. Eight verification levels.

Canonical page: https://phishdestroy.io/tgwitness/guides/modes

Compare TgWitness collection scopes, capture methods and verification mechanisms. Choose a workflow with fictional investigation cases.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/llms.txt)

Modes, scenarios and evidence levels

TgWitness records what the connected account observes. A third party can verify the record’s integrity against an independently trusted key.

[Collection modes](https://phishdestroy.io/tgwitness/guides/modes#scope)[Scenarios](https://phishdestroy.io/tgwitness/guides/modes#scenarios)[Evidence levels](https://phishdestroy.io/tgwitness/guides/modes#levels)

3–5 minute overview · fictional examples · current implementation

1. **Telegram**

   Account-visible updates
2. **Collector**

   Linked records, each signed
3. **Verifier**

   Trusted key + retained boundary

`h₁ → h₂ → h₃ · Ed25519`Read each observation together with its source identifiers and acquisition record.

## Choose the observation scope

Three scopes and an investigation preset. Exclusions and enabled source types still apply.

Default**Chosen chats**

Records

Only sources selected by hand.

New chats

Not added automatically.

Choose for

A known set of channels or groups. No fixed chat capacity has been qualified.

Account folder**Telegram folder**

Records

Folder inclusions and categories, minus exclusions and archived chats when configured.

New chats

Matching active chats; folder changes within an hour.

Choose for

An analyst already maintains a case folder. Confirm collection on a dedicated account.

Confirm scope**Whole account**

Records

Account-visible chats, including private conversations and bots, within selected types.

New chats

Added when the first update arrives.

Choose for

A dedicated observation account, including an account participating in a case.

Whole-account preset**Investigation mode**

Records

All source types, own actions, source profiles and the latest 200 visible messages of newly discovered sources.

New chats

A new chat or bot gets a profile and a history snapshot.

Choose for

Join a team or interact with a bot through the panel. Review and save the preset.

These cards are a local comparison, not live collector controls. They do not change an account.

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/collection/)

## GitHub Actions capture (preview)

A fresh Telegram login, one chat, an encrypted archive and GitHub provenance.

[Open capture helper](https://phishdestroy.io/tgwitness/docs/capture/)

## What is recorded

Only delivered or explicitly requested observations enter the record. Unknown attribution stays unknown.

 Capture switches · local illustrationNew messagesEditsDeletionsReactionsMembership

The panel applies these switches per workspace. Turning one off keeps existing records; turning it back on does not reconstruct missed events.

**Event matrix: saved material and remaining unknowns**

| Category | Saved |
| --- | --- |
| Message | Text, IDs, sender metadata, reply context and original update envelope. |
| Edit | Every observed version, without overwriting earlier ones. |
| Deletion | Notice plus previously saved text, if available. |
| Unscoped deletion | Account-level notice; unknown peer remains explicit. |
| Reaction | Delivered counters and visible recent identities. |
| Membership | Delivered service messages and participant updates. |
| Attachment | Original-version descriptor, saved bytes, SHA-256 and attempt outcomes. |
| History snapshot | Currently visible messages, marked as history observations. |
| Own actions | Outgoing messages/edits and matching reply-keyboard button_press metadata. |
| Bot buttons | Callback, URL, web-app and request metadata retained with the message. |

### Default attachment limits

Photos

20 MiB

Video

100 MiB

Files

50 MiB

Animations

20 MiB

Video notes

50 MiB

Voice

20 MiB

Audio

50 MiB

Stickers

5 MiB

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/collection/)

## Use the authorization you have

Each account has its own workspace, journal, signing key, route and queue.

### Phone + code

Enter 2FA when enabled.

### QR code

Scan from an authorized device; 2FA may still be required.

### Telethon .session

Import the account’s session file.

### Pyrogram .session

Import the supported Pyrogram session format.

### TData ZIP

One supported Desktop account; local passcode if set.

### StringSession text

Paste a Telethon StringSession.

### .session + .json

Select the session and matching companion metadata.

### Auth key HEX + DC ID

Import account authorization with its data-center identifier.

**API pair**

Your own API pair is optional. Without one, TgWitness uses a pool of public pairs, including pairs from official Telegram Desktop.

`Direct · SOCKS5 · HTTP CONNECT · MTProxy`MTProxy is experimental; built-in public MTProxy lists are available. A failed proxy route does not fall back to a direct connection.

Two workspaces on one machine are not two independent witnesses.

[Account formats](https://phishdestroy.io/tgwitness/docs/reference/accounts/)

## Act from the panel

Send or reply, press a current bot button, save a link preview, then explicitly join a chat or start a bot with its start parameter.

`interaction.preview``interaction.requested``interaction.result`

Preview, request and result receipts are signed. Before a button press, the server fetches the message again and rejects a changed keyboard. Returned callback text and URLs remain recorded context.

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/collection/)

## Recovery and continuity

Gaps are shown, not hidden.

### Resume the saved position

After restart, Telegram is asked for missed updates. Finite retention and expired differences can leave gaps.

### Recheck visible messages

Defaults: priority sources every 15 minutes, others every 6 hours. Outcomes include message.recovered and message.missing_on_recheck.

### Read coverage.json

Observation periods, gaps with reasons and unobserved IDs accompany the signed export. A missing-on-recheck record is not a deletion notice.

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/evidence/)

## Seven levels. Different questions.

Each mechanism answers a bounded question. Configure external services separately and retain their trust anchors outside the collector.

1. ### Record

   SHA-256 chain + Ed25519 per event; the first previous_hash is 64 zeroes.

   **Third party checks** Ordering and signatures under the pinned collector key.

   **Verification command**

   ```
   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256
   ```
2. ### Container

   manifest.json lists file hashes; manifest.sig signs it. media.saved binds attachment bytes to an event.

   **Third party checks** The supplied files agree with the signed manifest and media receipts.

   **Verification command**

   ```
   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256
   ```
3. ### Retained boundary

   Checkpoint at startup, every 5 minutes by default, and orderly stop. Keep a copy elsewhere.

   **Third party checks** The later export agrees with an earlier retained length and head; rollback can be detected.

   **Verification command**

   ```
   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --checkpoint checkpoint.json
   ```
4. ### External time

   Evidence mode sends a checkpoint SHA-256 to RFC 3161 authorities (FreeTSA, DigiCert) and OpenTimestamps calendars.

   **Third party checks** A verified TSA response dates those bytes; a confirmed OpenTimestamps proof anchors them to Bitcoin.

   **Verification command**

   ```
   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca trusted-ca.pem
   ots upgrade checkpoint.ots
   ots verify checkpoint.ots
   ```
5. ### Independent witness

   Separate host, scoped read-only endpoint, fresh challenge, its own key/journal and TGW1 channel posts.

   **Third party checks** Earlier accepted heads; statuses ok, key_changed, rollback, fork, invalid and no_response.

   **Verification command**

   ```
   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/WITNESS_CHANNEL
   ```
6. ### Off-site replica

   S3-compatible copy encrypted with AES-256-GCM; Object Lock when the bucket supports it.

   **Third party checks** Restore publishes files only after journal, checkpoint and preserved-media verification succeeds.

   **Verification command**

   ```
   python -m tgwitness.replica restore --key-file KEY.json --out EMPTY_DIR
   ```
7. ### Run provenance

   Signed run receipt: source hashes, dependency versions and process context. Self-reported.

   **Third party checks** What the signing collector reported about its own execution.

   **Verification command**

   ```
   python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256
   ```

### Source and acquisition record

Read each observation together with its source identifiers and acquisition record.

[Independent witness](https://phishdestroy.io/tgwitness/docs/reference/witness/)

Local SHA-256 experiment

### Try changing record 2

The next record keeps the previously saved link. Changing the text changes record 2’s calculated hash.

Text of record 2

Record 1`h1`Starts with 64 zeroes

Record 2`h2`Includes the saved h1

Record 3`h3`Includes the saved h2

Static example: h2 covers “Meet at 11:00”. Changing that text changes h2; record 3 still references the saved h2.

**Inspect the full digests**

Saved record 2 hash

`SHA-256(e₂)`

Recalculated record 2 hash

`SHA-256(e₂)`

This sample calculates hashes, not signatures. The real verifier checks every signature and link against the trusted key.

 [Read the details](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/)

## Choose a route through the evidence

Fictional situations. Start collection before the relevant event; preserve the boundaries and gaps alongside the content.

### A channel changes payment details

Mode → events

Chosen chats → messages, edits, deletions.

Output

Observed post versions and attachments by hash.

Verification

Signed ZIP + retained checkpoint + verified TSA response.

### Messages disappear after an incident

Mode → events

Folder or whole account → all event categories.

Output

Saved originals, deletion notices and coverage with gaps.

Verification

Signed ZIP + independent witness journal.

### Investigate a shop bot

Mode → events

Investigation preset → buttons, link previews and explicit bot start.

Output

Signed interaction receipts, returned callbacks and saved profiles.

Verification

Signed ZIP; verify any dossier against the ZIP.

### A participant changes names across chats

Mode → events

Any scope → observed sender/profile metadata.

Output

Name/username history by numeric ID, “also in” links and extracted leads.

Verification

Dossier JSON checked against the signed ZIP.

### Long-running observation with an off-site copy

Mode → events

Any scope → Evidence mode and an S3 replica with supported Object Lock.

Output

Encrypted copy, retained checkpoints and timestamp responses.

Verification

Restore with the exported key, then verify without the original server.

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/investigation/)

## Hand over a checkable package

Supply the signed original, an independently retained key fingerprint, the relevant checkpoint and the verification result.

- Signed ZIP
- JSONL
- CSV
- HTML
- Checkpoint
- Run receipt
- Chat export: chat.json / chat.html
- Dossier JSON
- Password-protected AES-256 ZIP
- Separate exports for multiple accounts
- Streaming CLI: 5 GiB default limit

```
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint checkpoint.json --require evidence
```

Obtain the verifier from a trusted copy, not from the archive being checked.

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/evidence/)

## Compare the delivered artifact

Basic artifacts without added signing, timestamp or witness systems. Scripts and loggers vary by implementation; “partial” means limited to captured or visible material.

| Approach | Edits / deletions | Record signature | External time | Independent witness | Coverage / gaps | Verification without author |
| --- | --- | --- | --- | --- | --- | --- |
| Telegram Desktop export | Partial | No | No | No | No | No |
| Telethon snapshot script | Partial | No | No | No | No | No |
| Deletion logger: text log | Partial | No | No | No | No | No |
| Screenshots / web capture | Partial | No | No | No | No | No |
| TgWitness with configured extras | Partial | Yes | Yes | Yes | Partial | Yes |

[Read the details](https://phishdestroy.io/tgwitness/docs/reference/evidence/)

[Setup guide](https://phishdestroy.github.io/TgWitness/demo/guide.html?lang=en)[Dedicated account](https://phishdestroy.io/tgwitness/docs/dedicated-account/)[EVIDENCE.md](https://phishdestroy.io/tgwitness/docs/reference/evidence/)[INVESTIGATION.md](https://phishdestroy.io/tgwitness/docs/reference/investigation/)
