Das war's. Die Shell präsentiert beim ersten Start ein einheitliches Authentifizierungsmenü mit 7 Methoden — wähle eine aus, authentifiziere dich, wähle einen Rechner aus, und schon bist du in einer REPL. Keine Konfigurationsdatei, keine Flags, nichts einzurichten.```
  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>` trennt die aktuelle LR-Sitzung, löscht den alten Authentifizierungsstatus und führt den Authentifizierungsablauf für den Zielmodus erneut aus. Wenn es zurückkommt, sind Sie im neuen Modus authentifiziert, ohne dass eine Maschine ausgewählt ist – führen Sie `machines` aus, um die Liste anzuzeigen, oder `connect <name|id>`, um direkt zu einem Ziel zu springen. Kein Neustart erforderlich.

### CLI-Verknüpfungen (optional)

Für Skripting oder wenn Sie das einheitliche Menü überspringen möchten:```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'

Konfigurationsschema (alle Felder optional, außer `official.tenantId` + `official.clientId` bei Verwendung von Client-Anmeldeinformationen):

| Section | Field | Description |
|---------|-------|-------------|
| `official` | `tenantId` | Azure AD-Mandanten-ID |
| `official` | `clientId` | App-Registrierungs-Client-ID |
| `official` | `clientSecret` | Client-Geheimnis (weglassen und `useDeviceCode: true` setzen für Gerätecode) |
| `official` | `useDeviceCode` | `true`, um den Gerätecode-Fluss anstelle von Client-Anmeldeinformationen zu verwenden |
| `defaults` | `defaultMachine` | Maschine beim Start vorauswählen (Namens-Teilzeichenfolge oder ID-Präfix) |
| `defaults` | `commandTimeoutSeconds` | Clientseitige Timeout-Obergrenze. `0` = Server entscheidet (bis zu 1800s). |
| `defaults` | `pollIntervalOfficial` | Offizielles API-Polling-Intervall in Sekunden (Standard 2) |
| `defaults` | `pollIntervalInternal` | Internes API-Polling-Intervall in Sekunden (Standard 1) |

**Sicherheit**: Schränken Sie Dateisystemberechtigungen für jede Konfigurationsdatei ein, die `clientSecret` enthält. Das `clientSecret` wird niemals über die Befehlszeile akzeptiert – nur über Konfigurationsdatei. Alle Anmeldeinformationen des internen Modus (Benutzername, Passwort, TOTP-Geheimnis, Cookies) werden interaktiv abgefragt und niemals auf der Festplatte gespeichert.

---

## Authentifizierungsmethoden

Die Shell zeigt beim Start ein einheitliches Menü mit 7 Authentifizierungsmethoden an. Der Modus (intern/offiziell) wird aus der Auswahl abgeleitet.

| # | Modus | Methode | Wie | Automatische Aktualisierung |
|---|------|--------|-----|--------------|
| 1 | Intern | Anmeldeinformationen + TOTP | Interaktive Eingabeaufforderung | Ja (still) – nur wenn ein TOTP-Geheimnis angegeben wurde. Bei Push/SMS-MFA kann die Sitzung nicht automatisch aktualisiert werden. |
| 2 | Intern | Software-Passkey | `-PasskeyPath`-Parameter oder Eingabeaufforderung | Ja (still) |
| 3 | Intern | ESTS-Cookie | Interaktive Eingabeaufforderung | Nein (~24h) |
| 4 | Intern | Temporärer Zugangspass | Interaktive Eingabeaufforderung | Nein (einmalig) |
| 5 | Intern | Direktes sccauth + XSRF | Interaktive Eingabeaufforderung | Nein (~1h) – XSRF automatische Aktualisierung gilt nicht; die Shell aktualisiert direkt bereitgestellte Cookies nicht automatisch. |
| 6 | Offiziell | Gerätecode | Browser-Anmeldung | Nein (~1h) |
| 7 | Offiziell | Client-Anmeldeinformationen | Konfigurationsdatei | Ja (still) |

Der Befehl `connect` authentifiziert bei Ablauf der Sitzung erneut, wobei dieselbe Methode verwendet wird, die ursprünglich ausgewählt wurde. Methoden ohne automatische Aktualisierung fordern erneut interaktiv zur Eingabe auf.

**Speicherinterne Handhabung von Anmeldeinformationen**: Bei Methode 1 werden das angegebene Passwort und das TOTP-Geheimnis im Speicher (als Klartext-Zeichenfolgen, innerhalb von `$script:Int_ReauthParams`) für die Lebensdauer des Shell-Prozesses aufbewahrt, sodass eine stille erneute Authentifizierung unbeaufsichtigt ausgeführt werden kann. Die Zeichenfolgenobjekte leben im PowerShell-Runspace; sie werden nicht auf die Festplatte serialisiert oder über die Befehlszeile übergeben. Wenn diese Offenlegung für Ihr Bedrohungsmodell nicht akzeptabel ist, verwenden Sie stattdessen Methode 2 (Passkey/HSM) oder Methode 7 (Client-Anmeldeinformationen).

---

## Shell-Befehle

### Shell-Steuerung

| Befehl | Beschreibung |
|---------|-------------|
| `help [command]` | Hilfe anzeigen (optional für einen bestimmten Befehl) |
| `help commands` | Alle nativen LR-Befehle mit Beschreibungen auflisten |
| `status` | Verbindungsstatus, Authentifizierungsstatus, Maschineninformationen anzeigen |
| `config` | Live-Response-Konfiguration anzeigen |
| `connect [name\|id]` | Erneut authentifizieren (falls abgelaufen) und eine Maschine auswählen |
| `disconnect` | Aktuelle LR-Sitzung trennen und Maschine zurücksetzen |
| `multi [options] <cmd>` | Befehl auf mehreren Maschinen ausführen (`-top N`, `-filter pattern`) |
| `session [list]` | Aktuelle Sitzungsinformationen oder alle zwischengespeicherten Sitzungen anzeigen |
| `mode` | Aktuellen API-Modus anzeigen |
| `mode internal\|official` | API-Modus inline wechseln – trennt die aktuelle Sitzung, baut den alten Authentifizierungsstatus ab und führt das Authentifizierungsmenü für den Zielmodus erneut aus. Anschließend mit `machines` oder `connect` fortfahren |
| `exit` / `quit` / `q` | Shell beenden |

### Maschinenverwaltung

| Befehl | Beschreibung |
|---------|-------------|
| `machines [refresh]` | Maschinen auflisten und eine auswählen (refresh = erzwungenes Neuladen) |
| `connect [name\|id]` | Mit einer Maschine über Namens-Teilzeichenfolge oder ID-Präfix verbinden |

### Native Live-Response-Befehle (insgesamt 25)

| Befehl | Beschreibung |
|---------|-------------|
| `run <script> [args]` | Ein Skript aus der MDE-Bibliothek ausführen |
| `getfile <path>` | Eine Datei von der entfernten Maschine herunterladen |
| `putfile <name>` | Eine Bibliotheksdatei in das entfernte Arbeitsverzeichnis hochladen |
| `processes` | Laufende Prozesse auflisten |
| `connections` | Aktive Netzwerkverbindungen auflisten |
| `cd <path>` | Arbeitsverzeichnis wechseln (interner Modus) |
| `dir [path]` | Verzeichnisinhalt auflisten |
| `findfile <name>` | Nach einer Datei mit Name auf allen Laufwerken suchen |
| `trace` | Diagnose-Trace-Informationen anzeigen |
| `analyze <path>` | Eine Datei zur Tiefenanalyse einreichen |
| `remediate <path>` | Eine Datei unter Quarantäne stellen/beheben |
| `undo <actionId>` | Eine vorherige Bereinigungsaktion rückgängig machen |
| `registry <key>` | Registrierungsschlüssel/-werte abfragen (nur Windows) |
| `scheduledtasks` | Geplante Aufgaben auflisten |
| `persistence` | Häufige Persistenzorte prüfen |
| `drivers` | Geladene Treiber auflisten (nur Windows) |
| `services` | Dienste auflisten |
| `startupfolders` | Inhalt des Autostart-Ordners auflisten (nur Windows) |
| `fileinfo <path>` | Detaillierte Dateiinformationen abrufen |
| `prefetch` | Prefetch-Daten auflisten (nur Windows) |
| `log` | Diagnoseprotokolle anzeigen |
| `jobs` | Hintergrundaufträge auflisten (interner Modus) |
| `fg <jobId>` | Einen Hintergrundauftrag in den Vordergrund holen (interner Modus) |
| `library` | Bibliotheksdateien verwalten (auflisten, hochladen, herunterladen, löschen) |
| `status` | Sitzungsstatus und Diagnose anzeigen |

### Befehlsaliase

| Alias | Wird aufgelöst zu |
|-------|-------------|
| `ls` | `dir` |
| `ps` | `processes` |
| `download` | `getfile` |
| `process` | `processes` |
| `netstat` | `connections` |

### Beliebige Befehle

Jede Eingabe, die keinem integrierten Befehl entspricht, wird als beliebiger Befehl behandelt und über den B64-Executor-Stub auf der entfernten Maschine ausgeführt. Beispiele: `whoami`, `ipconfig`, `cat /etc/hostname`.

- Windows-Ziele: Befehl wird UTF-16-LE Base64-kodiert und über `executor_b64.ps1` (PowerShell-ScriptBlock) ausgeführt
- Linux/macOS-Ziele: Befehl wird UTF-8 Base64-kodiert und über `executor_b64.sh` (bash) ausgeführt

**Pipeline-Erkennung**: Befehle, die Pipes (`|`), Semikolons (`;`), Umleitungen (`>>`) oder Unterausdrücke (`$(`) enthalten, werden immer B64-gewrappt, selbst wenn das erste Wort ein natives LR-Verb ist. Zum Beispiel wird `dir C:\ | Select-Object` über B64 geleitet, nicht über natives `dir`.

### Bibliotheksverwaltung

| Befehl | Beschreibung |
|---------|-------------|
| `library` | Alle Dateien in der MDE-Bibliothek auflisten |
| `library refresh` | Bibliotheksliste von der API erzwungen aktualisieren |
| `library upload <path>` | Eine lokale Datei in die Bibliothek hochladen |
| `library delete <name>` | Eine Datei nach Name aus der Bibliothek löschen |
| `library download <name>` | Inhalt einer Datei aus der Bibliothek herunterladen (Interne API: direkt; Offizielle API: über `getfile` aus dem Bibliothekscache des Endpunkts, sobald eine Maschine ausgewählt wurde – Synchronisation kann bis zu 10 Minuten dauern) |

### Aktionsverwaltung

| Befehl | Beschreibung |
|---------|-------------|
| `actions` | Ausstehende/laufende Aktionen für die aktuelle Maschine auflisten |
| `actions all` | Alle aktuellen Aktionen auf allen Maschinen auflisten |
| `actions cancel <id>` | Eine Aktion nach ID abbrechen (Teilübereinstimmung unterstützt) |

---

## Architektur

### Interne vs. Offizielle API

Die LaraC2 Shell stellt zwei unabhängige API-Pfade zum selben MDE Live Response-Backend bereit. Die interne API spiegelt das WebSocket-ähnliche Sitzungsmodell des Portals wider und liefert nahezu Echtzeit-Antworten. Die offizielle API verwendet die dokumentierten REST-Endpunkte von Microsoft und eignet sich für die Automatisierung.

| | Interne API | Offizielle API |
|---|---|---|
| Basis-URL | `security.microsoft.com/apiproxy/mtp/liveResponseApi/` | `api.securitycenter.microsoft.com/api/` |
| Sitzung | Persistent (30-min Keepalive, automatische Wiederverbindung) | Pro Befehl (zustandslos) |
| Polling-Intervall | ~1s (nahezu Echtzeit) | 2s |
| Mehrfachbefehle | Sequenziell innerhalb gemeinsamer Sitzung | Gebündelt (bis zu 5 pro API-Aufruf) |
| Authentifizierung | Eigenständig (ESTS/Passkey/TOTP -> sccauth) | OAuth2-Client-Anmeldeinformationen oder Gerätecode |
| Standard-Timeout | 1800s (Server entscheidet, nicht Client) | 1800s (Server entscheidet, nicht Client) |

#### Was LaraC2 über die rohe API hinaus bietet

| Schritt | Rohe Offizielle API | LaraC2 Shell |
|------|-----------------|-------------|
| Stub-Upload | Manuell: Multipart erstellen, POST, Konflikte behandeln | Automatisch bei Verbindung, 409-Überschreibung |
| B64-Codierung | Manuell: UTF-16LE/UTF-8 pro Betriebssystem wählen | Automatische Betriebssystemerkennung, automatische Codierung |
| RunScript erstellen | Manuell: JSON mit ScriptName + Args-Parametern | Befehl direkt eingeben |
| Polling + Abruf | Manuell: Schleife + Download-Link + JSON parsen | Transparent: gibt bereinigte Ausgabe zurück |
| Fehlerbehandlung | Manuell: Überprüfung 400/401/403/409/429/503 | Automatisch: Wiederholung, Backoff, Anleitung |
| Mehrfachbefehle | Manuell: Commands[]-Array erstellen | Automatische Bündelung bis zu 5 |

### Wichtige Einschränkung

Offizielle API und interne API teilen sich eine maschinenspezifische Aktionswarteschlange. Sie können nicht gleichzeitig auf derselben Maschine ausgeführt werden.

### Ratenbegrenzung (Transparent)

| Grenze | Wert | Behandlung |
|-------|------|----------|
| LR-Befehle pro Minute | 10 | 429-Antwort mit Retry-After-Header |
| Bibliotheks-Uploads pro Minute | 100 | Gleitfenster-Warteschlange |
| Bibliotheks-Uploads pro Stunde | 1500 | Stündlicher Zähler |
| HTTP 429 Too Many Requests | -- | Schlafen für Retry-After-Header (Standard 35s) |
| ActiveRequestAlreadyExists | -- | Konfliktaktion abbrechen + fester Backoff (10s, dann 15s bis zu 12 Wiederholungen) |
| Bearer-Token-Ablauf (offiziell) | ~1 Stunde | Automatische Aktualisierung vor Ablauf |
| sccauth-Ablauf (intern) | ~1 Stunde | Stille erneute Authentifizierung, wenn Anmeldeinformationen gespeichert |
| LR-Sitzungsinaktivität | 30 Minuten | Automatische Wiederverbindung |
| XSRF-Rotation | 4 Minuten | Transparente Aktualisierung |

---

## Machbarkeit einer nahezu Echtzeit-Shell

Gemessene Latenzen in einem Produktions-MDE-Mandanten auf Windows-, Linux- und macOS-Zielen:

| Vorgang | Interne API | Offizielle API |
|-----------|-------------|--------------|
| `whoami` (B64) | 4-9s | 20-46s |
| `dir` (nativ) | 2-4s | 14-25s |
| `processes` (nativ) | 3-15s | 20-175s |
| `connections` (nativ) | 2-4s | ~15s |
| `services` (nativ) | 2-5s | ~15s |
| `hostname` (B64) | 4-7s | 11-16s |
| Sitzungsverbindung (erster Befehl) | 9-15s | N/A (zustandslos) |
| Maschinenwechsel | 7-10s | 15-30s |

**Interne API: nahezu Echtzeit-fähig.** Bei Sitzungswiederverwendung antworten native Befehle in 2-5s. Das ist so nah an Echtzeit, wie MDE es zulässt. Der Engpass ist der SenseIR-Agent auf dem Ziel, nicht das Framework.

**Offizielle API: Automatisierungsgrad.** Mindestens ~15s pro Befehl aufgrund der zustandslosen Architektur (senden, abfragen, abrufen). Gut geeignet für Skriptautomatisierung und CI/CD, nicht für interaktive Nutzung.

---

## Plattformübergreifende Unterstützung

Linux- und macOS-Endpunkte werden über beide API-Modi vollständig unterstützt.

| Ziel-Betriebssystem | Interne API Durchschnitt | Offizielle API Durchschnitt |
|-----------|-----------------|-----------------|
| Windows | ~7s | ~30s |
| Linux | ~6s | ~26-33s |
| macOS | ~6s | ~26-33s |

**Worauf zu achten ist**:

1. `.sh`-Stubs **müssen** Unix-Zeilenumbrüche (LF, nicht CRLF) haben, sonst schlägt bash mit "ambiguous redirect" fehl.
2. Der Bibliotheks-Upload der offiziellen API synchronisiert `.sh`-Dateien **nicht** an Linux/macOS-Endpunkte. Laden Sie zuerst über die interne API (Portal) oder die Defender-Portal-UI hoch. Nach dem Upload funktioniert der offizielle API-RunScript einwandfrei.
3. `executor_b64.sh` funktioniert auf Linux und macOS, sobald es ordnungsgemäß hochgeladen wurde.

---

## Tests

Die Testsuite umfasst 712 Offline-Komponententests, 301 Integrationstests der offiziellen API, 251 Integrationstests der internen API sowie einen konfigurierbaren Stresstest-Treiber.

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

### Interne API-Tests (erfordert Portal-Cookies)

Integrationstests, die sccauth auth, Sitzungslebenszyklus, alle nativen Befehle, B64-Ausführung und plattformübergreifende Zielsetzung abdecken.```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 | Platforms | Requirements |
|-----|---------|-----------|--------------|
| PSScriptAnalyzer Lint | Every push/PR | Ubuntu | None |
| Offline Tests | Every push/PR | Ubuntu + Windows + macOS | None |
| Online Tests (Official) | Conditional | Ubuntu | `LARAC2_ONLINE_TESTS` Variable + `LARAC2_CONFIG` Geheimnis |
| Stress Tests | Manual dispatch | Ubuntu | `LARAC2_CONFIG` Geheimnis |

---

## Fehlerbehebung

| Fehler | Ursache | Lösung |
|-------|---------|--------|
| `ActiveRequestAlreadyExists` | Ein weiterer LR-Befehl wird auf dem Ziel ausgeführt | Automatisch behandelt (offizieller Modus): Konfliktierende Aktion abbrechen + feste 10s/15s Backoff bis zu 12 Wiederholungen. Interner Modus: Nur warten. Kein Benutzereingriff erforderlich. |
| HTTP 429 | Ratenbegrenzung überschritten (10 Befehle/min) | Automatisch behandelt: Wartet für die Retry-After-Periode und wiederholt. |
| "script not found" unter Linux/macOS | .sh-Stub nicht mit Endpunkt synchronisiert | Hochladen über interne API oder Defender-Portal-UI. Offizielle API-Uploads synchronisieren .sh-Dateien nicht. |
| "ambiguous redirect" unter Linux/macOS | .sh-Stub hat CRLF-Zeilenumbrüche | Erneut mit LF-Zeilenumbrüchen speichern und erneut hochladen. |
| HTTP 400 bei großem Befehl | B64-Nutzlast überschreitet ~30 KB | Verwenden Sie stattdessen `library upload` + `run <script>`. |
| HTTP 401 | Token/Sitzung abgelaufen | Shell aktualisiert automatisch für Client-Anmeldeinformationen, TOTP und Passkey. Für andere Methoden geben Sie `connect` ein. |
| HTTP 403 | Unzureichende Berechtigungen | Offiziell: Überprüfen Sie die Bereiche `Machine.LiveResponse` + `Library.Manage`. Intern: Überprüfen Sie die Rolle „Sicherheitsoperator“. |
| HTTP 404 | Computer nicht gefunden | Führen Sie `machines refresh` aus, um neu zu laden. |

---

## Anforderungen

| Anforderung | Detail |
|-------------|--------|
| PowerShell Core | 7.0 oder höher (`pwsh`) |
| MDE-App-Registrierung | Erforderlich für den offiziellen Modus (Berechtigungen `Machine.LiveResponse` + `Library.Manage`) |
| Betriebssystem | Windows, Linux oder macOS (Shell läuft auf jedem; Ziele können jedes MDE-eingeschriebene Betriebssystem sein) |

Die gesamte Authentifizierung ist in sich geschlossen – es sind keine externen Module erforderlich. Die Authentifizierungsabläufe im internen Modus basieren auf [XDRInternals](https://github.com/MSCloudInternals/XDRInternals) von Fabian Bader und Nathan McNulty.

---

## Dateistruktur```
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