このページの一部は依然として英語のままです。翻訳後に英語の原文が変更されたためです。
参考文献 / 収集
Telegram · ワークフローと操作方法
パネルの日常的な運用:モード、監視カテゴリ、パラメータ、通知、エクスポート、バックアップ、および容量について。
初回接続の際は、アカウントおよびセッション形式をご利用ください。 保存されたバージョン、イベントポリシー、およびデータ欠落に関する説明については、 「収集の仕組み」をご覧ください。本ガイドでは、日常的な運用と復旧について解説しています。
管理対象のインストールには、ランチャーのほかに、、START-HERE.html、、、START-HERE.txt、が含まれ、
リポジトリへのリンクやコマンドはインストールパスに合わせて調整されています。
SSH経由でtgwitness guide --printを実行するか、tgwitness pathsを実行して
実際のデータディレクトリを特定してください。root権限でのsystemdインストールでは、プライベートな状態情報は
/var/lib/tgwitness-…に保存され、/opt/tgwitnessにはプログラムが格納されます。
管理対象の一時的なCloudflareトンネルにおいて、tgwitness tunnel offは、
ローカルパネルと収集機能は稼働したまま、外部からのアクセスを遮断します。tgwitness tunnel onは
アクセスを有効にし、tgwitness tunnel restartは新しいトンネル接続を作成します。
tgwitness openを使用すると、現在のアドレスを確認できます。明示的な停止設定は、
サービスの再起動後も維持されます。tgwitness stopは、パネルと収集機能の両方を停止します。
このページでは
オペレーターのワークフロー#
図表をテキストで記述
- 保存先と鍵の保護方法を選択してください → トークンを使用してパネルを開く
- トークンを使用してパネルを開く → ワークスペースを選択してください
- ワークスペースを選択してください → ダイレクト接続またはプロキシ接続の設定
- ダイレクト接続またはプロキシ接続の設定 → 電話番号を入力するか、ファイルまたはQRコードを選択してください
- 電話番号を入力するか、ファイルまたはQRコードを選択してください → アカウントの身元を確認し、アクセス可能なグループを選択してください
- アカウントの身元を確認し、アクセス可能なグループを選択してください → イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください
- イベントおよび添付ファイルの保存ポリシーを設定してから、監視を開始してください → エラー、アクセス、キュー、ディスクの状態を監視します
- エラー、アクセス、キュー、ディスクの状態を監視します → 独立したチェックポイントを保持する
- 独立したチェックポイントを保持する → 資料のエクスポートと検証
認証、通信接続、グループへのアクセス、および配信の完全性は、 それぞれ異なる特性です。接続ステータスが緑色であっても、すべての イベントが記録されたことを意味するわけではありません。
主鍵を共有せずに作業内容を共有する#
[その他のツール] → [アクセス] を開き、レビュー担当者やアナリストに独自のトークンを付与します。そのユーザーが 開くことができるアカウントやチャットを選択し、閲覧、エクスポート、または操作アクションを許可します。 収集の開始・停止を行うオペレーターにはワークスペース全体へのアクセス権が必要です。一方、レビュー担当者は 単一のチャットに限定することも可能です。セッション制限、有効期限、およびIPルールは、 Telegramアカウントの認証とは別個に設定されます。「アクセスと権限」を参照してください。
「Open sessions」を使用して接続を終了するか、アクセス権を無効化してすべての セッションを終了させてください。管理者コンソールでは、ワークスペースを横断して 現在のプロセスのアクティビティを一元的に確認できます。セッションを終了しても、データ収集は継続されます。
実行モード#
| モード | アクション | 動作 |
|---|---|---|
| デモ | scripts\Demo.cmd または --demo |
合成データ;実際のアカウントとの連携は無効化されています |
| 所見 | 監視を開始する | 選択した情報源について、配信された更新情報を記録します |
| 履歴のスナップショット | チャット → チャット操作 → 履歴を読み込む | 最大500件の最新メッセージを保存します。過去の変更履歴のすべてを復元することはできません。 |
| 一時停止 | 観察の一時停止 | データを保持したまま、収集を停止し、キューに格納されたジョブを保留にする |
| レビュー/引き継ぎ | エクスポート | ZIP、JSONL/CSV/HTML、チェックポイント、処理確認書、およびタイムスタンプのリクエスト |
| 複数のアカウント | ワークスペース、または上部の「+」ボタン | 1つのプロセス内で、いくつでも個別のワークスペースを作成できます |
ローカルデモへのアクセスは、手動でトークンを入力することなく自動的に開始されます。これは、 隔離された 合成デモへの直接ループバックアクセスにのみ有効な、プロセス存続期間中の機能を使用しており、メインパネルのトークンは開示されません。実際のワークスペースおよびリモート またはプロキシ経由のデモアクセスでは、トークン認証が維持されます。デモへのアクセスによって、Telegramの権限が付与されることはありません。
監視カテゴリ#

[その他のツール] → [ソース] → [記録] → [保存する変更の選択] で、新規メッセージ、編集、 削除通知、リアクションの更新、メンバーシップイベントを個別に選択します。デフォルトでは すべてのカテゴリが保持されます。[メッセージ、編集、削除] を選択すると、元のコンテキストが 保持され、個別のリアクション/メンバーの更新は無効になります。[表示されているすべてのアクティビティ] を選択すると、 5つすべてが復元されます。プリセットで形式を変更し、[記録設定を保存] を押して適用します。
保存されたポリシーは、そのワークスペース内で選択されたすべての情報源に適用されます。その他の ワークスペースは、それぞれ独自の設定を維持します。実際の変更ごとに、署名付きの変更前・変更後の 値が記録されます。また、現在のポリシーは、処理レシートおよび観測 開始記録にも含まれます。カテゴリを無効にしても、それ以前の観測データは削除されません。再有効化 しても、見逃された変更は復元されません。 このバージョンでは、グループごとのカテゴリ上書き機能はありません。
以前のコンテンツが重要な場合は、新しいメッセージの記録を有効にしておいてください。削除通知では、 一度もキャプチャされなかったテキストを復元することはできません。運用・カバレッジ記録やその他のグループ サービスイベントは常に保持されます。 明示的な履歴スナップショットは、 リアルタイムのカテゴリ選択とは別のものであり、サービスメッセージが含まれる場合があります。これらの設定は、 それ以外にはキャプチャされたTelegramオブジェクトに埋め込まれた反応やメンバーのメタデータを 削除するものではありません。
履歴のスナップショットは、一時停止中に添付ファイルをキューに入れる場合があります。処理を行うには、監視を開始してください。 キューに入れられたからといって、ダウンロードされたわけではありません。利用できない元のファイルは、 新しい編集版に置き換えられず、結果は個別に記録されます。
「ロック」操作を行うと、ブラウザへのアクセス権と秘密フィールドはクリアされますが、データ収集は継続されます。 タブを閉じても、プロセスは実行されたままとなります。Pythonプロセスまたはサービスを停止すると、 ブラウザの状態にかかわらず、データ収集は停止します。
追加のワークスペースは、その ジャーナルおよびケースボードのメモを含む、署名済みのZIPまたはASiC-Eコンテナが完全にダウンロードされた後に削除できます。アーカイブの準備だけでは 不十分です。セットアップイベント以外の記録や、ダウンロード後に追加されたメモがある場合、「削除」 ボタンは利用できません。
パネルがファイル自体を受信した場合、すべての
バイトの受信が完了してから初めてエクスポートをカウントし、その後、そのサイズを `POST /api/exports/{id}/received` に報告します。途中で中断された
ダウンロードはカウントされません。ブラウザの保存ダイアログ(ファイルシステムアクセス)を使用する場合、パネルは
ファイルの書き込みと閉じ処理が完了した後に報告を行います。 保存ダイアログがない場合、パネルは受信したファイルをブラウザの
ダウンロード機能に引き渡すため、例えば保存ダイアログが
キャンセルされた場合など、ブラウザがファイルを保持したかどうかを確認できません。この場合、パネルはファイルが保存されたことではなく、ダウンロードが開始されたことを報告します。 ブラウザが
独自にダウンロードするファイル(パネルのブラウザバッファ容量を超えるエクスポート)や、
別のHTTPクライアントによるダウンロードは、サーバーがレスポンス全体を送信した時点でカウントされます。
オペレーティングシステムやリバースプロキシはレスポンスを数メガバイト単位でバッファするため、こうした
ダウンロードの場合、サーバー側では終了間際の途切れを検知できません。 パネルにファイルが保存されたと表示されない限り、
削除する前にダウンロードしたファイルを確認してください。グループエクスポートは、
準備完了直後にダウンロードされた場合にそのアカウントとしてカウントされますが、「準備済みのエクスポート」から再度ダウンロードした場合はカウントされません。
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).
追加のワークスペースを削除すると、そのコレクターが停止し、ローカルデータが削除されます。
ロックされたファイルやファイルシステムのエラーにより削除が中断された場合、パネルには失敗が報告され、
そのワークスペースは「利用不可(DeletionPending)」としてリストに残ります。そのファイルを保持している
プログラムを閉じてから、削除を再試行してください。 TgWitnessを再起動しても、そのワークスペースは停止したままとなり、
部分的に削除されたジャーナルや鍵は再作成されません。削除が成功したことは、
ディレクトリが削除された後にのみ記録されます。別途エクスポートまたはバックアップされたコピーは、
それぞれの保存ポリシーに従って保持されます。
通知#
[設定] → [通知とオフサイトコピー] → [通知先]、または [その他のツール] → [エクストラ] → [通知] → [設定] を開きます。TgWitnessは Appriseを使用して、Matrix、Telegram、Discord、Slack、ntfy、電子メール、およびその他の 対応サービスにアラートを送信します。1つのワークスペースに複数の通知先を追加できます。
- 1行につき1つのApprise送信先URLを入力してください。ご利用のサービスに応じた サービスカタログおよびURL形式をご使用ください。
- 「通知を送信」をオンにしてから、「問題アラート」、「監視対象の チャットでの変更」、および「日次サマリー」を選択してください。サマリーの時刻はサーバーの時刻に基づきます。
- 削除および編集された メッセージの保存テキストをアラートに含めたい場合は、「短い抜粋を含める」をオンにしてください。
- 「保存」通知をタップし、次に「テスト送信」をタップして配信状況を確認してください。
独自の受信先を設定する場合は、AppriseのJSON Webhookをご利用ください。
例えば、jsons://notify.example.org/tgwitnessはHTTPS経由でその
エンドポイントにJSONを送信します。これは架空の例ですので、実際の受信先に置き換えてください。
宛先や設定は、選択されたワークスペースに属します。変更通知は、 新たに追加されたチャットを含め、監視対象のソースを網羅しています。トップバーのベルアイコンには、 最近の問題やチャットの変更も一覧表示されます。
デモでは、通知設定は表示されていますが、送信機能は無効になっています。実際のワークスペースで 配信設定を行ってください。通知は、そのワークスペースのDirect、SOCKS5、または HTTPルートを使用します。MTProxyでは通知を転送できません。SMTPなどのHTTP以外の宛先には、 ダイレクトルートが必要です。
パネルレイアウト#

ジャーナルには、観測結果、検索、およびフィルタが表示されます。編集を行うと、記録された各バージョンが表示され、 削除を行うと、利用可能な場合は削除前のコンテンツが表示されます。出典が不明な場合は、その旨が明示されます。 集計データは「概要」で確認でき、取得の詳細についてはローカルガイドに記載されています。
編集されたメッセージを開くと、文中の差分または並べて表示でバージョンを比較できます。元データには保存されたフィールドが表示されます。隠しリンクやボットボタンへの変更は個別に表示されます。添付ファイルのプレビューを開くと、保存された画像、音声、または動画を確認できます。ダウンロードボタンを使用すると、保存されたオリジナルファイルを取得できます。
Live は、レコードの到着に合わせてジャーナルとチャットを更新します。確認中は一時停止するか、準備ができたときに新着イベントボタンを使用してください。その間も収集は継続されます。Ctrl/Cmd+K でパネルのアクションを検索したり、ジャーナル内を検索したりできます。
その他のツール → 「ソース」には、観測範囲(選択したチャット、Telegramのフォルダ、またはアカウント全体 )、アクセス可能なあらゆる種類のチャット、優先度スターが付いた選択済みソース、添付ファイル および再確認の設定、履歴のスナップショットが含まれます。非公開ソースは、公開リンクのないダイアログ/ID によって選択されます。アクセスステータスは、恒久的な権限ではなく、直近の確認状況を表します。
ソースをフィルタリングしてチェックボックスを選択し、まとめて有効化、一時停止、または優先としてマークできます。利用可能なチャットリストでは、選択した項目を追加は選択した項目を使用し、一致するすべてを追加は現在の検索条件とタイプフィルターを使用します。
「チャット」→「ユーザー一覧」には、メッセージが保存されているすべてのユーザーが表示されます。チャットでユーザープロファイル機能が有効になっている場合、 クリックするとそのユーザーのプロファイルが開き、ジャーナル記録へのリンクが表示されます。
その他のツール → エクストラ → 「独立したウィットネス」は、読み取り専用のウィットネストークンを作成し、各ウィットネスが最後に確認した日時を表示し、 ウィットネスを実行するためのコマンドとオプションを提供します(独立したウィットネス)。
その他のツール → 「パラメータ」には、他のページに記載されていないワークスペースのすべての制限とペースが記載されています:
読み込まれるダイアログの数、チャットリストが再読み込みされる頻度、ハートビートおよびチェックポイントの
間隔、起動バッファ、再チェックがリクエストを分散させる方法(最初の遅延、チャットごとの
パスごとのチャット数、チャット間の休止時間、復元および再リクエストされたメッセージ数)、ディスク予約容量、ダウンロードのタイムアウトおよび
再試行、ユーザープロファイルの検索条件(独自の正規表現を含む)、
通知のサイズと頻度、スナップショット、ZIPおよびブラウザダウンロードの制限、Telegram
クライアントのタイムアウトと再試行。各フィールドには範囲とデフォルト値が表示され、変更されたフィールドは
マークされ、1つずつまたはまとめて復元できます。 すべての変更は、変更前後の値とともに
parameters.changedとして記録され、監視開始記録には
適用中の値が記載されます。値は次回使用時から適用され、クライアントのタイムアウトおよび再試行は
次回の接続時から適用されます。再確認間隔、添付ファイルの種類とサイズ、証拠およびオフサイトコピーの
間隔は、それぞれのページに表示され、プリセットだけでなく、その範囲内の任意の値を設定できます。
上部バーのベルアイコンには、監視対象のチャットにおける最近の問題や変更が一覧表示されます。未読のものは、 既読としてマークされるまでカウントされます。変更はチャットごとおよび時間ごとにグループ化され(「削除 12件、 編集 1件、見つかりませんでした 0件」)、ログアウトやディスク容量不足などの問題は、 チャットがどれほど活発であってもリストに残ります。
その他のツール → アカウント登録 は電話番号入力欄から始まります。「続行」 をクリックすると直接 コード入力画面に進み、API 認証情報が未入力の場合にのみ入力が求められます。QR コードおよびファイルインポートは 別のタブで利用可能です。保存された API 認証情報は、そのワークスペース内でのみ再利用されます。 入力画面にはサイドバー、統計情報、設定説明文はありません。「設定」 アイコンをクリックすると、API、プロキシ、ストレージ、および追加アカウントの設定画面が開きます。新しいワークスペースを開くと 初期設定画面 が表示されます。サインイン後、保存済みのソースと記録を含むワークスペースが開くと、「チャット」 画面が表示されます。 ルートを変更するには、観測を一時停止する必要があり、未完了のログインはキャンセルされます。既存の ジャーナルを、別のTelegramアカウントに自動的に再紐付けすることはできません。
エクスポート機能はジャーナルの整合性をチェックし、ポータブルなファイルを生成します。そのワークスペースIDは ダウンロード用CLIに渡すことができます。各エクスポートは完全なジャーナルプレフィックスを固定します。それ以降の イベントは、次のエクスポートに含まれます。検索フィルターはパッケージの範囲を変更しません。 詳細な署名およびカバレッジ情報は、「検証と証拠」に記載されています。
このパネルでは、「Collector」の健全性状況として、コレクターの状態、キュー入りまたは失敗したメディア、最も古い保留中のメディア、空き ディスク容量、リクエストの一時停止、およびアクセスが未確認のソースを報告します。 これらの詳細は、初期状態では折りたたまれており、「アカウント」画面では非表示になっています。セットアップ カードには、次の手順(アカウントの接続、ソースの選択、または監視の開始)が表示されます。 アカウント一覧は読み込み時のスナップショットであり、 選択されたワークスペースは定期的に更新されます。これはマルチプロセス型のSLAモニターではありません。
UIはローカルのアセットを使い、ソースのコンテンツをテキストとして描画します。デスクトップと幅の狭いChromiumレイアウトはテスト済みです。
導入環境#
| 環境 | インストール | 検証状況 |
|---|---|---|
| Windows PC/サーバー | Python 3.11 以上、scripts\Setup.cmd/Start.cmd、プライベートデータディレクトリ | Windows/Python 3.12環境でローカルに検証済みです。 |
| Linuxサーバー/VPS | Pythonのvenv、専用サービスユーザー、HTTPS/SSH | コード、CI、および systemd の例が提供されていますが、このホスト上では実行されていません。 |
| macOS | Pythonのvenv、フォアグラウンドプロセス、またはユーザーエージェント | launchd の使用例を掲載しています。別途、インストール状況の確認が必要です。 |
| Docker/Compose | 永続ボリューム、ワーカー1台 | 定義とCIランタイムチェックが提供されています。ローカル環境ではDockerは利用できません。 |
| スマートフォン用ブラウザ | 稼働中のサーバー上の保護されたパネルに接続してください | Chromiumのナローレイアウトでの動作確認済みです。コレクターはiOS/Androidでは動作しません。 |
移植性が高いため、クラウドサービスやフロントエンドの構築は必須ではありません。ただし、各ターゲットには 互換性のある Python/crypto 依存関係、ローカルディスク、およびネットワークアクセスが必要です。 DEPLOYMENT.md およびサービステンプレートをご参照ください。
ワークスペースは、CPU、メモリ、およびイベントループを共有します。プロセスの分離を行うには、個別の インスタンス、ポート、データディレクトリ、およびアカウント認証を使用してください。別々のインスタンス間で統一された 管理パネルは存在しません。複数のワーカーを1つのデータベースに割り当てないでください。
起動時の確認とエクスポート#
準備済みの環境を起動する前に、python start.py --checkを実行してください。機械可読なチェックを行う場合は--jsonを
追加するか、指定した--data-dir、--host、--portを指定してください。
このコマンドは、Telegramへのログインやジャーナルの作成を行わずに、前提条件をチェックします。
アプリケーションの起動時にジャーナルの検証が実行され、キャプチャの準備状況が
パネルに表示されます。ポートが使用中の場合は、単に既存のインスタンスが存在している可能性があります。
File System Access API をサポートするブラウザでは、書き込み可能な ストリームを通じてエクスポートデータが保存されます。その他のブラウザでは、最大 128 MiB までがバッファリングされます。より大規模な エクスポートや、ファイルストリーミングに対応していないブラウザでは、ストリーミング CLI をご利用ください:
python -m tgwitness.download --token-file data/live/panel-token.txt --out evidence.zip
子ワークスペース用のエクスポートから「--profile ID
」を追加してください。リモートアクセスには「--url https://server
」を使用してください。プレーンHTTPは、ループバック先でのみ受け入れられます。トークンは
ファイルから読み込まれ、ヘッダーとして送信されます。画面に表示されたり、URLに含まれたりすることはありません。リダイレクトは
拒否されます。既存の出先は上書きされません。 転送に失敗した場合は、
その一時的な部分ファイルが削除されます。報告される SHA-256 は転送チェックサムです。署名付き
ZIP ファイルについては、信頼できるフィンガープリントまたはチェックポイントを用いて別途検証してください。
バックアップ、復元、および中断について#
- 監視を一時停止し、プロセスを完全に終了させてください。
- データディレクトリ全体をコピーしてください:データベース、WAL/SHM(存在する場合)、メディア、
credentials.enc、signing.enc、network.enc、Vaultキー/メタデータ、トークン、 チェックポイント、およびすべてのprofiles/ディレクトリです。 - 外部キーモードの場合、マスターキーを別途保管し、各
vault.external.jsonを保持してください。新しいキーを生成しても、以前の秘密鍵を復元することはできません。 - 宛先が停止している間に復元を行い、元のキーを設定し、 アクセスを制限し、再開前に整合性を検証してください。
- ダウンタイムと検証結果を記録する。ダウンタイムは記録された空白期間として残る; 履歴スナップショットは、その直後の状態を追加する。
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.
Four things are protected differently:
| 概要 | 保護 |
|---|---|
| パスワードなしでファイルをエクスポートする(デフォルト設定) | 署名されているため変更は検出できます。エクスポートを暗号化するにはパスワードを設定してください |
| パスワード付きでファイルをエクスポートする | パスワードを設定した場合、エクスポートされたデータは変更されることなく、7-ZipやWinRARで開くことができるWinZip AES-256 ZIP形式で保存されます。パスワードは保存されません(証拠の取り扱い)。 |
| ジャーナルデータベースおよびディスクに保存された添付ファイル | 暗号化されたディスクまたはボリュームとフォルダーのアクセス権 |
| Telegramのセッションと署名鍵 | データディレクトリ内で暗号化されています(credentials.enc、signing.enc、network.enc)。 |
フルサービスのバックアップとは、前述の停止されたデータディレクトリのことであり、エクスポートではありません。
両方とも、保護されたストレージと意図的な転送メカニズムを使用してください。一時的なサーバーエクスポートは各ワークスペースの
temporary-exports/に保存されます。完了したレスポンスはクリーンアップされ、中断されたエクスポート
ファイルは、そのワークスペースのインスタンスロックが保持されている間に、次回の起動時に削除されます。
接続復旧イベントの後、コレクターは 保存された更新位置から、見逃した更新を要求します。永続的なメディアジョブとTelegramの更新位置は再起動後も維持されます。 証拠形式を参照してください。
容量と保存期間#
デフォルトの制限(すべて「その他のツール」→「パラメータ」で変更可能):最初の1,000個のダイアログ、スナップショットあたり500件のメッセージ、
4 GiBの非圧縮署名付きZIPコンテンツ(より大きなアーカイブには
verify.py --max-gib Nが必要)、および128 MiBのブラウザ用フォールバック。「その他のツール」→「ソース」→「記録」→「添付ファイル」で、添付ファイルは種類ごとに1~2,000 MiBを
消費します。ダウンロードCLIのデフォルト転送量は5 GiBです。利用可能なディスク容量が
下限となる場合があります。 ジャーナル、メディア、WAL、一時的なエクスポート、およびバックアップ用にスペースを確保してください。
エクスポートでは、Composeの512MiBの/tmpではなく、データボリュームが使用されます。
グループ数のカウントだけでなく、イベント/秒、キューの経過時間、メディアバイト数、ディスクレイテンシを測定してください。 ライブ配信は、稼働中のコレクター上で測定されます。 自動的な保持期間満了による削除機能はありません。ジャーナルの末尾を削除すると、 保持されているチェックポイントとの関連性が無効になります。
優先再確認はすでにあります。スター付きのソースはデフォルトで15分ごと、それ以外は6時間ごとに再確認されます(再確認の階層を参照)。パスワード保護付きエクスポートは上記のとおり動作します。範囲を限定したアクセスはアクセスと権限に記載されています。READINESS.md、LIVE_ACCEPTANCE.md、VERIFICATION.mdも参照してください。