Voilà. Le shell présente un menu d'authentification unifié à 7 méthodes dès le premier lancement — choisissez-en une, authentifiez-vous, sélectionnez une machine, et vous êtes dans un REPL. Pas de fichier de configuration, pas de drapeaux, rien à configurer.```
  Select API mode:

    Internal API  (security.microsoft.com — near real-time, ~2-5s/cmd)
    1  Credentials + MFA        username + password, TOTP/push/SMS [auto-refresh]
    2  Software passkey          FIDO2/WebAuthn JSON key file [auto-refresh]
    3  ESTS cookie               ESTSAUTHPERSISTENT from browser (~24hr)
    4  Temporary Access Pass     one-time admin-issued code
    5  Direct sccauth + XSRF     cookies from browser DevTools (~1hr)

    Official API  (api.securitycenter.microsoft.com — CI/CD ready, ~20-60s/cmd)
    6  Device code               browser login (interactive)
    7  Client credentials        app registration with client secret

  Auth method (1-7):

`mode <target>` déconnecte toute session LR en cours, efface l'ancien état d'authentification et relance le flux d'authentification pour le mode cible. Quand il revient, vous êtes authentifié dans le nouveau mode sans machine sélectionnée — exécutez `machines` pour lister, ou `connect <name|id>` pour sauter directement vers une cible. Aucun redémarrage nécessaire.

### Raccourcis CLI (optionnel)

Pour le scripting ou quand vous voulez sauter le menu unifié :```powershell
# Pre-select the mode (narrows the auth menu to 1-5 or 6-7)
pwsh -File shell/Invoke-MDEShell.ps1 -Mode internal
pwsh -File shell/Invoke-MDEShell.ps1 -Mode official

# Pre-select a machine (skips the picker)
pwsh -File shell/Invoke-MDEShell.ps1 -Machine myhost

# Software passkey path (internal mode)
pwsh -File shell/Invoke-MDEShell.ps1 -PasskeyPath ./keys/passkey.json

# Non-interactive single command (exits with remote command's exit code)
pwsh -File shell/Invoke-MDEShell.ps1 -Machine myhost -Command 'whoami'

Schéma de configuration (tous les champs sont facultatifs sauf `official.tenantId` + `official.clientId` lors de l'utilisation d'identifiants client) :

| Section | Champ | Description |
|---------|-------|-------------|
| `official` | `tenantId` | ID du locataire Azure AD |
| `official` | `clientId` | ID client de l'inscription d'application |
| `official` | `clientSecret` | Secret client (omettre et définir `useDeviceCode: true` pour le code d'appareil) |
| `official` | `useDeviceCode` | `true` pour utiliser le flux de code d'appareil au lieu des identifiants client |
| `defaults` | `defaultMachine` | Présélectionner la machine au démarrage (sous-chaîne de nom ou préfixe d'ID) |
| `defaults` | `commandTimeoutSeconds` | Plafond de délai d'attente côté client. `0` = le serveur décide (jusqu'à 1800s). |
| `defaults` | `pollIntervalOfficial` | Intervalle d'interrogation de l'API officielle en secondes (défaut 2) |
| `defaults` | `pollIntervalInternal` | Intervalle d'interrogation de l'API interne en secondes (défaut 1) |

**Sécurité** : Restreignez les permissions du système de fichiers sur tout fichier de configuration contenant `clientSecret`. Le `clientSecret` n'est jamais accepté en ligne de commande — uniquement dans le fichier de configuration. Tous les identifiants en mode interne (nom d'utilisateur, mot de passe, secret TOTP, cookies) sont demandés de manière interactive et ne sont jamais persistés sur le disque.

---

## Méthodes d'authentification

L'interpréteur présente un menu d'authentification unifié à 7 méthodes au démarrage. Le mode (interne/officiel) est dérivé du choix.

| # | Mode | Méthode | Comment | Auto-rafraîchissement |
|---|------|--------|---------|------------------------|
| 1 | Interne | Identifiants + TOTP | Invite interactive | Oui (silencieux) -- uniquement lorsqu'un secret TOTP a été fourni. Avec MFA par notification push/SMS, la session ne peut pas s'auto-rafraîchir. |
| 2 | Interne | Passkey logiciel | paramètre `-PasskeyPath` ou invite | Oui (silencieux) |
| 3 | Interne | Cookie ESTS | Invite interactive | Non (~24h) |
| 4 | Interne | Temporary Access Pass | Invite interactive | Non (unique) |
| 5 | Interne | sccauth direct + XSRF | Invite interactive | Non (~1h) -- l'auto-rafraîchissement XSRF ne s'applique pas ; l'interpréteur n'auto-rafraîchit pas les cookies fournis directement. |
| 6 | Officiel | Code d'appareil | Connexion navigateur | Non (~1h) |
| 7 | Officiel | Identifiants client | Fichier de configuration | Oui (silencieux) |

La commande `connect` se réauthentifie lorsque la session expire, en utilisant la même méthode que celle initialement sélectionnée. Les méthodes sans auto-rafraîchissement invitent à nouveau de manière interactive.

**Gestion des identifiants en mémoire** : pour la méthode 1, le mot de passe et le secret TOTP fournis sont conservés en mémoire (sous forme de chaînes en clair, dans `$script:Int_ReauthParams`) pendant toute la durée de vie du processus de l'interpréteur, afin que la ré-authentification silencieuse puisse s'exécuter sans intervention. Les objets chaîne vivent dans l'espace d'exécution PowerShell ; ils ne sont pas sérialisés sur le disque ni passés en ligne de commande. Si cette exposition n'est pas acceptable pour votre modèle de menace, utilisez plutôt la méthode 2 (passkey/HSM) ou la méthode 7 (identifiants client).

---

## Commandes de l'interpréteur

### Contrôle de l'interpréteur

| Commande | Description |
|----------|-------------|
| `help [command]` | Afficher l'aide (éventuellement pour une commande spécifique) |
| `help commands` | Lister toutes les commandes LR natives avec descriptions |
| `status` | Afficher l'état de la connexion, l'état d'authentification, les informations de la machine |
| `config` | Afficher la configuration de Live Response |
| `connect [name\|id]` | Se réauthentifier (si expiré) et sélectionner une machine |
| `disconnect` | Déconnecter la session LR en cours et effacer la machine |
| `multi [options] <cmd>` | Exécuter une commande sur plusieurs machines (`-top N`, `-filter pattern`) |
| `session [list]` | Afficher les informations de la session en cours ou toutes les sessions mises en cache |
| `mode` | Afficher le mode API actuel |
| `mode internal\|official` | Basculer le mode API en ligne — déconnecte la session en cours, supprime l'ancien état d'authentification et réexécute le menu d'authentification pour le mode cible. Reprendre avec `machines` ou `connect` ensuite |
| `exit` / `quit` / `q` | Quitter l'interpréteur |

### Gestion des machines

| Commande | Description |
|----------|-------------|
| `machines [refresh]` | Lister les machines et en sélectionner une (refresh = forcer le rechargement) |
| `connect [name\|id]` | Se connecter à une machine par sous-chaîne de nom ou préfixe d'ID |

### Commandes Live Response natives (25 au total)

| Commande | Description |
|----------|-------------|
| `run <script> [args]` | Exécuter un script depuis la bibliothèque MDE |
| `getfile <path>` | Télécharger un fichier depuis la machine distante |
| `putfile <name>` | Téléverser un fichier de la bibliothèque dans le répertoire de travail distant |
| `processes` | Lister les processus en cours d'exécution |
| `connections` | Lister les connexions réseau actives |
| `cd <path>` | Changer de répertoire de travail (mode interne) |
| `dir [path]` | Lister le contenu du répertoire |
| `findfile <name>` | Rechercher un fichier par nom sur tous les lecteurs |
| `trace` | Afficher les informations de trace de diagnostic |
| `analyze <path>` | Soumettre un fichier pour analyse approfondie |
| `remediate <path>` | Mettre en quarantaine/corriger un fichier |
| `undo <actionId>` | Annuler une action de correction précédente |
| `registry <key>` | Interroger les clés/valeurs du registre (Windows uniquement) |
| `scheduledtasks` | Lister les tâches planifiées |
| `persistence` | Vérifier les emplacements de persistance courants |
| `drivers` | Lister les pilotes chargés (Windows uniquement) |
| `services` | Lister les services |
| `startupfolders` | Lister le contenu des dossiers de démarrage (Windows uniquement) |
| `fileinfo <path>` | Obtenir des informations détaillées sur un fichier |
| `prefetch` | Lister les données de préchargement (Windows uniquement) |
| `log` | Afficher les journaux de diagnostic |
| `jobs` | Lister les tâches d'arrière-plan (mode interne) |
| `fg <jobId>` | Mettre une tâche d'arrière-plan au premier plan (mode interne) |
| `library` | Gérer les fichiers de la bibliothèque (lister, téléverser, télécharger, supprimer) |
| `status` | Afficher l'état de la session et les diagnostics |

### Alias de commandes

| Alias | Résout en |
|-------|-----------|
| `ls` | `dir` |
| `ps` | `processes` |
| `download` | `getfile` |
| `process` | `processes` |
| `netstat` | `connections` |

### Commandes arbitraires

Toute entrée qui ne correspond pas à une commande intégrée est traitée comme une commande arbitraire et exécutée sur la machine distante via le stub d'exécution B64. Exemples : `whoami`, `ipconfig`, `cat /etc/hostname`.

- Cibles Windows : la commande est encodée en Base64 UTF-16-LE et exécutée via `executor_b64.ps1` (PowerShell ScriptBlock)
- Cibles Linux/macOS : la commande est encodée en Base64 UTF-8 et exécutée via `executor_b64.sh` (bash)

**Détection de pipeline** : les commandes contenant des pipes (`|`), points-virgules (`;`), redirections (`>>`) ou sous-expressions (`$(`) sont toujours encapsulées en B64, même si le premier mot est un verbe LR natif. Par exemple, `dir C:\ | Select-Object` passe par B64, pas par `dir` natif.

### Gestion de la bibliothèque

| Commande | Description |
|----------|-------------|
| `library` | Lister tous les fichiers de la bibliothèque MDE |
| `library refresh` | Forcer le rafraîchissement de la liste de la bibliothèque depuis l'API |
| `library upload <path>` | Téléverser un fichier local dans la bibliothèque |
| `library delete <name>` | Supprimer un fichier de la bibliothèque par nom |
| `library download <name>` | Télécharger le contenu d'un fichier depuis la bibliothèque (API interne : direct ; API officielle : via `getfile` depuis le cache de la bibliothèque du point de terminaison une fois une machine sélectionnée — la synchronisation peut prendre jusqu'à 10 min) |

### Gestion des actions

| Commande | Description |
|----------|-------------|
| `actions` | Lister les actions en attente/en cours pour la machine actuelle |
| `actions all` | Lister toutes les actions récentes sur toutes les machines |
| `actions cancel <id>` | Annuler une action par ID (correspondance partielle prise en charge) |

---

## Architecture

### API interne vs officielle

LaraC2 Shell expose deux chemins d'API indépendants vers le même backend Live Response de MDE. L'API interne reflète le modèle de session de type WebSocket du portail et fournit des réponses quasi en temps réel. L'API officielle utilise les points de terminaison REST documentés de Microsoft et est adaptée à l'automatisation.

| | API interne | API officielle |
|---|---|---|
| URL de base | `security.microsoft.com/apiproxy/mtp/liveResponseApi/` | `api.securitycenter.microsoft.com/api/` |
| Session | Persistante (keepalive de 30 min, reconnexion automatique) | Par commande (sans état) |
| Intervalle d'interrogation | ~1s (quasi temps réel) | 2s |
| Multi-commandes | Séquentielles dans une session partagée | Par lots (jusqu'à 5 par appel API) |
| Authentification | Autonome (ESTS/passkey/TOTP -> sccauth) | OAuth2 identifiants client ou code d'appareil |
| Délai d'attente par défaut | 1800s (le serveur décide, pas le client) | 1800s (le serveur décide, pas le client) |

#### Ce que LaraC2 ajoute au-delà de l'API brute

| Étape | API officielle brute | LaraC2 Shell |
|-------|---------------------|--------------|
| Téléversement du stub | Manuel : construire multipart, POST, gérer les conflits | Auto à la connexion, remplacement 409 |
| Encodage B64 | Manuel : choisir UTF-16LE/UTF-8 par OS | Détection automatique de l'OS, encodage automatique |
| Construction RunScript | Manuel : JSON avec paramètres ScriptName + Args | Taper la commande directement |
| Interrogation + récupération | Manuel : boucle + lien de téléchargement + analyse JSON | Transparent : retourne une sortie propre |
| Gestion des erreurs | Manuel : vérifier 400/401/403/409/429/503 | Automatique : nouvelle tentative, backoff, conseils |
| Multi-commandes | Manuel : construire un tableau Commands[] | Mise en lot automatique jusqu'à 5 |

### Contrainte clé

L'API officielle et l'API interne partagent une file d'actions par machine. Elles ne peuvent pas s'exécuter simultanément sur la même machine.

### Limitation de taux (transparente)

| Limite | Valeur | Gestion |
|--------|--------|---------|
| Commandes LR par minute | 10 | Réponse 429 avec en-tête Retry-After |
| Téléversements de bibliothèque par minute | 100 | File d'attente à fenêtre glissante |
| Téléversements de bibliothèque par heure | 1500 | Compteur horaire |
| HTTP 429 Too Many Requests | -- | Pause pour l'en-tête Retry-After (défaut 35s) |
| ActiveRequestAlreadyExists | -- | Annuler l'action conflictuelle + backoff fixe (10s, puis 15s jusqu'à 12 tentatives) |
| Expiration du jeton Bearer (officiel) | ~1 heure | Auto-rafraîchissement avant expiration |
| Expiration sccauth (interne) | ~1 heure | Ré-authentification silencieuse si les identifiants sont stockés |
| Inactivité de session LR | 30 minutes | Reconnexion automatique |
| Rotation XSRF | 4 minutes | Rafraîchissement transparent |

---

## Faisabilité d'un interpréteur quasi temps réel

Latences mesurées sur un locataire MDE de production, sur des cibles Windows, Linux et macOS :

| Opération | API interne | API officielle |
|-----------|-------------|----------------|
| `whoami` (B64) | 4-9s | 20-46s |
| `dir` (natif) | 2-4s | 14-25s |
| `processes` (natif) | 3-15s | 20-175s |
| `connections` (natif) | 2-4s | ~15s |
| `services` (natif) | 2-5s | ~15s |
| `hostname` (B64) | 4-7s | 11-16s |
| Connexion de session (première commande) | 9-15s | N/A (sans état) |
| Changement de machine | 7-10s | 15-30s |

**API interne : capable d'un quasi temps réel.** Avec la réutilisation de session, les commandes natives répondent en 2-5s. C'est aussi proche du temps réel que MDE le permet. Le goulot d'étranglement est l'agent SenseIR sur la cible, pas le framework.

**API officielle : adaptée à l'automatisation.** Minimum ~15s par commande en raison de l'architecture sans état (soumettre, interroger, récupérer). Bien adaptée pour l'automatisation par script et CI/CD, pas pour une utilisation interactive.

---

## Prise en charge multi-OS

Les points de terminaison Linux et macOS sont entièrement pris en charge via les deux modes API.

| OS cible | Moyenne API interne | Moyenne API officielle |
|----------|-------------------|------------------------|
| Windows | ~7s | ~30s |
| Linux | ~6s | ~26-33s |
| macOS | ~6s | ~26-33s |

**Ce qu'il faut surveiller** :

1. Les stubs `.sh` **doivent** avoir des fins de ligne Unix (LF, pas CRLF) sinon bash échoue avec « ambiguous redirect ».
2. Le téléversement de bibliothèque via l'API officielle ne **synchronise pas** les fichiers `.sh` vers les points de terminaison Linux/macOS. Téléversez d'abord via l'API interne (portail) ou l'interface du portail Defender. Une fois téléversé, RunScript via l'API officielle fonctionne.
3. `executor_b64.sh` fonctionne sur Linux et macOS une fois correctement téléversé.

---

## Tests

La suite de tests comprend 712 tests unitaires hors ligne, 301 tests d'intégration de l'API officielle, 251 tests d'intégration de l'API interne, ainsi qu'un pilote de test de stress configurable.

### Prérequis```powershell
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser

### Internal API Tests (requires portal cookies)

Integration tests covering sccauth auth, session lifecycle, all native commands, B64 execution, cross-OS targeting.```powershell
$env:LARAC2_SCCAUTH = 'your-sccauth-cookie'
$env:LARAC2_XSRF = 'your-xsrf-token'
Invoke-Pester ./tests/shell/LaraC2Shell.Internal.Tests.ps1 -Output Detailed

### CI/CD (GitHub Actions)

| Tâche | Déclencheur | Plateformes | Prérequis |
|-------|-------------|-------------|-----------|
| Analyse PSScriptAnalyzer | Chaque push/PR | Ubuntu | Aucun |
| Tests hors ligne | Chaque push/PR | Ubuntu + Windows + macOS | Aucun |
| Tests en ligne (officiel) | Conditionnel | Ubuntu | Variable `LARAC2_ONLINE_TESTS` + secret `LARAC2_CONFIG` |
| Tests manuels | Déclenchement manuel | Ubuntu | Secret `LARAC2_CONFIG` |

---

## Dépannage

| Erreur | Cause | Résolution |
|--------|-------|------------|
| `ActiveRequestAlreadyExists` | Une autre commande LR est en cours sur la cible | Géré automatiquement (mode officiel) : annulation de l'action conflictuelle + backoff fixe de 10s/15s jusqu'à 12 tentatives. Mode interne : attente seule. Aucune action utilisateur nécessaire. |
| HTTP 429 | Limite de débit dépassée (10 cmd/min) | Géré automatiquement : attend le délai Retry-After et réessaie. |
| « script not found » sur Linux/macOS | Le stub .sh n'est pas synchronisé sur le point de terminaison | Télécharger via l'API interne ou l'interface du portail Defender. Les téléchargements via l'API officielle ne synchronisent pas les fichiers .sh. |
| « ambiguous redirect » sur Linux/macOS | Le stub .sh a des fins de ligne CRLF | Réenregistrer avec des fins de ligne LF et retélécharger. |
| HTTP 400 sur une commande volumineuse | La charge utile B64 dépasse environ 30 Ko | Utiliser `library upload` + `run <script>` à la place. |
| HTTP 401 | Jeton/session expiré | Le shell se rafraîchit automatiquement pour les informations d'identification client, TOTP et passkey. Pour les autres méthodes, tapez `connect`. |
| HTTP 403 | Permissions insuffisantes | Mode officiel : vérifier les portées `Machine.LiveResponse` + `Library.Manage`. Mode interne : vérifier le rôle Security Operator. |
| HTTP 404 | Machine introuvable | Exécuter `machines refresh` pour recharger. |

---

## Prérequis

| Prérequis | Détail |
|-----------|--------|
| PowerShell Core | 7.0 ou ultérieur (`pwsh`) |
| Inscription d'application MDE | Requise pour le mode officiel (permissions `Machine.LiveResponse` + `Library.Manage`) |
| Système d'exploitation | Windows, Linux ou macOS (le shell s'exécute sur n'importe quel système ; les cibles peuvent être n'importe quel OS inscrit à MDE) |

Toute l'authentification est autonome – aucun module externe requis. Les flux d'authentification en mode interne sont basés sur [XDRInternals](https://github.com/MSCloudInternals/XDRInternals) par Fabian Bader & Nathan McNulty.

---

## Structure des fichiers```
shell/
  Invoke-MDEShell.ps1           Main shell entry point (REPL, dispatch, help)
  modules/
    Auth-Official.ps1           OAuth2 client credentials + device code
    Auth-Internal.ps1           Self-contained ESTS/passkey/TOTP/TAP authentication
    Auth-Crypto.ps1             Crypto helpers: TOTP, WebAuthn, passkey signing, Key Vault
    Rate-Limiter.ps1            429/backoff/ActiveRequest handling
    Invoke-LRCommand.ps1        Command execution (both modes, B64 stubs, multi-machine)
    Get-Machines.ps1            Machine list + picker
    Manage-Library.ps1          Library file management + auto-init stubs
    Manage-Actions.ps1          Action list/cancel
  config/
    shell-config.example.json   Config template (copy and fill in)

stubs/
  executor_b64.ps1              Windows PS B64 executor (auto-uploaded)
  executor_b64.sh               Linux/macOS bash B64 executor (auto-uploaded)

tests/
  shell/
    LaraC2Shell.Offline.Tests.ps1    Unit tests (no tenant needed)
    LaraC2Shell.Online.Tests.ps1     Integration tests (Official API)
    LaraC2Shell.Internal.Tests.ps1   Integration tests (Internal API)
    LaraC2Shell.Stress.Tests.ps1     Stress/throughput driver (configurable scenarios)

docs/
  USER_GUIDE.md                 Step-by-step usage guide
  COMMAND_REFERENCE.md          All commands, routing, batching
  ERROR_REFERENCE.md            Error messages and fixes
  PERFORMANCE_COMPARISON.md     Stress test data and API comparison