接続、プロキシ、およびデータ保護

このドキュメントでは、TgWitness 0.7.0 の動作とその制限事項について説明します。認証、 ソースへのアクセス、ネットワーク接続、およびキャプチャの完全性は、それぞれ独立した状態です。 サインインの手順、ファイル形式、および複数アカウントについては、「 アカウントとセッション形式」からご確認ください。イベントポリシーや再起動時の 動作については、「収集の仕組み」をご覧ください。

認証方法#

API ID および API ハッシュはアプリケーションを識別するものであり、アカウントへのログインに代わるものではありません。 TgWitness ではこれらはオプションです。優先順位は、フォームに入力されたペア、次に インポートされたアカウント JSON からのペア、次にワークスペースに保存されたペア、そして 50 組の 公開ペアのプールを順に試行し、Telegramが1つを拒否した場合は自動的にローテーションされます。 Telegram Desktopのペア（2040）のみ、対応するTelegram Desktopクライアントの説明とともに送信されます。 my.telegram. orgのAPI開発ツールから取得したご自身のペアは、すべてのアカウントで使用可能です。各アカウントには、引き続き独自の認証が適用されます。

Telegramはコードの配信方式を採用しており、SMSによる配信は保証されません。APIハッシュでは、 失効したセッションを復元したり、忘れた2FAパスワードを再発行したりすることはできません。TgWitnessは、 ログインコードやTelegramの2FAパスワードをディスクに保存することはありません。

非公開の情報源の場合、アカウントはすでにアクセス権を持っている必要があります。グループのユーザー名は 不要です。プロキシやセッションのインポートを行っても、メンバーシップや管理者 権限は付与されません。現在のメンバーシップがあっても、参加前の履歴へのアクセスが保証されるわけではありません。

Telethonのセッションファイルをインポートする#

Telethon SQLite、Pyrogram SQLite、および Telegram Desktop TData は、それぞれ異なる形式を使用しています。 パネルは、サポートされている構造を検出して変換しますが、ファイル名の変更は 変換には該当しません。「ファイル」から 1 つのセッションとその対応する JSON を選択し、「アカウントに接続」を押してください。最大 4 つの一致するファイルと 合計 8 MiB まで受け付けられます。 TData/JSONの詳細については、フォーマットの制限をご参照ください。 パスコードの復元機能はありません。電話/2FAまたはQRコードによるログインでは、別途認証が行われます。

オプションの「Telethon専用」コマンドラインパスは引き続き利用可能です：

1. 元のセッションを使用しているクライアントを停止し、一貫性のあるコピーを作成してください。 コンバーターは、WAL/ジャーナルが未完了のファイルを拒否します。チェックを回避するためにそれらのファイルを削除するのではなく、元の クライアントを適切に終了させてください。
2. TgWitness環境から、以下のコマンドを実行してください：

python -m tgwitness.sessions account.session --out account.tgwitness-session

3. 「アカウントの追加」→「ファイル」で、結果ファイルをアップロードするか、 その文字列を貼り付けて、次に進んでください。
4. 表示されている数値のアカウントIDを確認し、情報源を選択して、監視を開始してください。

このコンバーターはSQLiteを読み取り専用モードで開き、スキーマのアップグレードやネットワークリクエストは行わず、 セッションを出力することもありません。スキーマのバージョン、テーブル型、1つの セッション行、IP/ポート/データセンター、および鍵の長さを確認します。CLI入力は64 MiBに制限されており、StringSession のテキストは4 KiBに制限されています。 パネルでの変換では、認証済みのTgWitness サーバーにファイルをアップロードし、メモリ内で処理した後、正規化された認証情報をその ブラウザに返します。アップロードされた元のファイルは保存されません。リモートサーバーにはHTTPSを使用してください。

変換されたファイルは、暗号化されていないアカウントアクセス秘密鍵です。 これを保護された ストレージに保管し、決してコミットしたり、第三者の変換サービスに送信したりしないでください。TgWitnessは 認証済みセッションを暗号化された保管庫に保存します。セッションをコピーしても 別の認証が作成されることはありません。クローン化された認証キーを使用してクライアントを同時に実行したり、 独立した更新配信が行われると想定したりしないでください。

変換処理では、元のメッセージやエンティティキャッシュ、あるいは 永続的な更新カーソルではなく、権限のみが転送されます。また、プロセスの再起動を跨いだ更新の復元は行われません。

MTProto、Telethon、およびプロキシ#

MTProtoはTelegramのプロトコルです。Telethonは、TgWitnessが使用するPythonクライアントライブラリです。 MTProxyはTelegramのトランスポートプロキシであり、SOCKS5およびHTTP CONNECTが一般的な トンネルを提供します。いずれもアカウント認証に代わるものではありません。

ログイン前に、「アカウント」→「設定」→「接続設定」→「接続ルートの変更」から、各ワークスペースのルートを保存してください。 新しいワークスペースのデフォルト設定は、「自動 MTProxy」および「IP 非表示」機能を備えた公開リストとなります。 明示的に「ダイレクト」を使用していた既存のワークスペースについては、そのモードが維持されます。

IPモード#

接続経路によって接続方法が決定されます。IPモードによって、サーバーのアドレスが 公開される可能性があるタイミングが決まります。これらの設定により、VPNがインストールされたり、マシンからのすべてのトラフィックがルーティングされたりすることはありません。

トンネル／VPNモードは、そのネットワークを別途管理していることを前提としています。正常に動作する トンネルがない場合、宛先からはサーバー自身のアドレスが確認されてしまいます。オプションの名称ではなく、 実際のネットワーク環境に応じてモードを選択してください。

ルートを選択してください#

偽の TLS ee シークレットは拒否されます。Telethon 1.45 の正規化機能では、プレフィックス やドメインを削除できますが、これは偽の TLS を実装するものではありません。tg://proxy?server=…&port=…&secret=… または https://t.me/proxy?server=…&port=…&secret=… を貼り付け、「リンクからフィールドに値を入力」を選択してください。 これにより、接続や保存を行わずにフィールドの検証と入力が行われます。内容を確認し、 ルートは別途保存してください。手動入力用のフィールドは引き続き利用可能です。Telegramプロキシリンクをご参照ください。

インストール時に提供されるパブリックプロキシ#

組み込みのリストには、 SoliSpirit/mtproto、 zakky8/mtproto-proxy-pro、 kort0881/telegram-proxy-collector、 および 3yed-61/MTP-Collector の4つのソースが組み合わされています。 同梱のスナップショットには、エンドポイント情報、情報源の帰属、およびダウンロード日が含まれています。 プロバイダーがリストに掲載されていることは、そのプロキシが正常に動作することや、Telegramのすべての更新情報を配信することを保証するものではありません。

MTProxyはTelegramの通信接続を自動的にチェックし、正常に動作しているプロキシを維持するとともに、 接続に失敗した場合は別のプロキシに切り替えます。ワークスペースは、十分に 動作しているエントリが利用可能な場合、異なるプロキシを優先します。一意の出口アドレスは保証されません。 接続に失敗したプロキシは、 再試行する前に待機します。機能するプロキシが一つもない場合、IPモードによって、 収集を待機させるか、直接接続を使用できるかが決定されます。プロキシを変更しても、アカウントは 変更されず、そのジャーナルも消去されません。経路の選択や変更は、署名付きジャーナルに記録されます。

自動ルートが有効な場合、リストは1時間ごとに更新され、転送チェックは デフォルトで10分ごとに実行されます。これらの間隔は設定可能です。公開リストを更新すると リフレッシュが要求されますが、リストを閲覧するだけでは、保存済みの手動ルートは変更されません。

各フィードの応答は1 MiBに制限されており、リクエストのタイムアウトは8秒、 ダウンロードの総制限時間は20秒です。リダイレクトは 拒否されます。ソースごとに最大64件の互換性のあるエントリが保持され、重複排除が行われます。 パーサーは、サポートされている16進数およびbase64url形式のシークレット、ならびにJSONフィードを受け付けます。 偽のTLS「ee」、無効なリンク、プライベート／予約済みIPリテラル、およびローカルホスト名は スキップされます。ホスト名は使用前に解決および検証され、選択されたIPは その接続に対して固定されます。自動再取得時にはホスト名が再度解決されます。手動で 再入力することで、再度解決させることができます。

フィードの応答が失敗した場合、空の場合、または互換性がない場合は、以前のソースのスナップショットが保持されます。 更新はアトミックかつシリアル化されており、ワークスペースごとに1分間に1回の試行に制限されています。 転送プローブが成功しても、それは接続性が確立されたことを示すものであり、匿名性やキャプチャの完全性を保証するものではありません。

TelegramのトラフィックとHTTPSリクエストは、異なる経路を使用します。リストのダウンロードには、 別のHTTPS接続と、提供された外部リクエスト経路が使用されます。 TGWITNESS_PROXY_FEED_PROXYは、HTTP/SOCKS5プロキシを使用してその経路を明示的に上書きします。 両方のコレクター「Compose」バリアントは、これを転送します。バックグラウンドプールはメインワークスペースに従います。 Telegramのセッション、API認証情報、パネルトークン、ボットトークンは、フィードプロバイダーには送信されません。 プロバイダー名、スナップショットの日付、およびダウンロード経路は、「リストの出典」の下に表示されます。

MTProxyはTelegramのトラフィックのみを転送します。タイムスタンプ、 通知、オフサイトコピー、ソースチェックなどのワークスペースHTTP操作は、 設定されている場合は別のSOCKS5/HTTPプロキシを使用し、設定されていない場合はアカウントのSOCKS5/HTTPルートを使用します。いずれも設定されていない場合、Hide IPは リクエストを拒否します。その他のモードではDirectが許可されます。 外部リクエストは無効にできます。明示的に 設定されたフィードダウンロードプロキシは、引き続きオペレーターによる個別のオーバーライド対象となります。 独立したウィットネスサービスは、独自の経路を維持します。

自動プールパラメータ

**「パラメータ」→「自動MTProxy」**で、失敗の閾値、クールダウン、 計画的なローテーション、プロキシの共有、および許容されるフォールバック遅延を設定してください。 | 設定項目 | デフォルト値 | | --- | --- | | 置換前の切断回数 | 10分以内に3回 | | 接続試行ごとのプロキシ試行回数 | 3 | | 障害発生後の最初の待機時間／最大待機時間 | 10分／6時間 | | 計画的なローテーション | 無効；失敗時に切り替え | | プロキシあたりのアカウント数 | 0：個別のエントリを優先し、必要に応じて共有します。排他的なエントリを待つ場合は 1 に設定してください。 | | ダイレクトへのフォールバックが許可されるまでの遅延 | 10 分；Hide IP は依然としてダイレクトを拒否します | | フィードの更新／転送チェック | 60／10分；メインワークスペースの設定値が共有プールに適用されます | 異なるプロキシを使用しても、異なる出口アドレスが保証されるわけではありません。これらの設定は、 Telegramの制限を無効にするものではなく、匿名性を保証するものでもありません。

公開リストを独自のオペレーターカタログに置き換えるには、以下のオーバーライドを設定してください。 これにより、proxies配列が空の場合を含め、外部サブスクリプションが完全に無効化されます。

空のカタログをproxy-config/proxies.json にコピーし、デプロイ済みのパブリックエンドポイントを追加してください：

{"format": "tgwitness-proxy-catalog-v1", "proxies": [
  {"id": "project-eu", "label": "Project EU",
   "link": "tg://proxy?server=REPLACE_HOST&port=443&secret=REPLACE_SECRET"}
]}

例示された値は置き換える必要があります。最大32件の異なるエントリが受け入れられます。 認証済みリストは、共有秘密鍵なしでラベル／ホスト／ポートを返します。いずれかを選択すると、 その認証情報がワークスペースの保管庫に保存されます。明示的なトランスポートテストが行われるまでは、 可用性は未検証のままです。カタログの形式が不正な場合は、手動での設定が可能となります。

ネイティブ起動：TGWITNESS_PROXY_CATALOGをローカルのJSONパスに設定してください。Docker：

docker compose -f compose.yaml -f deploy/compose/compose.proxies.yaml up -d --build

オーバーレイはproxy-configを読み取り専用でマウントします。ファイルはコンテナのUID 10001から読み取り可能である必要があります。 当該ディレクトリは、Git、Dockerのビルドコンテキスト、およびソースアーカイブから除外されています。この カタログは収集アカウントを設定するものです。Witnessボットは、MTProxyではなく、独自の HTTP/SOCKS5ルートを使用します。

直接フォールバックは、上記のIPモードによって制御されます。ルートを変更する前に、 監視を一時停止してください。保存を行うと、古いクライアントは切断され、未完了のログインはキャンセルされます。 新しいクライアントは、保存されたルートを使用します。アカウントのジャーナルとセッションの紐付けは維持されます。 設定を変更すると、以前のルートが上書きされます。編集する際は、プロキシの認証情報を再入力してください。

認証情報はnetwork.encで暗号化されています。APIはユーザー名、 パスワード、またはシークレットを返しません。署名付きレコードには、ルートタイプと認証情報の 有無が含まれていますが、エンドポイントやシークレットは除外されています。オペレーターはパネル上で エンドポイントを確認できます。シークレットフィールドは、保存、ロック、またはワークスペースの切り替え後に消去されます。

「Telegram接続のテスト」は、ログイン前でも利用可能で、ルートを経由して一時的な 非認証のTelegram接続を開閉します。IPチェック サイトには接続しません。テストに成功しても、グループへのアクセス、完全な 配信、または匿名性が保証されるわけではなく、単にトランスポート接続が確立されたことを示すものです。

このプロキシは、Telegram DCからのメディア ダウンロードを含め、Telegramクライアントの接続に適用されます。ブラウザ、pip、SSH、および手動で起動されたTSAツールには、それぞれ別の経路が設定されています。 プロキシのホスト名はローカルで解決される場合があります。rdnsは宛先のホスト名に影響を及ぼしますが、 Telegramは多くの場合、数値のDC IPアドレスを提供します。

SOCKS5およびプレーンなHTTP CONNECT自体は、プロキシの認証情報や クライアントからプロキシへのトンネルを暗号化しません。TelegramのトラフィックはMTProtoによって別途保護されます。 信頼できないネットワーク上では、 プロキシへの適切なセキュアチャネルをご利用ください。プライベートグループは クラウドチャットであり、MTProto によってエンドツーエンド暗号化された「シークレットチャット」にはなりません。

暗号化と署名#

「アカウント」の「ストレージ保護」には、これらの状態が表示されます。パネルトークンは アクセスシークレットであり、暗号化パスワードではありません。これにより管理者権限が付与され、 発行されたトークンはアカウントやチャットごとに範囲を限定することができます。ワークスペースは ホストプロセスを共有しており、独立したテナントではありません。

明示的に起動された、隔離された合成デモは、直接の ループバック接続を介して自動的に開くことができます。これは、プロセス存続期間に限定された機能を利用しており、 設定されたパネルトークンを開示することも、実際のワークスペースへのアクセスを許可することもありません。リモート、 プロキシ経由、またはクロスオリジンからのリクエストでは、この自動起動機能を利用することはできません。 この利便性により、実際のアカウントデータに対する認証の境界が取り除かれることはありません。

BitLocker、LUKS、FileVault、または管理対象の暗号化ボリュームは、 それぞれの脅威モデルに基づいてストレージを保護することができます。 ロック解除され、稼働中のマシンの管理者は、 依然としてデータを読み取ることができます。ストレージの計画には、SQLiteのWAL/SHM、メディア、一時的なエクスポートデータ、スワップ領域、バックアップ、 およびブラウザのダウンロードデータを含めてください。Dockerボリュームは、単に ボリュームであるという理由だけで暗号化されるわけではありません。TgWitnessは、SQLCipherやオブジェクト暗号化を実装していません。

外部マスターキー#

新規インストールを行う場合は、マスターキーをデータディレクトリの外に配置してください。 これにより、既存のローカルキー保管庫が自動的に移行されるわけではありません。サービスIDのみがアクセス可能なキー ディレクトリを用意し、以下のコマンドを実行してください：

python -m tgwitness.security create-master-key /private/keys/tgwitness-master.key
export TGWITNESS_VAULT_KEY_FILE=/private/keys/tgwitness-master.key
python -m tgwitness --data-dir /private/observations/new-case

PowerShell（インストール済みのプロジェクト環境を使用）：

python -m tgwitness.security create-master-key E:\PrivateKeys\tgwitness-master.key
$env:TGWITNESS_VAULT_KEY_FILE = 'E:\PrivateKeys\tgwitness-master.key'
python -m tgwitness --data-dir E:\PrivateData\new-case

Dockerでは、ファイルを/dataの外側（例えば /run/secrets/tgwitness-master.key）に読み取り専用でマウントし、環境変数をそのパスに設定してください。 サービスUIDは、そのファイルを読み取れる権限を持っている必要があります。キーバイトではなく、パスを 環境変数または設定ファイルを介して渡してください。

各ワークスペースには、ランダムなパブリックソルトと、 HKDF-SHA256を通じて導出された独自のFernetキーが割り当てられます。vault.external.jsonには、マスターキーではなく、導出メタデータが保存されます。 キーが欠落している、または間違っている場合、自動的に置き換えられることなく起動に失敗します。復旧のために、 ソルトのメタデータとマスターキーの両方を保管しておいてください。

すべてのワークスペースは同一のマスターキーから派生しており、その秘密鍵が漏洩すると、 インストール全体に影響が及びます。実行中のプロセスは秘密情報を復号化できます。これはHSMや パスワードKDFではありません。ランダムな鍵の代わりに、任意のユーザー設定のパスワードは使用できません。

意図的な移行が 実施され、検証されるまでは、既存のインストール環境については既存の鍵を維持してください。vault.keyを削除したり、マスターキーを置き換えたりすると、 セッションや署名鍵へのアクセスが失われる可能性があります。暗号化されたバックアップと鍵は別々に保管し、 隔離されたインスタンスで復旧テストを行ってください。

情報源および検証範囲#

2026年10月26日時点でのレビュー：

• https://core.telegram.org/api/auth
• https://core.telegram.org/api/obtaining_api_id
• https://docs.telethon.dev/en/stable/basic/signing-in.html
• https://docs.telethon.dev/en/stable/concepts/sessions.html
• https://core.telegram.org/mtproto/mtproto-transports
• https://github.com/telegramdesktop/tdesktop/blob/dev/Telegram/SourceFiles/storage/storage_account.cpp
• Telethon 1.45.0：SQLiteSession、StringSession、Connection._proxy_connect、 TcpMTProxy.normalize_secret、およびダウンロード方法。

ローカルテストでは、ループバック SOCKS5/HTTP CONNECT フィクスチャ、合成 SQLite セッション、 経路の分離、秘密情報の除外、およびキー欠落時の拒否について検証しています。これらは、 実際の Telegram とプロキシ間の相互運用性や、MTProxy の実稼働時の挙動を検証するものではありません。 VERIFICATION.md および LIVE_ACCEPTANCE.md をご参照ください。