tgscope

TelegramのOSINT、スクレイピング、アーカイブ。
完全にあなたのマシン上で動作し、Telegramとのみ通信するローカルWebアプリ。

npm install
npm start

次に http://127.0.0.1:5173 を開きます。初回実行時には、API 認証情報、QR サインイン、ダイアログの読み込みを順に案内します。通信先は Telegram サーバーのみです。作成するアカウントも、テレメトリも、間に挟まるサービスもありません。収集したデータは、あなたが所有する SQLite ファイルに保存されます。

telegram-scraper、telescope、Harrier の後継で、Telethon 1.44 上に構築されています。

収集	複数アカウントにまたがるチャンネル、グループ、フォーラムトピックを、メディア、重複排除、再開機能付きで収集
調査	電話番号、@username、id、t.me リンクからプロフィール、過去のすべての写真、前回からの差分を調査
エクスポート	プレーンな CSV からハッシュ付き証拠バンドルまで、10 種類の形式
動作環境	Node 18+、Python 3.12+、SQLite。データベース 1 つ、フォルダー 1 つ、サービス不要

機能

収集

• すべてのチャンネル、グループ、フォーラムトピック、チャットを、サインイン中のすべてのアカウントにまたがって 1 つの選択可能なツリーに表示。名前と並べて完全な -100 id を表示し、それを閲覧できるアカウントのバッジも付与
• 各ダイアログは、実際に読み取り可能なアカウントの下で収集されるため、2 つのアカウントにまたがる選択では、アカウントごとに 1 回の実行が開始される
• 完全なメタデータ付きのメッセージ: 閲覧数、転送、リアクション、編集日時、アルバム、投票、位置情報、リンク、返信チェーン、投稿者、および各メッセージの転送元
• フォーラムグループはトピックごとに分割 — グループ全体ではなく個別のトピックを収集可能
• メディアは並列でダウンロードされ、SHA-256 と Telegram ファイル id で重複排除されるため、5 つのチャンネルに転送されたファイルも 1 回だけ保存される
• ダイアログごとのウォーターマークから再開。継続モードでは一定間隔で再チェック
• 保存済みコレクションはワンクリックで選択内容を再実行

調査

• 電話番号、@username、ユーザー id、t.me リンクを検索
• プロフィール、フラグ、プライバシー指標としての最終オンライン精度、共通のチャット、個人チャンネル
• Telegram が自発的に開示するアカウント情報: 登録月、電話番号の国、最後に名前を変更した時期や写真を差し替えた時期、自動削除タイマー、制限付き転送で表示される名前。ただし通常は何も開示されない点に注意。これらのフィールドは、見知らぬ人があなたにメッセージを送った際に Telegram が表示する詐欺対策パネルに付随しており、直接検索したプロフィールでは空で返るため、計画の前提とするのではなくボーナスとして扱うこと
• ビジネスアカウントでは、住所、座標、タイムゾーンが確実に取得できる
• すべての表示可能なプロフィール写真を SHA-256 と知覚ハッシュでハッシュ化し、ギャラリーとして表示
• 知覚ハッシュはアカウント間で照合されるため、2 つ目のプロフィールにある同じ画像が浮かび上がる
• メッセージ送信者はスクレイピング時に記録されるため、ユーザー名を持たない人物であっても、ブラウザ上の名前が検索への有効なリンクとなる。「メンバーを同期」で、以前に収集したものにもこれを補完
• すべての検索はスナップショット化され差分が取られる: ユーザー名の変更、表示名の変更、プロフィールの編集、写真の追加・削除、プライバシー設定の変更

エクスポート

形式	得られるもの
csv	ダイアログごとに 1 ファイル
json / jsonl	完全なメタデータ。JSONL は行ごとにストリーム出力
xlsx	メッセージ、メディア、参加者、リアクションのシート
html	スタンドアロンレポート: 統計、アクティビティ、上位送信者、転送元、検索可能なテーブル
markdown	同じレポートをテキストで出力
gexf / edges	Gephi および Maltego 用の転送グラフ
sqlite	選択したダイアログのみを含むスタンドアロンデータベース
bundle	データ、メディア、SHA-256 ハッシュのマニフェスト、収集ログを含む ZIP

要件

• Node.js 18+
• Python 3.12+
• my.telegram.org/apps から取得した API 認証情報

npm install は server/.venv の下に Python 環境を作成し、両側をインストールします。

ファイルの場所

内容	場所
設定	~/.config/tgscope/config.json (モード 600)
データベース	~/.local/share/tgscope/tgscope.db (WAL、FTS5)
メディア	~/.local/share/tgscope/media/
エクスポート	~/.local/share/tgscope/exports/<timestamp>-<label>/

1つのデータベースにすべてが格納されているため、ダイアログ横断検索、共有ユーザーテーブル、メディアの重複排除、転送グラフが可能になります。

メディアのレイアウト

ファイルはダイアログ種別、ダイアログ、フォーラムトピック、メディア種別の順に分類されます:

media/
├── channels/technews_-1001234567890/
│   ├── photos/00004711-8001-conference-slides.jpg
│   └── documents/00004802-8210-quarterly-report.pdf
├── groups/pythondev_-1009876543210/
│   ├── general/photos/…
│   └── help/voice/00000004-9004-voice.ogg
└── profiles/123456789/000-5544332211.jpg

ディレクトリ名はハンドルと完全なIDを組み合わせたもので、非ASCIIのタイトルは音訳され、ファイル名は時系列で並ぶようにゼロ埋めされます。

レート制限とアカウントの安全性

すべてのTelegram呼び出しは、トークンバケットとFloodWaitバックオフを備えたアカウントごとのガバナーを経由し、ページ単位の読み取り（メッセージ、ダイアログ、メンバー、プロフィール写真）はすべてフラッド待機を待って再開し、実行を失敗させません。3つのプロファイルがあります:

プロファイル	メディアワーカー	リクエスト間隔	サイレントに吸収される待機時間
stealth	1	1.6 s	最大180 s
balanced	4	0.35 s	最大90 s
fast	8	なし	最大45 s

より長い待機はアクティビティログで通知され、待機し続けます。1回の読み取りで12回連続した場合は諦めて報告します。

複数のアカウントがサポートされています。設定で1つをバーナーとしてマークすると、電話番号検索が自動的にそのアカウントで実行されます。これが唯一の危険な操作だからです:

電話番号検索は、その番号を一時的に連絡先としてインポートし、その後再び削除します。相手がすでにあなたの番号を保存している場合、相手に「Telegramに参加しました」という通知が表示される可能性があります。tgscopeは毎回最初に確認し、プロフィールカードには使用したアカウントが記録されます。

開発

npm test                    # 92 backend and 42 frontend tests, no network needed
npm run build               # production bundle of the client

バックエンドはTelethonコア上のFastAPIで、偽のTelethonクライアントに対してテストされています。スクレイパー、エクスポーター、メディアレイアウト、そしてすべてのスキーママイグレーションが対象です。フロントエンドのテストは、ブラウザの背後にある純粋なロジック、期間の算術、ヒストグラムのバケット化、数値とタイムスタンプのフォーマットをカバーし、すべての画面を2回（空の状態とデータが入った状態で）レンダリングします。

scripts/demo/ はシードされた偽データから docs/preview.gif を再生成します。chromium と ffmpeg が必要で、実際のワークスペースには一切触れず、アプリの一部でもありません。

ソースにはコメントがありません — 命名と構造が意味を担っており、それをテストが強制しています。

法的注意

研究、ジャーナリズム、および許可された調査のためのものです。Telethonを通じて公式のTelegram APIを使用し、あなたのアカウントがすでに見ることのできるものだけを読み取ります — 誰かのプライバシー設定を回避することはありません。嫌がらせやストーキングに使用しないでください。Telegramの利用規約を遵守し、あなたに適用されるデータ保護法に留意してください。

MITライセンス。