LaraC2 Shell -- MDE Live Response Interactive Shell

Cross-platform interactive shell for Microsoft Defender for Endpoint Live Response.

LaraC2 Shell connects to MDE Live Response through two independent API paths -- the internal portal API (persistent sessions, ~2-5s latency) and the official public API (per-command, ~20-60s latency). It auto-uploads executor stubs, handles rate limiting transparently, and provides a full REPL with machine management, library management, and a built-in help system.

Documentation

Features

• Two API modes: Internal (portal, ~2-5s/cmd, near-real-time) + Official (public, ~20-60s/cmd, CI/CD ready)
• 7 auth methods in a unified menu: client creds, device code, credentials+TOTP, passkey/HSM, ESTS cookie, TAP, direct sccauth -- mode is derived from the auth choice
• 25 native LR commands + arbitrary command execution via auto-uploaded B64 executor stubs
• Cross-OS targeting: Windows, Linux, macOS endpoints (auto-selects executor + encoding)
• Transparent rate limiting: 429 backoff, ActiveRequest smart conflict resolution (12 retries, cancel external / wait own)
• Session lifecycle: auto-connect, auto-reconnect on 30-min inactivity, stale session pruning, cross-machine switching
• Auth lifecycle: OAuth2 auto-refresh, XSRF auto-refresh (4-min TTL), silent re-auth for TOTP/passkey; connect command re-authenticates when session expires
• Session reuse: transparent auto-connect, auto-reconnect, and cross-machine switching with no user intervention
• Multi-machine execution: multi command with name pattern filtering and top-N limiting
• Multi-command batching: up to 5 commands per Official API call, auto-split for larger sets
• Library management: list, upload, delete, download, auto-upload executor stubs, 409 conflict override
• Action management: list, cancel (partial ID match), status detail
• Interactive UX: tab completion, command aliases (ls/ps/netstat), working directory tracking, help system
• Error guidance: context-aware messages (400->syntax, 401->reauth, 403->scopes, 429->rate limit)
• No secrets on CLI: credentials from config file or interactive prompt, never in command history

Quick Start

Prerequisites

• PowerShell Core 7.0+ (Windows, Linux, or macOS)
• Either a portal account with Live Response access (internal mode) or an MDE app registration with Machine.LiveResponse + Library.Manage permissions (official mode)

Launch

git clone https://github.com/akefallonitis/larac2shell.git
cd larac2shell
pwsh -File shell/Invoke-MDEShell.ps1

That's it. The shell presents a unified 7-method auth menu on first launch — pick one, authenticate, select a machine, and you're in a REPL. No config file, no flags, nothing to set up.

  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):

Choices 1-5 set internal mode, 6-7 set official. You can switch modes later without restarting — see Switching modes inline below.

Switching modes inline

[INT myhost C:\]> mode
  Current mode: Internal API
  Switch with: 'mode internal' or 'mode official'.

[INT myhost C:\]> mode official
  [Mode] Switching from Internal API to official...
  (auth menu for official mode opens)
  [Mode] Now in official mode.
  Run 'machines' to list targets or 'connect <name|id>' to select one.

mode <target> disconnects any current LR session, clears the old auth state, and re-runs the auth flow for the target mode. When it returns you're authenticated in the new mode with no machine selected — run machines to list, or connect <name|id> to jump straight to a target. No restart required.

CLI shortcuts (optional)

For scripting or when you want to skip the unified menu:

# 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'

Config file (optional)

Only used for one scenario: official mode with a client secret, non-interactively. Every other auth method prompts you interactively and stores nothing on disk. If you don't need unattended client-credentials auth, you can skip this section entirely.

Copy-Item shell/config/shell-config.example.json shell/config/shell-config.json
# Edit the file: set official.tenantId, official.clientId, official.clientSecret
pwsh -File shell/Invoke-MDEShell.ps1 -Config shell/config/shell-config.json

Config schema (all fields optional except official.tenantId + official.clientId when using client credentials):

Security: Restrict filesystem permissions on any config file containing clientSecret. The clientSecret is never accepted on the command line — config file only. All internal-mode credentials (username, password, TOTP secret, cookies) are prompted interactively and never persisted to disk.

Authentication Methods

The shell presents a unified 7-method auth menu on startup. Mode (internal/official) is derived from the choice.

The connect command re-authenticates when the session expires, using the same method that was originally selected. Methods without auto-refresh prompt interactively again.

In-memory credential handling: for method 1, the supplied password and TOTP secret are retained in-memory (as plain strings, inside $script:Int_ReauthParams) for the lifetime of the shell process so silent re-auth can run unattended. The string objects live in the PowerShell runspace; they are not serialized to disk or passed on the command line. If that exposure is not acceptable for your threat model, use method 2 (passkey/HSM) or method 7 (client credentials) instead.

Shell Commands

Shell Control

Machine Management

Native Live Response Commands (25 total)

Command Aliases

Arbitrary Commands

Any input that does not match a built-in command is treated as an arbitrary command and executed on the remote machine via the B64 executor stub. Examples: whoami, ipconfig, cat /etc/hostname.

• Windows targets: command is UTF-16-LE Base64-encoded and executed via executor_b64.ps1 (PowerShell ScriptBlock)
• Linux/macOS targets: command is UTF-8 Base64-encoded and executed via executor_b64.sh (bash)

Pipeline detection: Commands containing pipes (|), semicolons (;), redirects (>>), or subexpressions ($() are always B64-wrapped, even if the first word is a native LR verb. For example, dir C:\ | Select-Object goes through B64, not native dir.

Library Management

Action Management

Architecture

Internal vs Official API

LaraC2 Shell exposes two independent API paths to the same MDE Live Response backend. The Internal API mirrors the portal's WebSocket-like session model and delivers near-real-time responses. The Official API uses Microsoft's documented REST endpoints and is suited for automation.

What LaraC2 adds beyond the raw API

Key constraint

Official API and Internal API share a per-machine action queue. They cannot run simultaneously on the same machine.

Rate Limiting (Transparent)

Near-Real-Time Shell Feasibility

Measured latencies on a production MDE tenant, across Windows, Linux, and macOS targets:

Internal API: near-real-time capable. With session reuse, native commands respond in 2-5s. This is as close to real-time as MDE allows. The bottleneck is the SenseIR agent on the target, not the framework.

Official API: automation-grade. Minimum ~15s per command due to stateless architecture (submit, poll, fetch). Well-suited for scripted automation and CI/CD, not interactive use.

Cross-OS Support

Linux and macOS endpoints are fully supported via both API modes.

What to watch for:

1. .sh stubs must have Unix line endings (LF, not CRLF) or bash fails with "ambiguous redirect".
2. Official API library upload does not sync .sh files to Linux/macOS endpoints. Upload via Internal API (portal) or the Defender portal UI first. Once uploaded, Official API RunScript works fine.
3. executor_b64.sh works on Linux and macOS once properly uploaded.

Testing

The test suite includes 712 offline unit tests, 301 Official-API integration tests, 251 Internal-API integration tests, plus a configurable stress-test driver.

Prerequisites

Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser

Offline Tests (no tenant required)

Unit tests covering module loading, B64 encoding, command building, alias resolution, tokenizer, rate limiter, auth crypto, session management, error paths, and all auth flows via Pester Mock.

Invoke-Pester ./tests/shell/LaraC2Shell.Offline.Tests.ps1 -Output Detailed

Internal API Tests (requires portal cookies)

Integration tests covering sccauth auth, session lifecycle, all native commands, B64 execution, cross-OS targeting.

$env:LARAC2_SCCAUTH = 'your-sccauth-cookie'
$env:LARAC2_XSRF = 'your-xsrf-token'
Invoke-Pester ./tests/shell/LaraC2Shell.Internal.Tests.ps1 -Output Detailed

Stress Tests (throughput and reliability)

# Single-mode stress
pwsh -File tests/shell/LaraC2Shell.Stress.Tests.ps1 -Config config.json -Mode official -Rounds 5

# Cross-OS stress (Windows + Linux + macOS)
pwsh -File tests/shell/LaraC2Shell.Stress.Tests.ps1 -Config config.json -Mode both -Scenario crossos

CI/CD (GitHub Actions)

Troubleshooting

Requirements

All authentication is self-contained -- no external modules required. Internal mode auth flows are based on XDRInternals by Fabian Bader & Nathan McNulty.

File Layout

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

Authorization

See LICENSE for terms.

References & Credits