TgWitness / ドキュメント

テスト済みの内容 →

参考文献 / 収集

Telegram · 機能と対象範囲

TgWitnessの現在の収集モデル、マルチアカウントワークフロー、エクスポート機能、および運用上の制限事項。

TgWitness / ドキュメント · プロジェクト参照

プロジェクト参照

TgWitnessは、接続されたアカウントからアクセス可能なTelegramの会話内容を保存し、 観測された変更を記録し、検証可能なエクスポートデータを生成します。このリファレンスでは、 収集モデル、現在のワークフロー、およびその範囲について説明します。

このページでは

スタンドアロンアプリケーション#

TgWitnessには、独自のインストール手順、データディレクトリ、およびリリースライフサイクルがあります。同梱の Webインターフェースでは、設定や確認を行うことができ、エクスポートされた記録は単独でも利用可能です。

利用者は自身のアカウントを連携させ、各アカウントで表示可能な情報源を選択することで、 保存された観測ジャーナルを取得します。パネルには、コンテンツ、保存された変更内容、観測の 出所、および既知の欠落情報が表示されます。別の調査員が、エクスポートされた資料を検証することができます。

このパネルでは、アカウントの認証、ソースへのアクセス、コレクターの 活動、および記録範囲を区別しています。メッセージ数が少ない期間や接続の問題を 評価する際は、これらの状態を総合的に確認してください。

共同調査#

管理者は、ワークスペースや 個々のチャットを範囲とするアクセストークンを発行でき、アクションごとの権限、IP制限、有効期限、ログイン制限、 およびセッション制御を設定できます。読み取り専用のレビュー担当者は、 Telegramの認証やメインパネルのキーを受け取ることなく、ケースを閲覧できます。 チャット限定のアクセス権は、 アカウント全体の設定やジャーナル全体のエクスポートとは独立して管理されます。

自動MTProxyは、4つの公開ソースまたは オペレーターカタログから、Telegramの有効なルートを維持します。IPモードによって、 障害発生時に別のプロキシを待機するか、明示的に許可された直接ルートを使用できるかが決定されます。 外部HTTPリクエストには、個別のルートと無効化スイッチが用意されています。

アーカイブツール#

履歴の取得、アーカイブの検索と分析、 読み取り専用MCP、ローカルOCR/文字起こし、および 送信用Webhookは、バージョン0.7.1から実装されています。分析レポートと認識されたテキストは、 キャプチャされたイベントとは別個に保持されます。

Case Board は、ワークスペース内にソースにリンクされたブックマーク、引用、メモ、および コレクションを追加します。レポートコンストラクタでは、 資料やセクションを選択し、サポートされている HTML/PDF エクスポート用に 8 種類のデザインから 1 つを選択します。

オプション機能#

日常的な設定は、「アカウント」→「ソース」→「観測」の順で行います。「その他のツール」→「エクストラ」は、 独立したキャプチャ、保存、目標および保護レベル、通知、 証拠およびバックアップ、常時稼働サーバー、Telegramウィットネスボット、コードチェックのための 独立した設定画面です。各項目は、設定を表示する前にその利用可能性と要件を明示します。カードを選択すると 手順が表示されますが、サービスの登録や開始は行われません。

ボットのセットアップには、読み取り専用アクセス権の作成、公開設定の選択、および ウィットネスホストでの起動という3つのステップがあります。ネットワークおよび公開オプション、既存の接続、 検証コマンドは、必要に応じて開示されます。 ダウンロードされた構成は、 実行中のウィットネスとは別個のものです。追加機能の切り替えを行っても下書きは保持されますが、アカウントの変更やロックを行うと、 一時トークンとフォームはクリアされます。組み込みのガイドには起動手順が含まれています。「Exports」から開く 「GitHub Actions」は、あなたの フォークからピン留めされたコレクターを起動し、1回のチャットをキャプチャして、ワークフローの来歴を含む暗号化された引き継ぎデータを生成します。

プロトコルおよび非公開の情報源#

MTProtoはTelegramのプロトコルであり、TelethonはTgWitnessがMTProtoと 通信するために使用するPythonライブラリです。これらは別々の接続方法ではありません。「Collection」はMTProtoを使用し、 オプションの「witness」はBot APIを通じて署名付きチェックを公開します。

各ワークスペースには、独自の認証済みクライアントとアカウント更新ストリームがあります。TgWitnessは、 設定されたソースから観測データを選択し、履歴のスナップショットやメディアのダウンロードなどの機能については、 個別に明示的なリクエストを行います。

非公開の情報源には、公開ユーザー名は必要ありません。Telegramのピアタイプと数値IDが 識別子となります。タイトルやユーザー名は変更される可能性があります。アクセスは、既存の メンバーシップおよび権限によって決まります。TgWitnessは、情報源に自動的に参加したり、 参加承認を迂回したりすることはありません。別のアカウントからのアクセスハッシュは、汎用的なアクセストークンではありません。

収集モデルでは、参加前の非公開履歴、参加者/管理者の 役割、セッションの失効、権限の削除または変更、グループからスーパーグループへの 移行、トピック/フォーラム、関連するディスカッション、チャンネルの識別情報、および利用できない 添付ファイルなどを考慮する必要があります。すべての組み合わせについて、実稼働環境での検証が完了しているわけではありません。

ソースの可視性は、コレクターの起動時に確認されます。範囲内の ダイアログ結果からソースが欠落している場合、それはアクセスが確認されていないことを意味し、削除が証明されたわけではありません。1つのソースが 利用できない場合でも、他のアクセス可能なソースの監視には支障がありません。招待 リンクや実際のセッションを、公開用フィクスチャに決して記載しないでください。

複数のアカウント#

このパネルは、任意の数のワークスペースに対応しており、各ワークスペースには以下の機能が備わっています:

  • 認証、暗号化された保管庫、および接続経路。
  • SQLiteジャーナルおよびEd25519署名用ID。
  • 選択された情報源、メディアキュー、およびキャプチャ設定。
  • 監視状態、エラー、チェックポイント、およびエクスポート機能。

表示されているワークスペースを切り替えても、別のコレクターの動作は停止しません。ワークスペースをまたいだアカウントの 重複認証は拒否されます。すでに1つのTelegram アカウントに紐付けられているジャーナルを別のアカウントに再割り当てすることはできませんが、同じアカウントへの再接続は可能です。 これにより、アカウントの識別情報および関連するメッセージIDの範囲が保持されます。

本アプリケーションでは、ワークスペースの数に制限はありません。各ワークスペースは、共有の Python プロセスおよびイベントループ内で、 接続監視、メディアのダウンロード、再チェック、新規チャットの取り込みを行う独自のコレクター タスクを実行します。スループットはワークロードによって異なります。 プロセスの分離を行うには、別々のインストール、ポート、データディレクトリを使用してください。

各アカウントに、アクセス可能なソースを割り当ててください。異なるアカウントが同じ グループを監視している場合でも、その監視記録は分離されたままとなり、元のソースが保持されます。1台のオペレーター管理マシン上の2つのアカウントは、 2つの独立した「証人」とはみなされません。グループのエクスポートでは 、個別に署名されたワークスペースのZIPファイルと、それらの ワークスペースID、ハッシュ、および署名鍵のフィンガープリントを含む署名済みファイルリストがバンドルされます。 各ジャーナルは独自の 境界を維持します。ケースノートや分析ツール内で、これらのソース参照情報を保持したまま、 ワークスペースを横断した統合タイムラインを構築します。

キャプチャと出典明記#

「Sources」では、新規メッセージ、編集、削除、リアクション、 およびメンバーシップについて、アカウントごとの設定切り替えが可能です。プリセットでは、すべてのカテゴリ、またはメッセージ/編集/削除のいずれかを保持します。 このポリシーはワークスペースで選択されたグループに適用され、再起動後も維持され、 変更前後のデータで署名されます。デフォルトではすべてのカテゴリが保持されます。 カテゴリを無効にしても 過去の記録は削除されません。また、再度有効にしても、記録されなかったイベントは復元されません。 運用記録、その他のグループサービスイベント、および明示的な履歴スナップショットは 別個に扱われます。キャプチャされたTelegramオブジェクトは、 個別の更新設定にかかわらず、埋め込まれたメタデータを保持する場合があります。現時点では、グループごとのカテゴリ上書き機能はありません。

資料 現在キャプチャ中 境界
メッセージ テキスト、ピアID/メッセージID、送信者のメタデータ、返信、および元の更新エンベロープ コレクターが署名した、アカウントから閲覧可能な観察記録として保存されます
編集 新たに観測されたバージョン、以前にキャプチャされたバージョン、受信時刻、および提供された編集日時 メッセージの更新および利用可能な管理ログエントリは、それぞれの帰属フィールドを保持します。
削除 Telegram通知、受信時刻、および以前にキャプチャされたコンテンツ アクターおよびソースアクションの時刻は、別の管理ログレコードによって提供されている場合に保持されます。
アカウントレベルの削除通知 元の通知;解決済みの記録には、保存されたチャットおよび相関付け手法が含まれます 対象範囲内に、以前に保存されたプライベートチャットまたは通常グループの照合結果が正確に1件存在する必要があります。その他のIDは「deletion.unscoped」のままとなります。チャンネルおよびスーパーグループのIDは、この照合の対象外となります。
反応 配信されたカウンターと、確認可能な最近のID 利用可能なリアクターの完全なリストを確認するには、別途照会が必要です。チャンネルによっては身元が非公開となっている場合があります。
メンバーシップ サービスに関するお知らせおよび参加者への最新情報の配信 可視性は役割とチャットの種類によって異なります。メンバーシップは配信されたイベントから報告されます。
管理者の操作 チャンネル/スーパーグループのチャットエクスポートに含まれる、関連する配信済み更新情報および管理ログのスナップショット エクスポート機能は、エクスポートを行う管理者アカウントが利用可能な場合にログを読み取ります
添付ファイル オリジナルバージョンの記述、ダウンロードされたバイト数/SHA-256、および試行結果 元のバージョンは保持され、後のバージョンに置き換えられることはありません
沿革 現在表示されているメッセージの明確なスナップショット ライブ記録は以前のバージョンと削除通知を保持します
コレクタープロセス 開始/停止、ハートビート、エラー、設定、スコープ、および署名付き実行受領証 ローカルインベントリ;GitHubおよびTDXによる独立した環境チェックの追加

インターフェースでは、ソースイベントで指定されたアカウント名が使用され、観測された 名前やユーザー名はそのまま保持されます。イベントに実行者が記載されていない場合、レポートではそのフィールドは未指定のままとなります。

容量とTelegramの制限#

容量はデプロイメントごとに決定されます。これは、1秒あたりのピークイベント数、添付ファイルの量とサイズ、追加の RPC、アクティブなアカウント数、ディスクのレイテンシ/空き容量、ネットワーク状況、Telegramの制限、 許容可能な遅延、およびキューの深さによって異なります。

Telegramは、パッシブ配信とアクティブなショートポーリングを区別しています。その更新 ドキュメントでは、オープンな チャンネル/スーパーグループに対する追加のupdates.getChannelDifference呼び出しについて説明しており、同時にショートポーリングを行う ソースは最大10個までとすることを推奨しています。これはショートポーリングに適用されるものであり、選択されたグループの数は別途設定されます。

モード 目的 ステータス
標準的な観察事項 選択した情報源からの更新情報を記録します 実装済み
優先度の高い再確認項目 スター付きソースは独自に設定可能な間隔を使用し、各範囲指定再チェック処理において優先されます。 履歴およびメッセージのクエリ機能を実装

優先度スターにより、これらの再チェックが制御されます。追加の `updates.getChannelDifference ` によるショートポーリングは、独立したユーザーモードとしては公開されていません。

FloodWaitを無視したり、追加アカウントからの容量を線形と仮定したりする ような、恣意的な高頻度ポーリングは有効なサイジングモデルではありません。デフォルトの制限は、 リストされた最初の1,000件のダイアログ、履歴スナップショットあたり最大500メッセージ、 収集ファイルの種類ごとに1~2,000 MiB、および4 GiBの非圧縮署名付きZIPコンテンツです。各 制限はワークスペースごとに変更可能で、ファイルサイズは [More tools] → [Sources] → [Recording] で、その他の項目は [More tools] → [Parameters] で設定します。 エクスポートには、イベント数の固定上限はありません。 ブラウザのフォールバックは、デフォルトで128 MiBに制限されています。ストリーミングCLIには設定可能な 転送制限があり、デフォルトは5 GiBです。

信頼性と復旧#

実装されている機能には、SQLite WAL/同期トランザクション、メッセージ およびメディアジョブの原子的な書き込み、永続的なジョブと再試行の遅延、オリジナルバージョンの記述子、 再試行回数の制限;永続化されたメディアのFloodWait;テキストイベントの ネットワーク待機時間外でのメディアダウンロード;後続の書き込みが継続中の安定プレフィックスによるエクスポート;設定および 監査記録の原子性;ログイン置換失敗後の有効な認証情報の保持; 破損した追加ワークスペースの隔離;明示的な再接続試行;明確な 認証喪失の報告;および単調時計を用いた実時間変更検出などが含まれます。

アカウントおよびチャンネルの pts/qts/seq は保存され、再起動後も復元されます。また、監視対象のチャットは 定期的に再確認されます。証拠の形式については、こちらをご覧ください。位置情報を 定期的に保存することは、ジャーナルの受諾に対するアトミックかつロスレスな確認ではありません。

各プロセスの開始時には、前回のヘッドとオフライン境界が記録されます。現在の履歴は ギャップの修復として扱われません。Telegramの差分保持容量には限りがあり、 differenceTooLongでは消失したコンテンツのすべてを復元することはできません。復元不可能なギャップは、 後の履歴スナップショットが成功した場合でも、明示的に残しておく必要があります。

証拠モデル#

各イベントには、シーケンス、ローカルUTC観測時刻、提供されている場合は送信元時刻、 種類、送信元、提供されている場合はアクター、元のペイロード、前回のハッシュ、および署名が記録されます。 メッセージの観測データには、コレクターアカウントおよび実行コンテキストも保持されます。

署名付きプロセスレシートには、ランダムな実行ID、TgWitness/Python/OSの依存関係 バージョン、ソースファイルのSHA-256値および集約フィンガープリント、初期アカウント、 スコープおよび設定、UTC/単調な測定値、ならびに直前のジャーナルヘッダーが含まれます。 設定の変更、起動/停止、およびエラーは、同じジャーナルに記録されます。チェックポイントは、 起動時、監視中の5分ごと(変更可能)、および正常な停止時に保持されます。 保持されたローカルチェックポイントにより、以前のジャーナルプレフィックスへのロールバックを検出することが可能です。

仕組み 本ツールが実現すること
ファイルの SHA-256 バイト数が既知のダイジェストと一致しています
イベントハッシュチェーン 既知の境界を基準とした記録の順序付け/関連付け
Ed25519 特定の鍵による署名
独立して保持されているチェックポイント 後続の資料は、維持された境界と一致しています。
プログラムファイルの測定 収集ツールによる測定ファイルに関する自己報告
有効な独立したTSAの回答 明示的な信頼仮定の下における、TSA時刻ごとの特定のバイトの存在

RFC 3161 リクエストの作成と応答の検証は OpenSSL なしで実装されています。証拠モードでは、チェックポイントのハッシュを設定済みのタイムスタンプサービスにも送信します。独立した時刻の裏付けを得るには、発行機関の応答を保存して検証してください。TIMESTAMP.md を参照してください。

チェックポイントを個別に保持し、署名鍵へのアクセスを管理し、転送 記録を保持し、信頼できるソフトウェアを使用してエクスポートを検証します。検証の範囲 では、これらのチェックが互いにどのように補完し合うか、およびどのような信頼の前提が適用されるかが説明されています。

エクスポート、導入、および引き継ぎ#

署名付きZIPファイルには、元のJSONL、CSV、HTML、保存された添付ファイル、ハッシュ、 署名付きマニフェスト、および利便性を考慮した検証ツールが含まれています。これは1つのワークスペースと、固定された完全な ジャーナルプレフィックスを対象としています。パネル検索フィルターによって、記録が黙って削除されることはありません。 秘密鍵、 トークン、およびTelegramのセッションは除外されますが、元の観測データには依然として 個人情報やTelegramのメタデータが含まれている可能性があります。

ZIPダイジェスト、信頼できるフィンガープリント、チェックポイント、処理受領記録、および引き継ぎ記録は、 それぞれ個別に保持してください。検証対象のZIPファイルに含まれているという理由だけで実行可能コードを信頼するのではなく、 信頼できる環境から取得した検証ツールを使用してください。

ブラウザインターフェースは、Node.js、CDN、外部フォントを必要とせず、ローカルで動作します。1つの オペレータートークンでインストールを制御します。リモートアクセスには、HTTPSまたはSSHトンネルが必要です。 ネイティブのPythonおよびコンテナ定義が提供されており、 deploy/ディレクトリ下にサービスの例が掲載されています。実行されたプラットフォームチェックは別途一覧化されています。

デフォルトのワークスペースはデータルートを使用します。追加のワークスペースはprofiles/<id>/を使用します。 バックアップを行うには、プロセスを停止させ、完全なデータおよび鍵セットが必要です。証拠用ZIPファイルは アプリケーションのバックアップではありません。シークレットについては、新しいデータ ディレクトリ用に外部のマスターキーを使用できます。ジャーナルおよびメディアの暗号化は、オペレーターのディスクまたはボリュームによって提供されます。 CONNECTION-SECURITY.md および OPERATIONS.md を参照してください。

安定版のリリース基準#

安定版がリリースされるまでは、次のように補足してください:

  1. 実際のプライベートグループ、スーパーグループ、フォーラム、チャンネルにおいて、メンバー/管理者の役割や 非表示/表示の履歴(ログイン/2FA、権限の取り消し、アクセス権の喪失を含む)を記録します。
  2. 既知の行動に対する、編集、削除、リアクション、メンバーシップ、およびメディアの監視を行います。
  3. プロセスのクラッシュ/ホストのクラッシュ、ディスク障害/ディスク容量不足、有効期限切れのファイル参照、FloodWait、 ネットワーク切断、ファイルの破損、およびデータベースのロールバック。
  4. 測定された遅延、キュー、メモリ、ディスク容量を考慮した、継続的なマルチアカウント利用。これには、 静的なソースと動的なソースの両方を併せて含みます。
  5. MTProtoの状態遷移とジャーナルの受入の間に中断が生じました。
  6. 対象のOS/コンテナ環境へのクリーンインストール、およびバックアップと復元の検証が行われています。
  7. セキュリティ、署名、および帰属・証拠に関する主張についての独立した検証。

パネルのアクセス範囲については、「アクセスと権限」で説明されています。バージョン0.6以降、TgWitnessは ACCOUNTS.mdに記載されている、範囲限定の単一アカウントTDataおよびアカウントファイルのインポートをサポートしています。 公開前にTelegram APIの利用規約を確認してください。研究文献およびプラットフォームに関する 調査結果はRESEARCH.mdに記載されています。