TATS — Token Analysis and Tracking System

Suivez les jetons OAuth 2.0, OIDC et Microsoft Entra ID à travers le trafic réseau capturé. Ingère les exports XML de Burp Suite, les fichiers de flux mitmproxy ou les flux live du Chrome DevTools Protocol dans une base de données SQLite unique, puis sert un tableau de bord web interactif pour filtrer les jetons, parcourir les échanges, repérer les scopes à risque, exporter les jetons pour rejeu et visualiser les cycles de vie des jetons sous forme de graphes Mermaid.

Statut : TATS est stable pour un usage personnel / en engagement. Optimisé pour l'écosystème Microsoft 365 / Entra (FOCI, BroCI/NAA, cookies de session ESTSAUTH, enrichissement entrascopes.com) mais fonctionne contre tout trafic OAuth/OIDC à peu près standard.

Pourquoi il existe

Lorsque vous proxifiez une longue session Microsoft 365 ou Azure via Burp / mitmproxy, la capture résultante est énorme et la plupart des outils soit :

N'affichent qu'un seul jeton à la fois (l'extension JWT de Burp), soit
Ne suivent pas le dialecte OAuth de Microsoft (FOCI, BroCI, cookies ESTSAUTH), soit
Ne suivent pas les trames WebSocket, où Teams / Skype / SignalR envoient des jetons, soit
Ne vous disent pas quels jetons sont encore valides à l'instant présent.

Cet outil extrait chaque jeton access / refresh / id observé, les empreinte pour pouvoir corréler le même jeton entre les sources, décode les claims JWT, résout les GUID de client / ressource Microsoft contre entrascopes.com, et restitue l'ensemble du tableau sous forme d'un seul tableau de bord — y compris une vue des chaînes de refresh-token qui suit les échanges inter-applications FOCI et l'émission de jetons d'applications imbriquées BroCI.

Ce projet est destiné principalement à des fins de recherche et d'éducation mais fournit des options telles que l'aperçu de commandes et les fonctionnalités d'export de jetons qui peuvent soutenir certains outils offensifs.

> **Avertissement :** l'interface web expose les charges utiles JWT décodées (claims), les empreintes de jetons, la chronologie d'activité et les graphiques Mermaid à quiconque peut atteindre l'adresse d'écoute. Si vous avez ingéré avec `--store-tokens`, elle expose également les **jetons bruts complets** via `/api/token/<fp>` et `/api/export?fps=...`. Il n'y a **aucune authentification**. Gardez `--host` sur `127.0.0.1` sauf si vous en décidez spécifiquement autrement. #### Export prêt pour le rejeu Lorsque la base de données a été construite avec `--store-tokens`, chaque jeton développé dans l'onglet Tokens obtient une rangée d'actions en un clic : * **Copier le brut** — la chaîne de jeton complète dans le presse-papiers. * **Copier l'en-tête Bearer** — `Authorization: Bearer <token>`, prêt à coller. * **Copier l'exemple curl** — une commande d'une ligne qui cible l'`aud` du jeton (ou son hôte émetteur) avec l'en-tête bearer attaché. * **Télécharger le JSON** — un fichier JSON à jeton unique contenant le brut, les claims, les événements observés et les échanges. * **Copier en roadtx** — la forme JSON d'un cache de jetons roadtools (`tokenType`, `accessToken` / `refreshToken` / `idToken`, `expiresOn`, `tenantId`, `_clientId`, `resource`, `foci`, `scope`). Collez directement dans un fichier `.roadtools_auth`. * **Télécharger .roadtools_auth** — même charge utile, téléchargée sous forme de fichier. Renommez-le en `.roadtools_auth` (ou passez-le via `roadtx <cmd> --tokens-file`) et n'importe quelle sous-commande roadtx le récupère. La barre d'outils de l'onglet Tokens dispose également de **Exporter la sélection pour le rejeu**, qui appelle `/api/export?fps=fp1,fp2,...` et télécharge un document JSON unique contenant jusqu'à 200 jetons (brut, claims, événements) en un seul lot. Sans `--store-tokens`, les mêmes boutons affichent une indication pour réingérer avant que l'export prêt pour le rejeu ne devienne possible. #### Aperçu des commandes Chaque jeton développé dispose également d'un bloc **Aperçu des commandes** repliable qui pré-remplit les invocations de rejeu / d'inspection les plus courantes en utilisant les claims réels du jeton (et la valeur brute complète lorsque `--store-tokens` est activé). Chaque extrait dispose d'un bouton Copier en un clic. Le mélange exact dépend du type de jeton : * **Tout JWT :** `roadtx describe -t '<token>'` (décoder sans réseau). * **Jetons d'actualisation :** * `roadtx auth --refresh-token '...' -c <client_id> -t <tenant_id>` — échanger un jeton d'actualisation contre de nouveaux jetons d'accès. * `curl -X POST .../oauth2/v2.0/token` — l'équivalent OAuth pour les utilisateurs qui n'utilisent pas roadtx. * **Jetons d'accès / id / inconnus :** * `curl -H 'Authorization: Bearer ...' '<aud>'` * Python `requests.get(...)` avec l'en-tête bearer défini. * PowerShell `Invoke-RestMethod` avec le même en-tête. * **Toujours :** l'objet JSON à déposer dans `.roadtools_auth`. Lorsque `--store-tokens` est désactivé, les extraits s'affichent avec `<TOKEN>` comme espace réservé afin que le panneau reste utile comme référence de documentation. --- ## L'interface web en détail ### Navigation supérieure `Summary | Tokens | Exchanges | FOCI | BroCI | Graph | Sequence` Chaque onglet est rendu indépendamment à partir du même instantané en mémoire de `/api/data`. Le changement d'onglet est instantané ; les diagrammes de graphe et de séquence sont re-rendus à la demande et respectent la sélection en cours dans l'onglet Tokens. ### Summary Des tuiles de statistiques en haut (tokens / access / refresh / id / unknown / used / unused / events / exchanges / FOCI exchanges / BroCI exchanges / hosts) suivies d'une grille de cartes décrites dans [Fonctionnalités → Cartes du tableau de bord](#dashboard-cards). Cliquez sur n'importe quelle ligne de n'importe quelle carte pour accéder à un onglet Tokens pré-filtré — par exemple, cliquer sur une ligne de locataire filtre l'inventaire sur les jetons portant ce `tid`. ### Tokens Inventaire filtrable et triable. La sélection multiple pilote les boutons de mise en surbrillance / isolement / séquence. Le développement d'une ligne affiche le JWT décodé complet (en-tête + charge utile en JSON brut), chaque événement impliquant ce jeton, et chaque échange où il était une entrée ou une sortie. ### Exchanges Liste triable de chaque échange jeton-contre-jeton détecté — rotations de jetons d'actualisation, échanges croisés FOCI et échanges d'applications imbriquées BroCI. La colonne BroCI affiche les ID client broker + imbriqué côte à côte avec la preuve qui a déclenché la détection. ### FOCI Deux tableaux : chaque jeton d'actualisation étiqueté avec une famille FOCI (actuellement Microsoft n'émet que `"1"`), et chaque échange dont la réponse portait le champ `foci`. ### BroCI Les échanges d'authentification d'application imbriquée. Pour chacun : l'application broker (`brk_client_id`), le client imbriqué (`client_id`), la preuve qui a déclenché la détection (`brk_client_id`, `brk_redirect_uri`, URI de redirection `brk-<guid>://`), et les empreintes des jetons d'entrée / sortie. ### Graph `flowchart LR` Mermaid des relations jeton ↔ service. Les jetons d'actualisation sont dessinés comme des cylindres, les jetons d'accès / id comme des stades. Les arêtes montrent l'émission, la présentation, l'échange et la rotation. La mise en surbrillance (depuis l'onglet Tokens) ajoute un accent jaune ; l'isolement re-rend le graphe avec uniquement les jetons sélectionnés et les jetons avec lesquels ils échangent. ### Sequence Diagramme de séquence Mermaid de chaque événement dans l'ordre de capture. Sélectionner un seul jeton n'affiche que sa séquence ; en sélectionner plusieurs conserve la vue complète mais met en vedette les jetons sélectionnés. Plafond d'événements maximum configurable (par défaut 200 ; les diagrammes de séquence Mermaid deviennent illisibles au-delà de quelques centaines de messages). --- ## Prise en charge spécifique à Microsoft ### Family of Client IDs (FOCI) Microsoft permet qu'un jeton d'actualisation émis pour une application d'une « famille » soit échangé au point de terminaison de jeton par **n'importe quelle autre application** de la même famille. L'outil détecte FOCI sur le réseau en analysant le JSON de réponse du point de terminaison de jeton pour un champ `foci` (actuellement toujours `"1"` pour la seule famille connue). Les jetons d'actualisation émis dans une telle réponse sont étiquetés avec l'identifiant de famille et exposés dans l'onglet **FOCI** dédié. Si `--enrich` est activé, la colonne app de l'inventaire expose également l'indicateur `foci: true/false` de `firstpartyscopes.json` — notez que cela peut être en désaccord avec la détection sur le réseau (le jeu de données entrascopes est parfois conservateur). Le champ `foci` sur le réseau est toujours le signal faisant autorité. ### Brokered Client Init / Nested App Authentication (BroCI / NAA) Les compléments Office, les applications Teams et le portail Azure utilisent NAA pour acquérir des jetons pour un client imbriqué via une application broker. L'outil détecte cela côté requête via : * le paramètre de formulaire `brk_client_id` (GUID de l'application broker), * le paramètre de formulaire `brk_redirect_uri` (URI de redirection réelle du broker), * un `redirect_uri` de la forme `brk-<guid>://...` (où `<guid>` est le broker). Le claim `appid` / `azp` du jeton d'accès résultant est le client imbriqué ; le broker n'apparaît que sur le réseau — jamais comme claim JWT. Le tableau de bord expose clairement les deux côtés. ### Cookies de session `ESTSAUTH` `ESTSAUTH`, `ESTSAUTHPERSISTENT`, `ESTSAUTHLIGHT` et `SignInStateCookie` sont des cookies de session Microsoft Entra qui ne voyagent pas dans `Authorization: Bearer` mais sont utilisés par le navigateur pour générer de nouveaux jetons d'accès via des flux d'authentification silencieuse. L'outil les étiquette comme `refresh` (leur rôle fonctionnel) au lieu de laisser la règle générique de sous-chaîne `auth` les mal classer comme `access`. ### Enrichissement entrascopes.com (`--enrich`) Récupère et met en cache `firstpartyscopes.json` (~2,8 Mo ; 504 applications first-party avec leur indicateur FOCI, URI de redirection, scopes et capacité broker) et `resources.json` (~170 Ko ; plus de 1 750 mappages ressource → nom d'affichage) depuis <https://entrascopes.com/>. Le cache réside dans : | Variable | Défaut | |---|---| | `$TATS_CACHE` | (priorité la plus élevée ; `$BURP_TOKEN_TRACKER_CACHE` est honoré comme solution de repli pour une migration d'une version) | | `$XDG_CACHE_HOME/tats` | (Linux/macOS) | | `%LOCALAPPDATA%\tats\cache` | (Windows) | | `~/.cache/tats` | (repli) | Le TTL est de 7 jours. Utilisez `--no-enrich-cache` pour forcer une nouvelle récupération. Le cache est réutilisé comme repli obsolète lorsque l'outil est exécuté hors ligne. Lorsque `--enrich` est activé, chaque GUID `appid` / `azp` / `client_id` et chaque claim `aud` GUID-ou-URL est résolu en un nom convivial avec un lien cliquable `https://entrascopes.com/?appId=<guid>`. --- ## Architecture ### One-shot : fichier → DB → interface web``` burp.xml ─┐ .mitm ─┼─→ Tracker ─→ ingest_to_db ─→ tokens.db ─→ Store ─→ /api/data ─→ dashboard CDP WS ─┘ ▲ │ (live, repeated) └───── --append upserts on every flush ─┘

Besoin	Installation
Sous-commande `mitm`	`pip install mitmproxy`
Capture live depuis Chrome / Edge	Aucune — utilise un client WebSocket de la stdlib
`--enrich` (entrascopes.com)	Aucune — utilise `urllib.request`

Symptôme	Cause probable	Correctif
`error: could not parse <file> as XML`	Tentative d'ingestion d'un fichier de projet `.burp` binaire	Dans Burp : Proxy → HTTP history → sélectionner les éléments → clic droit → Save items
`error: no <item> elements found`	Le XML n'a pas été produit par Save items de Burp	Réexportez depuis Burp ; l'élément racine doit être `<items>`
`error: cannot append to DB with schema_version 1`	La base de données a été créée par une version antérieure	Supprimez la base de données et réingérez les sources d'origine ; la migration de schéma n'est intentionnellement pas automatique
`error: the 'mitm' source needs the mitmproxy Python package`	mitmproxy n'est pas installé	`pip install mitmproxy`
`error: cannot reach Chrome at 127.0.0.1:9222`	Chrome n'a pas été démarré avec `--remote-debugging-port`	Voir l'incantation de lancement dans `cdp` subcommand
CDP s'attache mais aucun événement ne circule	La page n'a pas encore effectué de requêtes réseau, ou toute l'activité est dans un OOPIF / worker (non auto-attaché)	Rechargez la page ; confirmez que les onglets ont été enregistrés (cherchez les lignes de log `tab attached: …` sur stderr)
`no browser-level webSocketDebuggerUrl at /json/version`	La version de Chrome est trop ancienne pour le CDP au niveau navigateur, ou il a renvoyé une forme incorrecte	Mettez à jour Chrome, ou passez `--target <id>` pour utiliser l'attachement mono-onglet hérité
`target … has no webSocketDebuggerUrl`	Un autre débogueur (par ex. la fenêtre DevTools) est déjà attaché	Fermez DevTools, ou attachez-vous à une autre cible
Le tableau de bord affiche `Failed to load /api/data`	Le serveur ne peut pas lire le fichier de base de données	Vérifiez que le chemin de la base de données est correct, que le fichier est lisible et que la version du schéma correspond
Les mises à jour en direct cessent d'arriver	Le processus `cdp` s'est arrêté ou le vidage du tampon réseau ne s'est pas encore déclenché

Chemin	Rôle
`tats/__init__.py`	L'outil complet — parseurs, couche BD, serveur HTTP, client CDP ; charge le tableau de bord depuis `tats/static/`
`tats/__main__.py`	Point d'entrée pour `python -m tats` ; même logique que le script console `tats` installé
`tats/static/index.html`	Squelette HTML du tableau de bord avec les espaces réservés `{{CSS}}` / `{{JS}}`
`tats/static/style.css`	Style du tableau de bord — à modifier avec vos outils CSS habituels
`tats/static/app.js`	Logique du tableau de bord — à modifier avec vos outils JS habituels (LSP / lint / formateur)
`pyproject.toml`	Métadonnées d'empaquetage, extras optionnels (`[mitm]`, `[test]`, `[all]`), point d'entrée console
`LICENSE`	GNU General Public License v3
`README.md`	Ce fichier
`examples/`	Captures synthétiques + scripts de construction de fixtures (voir examples/README.md)
`examples/make_fixture.py`	Générateur XML Burp synthétique
`examples/make_mitm_fixture.py`	Générateur de fichier de flux mitmproxy synthétique
`examples/fixture.xml`	Fixture XML Burp pré-construite
`examples/fixture.mitm`	Fixture de flux mitmproxy pré-construite
`tests/`	Suite pytest (à exécuter avec `pytest`)

TATS

Populaires

Fonctionnalités

Cœur

Classification et enrichissement des jetons

Cartes du tableau de bord

Onglets Tokens / Exchanges

Prise en charge WebSocket

Confidentialité

Installation

Prérequis

Dépendances optionnelles

Installation rapide

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

fresh DB, with Microsoft enrichment

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

... drive the browser ...

Ctrl-C to stop

Laisser l'outil lancer le navigateur (`--launch-chrome`)```bash

auto-detect Chrome / Edge / Chromium / Brave

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

default — opens a browser tab automatically

bind to a different port without auto-launching the browser

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

Schéma de base de données (v4)

Étiquetage des sources et mode append

Mises à jour en direct

Limitations

Dépannage

Développement

Fixtures de smoke-test

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

mitmproxy flow fixture (HTTP + WebSocket frames carrying tokens)

Arborescence des fichiers

Maintenir ce README

Licence