TgWitness / ドキュメント

テスト済みの内容 →

参考文献 / セキュリティとプロジェクト

アーキテクチャ

コレクター、パネル、ジャーナル、ワーカー、ウィットネスの各コンポーネントと、それら間でデータがどのようにやり取りされるかについて解説します。

TgWitness / ドキュメント

開発

1つのPythonプロセスがFastAPIパネルと、任意の数の分離されたワークスペースをホストし、 各ワークスペースにはTelethonユーザーアカウントクライアントが配置されています。 SQLiteには、追記専用の署名付きイベントジャーナルと、変更可能な運用設定が格納されています。 暗号化された保管庫には、API認証情報、StringSession、および署名鍵が格納されています。 フロントエンドは、HTML/CSS/JavaScriptをバンドルしたシンプルな形式となっており、Nodeによるビルド、CDN、 あるいは実行時のフロントエンドダウンロードは一切必要ありません。

オプションのブラウザおよびAyuGramレコーダーは、別々のプロセスまたはコンテナで実行されます。 この tgwitness_capture パッケージは、独自のイベント形式、キー、アーティファクト、 チェックポイントAPI、独立したウィットネス、およびスタンドアロンの検証機能を備えています。これはメインの wheelに同梱されており、 addons/captureから単独でインストールすることも可能です(コレクターをインポートする必要はありません)。メインパネルの capture_api.py および capture_connections.py は、 /api/capture; 接続トークンは暗号化されたボールトに保管されます。レコーダーや外部へのリクエストは、 メインプロセスから開始されることはありません。各明示的なコマンドは、 固定されたレコーダーキーに対して新しいチャレンジを検証します。エクスポートデータはダウンロード前に検証され、元の 署名を保持します。これらはTelegramメッセージイベントにはなりません。収集セッションとプロキシ ルートは各クライアントに留まります。展開および信頼境界については、英語の独立型 キャプチャガイドを参照してください。

モジュール 責任
collector.py 認証、ダイアログの選択、更新、スナップショット、メディアキュー、接続の監視
interactions.py / telegram_client.py 明確なパネル操作、署名付き受信確認、永続的なリクエストID、およびタスク単位のコールバック/参加リトライポリシー
message_content.py 転送アクセスに関するメタデータを除外した、メッセージの可視的な比較
workers.py キャンセル処理を行う前に、エクスポートファイルの処理が完了するまでお待ちください
distributed_export.py / distributed_pages.py 並行チャットジョブ、アカウントごとの予約、署名付きチェックポイント、およびアーカイブ検証後のクリーンアップ
distributed_takeout.py / export_timing.py 再開可能な「Takeout」セッションおよび各開始・再開時のタイミング
store.py WALトランザクション、順序付けられたイベントチェーン、クエリフィルター、運用設定
fulltext.py 署名付きジャーナルのヘッダーに紐付けられた派生フルテキストインデックス(語形、BM25)。エクスポートは一切行われない。
security.py プライベートファイルの作成、暗号化された保管庫、Ed25519による署名、シングルプロセスロック
evidence.py ジャーナル全体のエクスポート、派生ファイル、チェックポイント、添付ファイルの検証
verify.py スタンドアロン型の読み取り専用検証ツール(標準ライブラリ+暗号技術):アーカイブ、カバレッジ、ウィットネス・ジャーナル、チャンネルの投稿、プロフィールファイル
app.py 認証済みAPI、ライフサイクル、リクエストの検証、静的パネル
profiles.py 複数のアカウント収集機能、共有アクセス制御機能、ワークスペースごとのライフサイクル管理
access.py スコープ指定された権限付与、権限チェック、IP制限、セッション制限、および管理者コンソール
proxy_catalog.py 公開フィードのスナップショット、転送チェック、共有プロキシプール、および健全性に基づく選択
provenance.py 署名付き取得実行時の識別情報、コード、および依存関係の測定
network.py ワークスペースごとの検証済みルート、編集済みステータスおよび証拠、Telethonの転送オプション
sessions.py レビュー済みのTelethon SQLiteスキーマのオフライン読み取り専用変換
account_import.py サポートされているアカウントファイルおよびJSONのインメモリ検出と正規化
tdata.py 限定された機能を持つ最新のTData ZIPリーダー、チェックサム/復号の検証機能を備え、データの抽出は行いません。
doctor.py データの収集、ログイン、パッケージのインストールを必要としない、ローカルでの動作確認
download.py 認証済みのストリーミングエクスポートのダウンロード。読み取り範囲が制限されており、上書きは行われません。
monitoring.py ワークスペースごとのイベントポリシーおよび添付ファイルの種類ごとのルールが検証済みであり、ハンドラー、ステータス、および署名付き受領証によって共有されます。
scope.py 監視範囲(選択したチャット、Telegramフォルダ、アカウント全体)、ソースの種類、除外条件、再確認レベル
dossier.py 保存された記録から構築されたチャットごとのユーザープロフィール:記録参照付き事実、アバターのSHA-256/pHash、メンションの抽出
witness_api.py 読み取り専用のウィットネストークン、およびそれらによって取得可能な署名付きジャーナルヘッダー
witness.py 独立した証言プロセス:独自の鍵とジャーナル、ヘッドチェック、署名付きチャンネル投稿、エクスポート
alerts.py Appriseの通知およびパネルの通知一覧
logging_config.py ウィンドウレス起動時のコンソールログおよびローテーション方式のサーバー診断
static/ レスポンシブなインターフェース、ローカルアクセスゲート、フィルタ、詳細表示、エクスポート、アカウント設定
demo.py 「合成ジャーナル」と明確にラベル付けされ、実際の収集データとは分離されています。

監視ハンドラーは、接続前に登録されます。リアルタイム収集は、 アクティブなクライアントID、明示的な実行状態、有効化されたソース、または監視 範囲(フォルダモードやアカウント全体モードでは、最初の更新時に新しいチャットがソースとして追加されます)、およびイベント ポリシーによって制御されます。拒否されたクライアントや置き換えられたクライアントは、リアルタイムの更新情報を提供できません。 生の反応およびメンバーシップの更新は、 可視性の制限を保持します。受信メッセージの内容とその永続的なメディアジョブは、 一緒にコミットされます。ジョブは元のTL記述子を保持し、そのハッシュを 署名付きメッセージの観測に紐付けます。送信者/編集者/削除者のセマンティクスは分離されています。

各ワークスペースは1つのアカウントのみを受け入れ、独自のディレクトリと署名用IDを持っています。 互換性を確保するため、メインのワークスペースはルートディレクトリに配置され、追加のワークスペースは profiles/<id>/ に配置されます。1つのベアラートークンがインストール全体を管理しており、ワークスペースは 独立した認証テナントではありません。 プロセスロックによりディレクトリが保護され、データベースロックにより イベントの挿入がシリアライズされます。各追加処理は、FULL同期モードの SQLite WALに対して同期的にコミットされます。イベントの更新・削除トリガーにより、 通常のアプリケーションによる編集が防止され、ファイルシステム管理者は信頼境界内に留まります。

APIの認証はベアラートークン方式です。ログイン操作はシリアライズされ、時間制限があります。 アカウントへのアップロードには、12 MiBのエンコード済みボディ制限と8 MiBのデコード済みファイル 制限が適用されます。通常のAPIリクエストでは16 KiBの制限が維持されます。 変換はワーカースレッドで 実行され、アップロードデータをメモリ内に保持し、正規化された入力を認証済みの ブラウザに返します。QRログインには、ワークスペースごとの候補、短命な識別子、待機タスク、 および明示的なキャンセル機能があります。承認された認証のみがアクティブなクライアントとなります。 TelegramのFloodWaitはRetry-After値とともに返されます。認証情報および生のRPC エラーメッセージは、APIエラーでは公開されません。 ジャーナルのエクスポートは非同期 イベントループの外で実行され、ワークスペースごとにシリアル化されます。これらは、WALへの書き込みを継続しながら、安定した読み取りスナップショットを ストリーミングします。チャットの取得ジョブは、 別々のアカウントで並行して実行可能です。各アカウントは、そのジョブが停止するまで予約された状態のままです。一時停止または 失敗したジョブは、そのチェックポイントを保持します。アーカイブの検証に成功すると、その作業ファイルのクリーンアップが許可され、 ZIPファイル、署名付きプラン、およびステータスが残されます。ワークスペースコレクターは プロセス/イベントループを共有します。

現在の履歴スナップショットとリアルタイムの更新情報は重複する場合があります。これらはそれぞれ独立した観測データであり、 ソースごとにラベル付けされています。重複データは自動的に折りたたまれることはありません。IDの欠落、 削除されたテキストの捏造、メンバーの強制的な列挙、またはグループへの自動参加 に基づく推論機能は実装されていません。

運用担当者向けの説明については、「収集の仕組み」 および「アカウントとセッションの形式」をご覧ください。

ネットワーク設定は暗号化された保管庫に格納されています。ルートを適用すると、古い クライアントが閉じられ、未完了のログインがキャンセルされます。その後の接続では、そのルートが使用され、 直接的なフォールバックは行われません。 新しい外部キーによるインストールでは、マスターキーファイルと保存されたランダムなソルトから、 HKDF-SHA256 を使用して各ワークスペースの Fernet キーが生成されます。これにより、 機密情報はデータディレクトリとは別に保護され、ジャーナルやメディアのコンテンツが平文で保存されることはありません。

ローカルデモへのアクセスには、別途生成されたプロセス機能を使用しており、設定済みの パネルトークンは一切使用しません。発行および受諾には、明示的なデモモード、追加のワークスペースや認証済みセッションを伴わない合成ルート、 ループバックピア/ホスト、プロキシ 転送ヘッダーなし、およびクロスオリジンブラウザリクエストなしが必須となります。 本番用APIはベアラー 認証を維持し、デモモードでの収集変更を拒否します。