Questo è tutto. La shell presenta un menu di autenticazione unificato con 7 metodi al primo avvio — scegline uno, autenticati, seleziona una macchina e sei in una REPL. Nessun file di configurazione, nessun flag, niente da configurare.```
  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>` disconnette qualsiasi sessione LR corrente, cancella il vecchio stato di autenticazione e riesegue il flusso di autenticazione per la modalità target. Quando termina, sei autenticato nella nuova modalità senza una macchina selezionata — esegui `machines` per elencare, o `connect <name|id>` per passare direttamente a un target. Non è necessario un riavvio.

### Scorciatoie CLI (opzionali)

Per lo scripting o quando vuoi saltare il menu unificato:```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'

Schema di configurazione (tutti i campi opzionali tranne `official.tenantId` + `official.clientId` quando si usano le credenziali client):

| Sezione | Campo | Descrizione |
|---------|-------|-------------|
| `official` | `tenantId` | ID tenant di Azure AD |
| `official` | `clientId` | ID client della registrazione app |
| `official` | `clientSecret` | Segreto client (omettere e impostare `useDeviceCode: true` per il flusso del codice dispositivo) |
| `official` | `useDeviceCode` | `true` per utilizzare il flusso del codice dispositivo invece delle credenziali client |
| `defaults` | `defaultMachine` | Pre-seleziona la macchina all'avvio (sottostringa del nome o prefisso dell'ID) |
| `defaults` | `commandTimeoutSeconds` | Limite di timeout lato client. `0` = decide il server (fino a 1800s). |
| `defaults` | `pollIntervalOfficial` | Intervallo di polling dell'API ufficiale in secondi (default 2) |
| `defaults` | `pollIntervalInternal` | Intervallo di polling dell'API interna in secondi (default 1) |

**Sicurezza**: Limitare i permessi del filesystem su qualsiasi file di configurazione contenente `clientSecret`. Il `clientSecret` non viene mai accettato tramite riga di comando — solo tramite file di configurazione. Tutte le credenziali della modalità interna (nome utente, password, segreto TOTP, cookie) vengono richieste in modo interattivo e mai salvate su disco.

---

## Metodi di autenticazione

La shell presenta un menu di autenticazione unificato a 7 metodi all'avvio. La modalità (interna/ufficiale) viene derivata dalla scelta.

| # | Modalità | Metodo | Come | Aggiornamento automatico |
|---|----------|--------|------|--------------------------|
| 1 | Interna | Credenziali + TOTP | Richiesta interattiva | Sì (silenzioso) – solo quando è stato fornito un segreto TOTP. Con MFA push/SMS la sessione non può aggiornarsi automaticamente. |
| 2 | Interna | Passkey software | Parametro `-PasskeyPath` o richiesta | Sì (silenzioso) |
| 3 | Interna | Cookie ESTS | Richiesta interattiva | No (~24 ore) |
| 4 | Interna | Pass di accesso temporaneo | Richiesta interattiva | No (monouso) |
| 5 | Interna | sccauth diretto + XSRF | Richiesta interattiva | No (~1 ora) – l'aggiornamento automatico XSRF non si applica; la shell non aggiorna automaticamente i cookie forniti direttamente. |
| 6 | Ufficiale | Codice dispositivo | Accesso tramite browser | No (~1 ora) |
| 7 | Ufficiale | Credenziali client | File di configurazione | Sì (silenzioso) |

Il comando `connect` riautentica alla scadenza della sessione, utilizzando lo stesso metodo selezionato inizialmente. I metodi senza aggiornamento automatico richiedono di nuovo in modo interattivo.

**Gestione delle credenziali in memoria**: per il metodo 1, la password fornita e il segreto TOTP vengono conservati in memoria (come stringhe semplici, all'interno di `$script:Int_ReauthParams`) per l'intera durata del processo della shell, in modo che la riautenticazione silenziosa possa essere eseguita senza intervento. Gli oggetti stringa vivono nello spazio di esecuzione di PowerShell; non vengono serializzati su disco né passati sulla riga di comando. Se questa esposizione non è accettabile per il tuo modello di minaccia, utilizza invece il metodo 2 (passkey/HSM) o il metodo 7 (credenziali client).

---

## Comandi della Shell

### Controllo della Shell

| Comando | Descrizione |
|---------|-------------|
| `help [command]` | Mostra aiuto (opzionalmente per un comando specifico) |
| `help commands` | Elenca tutti i comandi LR nativi con descrizione |
| `status` | Mostra stato connessione, stato autenticazione, info macchina |
| `config` | Mostra configurazione di Live Response |
| `connect [name\|id]` | Riautentica (se scaduto) e seleziona una macchina |
| `disconnect` | Disconnette la sessione LR corrente e cancella la macchina |
| `multi [options] <cmd>` | Esegue comando su più macchine (`-top N`, `-filter pattern`) |
| `session [list]` | Mostra informazioni sulla sessione corrente o tutte le sessioni in cache |
| `mode` | Mostra la modalità API corrente |
| `mode internal\|official` | Cambia modalità API inline — disconnette la sessione corrente, smantella il vecchio stato di autenticazione e ripropone il menu di autenticazione per la modalità di destinazione. Proseguire con `machines` o `connect` |
| `exit` / `quit` / `q` | Esce dalla shell |

### Gestione Macchine

| Comando | Descrizione |
|---------|-------------|
| `machines [refresh]` | Elenca le macchine e ne seleziona una (refresh = forza ricarica) |
| `connect [name\|id]` | Si connette a una macchina per sottostringa del nome o prefisso dell'ID |

### Comandi Nativa di Live Response (25 totali)

| Comando | Descrizione |
|---------|-------------|
| `run <script> [args]` | Esegue uno script dalla libreria MDE |
| `getfile <path>` | Scarica un file dalla macchina remota |
| `putfile <name>` | Carica un file della libreria nella directory di lavoro remota |
| `processes` | Elenca i processi in esecuzione |
| `connections` | Elenca le connessioni di rete attive |
| `cd <path>` | Cambia directory di lavoro (modalità interna) |
| `dir [path]` | Elenca il contenuto della directory |
| `findfile <name>` | Cerca un file per nome su tutte le unità |
| `trace` | Mostra informazioni di traccia diagnostica |
| `analyze <path>` | Invia un file per analisi approfondita |
| `remediate <path>` | Mette in quarantena/ripara un file |
| `undo <actionId>` | Annulla un'azione di correzione precedente |
| `registry <key>` | Interroga chiavi/valori del registro (solo Windows) |
| `scheduledtasks` | Elenca le attività pianificate |
| `persistence` | Controlla le posizioni comuni di persistenza |
| `drivers` | Elenca i driver caricati (solo Windows) |
| `services` | Elenca i servizi |
| `startupfolders` | Elenca il contenuto delle cartelle di avvio (solo Windows) |
| `fileinfo <path>` | Ottiene informazioni dettagliate sul file |
| `prefetch` | Elenca i dati prefetch (solo Windows) |
| `log` | Visualizza i log diagnostici |
| `jobs` | Elenca i job in background (modalità interna) |
| `fg <jobId>` | Porta in primo piano un job in background (modalità interna) |
| `library` | Gestisce i file della libreria (elenca, carica, scarica, elimina) |
| `status` | Mostra stato sessione e diagnostica |

### Alias dei Comandi

| Alias | Risolve in |
|-------|------------|
| `ls` | `dir` |
| `ps` | `processes` |
| `download` | `getfile` |
| `process` | `processes` |
| `netstat` | `connections` |

### Comandi Arbitrari

Qualsiasi input che non corrisponda a un comando incorporato viene trattato come comando arbitrario ed eseguito sulla macchina remota tramite lo stub esecutore B64. Esempi: `whoami`, `ipconfig`, `cat /etc/hostname`.

- Destinazioni Windows: il comando è codificato in Base64 UTF-16-LE ed eseguito tramite `executor_b64.ps1` (ScriptBlock di PowerShell)
- Destinazioni Linux/macOS: il comando è codificato in Base64 UTF-8 ed eseguito tramite `executor_b64.sh` (bash)

**Rilevamento pipeline**: i comandi contenenti pipe (`|`), punti e virgola (`;`), redirect (`>>`) o sottoespressioni (`$(`) vengono sempre incapsulati in B64, anche se la prima parola è un verbo LR nativo. Ad esempio, `dir C:\ | Select-Object` passa attraverso B64, non il nativo `dir`.

### Gestione Libreria

| Comando | Descrizione |
|---------|-------------|
| `library` | Elenca tutti i file nella libreria MDE |
| `library refresh` | Forza l'aggiornamento dell'elenco libreria dall'API |
| `library upload <path>` | Carica un file locale nella libreria |
| `library delete <name>` | Elimina un file dalla libreria per nome |
| `library download <name>` | Scarica il contenuto di un file dalla libreria (API interna: diretto; API ufficiale: tramite `getfile` dalla cache libreria dell'endpoint una volta selezionata una macchina — la sincronizzazione può richiedere fino a 10 min) |

### Gestione Azioni

| Comando | Descrizione |
|---------|-------------|
| `actions` | Elenca le azioni in sospeso/in corso per la macchina corrente |
| `actions all` | Elenca tutte le azioni recenti su tutte le macchine |
| `actions cancel <id>` | Annulla un'azione per ID (supporto corrispondenza parziale) |

---

## Architettura

### API Interna vs Ufficiale

LaraC2 Shell espone due percorsi API indipendenti allo stesso backend di Live Response di MDE. L'API interna replica il modello di sessione simile a WebSocket del portale e fornisce risposte quasi in tempo reale. L'API ufficiale utilizza gli endpoint REST documentati di Microsoft ed è adatta per l'automazione.

| | API Interna | API Ufficiale |
|---|---|---|
| URL base | `security.microsoft.com/apiproxy/mtp/liveResponseApi/` | `api.securitycenter.microsoft.com/api/` |
| Sessione | Persistente (keepalive 30 min, riconnessione automatica) | Per comando (senza stato) |
| Intervallo di polling | ~1s (quasi in tempo reale) | 2s |
| Multi-comando | Sequenziale all'interno di una sessione condivisa | In batch (fino a 5 per chiamata API) |
| Autenticazione | Autonoma (ESTS/passkey/TOTP → sccauth) | OAuth2 credenziali client o codice dispositivo |
| Timeout predefinito | 1800s (decide il server, non il client) | 1800s (decide il server, non il client) |

#### Cosa aggiunge LaraC2 oltre all'API grezza

| Passo | API Ufficiale Grezza | LaraC2 Shell |
|-------|----------------------|-------------|
| Caricamento stub | Manuale: creare multipart, POST, gestire conflitti | Automatico alla connessione, override 409 |
| Codifica B64 | Manuale: scegliere UTF-16LE/UTF-8 per OS | Rilevamento automatico dell'OS, codifica automatica |
| Costruzione RunScript | Manuale: JSON con parametri ScriptName + Args | Digitare il comando direttamente |
| Polling e recupero | Manuale: ciclo + link download + parsing JSON | Trasparente: restituisce output pulito |
| Gestione errori | Manuale: controllare 400/401/403/409/429/503 | Automatico: retry, backoff, guida |
| Multi-comando | Manuale: costruire array Commands[] | Raggruppamento automatico fino a 5 |

### Vincolo chiave

L'API ufficiale e l'API interna condividono una coda di azioni per macchina. Non possono essere eseguite simultaneamente sulla stessa macchina.

### Limitazione della Frequenza (Trasparente)

| Limite | Valore | Gestione |
|--------|-------|----------|
| Comandi LR al minuto | 10 | Risposta 429 con intestazione Retry-After |
| Caricamenti libreria al minuto | 100 | Coda a finestra scorrevole |
| Caricamenti libreria all'ora | 1500 | Contatore orario |
| HTTP 429 Troppe Richieste | -- | Attesa per intestazione Retry-After (default 35s) |
| ActiveRequestAlreadyExists | -- | Annulla azione in conflitto + backoff fisso (10s, poi 15s fino a 12 tentativi) |
| Scadenza token Bearer (ufficiale) | ~1 ora | Aggiornamento automatico prima della scadenza |
| Scadenza sccauth (interna) | ~1 ora | Riautenticazione silenziosa se le credenziali sono memorizzate |
| Inattività sessione LR | 30 minuti | Riconnessione automatica |
| Rotazione XSRF | 4 minuti | Aggiornamento trasparente |

---

## Fattibilità di una Shell Quasi in Tempo Reale

Latenze misurate su un tenant MDE di produzione, su destinazioni Windows, Linux e macOS:

| Operazione | API Interna | API Ufficiale |
|------------|-------------|--------------|
| `whoami` (B64) | 4-9s | 20-46s |
| `dir` (nativa) | 2-4s | 14-25s |
| `processes` (nativa) | 3-15s | 20-175s |
| `connections` (nativa) | 2-4s | ~15s |
| `services` (nativa) | 2-5s | ~15s |
| `hostname` (B64) | 4-7s | 11-16s |
| Connessione sessione (primo comando) | 9-15s | N/A (senza stato) |
| Cambio macchina | 7-10s | 15-30s |

**API Interna: capace di quasi tempo reale.** Con il riutilizzo della sessione, i comandi nativi rispondono in 2-5s. Questo è il più vicino possibile al tempo reale che MDE consente. Il collo di bottiglia è l'agente SenseIR sul target, non il framework.

**API Ufficiale: grado automazione.** Minimo ~15s per comando a causa dell'architettura senza stato (invio, polling, recupero). Adatto per automazione scriptata e CI/CD, non per uso interattivo.

---

## Supporto Multi-OS

Gli endpoint Linux e macOS sono completamente supportati tramite entrambe le modalità API.

| SO di destinazione | Media API Interna | Media API Ufficiale |
|-------------------|------------------|-------------------|
| Windows | ~7s | ~30s |
| Linux | ~6s | ~26-33s |
| macOS | ~6s | ~26-33s |

**A cosa prestare attenzione**:

1. Gli stub `.sh` **devono** avere terminatori di riga Unix (LF, non CRLF) altrimenti bash fallisce con "ambiguous redirect".
2. Il caricamento nella libreria dell'API ufficiale **non** sincronizza i file `.sh` con gli endpoint Linux/macOS. Caricare prima tramite API interna (portale) o l'interfaccia del portale Defender. Una volta caricati, l'API ufficiale RunScript funziona correttamente.
3. `executor_b64.sh` funziona su Linux e macOS una volta caricato correttamente.

---

## Test

La suite di test include 712 test unitari offline, 301 test di integrazione dell'API ufficiale, 251 test di integrazione dell'API interna, più un driver di stress test configurabile.

### Prerequisiti```powershell
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser

### Test delle API interne (richiede cookie del portale)

Test di integrazione che coprono sccauth auth, session lifecycle, tutti i comandi nativi, esecuzione B64, targeting cross-OS.```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)

| Job | Trigger | Piattaforme | Requisiti |
|-----|---------|-------------|-----------|
| PSScriptAnalyzer Lint | Ogni push/PR | Ubuntu | Nessuno |
| Test offline | Ogni push/PR | Ubuntu + Windows + macOS | Nessuno |
| Test online (Ufficiale) | Condizionale | Ubuntu | variabile `LARAC2_ONLINE_TESTS` + segreto `LARAC2_CONFIG` |
| Test di stress | Attivazione manuale | Ubuntu | segreto `LARAC2_CONFIG` |

---

## Risoluzione dei problemi

| Errore | Causa | Risoluzione |
|--------|-------|-------------|
| `ActiveRequestAlreadyExists` | Un altro comando LR è in esecuzione sul target | Gestito automaticamente (modalità ufficiale): annullamento azione conflittuale + backoff fisso di 10s/15s fino a 12 tentativi. Modalità interna: solo attesa. Nessuna azione utente necessaria. |
| HTTP 429 | Limite di velocità superato (10 comandi/min) | Gestito automaticamente: attende per il periodo Retry-After e riprova. |
| "script not found" su Linux/macOS | Stub .sh non sincronizzato all'endpoint | Carica tramite API interna o UI del portale Defender. I caricamenti dell'API ufficiale non sincronizzano i file .sh. |
| "ambiguous redirect" su Linux/macOS | Lo stub .sh ha terminazioni di riga CRLF | Risalva con terminazioni di riga LF e ricarica. |
| HTTP 400 su comando grande | Il payload B64 supera ~30 KB | Usa invece `library upload` + `run <script>`. |
| HTTP 401 | Token/sessione scaduto | La shell si aggiorna automaticamente per credenziali client, TOTP e passkey. Per altri metodi, digita `connect`. |
| HTTP 403 | Permessi insufficienti | Ufficiale: controlla gli ambiti `Machine.LiveResponse` + `Library.Manage`. Interno: controlla il ruolo di Operatore di sicurezza. |
| HTTP 404 | Macchina non trovata | Esegui `machines refresh` per ricaricare. |

---

## Requisiti

| Requisito | Dettaglio |
|-----------|-----------|
| PowerShell Core | 7.0 o successivo (`pwsh`) |
| Registrazione app MDE | Richiesto per la modalità ufficiale (autorizzazioni `Machine.LiveResponse` + `Library.Manage`) |
| Sistema operativo | Windows, Linux o macOS (la shell gira su qualsiasi; i target possono essere qualsiasi SO registrato con MDE) |

Tutta l'autenticazione è autonoma -- nessun modulo esterno richiesto. I flussi di autenticazione in modalità interna si basano su [XDRInternals](https://github.com/MSCloudInternals/XDRInternals) di Fabian Bader & Nathan McNulty.

---

## Struttura dei file```
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