トークンの分類とエンリッチメント

• OAuth ボディキー (access_token、refresh_token、id_token) と Cookie 名のヒューリスティックがトークンタイプを決定します。
• Microsoft セッション Cookie (ESTSAUTH、ESTSAUTHPERSISTENT、ESTSAUTHLIGHT、SignInStateCookie`) はリフレッシュ相当のトークンとして明示的に認識されます (そうでなければ、汎用的な「auth」Cookie ヒントによって誤分類されるでしょう)。
• JWT クレーム (ヘッダー + ペイロード) はデコードされ、そのまま保存されます — 切り詰められることはありません。
• Microsoft FOCI (Family of Client IDs) は、トークンエンドポイントのレスポンス内の foci フィールドを介して検出されます。
• Microsoft BroCI / Nested App Authentication は、リクエストボディ内の brk_client_id、brk_redirect_uri、および brk-<guid>:// リダイレクトスキームを介して検出されます。
• オプションの --enrich フラグは https://entrascopes.com/ から firstpartyscopes.json と resources.json を取得し、appid / azp / aud GUID をクリック可能なリンク付きの分かりやすい名前へと解決します。

ダッシュボードカード

• サマリータイル — トークン数、ホスト、交換 (FOCI / BroCI の注記付き)、およびエンリッチメントステータスインジケーター。
• ユーザー — upn / preferred_username / unique_name / email / name によるトークンのバケット化。sub@iss または oid にフォールバックし、アプリ専用および不明な ID のバケットを別途表示します。各 ID 行は、そのユーザーが 2 つ以上の source_tag に現れる場合に captures バッジ (クロスキャプチャ生存、--append の主要な研究シグナル) を表示し、さらに first_seen → last_seen のスパンと、Sequence-diagram タブでそのユーザーのすべてのトークンをハイライトする timeline ボタンを表示します。
• トークン有効性 — 現在有効な access トークンと期限切れの access トークンの数、リフレッシュトークンの有効期限ステータス (不透明トークンには「unknown expiry」)、および 30 秒の自動更新付きのトップ 3「次に期限切れになる」リスト。
• クライアント — 交換に現れたすべての異なるアプリ (appid / azp / フォームボディの client_id / brk_client_id / brk_nested_id)。FOCI / brokerable / broker / nested バッジ付き。
• オーディエンス — 観測されたすべての aud クレーム。可能な場合は entrascopes のリソース名に解決されます。
• テナント — トークン / ユーザー / アプリの数を含む、異なる tid 値。
• ホスト — ホストごとのイベント、異なるベアラ受信者、異なる発行者、および交換数。
• 特権スコープとロール — 各トークンの scp / scope / roles を、影響度の高い Microsoft Graph アクセス許可と Azure リソーススコープの厳選されたウォッチリストに対してチェックします。
• オーディエンス / ホストの不一致 — トークンがその aud クレームと一致しないホストで使用されたすべての (token, host) ペアにフラグを立てます (資格情報の漏洩または誤用を示唆)。
• 認証方法 (amr) — pwd / mfa / pop / smartcard の分布。
• セキュリティ機能 — Continuous Access Evaluation (xms_cc=CP1)、proof-of-possession バインディング (cnf クレーム、オーディエンス間での共有 kid 検出付き)、ステップアップ認証要件 (acrs)、および acr 認証コンテキストレベルにフラグを立てます。各行はクリック可能で、そのマーカーを持つトークンのみに Tokens タブをフィルタリングします。
• リフレッシュトークンチェーン — 交換エッジをたどってローテーション系統、最長チェーン長、およびアイドル状態のリフレッシュトークンを特定します。各チェーンは Δ scopes 列 (ホップ間で追加 / 削除されたスコープ、ホバー時にホップごとの完全な差分を表示) を表示し、追加されたスコープが特権スコープのウォッチリストに一致するチェーンには ⚠ priv バッジを付けます — FOCI / BroCI スタイルの特権拡大の研究シグナルです。
• ソース — source_tag ごとのトークン数。各取り込みパスから何行が来たかを確認できます。

Tokens / Exchanges タブ

• 列ヘッダーをクリックして並べ替え。
• 複数選択チェックボックスがツールバーを操作します:
  • Highlight in Graph — 選択したノードに黄色のアクセントを付けます。
  • Isolate in Graph — 選択したトークンとそれらが交換するトークンのみを表示するように図を再描画します。
  • Show in Sequence — 選択したトークンのフォーカスされたシーケンス図。
• 行をクリックすると、完全な JWT ヘッダー + ペイロード (生の JSON)、すべてのイベント、関連する交換、リプレイ可能なエクスポートボタン (raw / Bearer / curl / JSON / roadtx トークンキャッシュ)、および roadtx describe、roadtx auth、curl、Python requests、PowerShell Invoke-RestMethod のコピー&ペースト用スニペットを含むコマンドプレビューブロックを備えたインラインパネルが展開されます。
• フィルター: タイプチップ (access / refresh / id / unknown)、フォーマットチップ (jwt / opaque)、used / unused ドロップダウン、validity ドロップダウン (any / valid / expired / unknown expiry)、FOCI-only、BroCI-only、has-app-match、has-resource-match、さらに fp / sample / claims / host / app / resource / source_tag / user にわたるフリーテキスト検索。
• 現在フィルタリングおよび並べ替えられた行の CSV / JSON エクスポート。
• URL ハッシュの永続化 — アクティブなタブとすべてのフィルター状態が URL ハッシュにシリアル化されるため、特定のフィルタリング済みビューへのリンクを共有できます。

WebSocket サポート

• mitmproxy および CDP キャプチャは、すべての WebSocket テキスト / バイナリフレームのペイロードを保持します。フレームの内容は、HTTP ボディを処理するのと同じ JSON / フォーム / 生 JWT ウォーカーでトークンをスキャンされます。
• フレーム内で見つかったトークンは、ロール ws-frame-sent / ws-frame-received、ソース ws[body_json[<key>]]、および 1 つの WebSocket 接続内のすべてのフレームをグループ化する ws_session_id を持つイベントを生成します。
• ハンドシェイクは通常の HTTP イベントとしてキャプチャされるため、アップグレードに持ち込まれた Cookie / ベアラトークンも追跡されます。

プライバシー

• データベースは、観測されたすべてのトークンの SHA-256 フィンガープリント (先頭 12 桁の 16 進文字) と 12 文字のプレフィックスを保存します。完全なトークン文字列が入力ファイルから外に出ることはありません。

• デコードされた JWT クレームの内容 (ヘッダー + ペイロード、oid、sub、upn、email、tid、スコープリストなどを含む) は、分析のまさに目的であるため、デフォルトでそのまま保存されます。JWT が存在する場合は常に、データベースおよび共有されたダッシュボード URL を機密として扱ってください。

• --redact-claims (ingest、mitm、および cdp で利用可能) は、データベースに到達する前に、リストされたクレーム値を安定したハッシュプレースホルダーに置き換えます。デフォルトのフィールドリストは sub、oid、upn、email、name、unique_name、preferred_username、emails、mail、ipaddr、given_name、family_name をカバーします。明示的なカンマ区切りリスト (例: --redact-claims sub,upn,oid) を渡してデフォルトを上書きします。同じ入力は常に同じプレースホルダーにマッピングされるため、ダッシュボードの Users / Tenants のグループ化はユーザーを明かすことなく機能し続けます。

• --store-tokens (ingest、mitm、および cdp で利用可能、デフォルトではオフ) は、ダッシュボードが以下を提供できるように、完全なトークン文字列をデータベースに書き込むことを選択します:

  • Copy raw / Copy Bearer / Copy curl アクション。
  • トークン JSON のダウンロード (raw + claims + 観測されたイベント)。
  • roadtools トークンキャッシュとしてのコピー / ダウンロード (ファイルを .roadtools_auth にドロップすると、任意の roadtx サブコマンドがそれを拾い上げます)。
  • トークンごとの Command preview ブロック。最も一般的なリプレイ呼び出し — roadtx describe、roadtx auth、curl、Python requests、PowerShell Invoke-RestMethod — を、トークンの実際の tid、appid、および クレームを使用して事前入力します。

インストール

要件

• Python 3.10+ (match 文に適した型構文とモダンな dataclasses を使用)。3.12 でテスト済み。
• ビルドステップはありません。リポジトリをクローンして python -m tats を直接実行します。

オプションの依存関係

クイックインストール

チェックアウトから実行 (インストールなし):```bash git clone tats cd tats python -m tats --help

インストール後は、短縮名でツールを呼び出せます:```bash tats ingest engagement.xml -o tokens.db --enrich tats serve tokens.db

Burp キャプチャと mitmproxy フローファイルを1つの DB に統合する:```bash tats ingest engagement.xml -o tokens.db --enrich tats mitm chat-session.mitm -o tokens.db --enrich --append tats serve tokens.db

起動されたブラウザは、cdp コマンドを Ctrl-C すると終了し、その一時プロファイルは削除されます。

すでに実行中のブラウザにアタッチしたい場合は、--remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile を付けて起動し、--launch-chrome なしで cdp を実行してください。

共有する前にデータベースをサニタイズする（PII の秘匿化）：```bash tats ingest engagement.xml -o tokens.db
--enrich --redact-claims

every sub / oid / upn / email / name / unique_name / preferred_username

(and a few related claims) is replaced with a stable hash placeholder

例：```bash

fresh DB, with Microsoft enrichment

tats ingest burp.xml -o tokens.db --enrich

add another Burp export to an existing DB without losing the first one

tats ingest day2.xml -o tokens.db --append
--source-tag burp:day2

pip install mitmproxy が必要です。パッケージが欠けている場合、ツールは明確なエラーを出力します。

mitmproxy でフローファイルをキャプチャします:```bash mitmdump -w session.mitm

... drive the browser ...

Ctrl-C to stop

tats mitm session.mitm -o tokens.db --enrich

ツールにブラウザを起動させる (--launch-chrome)```bash

auto-detect Chrome / Edge / Chromium / Brave

tats cdp -o tokens.db --launch-chrome

explicit path (useful for non-default installs / sandboxed builds)

tats cdp -o tokens.db
--launch-chrome /opt/google/chrome-canary/chrome

別の user-data-dir を使うことで、個人プロファイルへのアタッチを避け、 実行中のブラウザがデバッグフラグを拒否するのを防ぎます。

デフォルトでは cdp は browser レベルでアタッチし、起動時に存在するすべてのタブ と、実行中に開かれたすべてのタブ（window.open、Ctrl-click、新しいタブボタン）を追跡します。 すべてのタブは CDP フラットプロトコルセッションマルチプレクサを介して単一の WebSocket を共有するため、キャプチャ実行中にタブを開いたり閉じたりすることは完全にサポートされています。 各タブのアタッチ / デタッチは、INFO レベルで stderr に 1 行のメモを出力します。

単一のタブに固定し、そのタブが閉じたときにアタッチを終了させたい場合は、 利用可能なターゲットを一覧表示します:```bash curl http://127.0.0.1:9222/json/list

例：```bash

default — opens a browser tab automatically

tats serve tokens.db

bind to a different port without auto-launching the browser

tats serve tokens.db --port 9000 --no-browser

(do this only on a trusted network — no auth)

tats serve tokens.db --host 0.0.0.0

すべてのソースパスは同じ Tracker オブジェクトを生成します。ingest_to_db はそれをデータベースの行に変換します。Store は HTTP サーバー用にデータベースを読み取り、 サーバーは /api/data、/api/meta、 /api/token/<fp>、/api/export、/api/graph、/api/sequence で JSON を公開します。

データベーススキーマ (v4)

• tokens (主キー fp) — フィンガープリント、サンプルプレフィックス、タイプ、 フォーマット、観測されたライフタイム、JSON としての JWT ヘッダー / ペイロード、エンリッチメント フィールド、派生フィールド (user_identity、exp_unix、tenant_id、 scopes_text)、カンマ区切りの source_tag、raw (完全なトークン 文字列、--store-tokens で取り込まれない限り NULL)、および security_features (検出された CAE / PoP / ステップアップマーカーを記述するコンパクトな JSON — セキュリティ機能カードを参照)。 古い v2 / v3 データベースは、追加モードで再度開かれたときに自動移行されます: v2 → v3 は NULL 許容の raw カラムを追加します; v3 → v4 は NULL 許容の security_features カラムを追加し、初回オープン時に各トークンの保存された jwt_payload_json からそれをバックフィルします。既存の行は両方の カラムを以前の値のまま保持します。
• events — 観測されたすべてのトークンインタラクション: HTTP リクエスト / レスポンスまたは WebSocket フレーム。ロール: issued / returned / presented / used / exchanged-in / ws-frame-sent / ws-frame-received。接続内のフレームをグループ化するための ws_session_id を 持ちます。
• exchanges — トークンエンドポイントへのトークンを含むリクエストが そのレスポンスで新しいトークンを生成したとき。FOCI / BroCI メタデータを記録します。
• exchange_inputs、exchange_outputs — すべての交換の 各側のトークンフィンガープリント。
• hosts — 個別の host:port ラベル。
• meta — スキーマバージョン、ソースリスト、generated_at、last_modified (ダッシュボードのライブポーリングで使用)、カウント。

ソースタグ付けと追加モード

DB に書き込まれるすべての行は source_tag を持ちます — デフォルトでは burp:<filename>、mitm:<filename>、または cdp:<host>:<port> ですが、 --source-tag で上書き可能です。同じフィンガープリントが複数の取り込みパスで 見られた場合、source_tag フィールドはカンマ区切りのリストとして蓄積されるため、 ダッシュボードの Sources カードはすべてのトークンの来歴を表示できます。

--append は既存の DB を保持し、トークンに対しては UPSERT でマージし (使用回数 + 観測されたライフタイムが蓄積され、不明なタイプはアップグレードされます)、 イベント / 交換に対しては INSERT でマージします (seq 番号は既存の最大値を 超えてオフセットされるため、アクティビティタイムラインは単調に保たれます)。 スキーマバージョンの不一致は、サイレントなデータ損失を防ぐためにマージを拒否します。

ライブ更新

Web サーバーの /api/meta エンドポイントは meta テーブル (~200 バイト) を返します。ダッシュボードは 5 秒ごとにそれをポーリングし、 last_modified が変化したときのみ完全な /api/data を再取得します。cdp 取り込みパスは デフォルトで 25 イベントごとにインメモリトラッカーを DB にフラッシュするため、 ブラウザリクエストからダッシュボード更新までの実時間レイテンシは 通常 10 秒未満です。

制限事項

• Burp .burp プロジェクトファイルはサポートされていません。 Save items を使用して ツールが消費する XML を生成してください。
• プロキシ CA 管理はありません。 このツール自体は TLS を傍受しません。 Burp / mitmproxy の下流で使用するか、ブラウザ内部から TLS 復号されたトラフィックを参照する CDP パスを使用してください。
• CDP アタッチはトップレベルページターゲットをカバーします。 アウトオブプロセス iframe (OOPIF) と専用ワーカーは再帰的に自動アタッチされないため、 それらのターゲットタイプを流れるイベントは見逃される可能性があります。このツールが 対象としている Microsoft / OAuth フローでは、トップレベルページ アタッチで重要なものはすべて捕捉されます。
• JWT の署名検証はありません。このツールは表示用にクレームをデコードします; 署名チェック、alg=none、および鍵混同攻撃は対象外です。それらには 専用の JWT 監査ツールを使用してください。
• 不透明トークンの誤検出。 「これはトークンか?」というヒューリスティックは、 OAuth 形式のコンテキストにおける 20 文字以上の URL セーフ文字列を トークンとして扱います。長いランダム ID が誤ってフラグ付けされる可能性があります。タイプを 推測できないトークンは unknown になり、デフォルトでは非表示になります (Burp 専用の古いフラグで --include-unknown が設定されている場合を除く)。
• --enrich は外部 HTTP リクエストを行います https://entrascopes.com/ に対して。環境がそれを許可しない場合は このフラグをスキップしてください。
• Web UI には認証がありません。 別の認証レイヤーを前に置いていない限り、 localhost にバインドしてください。

トラブルシューティング

開発

スモークテストフィクスチャ

2 つのフィクスチャビルダーが examples/ にあります:```bash

Burp XML fixture (HTTP-only, includes FOCI + BroCI exchanges)

python examples/make_fixture.py examples/fixture.xml tats ingest examples/fixture.xml -o tokens.db --enrich

mitmproxy flow fixture (HTTP + WebSocket frames carrying tokens)

python examples/make_mitm_fixture.py examples/fixture.mitm tats mitm examples/fixture.mitm -o tokens.db --enrich --append

このスイートは、トークン抽出、JWT 解析、Microsoft セッション Cookie の分類、FOCI / BroCI 検出、クレームサマリー、PII の秘匿化、append モードの UPSERT セマンティクスを伴う Burp XML 取り込みパス、および mitmproxy WebSocket フレーム取り込みパス（オプションの mitmproxy 依存関係が欠落している場合は自動スキップ）をカバーしています。```text $ pytest tests/ ============================= test session starts ============================= … ======================== 62 passed in 1.4s =================================

…そして手動で http://127.0.0.1:8765 を開きます。サーバーはすべての リクエストとハンドラーのエラーを stderr にログ出力します。

ファイル構成

シングルファイル構成は意図的なものです。このツールは、Python が インストールされている誰でも読めて、監査でき、調査に投入できる ように作られています。隠れたセットアップも、評価すべき依存関係 ツリーも、ファイル自体以外の表面もありません。

この README のメンテナンス

サブコマンド、スキーマ、ダッシュボードカード、または公開 API サーフェス（CLI フラグ、/api/* エンドポイント）を変更した場合は、 同じ変更の中でこのファイルの関連セクションを更新してください。 最も乖離しやすいセクション:

• Features — 取り込みソースやダッシュボードカードを追加したとき
• Subcommands — フラグを変更したとき
• Microsoft-specific support — 検出ロジックが変わったとき
• Architecture — スキーマやライブ更新フローが変わったとき
• Troubleshooting — 新しいエラーメッセージが追加されたとき

ライセンス

GNU General Public License v3.0 以降 — 全文はリポジトリ ルートの LICENSE ファイルにあります。スクリプトのソースには、 同じものを指す標準の短いヘッダーが含まれています。

GPL v3（または、あなたの選択によりそれ以降のバージョン）の条件の 下で、このツールを再配布および/または改変することができます。いかなる 保証もなく配布されます。完全な条件については LICENSE を参照してください。

これを有効にすると、データベースはまるごと資格情報になります — キャプチャされた任意のセッションをリプレイするために必要なすべてのバイトがそこに含まれます。--redact-claims と組み合わせてデコードされた JWT ビューをスクラブできますが、生のトークンには依然としてその内部にエンコードされた未編集のクレームが含まれていることに注意してください。フラグがオフの場合でも、ダッシュボードのコマンドプレビューブロックはレンダリングされますが、<TOKEN> がプレースホルダーとして使用されるため、構文リファレンスとして機能します。エクスポートボタンは再取り込みを促すヒントを表示します。