Características

Núcleo

• Tres fuentes de ingesta en una sola herramienta:
  • ingest — exportación XML "Save items" de Burp Suite
  • mitm — archivo de flujo .mitm de mitmproxy (tramas HTTP y WebSocket)
  • cdp — conexión en vivo a Chrome / Edge mediante el Protocolo DevTools (en tiempo real, captura tramas HTTP y WebSocket descifradas por TLS sin una CA de proxy; rastrea cada pestaña existente Y cada pestaña abierta durante la ejecución mediante auto-attach a nivel de navegador)
• Un único almacén SQLite canónico del que lee el panel. Cada pasada de ingesta puede ejecutarse con --append para fusionarse en una base de datos existente; los tokens se hacen upsert (el conteo de usos + el tiempo de vida observado se acumulan), los eventos y los intercambios se añaden, y el source_tag de la fila registra cada pasada que ha visto el token.
• Panel web en vivo servido por un servidor HTTP de la stdlib. Sondea la base de datos cada 5 segundos y vuelve a renderizar cuando los datos subyacentes cambian — así una captura CDP en ejecución actualiza el panel casi en tiempo real.
• Sin dependencias propietarias para las rutas principales. La ingesta de Burp, la capa de base de datos, la interfaz web y el attach CDP son todos solo stdlib. La importación de mitmproxy es la única dependencia opcional (pip install mitmproxy).

Clasificación y enriquecimiento de tokens

• Claves del cuerpo OAuth (access_token, refresh_token, id_token) y heurísticas de nombres de cookies determinan el tipo de token.
• Cookies de sesión de Microsoft (ESTSAUTH, ESTSAUTHPERSISTENT, ESTSAUTHLIGHT, SignInStateCookie) se reconocen explícitamente como tokens equivalentes a refresh (de lo contrario serían mal clasificados por la pista genérica de cookie "auth").
• Claims JWT (cabecera + payload) decodificadas y almacenadas textualmente — nunca truncadas.
• Microsoft FOCI (Family of Client IDs) detectado mediante el campo foci en las respuestas del endpoint de token.
• Microsoft BroCI / Nested App Authentication detectado mediante brk_client_id, brk_redirect_uri y esquemas de redirección brk-<guid>:// en el cuerpo de la solicitud.
• Flag opcional --enrich obtiene firstpartyscopes.json y resources.json de https://entrascopes.com/ y resuelve los GUID de appid / azp / aud en nombres amigables con enlaces clicables.

Tarjetas del panel

• Mosaicos de resumen — conteos de tokens, hosts, intercambios (con llamados a FOCI / BroCI) y un indicador de estado de enriquecimiento.
• Usuarios — agrupación de tokens por upn / preferred_username / unique_name / email / name, con fallback a sub@iss o oid, y mostrando por separado los grupos de solo aplicación e identidad desconocida. Cada fila de identidad muestra una insignia de capturas cuando el usuario aparece en ≥2 source_tags (supervivencia entre capturas, la señal de investigación principal de --append) más un lapso first_seen → last_seen y un botón de timeline que resalta cada token de ese usuario en la pestaña de diagrama de secuencia.
• Validez de tokens — conteos de tokens de acceso actualmente válidos vs expirados, estado de expiración de refresh-token (con "expiración desconocida" para tokens opacos), y una lista top-3 de "próximos a expirar" con auto-refresco cada 30 segundos.
• Clientes — cada aplicación distinta (appid / azp / client_id del cuerpo del formulario / brk_client_id / brk_nested_id) que ha aparecido en intercambios, con insignias de FOCI / brokerable / broker / anidada.
• Audiencias — cada claim aud observada, resuelta a nombres de recursos de entrascopes donde sea posible.
• Inquilinos — valores tid distintos con conteos de tokens / usuarios / aplicaciones.
• Hosts — eventos, destinatarios bearer distintos, emisores distintos y conteos de intercambios por host.
• Ámbitos y roles privilegiados — verifica el scp / scope / roles de cada token contra una lista de vigilancia curada de permisos de Microsoft Graph de alto impacto y ámbitos de recursos de Azure.
• Desajustes de audiencia / host — marca cada par (token, host) donde el token se usó en un host que no concuerda con su claim aud (sugiere fuga o mal uso de credenciales).
• Métodos de autenticación (amr) — distribución de pwd / mfa / pop / smartcard.
• Características de seguridad — marca Continuous Access Evaluation (xms_cc=CP1), vinculación proof-of-possession (claim cnf, con detección de kid compartido entre audiencias), requisitos de step-up auth (acrs) y el nivel de contexto de autenticación acr. Cada fila es clicable y filtra la pestaña Tokens para mostrar solo los tokens que llevan ese marcador.
• Cadenas de refresh-token — recorre las aristas de intercambio para identificar linajes de rotación, longitud de cadena más larga y refresh tokens inactivos. Cada cadena muestra una columna Δ scopes (ámbitos añadidos / eliminados entre saltos, con el diff completo por salto al pasar el cursor) y marca las cadenas donde un ámbito añadido coincide con la lista de vigilancia de ámbitos privilegiados con una insignia ⚠ priv — la señal de investigación de expansión de privilegios al estilo FOCI / BroCI.
• Fuentes — conteos de tokens por source_tag para que puedas ver cuántas filas provinieron de cada pasada de ingesta.

Pestañas Tokens / Exchanges

• Haz clic en el encabezado de una columna para ordenar.
• Las casillas de selección múltiple controlan una barra de herramientas:
  • Highlight in Graph — acento amarillo en los nodos seleccionados.
  • Isolate in Graph — redibuja el diagrama mostrando solo los tokens seleccionados más los tokens con los que intercambian.
  • Show in Sequence — diagrama de secuencia enfocado para el/los token(s) seleccionado(s).
• Haz clic en una fila para expandir un panel en línea con la cabecera + payload JWT completos (JSON sin procesar), todos los eventos, intercambios relacionados, botones de exportación listos para replay (raw / Bearer / curl / JSON / caché de tokens de roadtx) y un bloque de vista previa de comandos con fragmentos para copiar y pegar de roadtx describe, roadtx auth, curl, requests de Python y Invoke-RestMethod de PowerShell.
• Filtros: chips de tipo (access / refresh / id / unknown), chips de formato (jwt / opaque), menú desplegable used / unused, menú desplegable de validez (any / valid / expired / unknown expiry), solo FOCI, solo BroCI, has-app-match, has-resource-match, más una búsqueda de texto libre en fp / sample / claims / host / app / resource / source_tag / user.
• Exportación CSV / JSON de las filas actualmente filtradas + ordenadas.
• Persistencia en el hash de la URL — la pestaña activa y cada estado de filtro se serializan en el hash de la URL, para que los enlaces a vistas filtradas específicas sean compartibles.

Soporte de WebSocket

• Las capturas de mitmproxy y CDP preservan cada payload de trama WebSocket de texto / binaria. El contenido de las tramas se escanea en busca de tokens con el mismo recorredor de JSON / formulario / JWT sin procesar que maneja los cuerpos HTTP.
• Los tokens encontrados en tramas generan eventos con rol ws-frame-sent / ws-frame-received, origen ws[body_json[<key>]] y un ws_session_id que agrupa todas las tramas dentro de una conexión WebSocket.
• El handshake se captura como un evento HTTP normal, por lo que las cookies / tokens bearer transportados hacia el upgrade también se rastrean.

Privacidad

• La base de datos almacena huellas SHA-256 (primeros 12 caracteres hex) y un prefijo de 12 caracteres de cada token observado. Las cadenas de token completas nunca salen del archivo de entrada.

• El contenido de las claims JWT decodificadas (cabecera + payload, incluyendo oid, sub, upn, email, tid, listas de ámbitos, etc.) se almacena textualmente por defecto porque es el objetivo central del análisis. Trata la base de datos y cualquier URL de panel compartida como sensibles siempre que haya JWTs presentes.

• --redact-claims (disponible en ingest, mitm y cdp) reemplaza los valores de claims listados con marcadores de posición hash estables antes de que lleguen a la base de datos. La lista de campos predeterminada cubre sub, oid, upn, email, name, unique_name, preferred_username, emails, mail, ipaddr, given_name, family_name. Pasa una lista explícita separada por comas (p. ej. --redact-claims sub,upn,oid) para sobrescribir la predeterminada. La misma entrada siempre se asigna al mismo marcador de posición, por lo que la agrupación de Usuarios / Inquilinos del panel sigue funcionando sin revelar el usuario.

• --store-tokens (disponible en ingest, mitm y cdp, desactivado por defecto) opta por escribir la cadena de token completa en la base de datos para que el panel pueda ofrecer:

  • Acciones Copy raw / Copy Bearer / Copy curl.
  • Descargar JSON del token (raw + claims + eventos observados).
  • Copiar / Descargar como caché de tokens de roadtools (coloca el archivo en .roadtools_auth y cualquier subcomando de roadtx lo tomará).
  • Un bloque de Command preview por token que pre-rellena las invocaciones de replay más comunes — roadtx describe, roadtx auth, curl, requests de Python, Invoke-RestMethod de PowerShell — usando las claims reales de tid, y del token.

Instalación

Requisitos

• Python 3.10+ (usa sintaxis de tipos compatible con match-statement y dataclasses modernos). Probado en 3.12.
• Sin paso de compilación. Clona el repositorio y ejecuta python -m tats directamente.

Dependencias opcionales

Instalación rápida

Ejecutar desde un checkout (sin instalación):```bash git clone tats cd tats python -m tats --help

Después de instalar, puedes llamar a la herramienta por su nombre corto:```bash tats ingest engagement.xml -o tokens.db --enrich tats serve tokens.db

Combinar una captura de Burp con un archivo de flujo de mitmproxy en una sola base de datos:```bash tats ingest engagement.xml -o tokens.db --enrich tats mitm chat-session.mitm -o tokens.db --enrich --append tats serve tokens.db

El navegador lanzado se termina y su perfil temporal se elimina cuando pulsas Ctrl-C en el comando cdp.

Si prefieres conectarte a un navegador que ya está en ejecución, inícialo con --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile y ejecuta cdp sin --launch-chrome.

Sanitizar una base de datos antes de compartirla (redacción 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

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

Requiere pip install mitmproxy. La herramienta emitirá un error claro si falta el paquete.

Captura un archivo de flujo con mitmproxy:```bash mitmdump -w session.mitm

... drive the browser ...

Ctrl-C to stop

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

Permitir que la herramienta lance el 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

Un user-data-dir separado evita adjuntarse a un perfil personal y evita que el navegador en ejecución rechace el flag de depuración.

Por defecto, cdp se adjunta a nivel del navegador y rastrea cada pestaña que existe cuando se inicia Y cada pestaña abierta durante la ejecución (window.open, Ctrl-click, botón de nueva pestaña). Todas las pestañas comparten el único WebSocket a través del multiplexor de sesiones del protocolo plano de CDP, por lo que abrir o cerrar pestañas mientras la captura está en ejecución es totalmente compatible. Cada adjuntar / desadjuntar de pestaña imprime una nota de una línea en stderr a nivel INFO.

Si prefieres fijarte a una sola pestaña y que la conexión termine cuando esa pestaña se cierre, lista los objetivos disponibles:```bash curl http://127.0.0.1:9222/json/list

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

Cada ruta de origen produce el mismo objeto Tracker. ingest_to_db lo convierte en filas de la base de datos. Store lee la base de datos para el servidor HTTP, que expone JSON a través de /api/data, /api/meta, /api/token/<fp>, /api/export, /api/graph y /api/sequence.

Esquema de base de datos (v4)

• tokens (clave primaria fp) — huella, prefijo de muestra, tipo, formato, tiempo de vida observado, cabecera / payload JWT como JSON, campos de enriquecimiento, campos derivados (user_identity, exp_unix, tenant_id, scopes_text), source_tag separado por comas, raw (cadena de token completa, NULL a menos que se ingiera con --store-tokens) y security_features (JSON compacto que describe los marcadores CAE / PoP / step-up detectados — véase la tarjeta Security features). Las bases de datos v2 / v3 más antiguas se migran automáticamente al reabrirse en modo append: v2 → v3 añade la columna raw anulable; v3 → v4 añade la columna security_features anulable y la rellena desde el jwt_payload_json almacenado de cada token en la primera apertura. Las filas preexistentes mantienen ambas columnas con sus valores anteriores.
• events — cada interacción de token observada: petición / respuesta HTTP o frame WebSocket. Roles: issued / returned / presented / used / exchanged-in / ws-frame-sent / ws-frame-received. Lleva ws_session_id para agrupar frames dentro de una conexión.
• exchanges — cuando una petición con token a un endpoint de token produjo nuevos tokens en su respuesta. Registra metadatos FOCI / BroCI.
• exchange_inputs, exchange_outputs — huellas de token en cada lado de cada intercambio.
• hosts — etiquetas host:port distintas.
• meta — versión del esquema, lista de fuentes, generated_at, last_modified (usado por el sondeo en vivo del dashboard), recuentos.

Etiquetado de fuentes y modo append

Cada fila escrita en la BD lleva un source_tag — por defecto burp:<filename>, mitm:<filename> o cdp:<host>:<port>, pero sobrescribible mediante --source-tag. Cuando la misma huella es vista por más de una pasada de ingesta, el campo source_tag se acumula como una lista separada por comas, de modo que la tarjeta Sources del dashboard puede mostrar la procedencia de cada token.

--append conserva una BD existente y fusiona en ella mediante UPSERT para tokens (el recuento de usos + el tiempo de vida observado se acumulan, los tipos desconocidos se actualizan) e INSERT para eventos / exchanges (con sus números seq desplazados más allá del máximo existente, para que la línea temporal de actividad se mantenga monótona). La discrepancia de versión del esquema rechaza la fusión para prevenir la pérdida silenciosa de datos.

Actualizaciones en vivo

El endpoint /api/meta del servidor web devuelve la tabla meta (~200 bytes). El dashboard lo sondea cada 5 segundos y solo vuelve a obtener el /api/data completo cuando last_modified cambia. La ruta de ingesta cdp vuelca su tracker en memoria a la BD cada 25 eventos por defecto, por lo que la latencia de reloj de pared desde una petición del navegador hasta una actualización del dashboard es típicamente < 10 segundos.

Limitaciones

• Los archivos de proyecto .burp de Burp no son compatibles. Use Save items para producir el XML que consume la herramienta.
• Sin gestión de CA de proxy. Esta herramienta no intercepta TLS por sí misma. Úsela aguas abajo de Burp / mitmproxy, o use la ruta CDP que ve tráfico descifrado por TLS desde dentro del navegador.
• La conexión CDP cubre los targets de página de nivel superior. Los iframes fuera de proceso (OOPIFs) y los workers dedicados no se conectan automáticamente de forma recursiva, por lo que los eventos que fluyen a través de esos tipos de target pueden perderse. Para los flujos de Microsoft / OAuth en torno a los cuales está construida esta herramienta, la conexión de página de nivel superior captura todo lo que importa.
• Sin verificación de firma en los JWT. La herramienta decodifica las claims para mostrarlas; la comprobación de firmas, alg=none y los ataques de confusión de claves quedan fuera del alcance. Use un auditor de JWT dedicado para eso.
• Falsos positivos de tokens opacos. La heurística de "¿es esto un token?" trata cualquier cadena segura para URL de 20+ caracteres en contextos con forma de OAuth como un token. Los IDs aleatorios largos pueden marcarse incorrectamente. Los tokens cuyo tipo no puede inferirse acaban como unknown y se ocultan por defecto a menos que se establezca --include-unknown en el flag más antiguo (solo para Burp).
• --enrich realiza peticiones HTTP salientes a https://entrascopes.com/. Omita el flag si su entorno no lo permite.
• La interfaz web no tiene autenticación. Vincúlela a localhost a menos que haya puesto otra capa de autenticación delante.

Solución de problemas

Desarrollo

Fixtures de prueba de humo

Hay dos constructores de fixtures en 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

La suite cubre la extracción de tokens, el análisis de JWT, la clasificación de cookies de sesión de Microsoft, la detección de FOCI / BroCI, el resumen de claims, la redacción de PII, la ruta de ingesta de XML de Burp con semántica UPSERT en modo append, y la ruta de ingesta de frames WebSocket de mitmproxy (omitida automáticamente cuando la dependencia opcional mitmproxy no está presente).```text $ pytest tests/ ============================= test session starts ============================= … ======================== 62 passed in 1.4s =================================

…y abre http://127.0.0.1:8765 manualmente. El servidor registra cada petición y cualquier error del manejador en stderr.

Estructura de archivos

La estructura de archivo único es deliberada: la herramienta está pensada para ser leída, auditada y usada en investigaciones por cualquiera que tenga Python instalado. No hay configuración oculta, ni árbol de dependencias que evaluar, ni ninguna superficie más allá del propio archivo.

Mantener este README

Si cambias subcomandos, esquema, tarjetas del dashboard o la superficie de API pública (flags de CLI, endpoints /api/*), actualiza las secciones relevantes de este archivo en el mismo cambio. Las secciones con más probabilidad de quedar desactualizadas:

• Features — al añadir fuentes de ingesta o tarjetas del dashboard
• Subcommands — al cambiar flags
• Microsoft-specific support — cuando cambia la lógica de detección
• Architecture — cuando cambia el esquema o el flujo de actualización en vivo
• Troubleshooting — cuando aparece un nuevo mensaje de error

Licencia

GNU General Public License v3.0 o posterior — texto completo en el archivo LICENSE en la raíz del repositorio. El código fuente del script incluye el encabezado corto estándar que apunta al mismo.

Puedes redistribuir y/o modificar la herramienta bajo los términos de la GPL v3 (o cualquier versión posterior, a tu elección). Se distribuye sin ninguna garantía; consulta la LICENSE para los términos completos.

Activar esto convierte la base de datos en una credencial al por mayor — cada byte necesario para reproducir cualquier sesión capturada está en ella. Combínalo con --redact-claims para limpiar la vista JWT decodificada, pero ten en cuenta que el token sin procesar aún lleva las claims sin redactar codificadas dentro de él. Cuando el flag está desactivado, el bloque de vista previa de comandos del panel aún se renderiza, solo que con <TOKEN> como marcador de posición para que funcione como referencia de sintaxis; los botones de exportación muestran una pista para re-ingerir.