Núcleo

• Três fontes de ingestão em uma ferramenta:
  • ingest — exportação XML "Save items" do Burp Suite
  • mitm — arquivo de fluxo .mitm do mitmproxy (frames HTTP e WebSocket)
  • cdp — anexação ao vivo ao Chrome / Edge via DevTools Protocol (em tempo real, captura frames HTTP e WebSocket descriptografados por TLS sem um proxy CA; rastreia cada aba existente E cada aba aberta durante a execução via auto-attach em nível de navegador)
• Um armazenamento SQLite canônico do qual o dashboard lê. Cada passagem de ingestão pode ser executada com --append para mesclar em um banco de dados existente; tokens são upserted (contagem de usos + tempo de vida observado acumulam), eventos e trocas são anexados, e o source_tag da linha registra cada passagem que viu o token.
• Dashboard web ao vivo servido por um servidor HTTP da stdlib. Consulta o banco de dados a cada 5 segundos e re-renderiza quando os dados subjacentes mudam — então uma captura CDP em execução atualiza o dashboard em quase tempo real.
• Sem dependências proprietárias para os caminhos principais. Ingestão do Burp, a camada de banco de dados, a UI web e a anexação CDP são todas apenas stdlib. A importação do mitmproxy é a única dependência opcional (pip install mitmproxy).

Classificação e enriquecimento de tokens

• Chaves de corpo OAuth (access_token, refresh_token, id_token) e heurísticas de nome de cookie determinam o tipo de token.
• Cookies de sessão da Microsoft (ESTSAUTH, ESTSAUTHPERSISTENT, ESTSAUTHLIGHT, SignInStateCookie) são explicitamente reconhecidos como tokens equivalentes a refresh (caso contrário seriam mal classificados pela dica genérica de cookie "auth").
• Claims JWT (header + payload) decodificadas e armazenadas literalmente — nunca truncadas.
• Microsoft FOCI (Family of Client IDs) detectado via o campo foci nas respostas do token-endpoint.
• Microsoft BroCI / Nested App Authentication detectado via brk_client_id, brk_redirect_uri, e esquemas de redirecionamento brk-<guid>:// no corpo da requisição.
• Flag opcional --enrich busca firstpartyscopes.json e resources.json de https://entrascopes.com/ e resolve GUIDs de appid / azp / aud em nomes amigáveis com links clicáveis.

Cards do dashboard

• Tiles de resumo — contagens de tokens, hosts, trocas (com destaques FOCI / BroCI), e um indicador de status de enriquecimento.
• Usuários — agrupamento de tokens por upn / preferred_username / unique_name / email / name, com fallback para sub@iss ou oid, e exibindo buckets de identidade app-only e desconhecida separadamente. Cada linha de identidade mostra um badge de capturas quando o usuário aparece em ≥2 source_tags (sobrevivência entre capturas, o principal sinal de pesquisa do --append) mais um intervalo first_seen → last_seen e um botão timeline que destaca cada token daquele usuário na aba de diagrama de Sequência.
• Validade de token — contagens de access tokens atualmente válidos vs expirados, status de expiração de refresh-token (com "expiração desconhecida" para tokens opacos), e uma lista top-3 "próximos a expirar" com auto-refresh de 30 segundos.
• Clients — cada app distinto (appid / azp / client_id no corpo do formulário / brk_client_id / brk_nested_id) que apareceu em trocas, com badges FOCI / brokerable / broker / nested.
• Audiences — cada claim aud observada, resolvida para nomes de recursos do entrascopes onde possível.
• Tenants — valores tid distintos com contagens de token / usuário / app.
• Hosts — eventos, destinatários bearer distintos, emissores distintos, e contagens de trocas por host.
• Escopos e roles privilegiados — verifica o scp / scope / roles de cada token contra uma watchlist curada de permissões de alto impacto do Microsoft Graph e escopos de recursos do Azure.
• Incompatibilidades de audience / host — sinaliza cada par (token, host) onde o token foi usado em um host que discorda de sua claim aud (sugere vazamento ou uso indevido de credencial).
• Métodos de autenticação (amr) — distribuição de pwd / mfa / pop / smartcard.
• Recursos de segurança — sinaliza Continuous Access Evaluation (xms_cc=CP1), vinculação proof-of-possession (claim cnf, com detecção de kid compartilhado entre audiences), requisitos de step-up auth (acrs), e o nível de contexto de autenticação acr. Cada linha é clicável e filtra a aba Tokens para apenas os tokens que carregam aquele marcador.
• Cadeias de refresh-token — percorre arestas de troca para identificar linhagens de rotação, comprimento da cadeia mais longa, e refresh tokens ociosos. Cada cadeia mostra uma coluna Δ scopes (escopos adicionados / removidos entre hops, com o diff completo por hop no hover) e sinaliza cadeias onde um escopo adicionado corresponde à watchlist de escopos privilegiados com um badge ⚠ priv — o sinal de pesquisa de expansão de privilégios no estilo FOCI / BroCI.
• Fontes — contagens de tokens por source_tag para que você veja quantas linhas vieram de cada passagem de ingestão.

Abas Tokens / Exchanges

• Clique em um cabeçalho de coluna para ordenar.
• Checkboxes de seleção múltipla acionam uma barra de ferramentas:
  • Highlight in Graph — destaque amarelo nos nós selecionados.
  • Isolate in Graph — redesenha o diagrama mostrando apenas os tokens selecionados mais os tokens com os quais eles trocam.
  • Show in Sequence — diagrama de sequência focado para o(s) token(s) selecionado(s).
• Clique em uma linha para expandir um painel inline com header + payload JWT completos (JSON bruto), todos os eventos, trocas relacionadas, botões de exportação prontos para replay (raw / Bearer / curl / JSON / cache de token roadtx), e um bloco de pré-visualização de comando com snippets copiáveis para roadtx describe, roadtx auth, curl, Python requests, e PowerShell Invoke-RestMethod.
• Filtros: chips de tipo (access / refresh / id / unknown), chips de formato (jwt / opaque), dropdown usado / não usado, dropdown de validade (any / valid / expired / unknown expiry), apenas FOCI, apenas BroCI, has-app-match, has-resource-match, mais uma busca de texto livre em fp / sample / claims / host / app / resource / source_tag / user.
• Exportação CSV / JSON das linhas atualmente filtradas + ordenadas.
• Persistência no hash da URL — a aba ativa e cada estado de filtro é serializado no hash da URL, então links para visões filtradas específicas são compartilháveis.

Suporte a WebSocket

• Capturas mitmproxy e CDP preservam cada payload de frame de texto / binário WebSocket. O conteúdo dos frames é escaneado em busca de tokens com o mesmo walker de JSON / form / raw-JWT que lida com corpos HTTP.
• Tokens encontrados em frames geram eventos com role ws-frame-sent / ws-frame-received, source ws[body_json[<key>]], e um ws_session_id que agrupa todos os frames dentro de uma conexão WebSocket.
• O handshake é capturado como um evento HTTP normal para que cookies / bearer tokens carregados no upgrade também sejam rastreados.

Privacidade

• O banco de dados armazena fingerprints SHA-256 (primeiros 12 caracteres hex) e um prefixo de 12 caracteres de cada token observado. Strings completas de token nunca saem do arquivo de entrada.

• O conteúdo das claims JWT decodificadas (header + payload, incluindo oid, sub, upn, email, tid, listas de escopo, etc.) é armazenado literalmente por padrão porque é exatamente o objetivo da análise. Trate o banco de dados e qualquer URL de dashboard compartilhada como sensível sempre que JWTs estiverem presentes.

• --redact-claims (disponível em ingest, mitm, e cdp) substitui valores de claims listados por placeholders de hash estáveis antes que cheguem ao banco de dados. A lista padrão de campos cobre sub, oid, upn, email, name, unique_name, preferred_username, emails, mail, ipaddr, given_name, family_name. Passe uma lista explícita separada por vírgulas (ex.: --redact-claims sub,upn,oid) para sobrescrever o padrão. A mesma entrada sempre mapeia para o mesmo placeholder, então o agrupamento de Usuários / Tenants do dashboard ainda funciona sem revelar o usuário.

• --store-tokens (disponível em ingest, mitm, e cdp, desativado por padrão) opta por escrever a string completa do token no banco de dados para que o dashboard possa oferecer:

  • Ações Copy raw / Copy Bearer / Copy curl.
  • Download do JSON do token (raw + claims + eventos observados).
  • Copy / Download como cache de token roadtools (coloque o arquivo em .roadtools_auth e qualquer subcomando roadtx o reconhece).
  • Um bloco de Command preview por token que pré-preenche as invocações de replay mais comuns — roadtx describe, roadtx auth, curl, Python requests, PowerShell Invoke-RestMethod — usando as claims reais de tid, appid, e do token.

Instalação

Requisitos

• Python 3.10+ (usa sintaxe de tipos compatível com match-statement e dataclasses modernas). Testado em 3.12.
• Sem etapa de build. Clone o repositório e execute python -m tats diretamente.

Dependências opcionais

Instalação rápida

Executar a partir de um checkout (sem instalação):```bash git clone tats cd tats python -m tats --help

Após a instalação, você pode chamar a ferramenta pelo seu nome curto:```bash tats ingest engagement.xml -o tokens.db --enrich tats serve tokens.db

Combine uma captura do Burp com um arquivo de fluxo do mitmproxy em um único DB:```bash tats ingest engagement.xml -o tokens.db --enrich tats mitm chat-session.mitm -o tokens.db --enrich --append tats serve tokens.db

O navegador iniciado é encerrado e seu perfil temporário é excluído quando você pressiona Ctrl-C no comando cdp.

Se você preferir se conectar a um navegador já em execução, inicie-o com --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile e execute cdp sem --launch-chrome.

Sanitize um banco de dados antes de compartilhá-lo (redação de 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

Exemplos:```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

Requer pip install mitmproxy. A ferramenta emitirá um erro claro se o pacote estiver ausente.

Capture um arquivo de fluxo com mitmproxy:```bash mitmdump -w session.mitm

... drive the browser ...

Ctrl-C to stop

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

Permitindo que a ferramenta inicie o navegador (--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

Um user-data-dir separado evita anexar a um perfil pessoal e impede que o navegador em execução recuse a flag de depuração.

Por padrão, o cdp anexa no nível do navegador e rastreia cada aba que existe quando ele inicia E cada aba aberta durante a execução (window.open, Ctrl-click, botão de nova aba). Todas as abas compartilham o único WebSocket através do multiplexador de sessão do protocolo flat do CDP, portanto, abrir ou fechar abas enquanto a captura está em execução é totalmente suportado. Cada anexação / desanexação de aba imprime uma nota de uma linha no stderr no nível INFO.

Se você preferir fixar em uma única aba e ter a anexação encerrada quando essa aba fechar, liste os alvos disponíveis:```bash curl http://127.0.0.1:9222/json/list

Exemplos:```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

Todo caminho de origem produz o mesmo objeto Tracker. ingest_to_db transforma-o em linhas na base de dados. Store lê a base de dados para o servidor HTTP, que expõe JSON em /api/data, /api/meta, /api/token/<fp>, /api/export, /api/graph e /api/sequence.

Esquema da base de dados (v4)

• tokens (chave primária fp) — fingerprint, prefixo da amostra, tipo, formato, tempo de vida observado, cabeçalho / payload JWT como JSON, campos de enriquecimento, campos derivados (user_identity, exp_unix, tenant_id, scopes_text), source_tag separado por vírgulas, raw (string completa do token, NULL a menos que ingerido com --store-tokens) e security_features (JSON compacto que descreve marcadores CAE / PoP / step-up detetados — ver o cartão Security features). Bases de dados v2 / v3 mais antigas migram automaticamente quando reabertas em modo append: v2 → v3 adiciona a coluna raw anulável; v3 → v4 adiciona a coluna security_features anulável e preenche-a a partir do jwt_payload_json armazenado de cada token na primeira abertura. Linhas pré-existentes mantêm ambas as colunas nos seus valores anteriores.
• events — cada interação de token observada: pedido / resposta HTTP ou frame WebSocket. Papéis: issued / returned / presented / used / exchanged-in / ws-frame-sent / ws-frame-received. Transporta ws_session_id para agrupar frames dentro de uma ligação.
• exchanges — quando um pedido portador de token a um endpoint de token produziu novos tokens na sua resposta. Regista metadados FOCI / BroCI.
• exchange_inputs, exchange_outputs — fingerprints de tokens em cada lado de cada exchange.
• hosts — etiquetas host:port distintas.
• meta — versão do esquema, lista de origens, generated_at, last_modified (usado pelo poll em direto do dashboard), contagens.

Etiquetagem de origem e modo append

Cada linha escrita na BD transporta um source_tag — por predefinição burp:<filename>, mitm:<filename> ou cdp:<host>:<port>, mas sobreponível via --source-tag. Quando o mesmo fingerprint é visto por mais do que uma passagem de ingestão, o campo source_tag acumula como uma lista separada por vírgulas, para que o cartão Sources do dashboard possa mostrar a proveniência de cada token.

--append mantém uma BD existente e faz merge nela via UPSERT para tokens (contagens de utilizações + tempo de vida observado acumulam, tipos desconhecidos são atualizados) e INSERT para events / exchanges (com os seus números seq deslocados para além do máximo existente, para que a linha temporal de atividade se mantenha monotónica). Incompatibilidade de versão do esquema recusa o merge para evitar perda silenciosa de dados.

Atualizações em direto

O endpoint /api/meta do servidor web devolve a tabela meta (~200 bytes). O dashboard faz poll a cada 5 segundos e só volta a obter o /api/data completo quando last_modified muda. O caminho de ingestão cdp descarrega o seu tracker em memória para a BD a cada 25 eventos por predefinição, pelo que a latência de relógio de parede desde um pedido do browser até uma atualização do dashboard é tipicamente < 10 segundos.

Limitações

• Ficheiros de projeto .burp do Burp não são suportados. Use Save items para produzir o XML que a ferramenta consome.
• Sem gestão de CA de proxy. Esta ferramenta não interceta TLS por si própria. Use-a a jusante do Burp / mitmproxy, ou use o caminho CDP que vê tráfego desencriptado de TLS a partir de dentro do browser.
• O attach CDP cobre alvos de página de topo. Iframes fora de processo (OOPIFs) e workers dedicados não são auto-anexados recursivamente, pelo que eventos que fluem através desses tipos de alvo podem ser perdidos. Para os fluxos Microsoft / OAuth em torno dos quais esta ferramenta foi construída, o attach à página de topo captura tudo o que importa.
• Sem verificação de assinatura em JWTs. A ferramenta descodifica claims para exibição; verificação de assinatura, alg=none e ataques de confusão de chaves estão fora do âmbito. Use um auditor de JWT dedicado para esses casos.
• Falsos positivos de tokens opacos. A heurística "isto é um token?" trata qualquer string URL-safe de 20+ caracteres em contextos com forma de OAuth como um token. IDs aleatórios longos podem ser incorretamente sinalizados. Tokens cujo tipo não pode ser inferido acabam como unknown e são ocultados por predefinição a menos que --include-unknown esteja definido na flag mais antiga (apenas Burp).
• --enrich faz pedidos HTTP de saída para https://entrascopes.com/. Ignore a flag se o seu ambiente não o permitir.
• A UI web não tem autenticação. Vincule-a a localhost a menos que tenha colocado outra camada de autenticação à frente.

Resolução de problemas

Desenvolvimento

Fixtures de smoke-test

Dois construtores de fixtures residem em 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

A suíte cobre extração de token, parsing de JWT, classificação de session-cookie da Microsoft, detecção de FOCI / BroCI, resumo de claims, redação de PII, o caminho de ingestão de XML do Burp com semântica de UPSERT em modo append, e o caminho de ingestão de frames WebSocket do mitmproxy (ignorado automaticamente quando a dependência opcional mitmproxy está ausente).```text $ pytest tests/ ============================= test session starts ============================= … ======================== 62 passed in 1.4s =================================

…e abra http://127.0.0.1:8765 manualmente. O servidor registra cada requisição e quaisquer erros de handler em stderr.

Estrutura de arquivos

O layout de arquivo único é intencional: a ferramenta foi feita para ser lida, auditada e inserida em investigações por qualquer pessoa com Python instalado. Não há configuração oculta, nenhuma árvore de dependências para avaliar e nenhuma superfície além do próprio arquivo.

Mantendo este README

Se você alterar subcomandos, schema, cards do dashboard ou a superfície pública da API (flags da CLI, endpoints /api/*), atualize as seções relevantes deste arquivo na mesma alteração. As seções com maior probabilidade de desatualização:

• Features — ao adicionar fontes de ingestão ou cards do dashboard
• Subcommands — ao alterar flags
• Microsoft-specific support — quando a lógica de detecção muda
• Architecture — quando o schema ou o fluxo de atualização ao vivo muda
• Troubleshooting — quando uma nova mensagem de erro é adicionada

Licença

GNU General Public License v3.0 ou posterior — texto completo no arquivo LICENSE na raiz do repositório. O código-fonte do script carrega o cabeçalho curto padrão apontando para o mesmo.

Você pode redistribuir e/ou modificar a ferramenta sob os termos da GPL v3 (ou qualquer versão posterior, a seu critério). Ela é distribuída sem qualquer garantia; consulte a LICENSE para os termos completos.

Ativar isso transforma o banco de dados em uma credencial completa — cada byte necessário para reproduzir qualquer sessão capturada está nele. Combine com --redact-claims para limpar a visão decodificada do JWT, mas esteja ciente de que o token bruto ainda carrega as claims não redigidas codificadas dentro dele. Quando a flag está desativada, o bloco de pré-visualização de comando do dashboard ainda é renderizado, apenas com <TOKEN> como placeholder para funcionar como uma referência de sintaxe; os botões de exportação renderizam uma dica para re-ingerir.