令牌分类与增强

• OAuth 正文键（access_token、refresh_token、id_token）和 Cookie 名称启发式规则决定令牌类型。
• Microsoft 会话 Cookie（ESTSAUTH、ESTSAUTHPERSISTENT、ESTSAUTHLIGHT、SignInStateCookie）被明确识别为 refresh 等效令牌（否则它们会被通用的 “auth” Cookie 提示错误分类）。
• JWT 声明（header + payload）被解码并原样存储——绝不截断。
• 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，并单独呈现仅应用和未知身份桶。当用户出现在 ≥2 个 source_tag 中时，每个身份行会显示一个 captures 徽章（跨捕获存活，这是 --append 研究的核心信号），外加一个 first_seen → last_seen 时间跨度，以及一个 timeline 按钮，用于在 Sequence-diagram 标签页上高亮该用户的每个令牌。
• 令牌有效性 — 当前有效与已过期 access token 的计数、refresh-token 过期状态（对于不透明令牌显示 “unknown expiry”），以及一个 top-3 “next to expire” 列表，每 30 秒自动刷新。
• 客户端 — 交换中出现过的每个不同应用（appid / azp / 表单正文 client_id / brk_client_id / brk_nested_id），带有 FOCI / brokerable / broker / nested 徽章。
• 受众 — 观察到的每个 aud 声明，尽可能解析为 entrascopes 资源名称。
• 租户 — 不同的 tid 值，以及令牌 / 用户 / 应用计数。
• 主机 — 每个主机的事件、不同 bearer 接收方、不同签发者和交换计数。
• 特权作用域与角色 — 将每个令牌的 scp / scope / roles 与一份精选的高影响 Microsoft Graph 权限和 Azure 资源作用域监视列表进行比对。
• 受众 / 主机不匹配 — 标记每个 (token, host) 对，其中令牌被用于与其 aud 声明不一致的主机（表明凭据泄露或滥用）。
• 认证方法（amr）— pwd / mfa / pop / smartcard 分布。
• 安全功能 — 标记 Continuous Access Evaluation（xms_cc=CP1）、持有证明绑定（cnf 声明，并跨受众检测共享 kid）、step-up 认证要求（acrs）以及 acr 认证上下文级别。每一行都可点击，并将 Tokens 标签页过滤为仅显示携带该标记的令牌。
• Refresh-token 链 — 遍历交换边以识别轮换谱系、最长链长度和空闲 refresh token。每条链显示一个 Δ scopes 列（跨跳添加 / 移除的作用域，悬停时显示完整的逐跳差异），并标记其中添加的作用域匹配特权作用域监视列表的链，带有 ⚠ priv 徽章——这是 FOCI / BroCI 式权限扩展研究信号。
• 来源 — 按 source_tag 统计令牌计数，以便查看每次摄取过程产生了多少行。

Tokens / Exchanges 标签页

• 点击列标题进行排序。
• 多选复选框驱动一个工具栏：
  • Highlight in Graph — 对选中节点加黄色强调。
  • Isolate in Graph — 仅重绘显示选中令牌及其交换对象的图。
  • Show in Sequence — 为选中令牌显示聚焦的序列图。
• 点击一行可展开内联面板，其中包含完整 JWT header + payload（原始 JSON）、所有事件、相关交换、可重放导出按钮（raw / Bearer / curl / JSON / roadtx token cache），以及一个命令预览块，包含 roadtx describe、roadtx auth、curl、Python requests 和 PowerShell Invoke-RestMethod 的可复制粘贴片段。
• 过滤器： 类型 chips（access / refresh / id / unknown）、格式 chips（jwt / opaque）、used / unused 下拉框、有效性下拉框（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 hash 持久化 — 活动标签页和每个过滤器状态都会序列化到 URL hash，因此指向特定过滤视图的链接可共享。

WebSocket 支持

• mitmproxy 和 CDP 捕获会保留每个 WebSocket 文本 / 二进制帧负载。帧内容会使用与处理 HTTP 正文相同的 JSON / form / raw-JWT 遍历器扫描令牌。
• 在帧中找到的令牌会生成事件，角色为 ws-frame-sent / ws-frame-received，来源为 ws[body_json[<key>]]，并带有一个 ws_session_id，用于将单个 WebSocket 连接内的所有帧分组。
• 握手会作为普通 HTTP 事件捕获，因此带入升级过程的 Cookie / bearer 令牌也会被追踪。

隐私

• 数据库存储每个观察到的令牌的 SHA-256 指纹（前 12 个十六进制字符）和 12 字符前缀。完整令牌字符串绝不会离开输入文件。

• 解码后的 JWT 声明内容（header + payload，包括 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 + observed events）。
  • 复制 / 下载为 roadtools token cache（将文件放入 .roadtools_auth，任何 roadtx 子命令都会读取它）。
  • 每个令牌的 Command preview 块，使用令牌实际的 tid、appid 和 aud 声明预填最常见的重放调用——roadtx describe、roadtx auth、curl、Python requests、PowerShell Invoke-RestMethod。

安装

要求

• 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 流文件合并到一个数据库中：```bash tats ingest engagement.xml -o tokens.db --enrich tats mitm chat-session.mitm -o tokens.db --enrich --append tats serve tokens.db

当你按下 Ctrl-C 终止 cdp 命令时，启动的浏览器会被终止，其临时配置文件也会被删除。

如果你更愿意附加到一个已经运行的浏览器，请使用 --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile 启动它，并在运行 cdp 时不带 --launch-chrome。

在共享数据库之前对其进行脱敏（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 在 浏览器 级别附加，并跟踪启动时存在的每个标签页以及运行期间打开的每个标签页（window.open、Ctrl-点击、新建标签页按钮）。所有标签页通过 CDP 扁平协议会话多路复用器共享同一个 WebSocket，因此在捕获运行期间打开或关闭标签页是完全支持的。每个标签页的附加/分离都会在 INFO 级别向 stderr 打印一行说明。

如果你更希望固定到单个标签页，并在该标签页关闭时结束附加，请列出可用的目标：```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）—— 指纹、样本前缀、类型、 格式、观察到的生命周期、JWT 头部 / 载荷（JSON 格式）、富化 字段、派生字段（user_identity、exp_unix、tenant_id、 scopes_text）、逗号分隔的 source_tag、raw（完整令牌 字符串，除非使用 --store-tokens 摄取，否则为 NULL），以及 security_features（描述检测到的 CAE / PoP / 步骤升级标记的紧凑 JSON —— 参见 Security features 卡片）。 较旧的 v2 / v3 数据库在以追加模式重新打开时自动迁移： v2 → v3 添加可空的 raw 列；v3 → v4 添加可空的 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 （由仪表板的实时轮询使用）、计数。

源标记和追加模式

写入数据库的每一行都携带一个 source_tag —— 默认情况下 burp:<filename>、mitm:<filename> 或 cdp:<host>:<port>，但 可通过 --source-tag 覆盖。当同一指纹被 多个摄取过程看到时，source_tag 字段会累积为 逗号分隔的列表，因此仪表板的 Sources 卡片可以显示 每个令牌的来源。

--append 保留现有数据库并通过 UPSERT 合并到其中 （令牌使用计数 + 观察到的生命周期累积，未知类型 升级），并对事件 / 交换使用 INSERT（其 seq 编号 偏移超过现有最大值，因此活动时间线保持 单调）。模式版本不匹配会拒绝合并以防止静默 数据丢失。

实时更新

Web 服务器的 /api/meta 端点返回 meta 表（约 200 字节）。仪表板每 5 秒轮询一次，并且仅在 last_modified 变化时 重新获取完整的 /api/data。cdp 摄取路径默认每 25 个事件 将其内存跟踪器刷新到数据库，因此 从浏览器请求到仪表板更新的挂钟延迟通常 < 10 秒。

限制

• 不支持 Burp .burp 项目文件。 使用 Save items 生成 该工具消费的 XML。
• 无代理 CA 管理。 此工具本身不拦截 TLS。 在 Burp / mitmproxy 下游使用它，或使用 CDP 路径，该路径 从浏览器内部看到 TLS 解密后的流量。
• CDP 附加覆盖顶层页面目标。 进程外 iframe （OOPIF）和专用 worker 不会递归自动附加，因此 流经这些目标类型的事件可能会被遗漏。对于 此工具所围绕的 Microsoft / OAuth 流程，顶层页面 附加能捕获所有重要内容。
• 无签名验证（针对 JWT）。该工具解码声明用于 显示；签名检查、alg=none 和密钥混淆攻击 不在范围内。请使用专用的 JWT 审计器进行这些操作。
• 不透明令牌误报。 “这是令牌吗？”启发式 将 OAuth 形状上下文中任何 20+ 字符的 URL 安全字符串视为 令牌。长随机 ID 可能会被错误标记。无法推断类型的令牌 最终为 unknown，默认隐藏，除非在（仅 Burp）较旧标志上 设置了 --include-unknown。
• --enrich 会发出站 HTTP 请求 到 https://entrascopes.com/。如果您的环境不允许，请跳过该标志。
• Web UI 没有身份验证。 将其绑定到 localhost，除非 您在前面放置了另一个认证层。

故障排除

开发

冒烟测试夹具

两个夹具构建器位于 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 脱敏、带追加模式 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/* 端点），请在同一次更改中更新本文件的相关章节。最可能发生偏移的章节：

• 功能 — 在添加摄取源或仪表板卡片时
• 子命令 — 在更改标志时
• Microsoft 特定支持 — 在检测逻辑发生变化时
• 架构 — 在模式或实时更新流程发生变化时
• 故障排除 — 在出现新的错误消息时

许可证

GNU 通用公共许可证 v3.0 或更高版本 — 完整文本见仓库根目录下的 LICENSE 文件。脚本源代码带有指向同一许可证的标准简短头部。

你可以根据 GPL v3（或你选择的任何更高版本）的条款重新分发和/或修改本工具。本工具在没有任何担保的情况下分发；完整条款请参见 LICENSE。

启用此项会将数据库变成一份完整的凭据——重放任何捕获会话所需的每个字节都在其中。可与 --redact-claims 结合使用以清理解码后的 JWT 视图，但请注意原始令牌内部仍携带未脱敏的声明编码。当该标志关闭时，仪表板的命令预览块仍会渲染，只是使用 <TOKEN> 作为占位符，因此可作为语法参考；导出按钮会渲染一个提示，要求重新摄取。