╔╦╦╬╬╬╬╬╬╦╦╗
 ╔╬╬╬╝╝┘      ╚╝╝╬╬╬┐
╬╬╝╚╩╬╗╔          ╚╬╬╬

**Que peut réellement faire cet ID client + secret Entra ID ?**

Vous avez trouvé un identifiant d'application Entra ID (Azure AD) — un ID client et un secret —
lors d'un engagement autorisé, et le locataire auquel il appartient est dans le périmètre.
`secret_stalker` prend ces deux valeurs et vous indique, à froid :

1. **Est-il valide et quand le secret expire-t-il ?** — et s'il n'est pas valide, *pourquoi*
   (mauvais secret, secret expiré, application absente du locataire…). Pour un secret valide, il
   lit les `passwordCredentials` de l'inscription de l'application et rapporte la date d'expiration
   + les jours restants (nécessite une lecture de l'annuaire ; voir la note ci-dessous).
2. **Quels droits Microsoft Graph possède-t-il ?** — autorisations d'application lues
   directement depuis le jeton émis, plus les **rôles d'annuaire Entra** qu'il détient (même
   détectés passivement via la revendication `wids` du jeton) et les **objets qu'il possède**
   (applications / principaux de service auxquels vous pouvez ajouter des informations d'identification).
3. **Quel contrôle a-t-il sur Azure ?** — attributions de rôles RBAC au niveau des
   groupes de gestion et des abonnements.
4. **Peut-il atteindre des données réelles ?** — vérifications facultatives de l'accessibilité du plan de données
   de Key Vault (secrets / clés / certificats), Storage (blob / fichier / file d'attente / table) et Cosmos DB.
5. **Quel est l'impact ?** — permissions dangereuses, rôles, propriété et données accessibles
   mappés à des primitives connues d'élévation de privilèges / mouvement latéral, classés par sévérité,
   avec des scénarios concrets de **chemin d'attaque**.

Il s'authentifie avec un **secret client** ou un **certificat** (`--cert`),
et fonctionne avec les **clouds commerciaux et souverains** (`--cloud`).

Il est **passif par défaut** et **ne modifie jamais rien** — énumération en lecture seule
uniquement.

> ⚠️ **Test autorisé uniquement.** Exécutez-le uniquement contre des locataires qui sont
> explicitement dans le périmètre d'un engagement que vous êtes autorisé à effectuer.

---

## Installation```bash
pip install -r requirements.txt        # just runs it from source
#   — or —
pip install .                          # installs the `secret_stalker` command
pip install '.[cert]'                  # + certificate (--cert) auth support
pip install '.[dev]'                   # + pytest for the test suite

`--tenant` accepte soit un GUID de tenant, soit un domaine — un domaine est résolu automatiquement en son identifiant de tenant via le point de terminaison public de configuration OpenID.

### Gardez le secret hors de votre historique de shell

Transmettez les identifiants via des variables d'environnement plutôt que par des options :```bash
export SS_TENANT=contoso.onmicrosoft.com
export SS_CLIENT_ID=11111111-2222-3333-4444-555555555555
export SS_SECRET='<client-secret>'

python -m secret_stalker

L'authentification par certificat nécessite le paquet optionnel `cryptography` (`pip install '.[cert]'`).
L'outil signale l'expiration du certificat lui-même (correspondant à son empreinte dans `keyCredentials` de l'application), tout comme il le fait pour un secret. `--cert`/`--cert-password` sont également lus depuis `SS_CERT` / `SS_CERT_PASSWORD`.

### Clouds souverains et gouvernementaux

Par défaut, secret_stalker cible le cloud **commercial**. Pour les locataires souverains, passez `--cloud` (ou `SS_CLOUD`) afin que l'autorité Entra et les points de terminaison Graph / ARM / Key Vault correspondent — sinon des identifiants valides semblent ne donner aucun accès :```bash
# US Government (GCC High)
python -m secret_stalker --cloud usgov  --tenant contoso.onmicrosoft.us ...

# US DoD (L5)
python -m secret_stalker --cloud usdod  ...

# Azure operated by 21Vianet (China)
python -m secret_stalker --cloud china  --tenant contoso.partner.onmschina.cn ...

- **Acquisition de jeton** liste chaque audience sondée (Graph, ARM et — avec
  `--active`, lorsque des ressources correspondantes sont découvertes — Key Vault /
  Storage / Cosmos DB). Graph et ARM sont *indépendants* : une identité peut détenir
  l'un sans l'autre.
- **Secret** indique la validité et, pour un secret valide, la date d'expiration et
  les jours restants (la proximité de l'expiration est mise en évidence). Voir la
  note ci-dessous sur les secrets expirés.
- **Findings** est la section à lire en premier — permissions Graph à fort impact
  (`GRAPH`), rôles ARM (`ARM`), rôles d'annuaire Entra (`ROLE`), applications/SP
  possédés (`OWN`), surfaces data-plane accessibles (`DATA`) et cibles d'attaque par
  consentement demandées mais non consenties (`WANT`) — dédupliqués et classés par
  sévérité. Pouvoir lire chaque secret de Key Vault, ou détenir un rôle
  d'annuaire, constitue un résultat en soi, même sans octroi Graph/ARM dangereux.
- **Chemins d'attaque** transforment les principaux résultats en étapes concrètes
  (ex. *Privileged Role Administrator → assigner Global Administrator à soi-même →
  prise de contrôle du locataire*).
- **Énumération Graph active** (`--active`) rapporte ce que chaque sonde en
  lecture seule a renvoyé. La plupart des sondes demandent une petite page plafonnée,
  donc une page pleine est affichée comme `N+` (ex. `users  accessible  (returned 5+)`)
  — ce qui signifie *au moins* cinq, pas exactement cinq. Les sondes sans plafond
  (`organization`, `directoryRoles`) rapportent un total réel sans `+`.
- **Rôles d'annuaire / Objets possédés / Permissions déléguées** disposent de leurs
  propres sections. Les rôles d'annuaire sont détectés à partir de la revendication
  `wids` du jeton, même sans lecture d'annuaire ; les permissions déléguées ne sont
  pas utilisables par une identité applicative seule, mais sont affichées pour les
  pivots en contexte utilisateur et le ciblage d'attaques par consentement.
- **Risque global** correspond à la sévérité du résultat unique le plus élevé.

> **Expiration du secret — ce qui est connaissable.** La date d'expiration n'est *pas*
> dans le jeton ; elle réside dans `passwordCredentials` de l'enregistrement
> d'application dans Entra ID. Pour un secret **valide**, secret_stalker la lit via
> Graph et fait correspondre votre secret à la bonne identité via son `hint`
> (3 premiers caractères) — cela nécessite la lecture d'annuaire
> (`Application.Read.All` / `Directory.Read.All`) ; si le SP ne l'a pas, la date est
> indiquée comme indisponible plutôt que devinée. Pour un secret **expiré**,
> l'authentification elle-même échoue, donc l'identité morte ne peut pas lire ses
> propres métadonnées — l'outil la marque `EXPIRED (AADSTS7000222)` mais la date de
> fin exacte n'est pas récupérable via cette seule identité.

### Codes de sortie

Utiles pour les scripts :

| Code | Signification |
|------|---------|
| `0`  | L'identité est valide (au moins un jeton obtenu). |
| `2`  | L'identité est invalide / n'a aucun accès. |
| `1`  | Erreur — le locataire n'a pas pu être résolu, le certificat n'a pas pu être chargé, ou le fichier `--export` n'a pas pu être écrit. |

---

## Tous les drapeaux

| Drapeau | Effet |
|------|--------|
| `--tenant` | GUID ou domaine du locataire. (ou `SS_TENANT`) |
| `--cloud` | Cloud Azure : `public` (défaut), `usgov` (GCC High), `usdod` (DoD), `china` (21Vianet). Sélectionne l'autorité Entra et les points de terminaison Graph/ARM/Key Vault. Les alias comme `gov`/`dod`/`commercial` sont acceptés. (ou `SS_CLOUD`) |
| `--client-id` | ID d'application (client). (ou `SS_CLIENT_ID`) |
| `--secret` | Secret client. Préférez `SS_SECRET` pour le garder hors de l'historique. |
| `--cert` | Certificat pour l'authentification par assertion JWT au lieu d'un secret : un PEM (clé+certificat) ou `.pfx`/`.p12`. Nécessite `cryptography`. (ou `SS_CERT`) |
| `--cert-password` | Mot de passe pour une clé/PFX `--cert` chiffrée. (ou `SS_CERT_PASSWORD`) |
| `--active` | Énumération en lecture seule sur option : échantillons d'objets Graph **plus** accessibilité data-plane Key Vault / Storage. Désactivé par défaut pour rester discret. |
| `--deep` | Avec `--active` : descend d'un niveau dans le Storage accessible — liste les objets blob dans les conteneurs accessibles et les fichiers dans les partages accessibles (noms uniquement, plafonné). Plus bruyant. |
| `--no-arm` | Ignorer l'énumération des groupes de management / abonnements / RBAC (Graph uniquement). |
| `--workers N` | Workers HTTP parallèles pour les recherches de portée ARM et les sondes data-plane (défaut 8 ; `1` = séquentiel). |
| `--update-manifest` | Récupérer la carte autoritative appRole GUID→nom depuis le locataire actif (Graph **plus** toutes les autres API de ressources auxquelles cette identité est assignée), la mettre en cache, puis quitter. |
| `--json` | Afficher le résultat imbriqué complet en JSON au lieu du rapport. |
| `--export PATH` | Écrire les résultats dans un fichier. Le format est déduit de l'extension (`.csv` / `.ndjson` / `.jsonl` / `.json` / `.html`). Les fichiers sont écrits en propriétaire seul (`0600`). |
| `--export-format` | Forcer le format d'exportation (`ndjson` / `csv` / `json` / `html`). |
| `--timeout N` | Délai d'expiration par requête en secondes (défaut 20). Les requêtes du plan de contrôle ARM (énumération RBAC + découverte Resource Graph) utilisent un délai plus long — `1,5×`, minimum 30 s — car elles s'exécutent plus lentement. |
| `--verbose`, `-v` | Tracer chaque requête HTTP Graph/ARM/data-plane (méthode, URL, statut) sur stderr. |
| `--no-banner` | Supprimer la bannière ASCII. |
| `--version` | Afficher la version et quitter. |

---

## Exportation des résultats

`--export` aplatit le résultat en **un enregistrement par élément découvert** —
identité, jeton, permission Graph, assignation de rôle d'application, rôle ARM,
accès data-plane et résultat scoré — chacun portant le contexte de l'identité afin
qu'une ligne se suffise à elle-même.```bash
# NDJSON — stream into a SIEM / log pipeline
python -m secret_stalker --export results.ndjson

# CSV — open in a spreadsheet for triage
python -m secret_stalker --active --export results.csv

# Full nested JSON to a file
python -m secret_stalker --export results.json

Le rapport terminal et `--export` fonctionnent ensemble — l'exportation ne supprime pas le rapport (la confirmation "Exported …" va sur stderr, donc le pipe de `--json` reste propre).

Les fichiers d'exportation portent le contexte des identifiants (revendications du jeton, le `hint` du secret, identifiants de clé), ils sont donc écrits **réservés au propriétaire (`0600`)** pour éviter toute fuite sur un hôte partagé ou synchronisé. Traitez-les comme des artefacts d'engagement sensibles. L'écriture via un lien symbolique est refusée catégoriquement, de sorte qu'un chemin d'exportation ne peut pas être redirigé pour tronquer autre chose.

Les noms dans un résultat proviennent du locataire évalué — noms d'affichage des applications et des groupes, noms de conteneurs et d'objets blob — ils sont donc traités comme une sortie non fiable :

- **CSV** : les valeurs qui seraient lues comme une formule (commençant par `=`, `+`, `-`, `@`) sont préfixées par une apostrophe, de sorte qu'un nom d'affichage comme `=cmd|' /C calc'!A0` ne peut pas s'exécuter lorsque le fichier est ouvert dans un tableur. Les tableurs suppriment l'apostrophe à l'affichage.
- **Terminal, CSV et HTML** : la sortie a les caractères de contrôle supprimés, de sorte qu'un nom contenant des séquences d'échappement ANSI ne peut pas changer le titre de votre terminal ni écraser les résultats au-dessus — que vous lisiez le rapport en direct, `cat` le CSV ou `cat` le HTML.
- **JSON / NDJSON restent fidèles** : `json.dumps` encode les caractères de contrôle en `\uXXXX`, ce qui est inerte en tant que texte, tandis qu'un analyseur reconstitue toujours la valeur exacte renvoyée par le locataire. Le nom brut est une preuve, il est donc préservé ici.

---

## Comment les GUID d'autorisation sont résolus

`appRoleAssignments` reviennent sous forme de GUID. secret_stalker les résout en noms par une recherche à plat (les GUID d'appRole sont globalement uniques), ce qui continue de fonctionner **même lorsque les lectures d'annuaire sont refusées** :

- Une carte best-effort des autorisations Graph connues est fournie dans `secret_stalker/data/graph_app_roles.json`.
- `--update-manifest` la remplace par des données faisant autorité, récupérées en direct auprès du locataire évalué — Microsoft Graph **plus toutes les autres API de ressources auxquelles cet identifiant est affecté** (par ex. Exchange Online, SharePoint), de sorte que les GUID non-Graph sont également résolus.
- Un GUID inconnu est affiché **brut et signalé** — l'outil ne devine jamais un nom.

---

## Comment ça marche (en bref)

- **Validité + autorisations en une seule requête.** La revendication `roles` d'un jeton Graph valide *est* la liste des autorisations d'application accordées. secret_stalker la lit depuis le jeton décodé — rapide et discret, aucun appel Graph requis.
- **Graph ≠ ARM.** Ce sont des audiences de jeton différentes. Un identifiant peut avoir des droits sur l'un mais pas sur l'autre, donc chacun est testé indépendamment.
- **Plan de données ≠ plan de contrôle.** Avoir des droits ARM sur un Key Vault (gestion) n'est pas la même chose que pouvoir lire ses secrets (plan de données). Avec `--active`, l'accessibilité du plan de données est testée avec l'audience de jeton propre à la ressource — et elle liste **uniquement les noms** des objets, jamais les valeurs ni les contenus.
- **Sondage du plan de données par surface.** Le RBAC du plan de données est accordé par type d'objet / service, donc chacun est testé indépendamment : Key Vault **secrets / clés / certificats**, Storage **blob / fichier / file d'attente / table**, et Cosmos DB **bases de données**. Un identifiant qui est `Storage File Data SMB Share Reader` mais pas lecteur de blobs est détecté, pas manqué. (Cosmos utilise un en-tête REST AAD non standard et est **de meilleur effort** — validez un résultat `denied` avec un compte réel.)
- **Découverte à l'échelle du locataire.** Les ressources sont trouvées avec un seul balayage Azure Resource Graph sur chaque abonnement que le principal peut voir (respectant le RBAC), avec repli sur la liste des fournisseurs par abonnement si ARG est refusé. Le rapport indique quel chemin a été utilisé (`[discovery: resource-graph]` vs `per-subscription`). Le balayage parcourt les résultats jusqu'à une limite (40 pages × 1000 lignes par type de ressource) afin qu'une exécution se termine toujours ; `--verbose` le signale si la limite est atteinte.
- **Le mappage de sévérité** se trouve dans `secret_stalker/risk.py` — modifiez-le pour ajuster ce que votre équipe considère comme à fort impact.

---

## Structure du projet```
secret_stalker/
  clouds.py      Azure cloud endpoint table (public / usgov / usdod / china)
  auth.py        client_credentials flow + tenant discovery + AADSTS decoding
  jwt_utils.py   local JWT claim extraction
  manifest.py    Graph appRole GUID -> name resolution (bundled + live cache)
  graph.py       service principal lookup + appRole resolution + active probes
  arm.py         management-group / subscription RBAC + resource discovery
  dataplane.py   Key Vault / Storage data-plane reachability probes
  risk.py        permission/role/data-plane -> impact mapping (tune this)
  report.py      terminal + JSON output
  export.py      flatten to NDJSON / CSV / JSON records for ingestion
  util.py        shared HTTP (retry/backoff + safe JSON), pmap parallel map,
                 untrusted-output sanitizing
  banner.py      ASCII banner (stderr only)
  cli.py         orchestration
  data/graph_app_roles.json   bundled permission manifest
tests/           pytest suite (run: pytest)
pyproject.toml   packaging + `secret_stalker` console entry point