É isso. O shell apresenta um menu de autenticação unificado com 7 métodos no primeiro lançamento — escolha um, autentique-se, selecione uma máquina, e você estará em um REPL. Sem arquivo de configuração, sem flags, nada para configurar.```
  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>` desconecta qualquer sessão LR atual, limpa o estado de autenticação antigo e executa novamente o fluxo de autenticação para o modo alvo. Quando retorna, você está autenticado no novo modo sem nenhuma máquina selecionada — execute `machines` para listar, ou `connect <name|id>` para ir diretamente a um alvo. Nenhuma reinicialização necessária.

### Atalhos de CLI (opcional)```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'

Esquema de configuração (todos os campos opcionais, exceto `official.tenantId` + `official.clientId` ao usar credenciais de cliente):

| Secção | Campo | Descrição |
|---------|-------|-------------|
| `official` | `tenantId` | ID do inquilino do Azure AD |
| `official` | `clientId` | ID do cliente do registo da aplicação |
| `official` | `clientSecret` | Segredo do cliente (omitir e definir `useDeviceCode: true` para código de dispositivo) |
| `official` | `useDeviceCode` | `true` para usar o fluxo de código de dispositivo em vez de credenciais de cliente |
| `defaults` | `defaultMachine` | Pré-selecionar máquina no arranque (substring do nome ou prefixo do ID) |
| `defaults` | `commandTimeoutSeconds` | Teto de tempo limite do lado do cliente. `0` = o servidor decide (até 1800s). |
| `defaults` | `pollIntervalOfficial` | Intervalo de polling da API oficial em segundos (padrão 2) |
| `defaults` | `pollIntervalInternal` | Intervalo de polling da API interna em segundos (padrão 1) |

**Segurança**: Restrinja as permissões do sistema de ficheiros em qualquer ficheiro de configuração que contenha `clientSecret`. O `clientSecret` nunca é aceite na linha de comandos — apenas no ficheiro de configuração. Todas as credenciais de modo interno (nome de utilizador, palavra-passe, segredo TOTP, cookies) são solicitadas interativamente e nunca são persistidas em disco.

---

## Métodos de Autenticação

A shell apresenta um menu de autenticação unificado de 7 métodos no arranque. O modo (interno/oficial) é derivado da escolha.

| # | Modo | Método | Como | Auto-Atualização |
|---|------|--------|-----|--------------|
| 1 | Interno | Credenciais + TOTP | Prompt interativo | Sim (silencioso) — apenas quando um segredo TOTP foi fornecido. Com MFA push/SMS a sessão não pode auto-atualizar-se. |
| 2 | Interno | Passkey de software | Parâmetro `-PasskeyPath` ou prompt | Sim (silencioso) |
| 3 | Interno | Cookie ESTS | Prompt interativo | Não (~24h) |
| 4 | Interno | Passe de Acesso Temporário | Prompt interativo | Não (uma vez) |
| 5 | Interno | sccauth direto + XSRF | Prompt interativo | Não (~1h) — a auto-atualização XSRF não se aplica; a shell não atualiza automaticamente cookies fornecidos diretamente. |
| 6 | Oficial | Código de dispositivo | Login no navegador | Não (~1h) |
| 7 | Oficial | Credenciais de cliente | Ficheiro de configuração | Sim (silencioso) |

O comando `connect` reautentica quando a sessão expira, usando o mesmo método que foi originalmente selecionado. Métodos sem auto-atualização solicitam novamente de forma interativa.

**Manuseamento de credenciais em memória**: para o método 1, a palavra-passe fornecida e o segredo TOTP são retidos em memória (como strings simples, dentro de `$script:Int_ReauthParams`) durante todo o tempo de vida do processo da shell para que a reautenticação silenciosa possa ser executada sem supervisão. Os objetos string vivem no runspace do PowerShell; não são serializados para disco nem passados na linha de comandos. Se essa exposição não for aceitável para o seu modelo de ameaça, use o método 2 (passkey/HSM) ou o método 7 (credenciais de cliente).

---

## Comandos da Shell

### Controlo da Shell

| Comando | Descrição |
|---------|-------------|
| `help [comando]` | Mostrar ajuda (opcionalmente para um comando específico) |
| `help commands` | Listar todos os comandos nativos do LR com descrições |
| `status` | Mostrar estado da ligação, estado de autenticação, informação da máquina |
| `config` | Mostrar configuração do Live Response |
| `connect [nome\|id]` | Reautenticar (se expirado) e selecionar uma máquina |
| `disconnect` | Desligar sessão atual do LR e limpar máquina |
| `multi [opções] <cmd>` | Executar comando em várias máquinas (`-top N`, `-filter padrão`) |
| `session [list]` | Mostrar informação da sessão atual ou todas as sessões em cache |
| `mode` | Mostrar o modo atual da API |
| `mode interno\|oficial` | Alternar modo API inline — desliga a sessão atual, limpa o estado de autenticação antigo e reexecuta o menu de autenticação para o modo de destino. Continue com `machines` ou `connect` depois |
| `exit` / `quit` / `q` | Sair da shell |

### Gestão de Máquinas

| Comando | Descrição |
|---------|-------------|
| `machines [refresh]` | Listar máquinas e selecionar uma (refresh = forçar recarregamento) |
| `connect [nome\|id]` | Ligar a uma máquina por substring do nome ou prefixo do ID |

### Comandos Nativos do Live Response (25 no total)

| Comando | Descrição |
|---------|-------------|
| `run <script> [args]` | Executar um script da Biblioteca MDE |
| `getfile <caminho>` | Descarregar um ficheiro da máquina remota |
| `putfile <nome>` | Enviar um ficheiro da biblioteca para o diretório de trabalho remoto |
| `processes` | Listar processos em execução |
| `connections` | Listar ligações de rede ativas |
| `cd <caminho>` | Mudar diretório de trabalho (modo interno) |
| `dir [caminho]` | Listar conteúdo do diretório |
| `findfile <nome>` | Procurar um ficheiro por nome em todas as unidades |
| `trace` | Mostrar informação de diagnóstico de rastreio |
| `analyze <caminho>` | Submeter um ficheiro para análise aprofundada |
| `remediate <caminho>` | Colocar em quarentena/ remediar um ficheiro |
| `undo <actionId>` | Desfazer uma ação de remediação anterior |
| `registry <chave>` | Consultar chaves/valores do registo (apenas Windows) |
| `scheduledtasks` | Listar tarefas agendadas |
| `persistence` | Verificar locais comuns de persistência |
| `drivers` | Listar drivers carregados (apenas Windows) |
| `services` | Listar serviços |
| `startupfolders` | Listar conteúdo das pastas de inicialização (apenas Windows) |
| `fileinfo <caminho>` | Obter informação detalhada do ficheiro |
| `prefetch` | Listar dados de prefetch (apenas Windows) |
| `log` | Ver logs de diagnóstico |
| `jobs` | Listar tarefas em segundo plano (modo interno) |
| `fg <jobId>` | Trazer tarefa em segundo plano para primeiro plano (modo interno) |
| `library` | Gerir ficheiros da biblioteca (listar, enviar, descarregar, apagar) |
| `status` | Mostrar estado da sessão e diagnósticos |

### Atalhos de Comandos

| Atalho | Resolve Para |
|-------|-------------|
| `ls` | `dir` |
| `ps` | `processes` |
| `download` | `getfile` |
| `process` | `processes` |
| `netstat` | `connections` |

### Comandos Arbitrários

Qualquer entrada que não corresponda a um comando interno é tratada como um comando arbitrário e executada na máquina remota através do stub executor B64. Exemplos: `whoami`, `ipconfig`, `cat /etc/hostname`.

- Alvos Windows: o comando é codificado em Base64 UTF-16-LE e executado via `executor_b64.ps1` (PowerShell ScriptBlock)
- Alvos Linux/macOS: o comando é codificado em Base64 UTF-8 e executado via `executor_b64.sh` (bash)

**Deteção de pipelines**: Comandos que contenham pipes (`|`), ponto e vírgula (`;`), redirecionamentos (`>>`) ou subexpressões (`$(`) são sempre encapsulados em B64, mesmo que a primeira palavra seja um verbo LR nativo. Por exemplo, `dir C:\ | Select-Object` passa pelo B64, não pelo `dir` nativo.

### Gestão da Biblioteca

| Comando | Descrição |
|---------|-------------|
| `library` | Listar todos os ficheiros na Biblioteca MDE |
| `library refresh` | Forçar atualização da lista da biblioteca a partir da API |
| `library upload <caminho>` | Enviar um ficheiro local para a biblioteca |
| `library delete <nome>` | Apagar um ficheiro da biblioteca pelo nome |
| `library download <nome>` | Descarregar o conteúdo de um ficheiro da biblioteca (API Interna: direto; API Oficial: via `getfile` da cache da biblioteca do endpoint assim que uma máquina é selecionada — a sincronização pode demorar até 10 min) |

### Gestão de Ações

| Comando | Descrição |
|---------|-------------|
| `actions` | Listar ações pendentes/em andamento para a máquina atual |
| `actions all` | Listar todas as ações recentes em todas as máquinas |
| `actions cancel <id>` | Cancelar uma ação pelo ID (correspondência parcial suportada) |

---

## Arquitetura

### API Interna vs API Oficial

A LaraC2 Shell expõe dois caminhos de API independentes para o mesmo backend de Live Response do MDE. A API Interna espelha o modelo de sessão tipo WebSocket do portal e oferece respostas quase em tempo real. A API Oficial utiliza os endpoints REST documentados da Microsoft e é adequada para automação.

| | API Interna | API Oficial |
|---|---|---|
| URL Base | `security.microsoft.com/apiproxy/mtp/liveResponseApi/` | `api.securitycenter.microsoft.com/api/` |
| Sessão | Persistente (keepalive de 30 min, reconexão automática) | Por comando (sem estado) |
| Intervalo de polling | ~1s (quase em tempo real) | 2s |
| Vários comandos | Sequenciais dentro da mesma sessão partilhada | Em lote (até 5 por chamada à API) |
| Autenticação | Autossuficiente (ESTS/passkey/TOTP -> sccauth) | OAuth2 credenciais de cliente ou código de dispositivo |
| Tempo limite padrão | 1800s (o servidor decide, não o cliente) | 1800s (o servidor decide, não o cliente) |

#### O que a LaraC2 acrescenta para além da API bruta

| Passo | API Oficial Bruta | LaraC2 Shell |
|------|-----------------|-------------|
| Upload do stub | Manual: construir multipart, POST, lidar com conflitos | Automático ao ligar, override 409 |
| Codificação B64 | Manual: escolher UTF-16LE/UTF-8 por SO | Deteção automática do SO, codificação automática |
| Construir RunScript | Manual: JSON com parâmetros ScriptName + Args | Escrever comando diretamente |
| Poll + fetch | Manual: loop + link de download + analisar JSON | Transparente: devolve resultado limpo |
| Tratamento de erros | Manual: verificar 400/401/403/409/429/503 | Automático: repetição, backoff, orientação |
| Vários comandos | Manual: construir array Commands[] | Agrupamento automático até 5 |

### Restrição fundamental

A API Oficial e a API Interna partilham uma fila de ações por máquina. Não podem ser executadas simultaneamente na mesma máquina.

### Limitação de Taxa (Transparente)

| Limite | Valor | Tratamento |
|-------|-------|----------|
| Comandos LR por minuto | 10 | Resposta 429 com cabeçalho Retry-After |
| Uploads de biblioteca por minuto | 100 | Fila de janela deslizante |
| Uploads de biblioteca por hora | 1500 | Contador horário |
| HTTP 429 Too Many Requests | -- | Dormir durante cabeçalho Retry-After (padrão 35s) |
| ActiveRequestAlreadyExists | -- | Cancelar ação conflituosa + backoff fixo (10s, depois 15s até 12 tentativas) |
| Expiração do token bearer (oficial) | ~1 hora | Atualização automática antes da expiração |
| Expiração do sccauth (interno) | ~1 hora | Reautenticação silenciosa se as credenciais estiverem armazenadas |
| Inatividade da sessão LR | 30 minutos | Reconexão automática |
| Rotação XSRF | 4 minutos | Atualização transparente |

---

## Viabilidade de Shell Quase em Tempo Real

Latências medidas num inquilino de produção do MDE, em alvos Windows, Linux e macOS:

| Operação | API Interna | API Oficial |
|-----------|-------------|-------------|
| `whoami` (B64) | 4-9s | 20-46s |
| `dir` (nativo) | 2-4s | 14-25s |
| `processes` (nativo) | 3-15s | 20-175s |
| `connections` (nativo) | 2-4s | ~15s |
| `services` (nativo) | 2-5s | ~15s |
| `hostname` (B64) | 4-7s | 11-16s |
| Ligação de sessão (primeiro comando) | 9-15s | N/A (sem estado) |
| Troca entre máquinas | 7-10s | 15-30s |

**API Interna: capaz de quase tempo real.** Com reutilização de sessão, os comandos nativos respondem em 2-5s. Isto é o mais próximo do tempo real que o MDE permite. O gargalo é o agente SenseIR no alvo, não a estrutura.

**API Oficial: grau de automação.** Mínimo ~15s por comando devido à arquitetura sem estado (submeter, consultar, obter). Adequada para automação de scripts e CI/CD, não para uso interativo.

---

## Suporte Multi-SO

Os endpoints Linux e macOS são totalmente suportados em ambos os modos de API.

| SO Alvo | Média API Interna | Média API Oficial |
|-----------|-----------------|-----------------|
| Windows | ~7s | ~30s |
| Linux | ~6s | ~26-33s |
| macOS | ~6s | ~26-33s |

**O que vigiar**:

1. Os stubs `.sh` **devem** ter terminações de linha Unix (LF, não CRLF) ou o bash falha com "ambiguous redirect".
2. O upload de biblioteca via API Oficial **não** sincroniza ficheiros `.sh` para endpoints Linux/macOS. Faça o upload através da API Interna (portal) ou da interface do portal Defender primeiro. Depois de carregados, o RunScript da API Oficial funciona bem.
3. O `executor_b64.sh` funciona em Linux e macOS depois de ser carregado corretamente.

---

## Testes

O conjunto de testes inclui 712 testes unitários offline, 301 testes de integração da API Oficial, 251 testes de integração da API Interna, além de um driver de teste de stress configurável.

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

### Testes de API Interna (requer cookies do portal)

Testes de integração que cobrem autenticação sccauth, ciclo de vida da sessão, todos os comandos nativos, execução B64, segmentação entre sistemas operacionais.```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 | Gatilho | Plataformas | Requisitos |
|-----|---------|-------------|------------|
| PSScriptAnalyzer Lint | Cada push/PR | Ubuntu | Nenhum |
| Testes Offline | Cada push/PR | Ubuntu + Windows + macOS | Nenhum |
| Testes Online (Oficial) | Condicional | Ubuntu | Variável `LARAC2_ONLINE_TESTS` + segredo `LARAC2_CONFIG` |
| Testes de Estresse | Envio manual | Ubuntu | segredo `LARAC2_CONFIG` |

---

## Solução de Problemas

| Erro | Causa | Resolução |
|------|-------|-----------|
| `ActiveRequestAlreadyExists` | Outro comando LR está em execução no destino | Tratado automaticamente (modo oficial): cancelar ação conflitante + espera fixa de 10s/15s com até 12 tentativas. Modo interno: apenas espera. Nenhuma ação do usuário necessária. |
| HTTP 429 | Limite de taxa excedido (10 comandos/min) | Tratado automaticamente: pausa pelo período Retry-After e tenta novamente. |
| "script não encontrado" no Linux/macOS | Stub .sh não sincronizado ao endpoint | Envie via API Interna ou interface do portal Defender. Os uploads da API Oficial não sincronizam arquivos .sh. |
| "redirecionamento ambíguo" no Linux/macOS | Stub .sh tem terminações de linha CRLF | Salve novamente com terminações LF e faça upload novamente. |
| HTTP 400 em comando grande | Carga útil B64 excede ~30 KB | Use `library upload` + `run <script>` em vez disso. |
| HTTP 401 | Token/sessão expirados | O shell atualiza automaticamente para credenciais de cliente, TOTP e chave de acesso. Para outros métodos, digite `connect`. |
| HTTP 403 | Permissões insuficientes | Oficial: verifique os escopos `Machine.LiveResponse` + `Library.Manage`. Interno: verifique a função Security Operator. |
| HTTP 404 | Máquina não encontrada | Execute `machines refresh` para recarregar. |

---

## Requisitos

| Requisito | Detalhe |
|-----------|---------|
| PowerShell Core | 7.0 ou posterior (`pwsh`) |
| Registro de Aplicativo MDE | Necessário para modo oficial (permissões `Machine.LiveResponse` + `Library.Manage`) |
| Sistema Operacional | Windows, Linux ou macOS (o shell é executado em qualquer um; os destinos podem ser qualquer SO inscrito no MDE) |

Toda a autenticação é autocontida — nenhum módulo externo necessário. Os fluxos de autenticação do modo interno são baseados em [XDRInternals](https://github.com/MSCloudInternals/XDRInternals) por Fabian Bader & Nathan McNulty.

---

## Layout de Arquivos```
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