그게 전부입니다. 셸은 최초 실행 시 통합된 7가지 인증 메뉴를 제공합니다 — 하나를 선택하고 인증한 후 머신을 선택하면 REPL에 진입합니다. 설정 파일도, 플래그도, 설정할 것이 없습니다.```
  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>` 는 현재 LR 세션을 끊고, 이전 인증 상태를 지우며, 대상 모드에 대한 인증 흐름을 다시 실행합니다. 완료되면 새 모드에서 인증되며 선택된 기계는 없습니다 — 목록을 보려면 `machines`를 실행하거나, 대상으로 바로 이동하려면 `connect <name|id>`를 실행하세요. 재시작이 필요하지 않습니다.

### CLI 단축키 (선택 사항)

스크립팅을 위해 또는 통합 메뉴를 건너뛰고 싶을 때:```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'

구성 스키마 (클라이언트 자격 증명을 사용할 때 `official.tenantId` + `official.clientId`를 제외한 모든 필드는 선택 사항):

| 섹션 | 필드 | 설명 |
|------|------|------|
| `official` | `tenantId` | Azure AD 테넌트 ID |
| `official` | `clientId` | 앱 등록 클라이언트 ID |
| `official` | `clientSecret` | 클라이언트 비밀 (생략하고 `useDeviceCode: true`로 설정하면 디바이스 코드 사용) |
| `official` | `useDeviceCode` | `true`로 설정하면 클라이언트 자격 증명 대신 디바이스 코드 흐름 사용 |
| `defaults` | `defaultMachine` | 시작 시 미리 머신 선택 (이름 하위 문자열 또는 ID 접두사) |
| `defaults` | `commandTimeoutSeconds` | 클라이언트 측 시간 초과 상한. `0` = 서버가 결정 (최대 1800초) |
| `defaults` | `pollIntervalOfficial` | 공식 API 폴링 간격(초) (기본값 2) |
| `defaults` | `pollIntervalInternal` | 내부 API 폴링 간격(초) (기본값 1) |

**보안**: `clientSecret`이 포함된 모든 구성 파일의 파일 시스템 권한을 제한하세요. `clientSecret`은 명령줄에서 절대 허용되지 않으며 구성 파일로만 제공됩니다. 모든 내부 모드 자격 증명(사용자 이름, 암호, TOTP 비밀, 쿠키)은 대화식으로 입력되며 디스크에 저장되지 않습니다.

---

## 인증 방법

쉘은 시작 시 통합된 7가지 방법 인증 메뉴를 제공합니다. 모드(내부/공식)는 선택에 따라 결정됩니다.

| # | 모드 | 방법 | 방식 | 자동 갱신 |
|---|------|------|------|-----------|
| 1 | 내부 | 자격 증명 + TOTP | 대화식 프롬프트 | 예(무음) - TOTP 비밀이 제공된 경우에만 해당. 푸시/SMS MFA를 사용하면 세션을 자동 갱신할 수 없습니다. |
| 2 | 내부 | 소프트웨어 패스키 | `-PasskeyPath` 매개 변수 또는 프롬프트 | 예(무음) |
| 3 | 내부 | ESTS 쿠키 | 대화식 프롬프트 | 아니요(~24시간) |
| 4 | 내부 | 임시 액세스 패스 | 대화식 프롬프트 | 아니요(일회성) |
| 5 | 내부 | 직접 sccauth + XSRF | 대화식 프롬프트 | 아니요(~1시간) -- XSRF 자동 갱신이 적용되지 않습니다. 쉘은 직접 제공된 쿠키를 자동 갱신하지 않습니다. |
| 6 | 공식 | 디바이스 코드 | 브라우저 로그인 | 아니요(~1시간) |
| 7 | 공식 | 클라이언트 자격 증명 | 구성 파일 | 예(무음) |

`connect` 명령은 세션이 만료되면 원래 선택한 방법과 동일한 방법을 사용하여 다시 인증합니다. 자동 갱신이 없는 방법은 대화식으로 다시 프롬프트합니다.

**메모리 내 자격 증명 처리**: 방법 1의 경우, 제공된 암호와 TOTP 비밀은 쉘 프로세스 수명 동안 메모리(일반 문자열로, `$script:Int_ReauthParams` 내부)에 유지되어 무음 재인증이 자동으로 실행될 수 있습니다. 문자열 개체는 PowerShell 실행 공간에 존재하며 디스크에 직렬화되거나 명령줄에 전달되지 않습니다. 해당 노출이 위협 모델에 적합하지 않은 경우 방법 2(패스키/HSM) 또는 방법 7(클라이언트 자격 증명)을 대신 사용하십시오.

---

## 쉘 명령

### 쉘 제어

| 명령 | 설명 |
|------|------|
| `help [command]` | 도움말 표시 (특정 명령에 대해 선택 사항) |
| `help commands` | 설명과 함께 모든 기본 LR 명령 나열 |
| `status` | 연결 상태, 인증 상태, 머신 정보 표시 |
| `config` | Live Response 구성 표시 |
| `connect [name\|id]` | 다시 인증(만료된 경우)하고 머신 선택 |
| `disconnect` | 현재 LR 세션 연결 해제 및 머신 지우기 |
| `multi [options] <cmd>` | 여러 머신에서 명령 실행 (`-top N`, `-filter pattern`) |
| `session [list]` | 현재 세션 정보 또는 모든 캐시된 세션 표시 |
| `mode` | 현재 API 모드 표시 |
| `mode internal\|official` | API 모드 인라인 전환 - 현재 세션 연결을 끊고, 이전 인증 상태를 정리한 후, 대상 모드에 대한 인증 메뉴를 다시 실행합니다. 이후 `machines` 또는 `connect`로 계속 진행하세요. |
| `exit` / `quit` / `q` | 쉘 종료 |

### 머신 관리

| 명령 | 설명 |
|------|------|
| `machines [refresh]` | 머신 나열 및 선택 (refresh = 강제 다시 로드) |
| `connect [name\|id]` | 이름 하위 문자열 또는 ID 접두사로 머신에 연결 |

### 기본 Live Response 명령 (총 25개)

| 명령 | 설명 |
|------|------|
| `run <script> [args]` | MDE 라이브러리에서 스크립트 실행 |
| `getfile <path>` | 원격 머신에서 파일 다운로드 |
| `putfile <name>` | 라이브러리 파일을 원격 작업 디렉터리에 업로드 |
| `processes` | 실행 중인 프로세스 나열 |
| `connections` | 활성 네트워크 연결 나열 |
| `cd <path>` | 작업 디렉터리 변경 (내부 모드) |
| `dir [path]` | 디렉터리 내용 나열 |
| `findfile <name>` | 모든 드라이브에서 파일 검색 |
| `trace` | 진단 추적 정보 표시 |
| `analyze <path>` | 심층 분석을 위해 파일 제출 |
| `remediate <path>` | 파일 격리/수정 |
| `undo <actionId>` | 이전 수정 작업 실행 취소 |
| `registry <key>` | 레지스트리 키/값 쿼리 (Windows 전용) |
| `scheduledtasks` | 예약된 작업 나열 |
| `persistence` | 일반적인 지속성 위치 확인 |
| `drivers` | 로드된 드라이버 나열 (Windows 전용) |
| `services` | 서비스 나열 |
| `startupfolders` | 시작 폴더 내용 나열 (Windows 전용) |
| `fileinfo <path>` | 자세한 파일 정보 가져오기 |
| `prefetch` | 프리페치 데이터 나열 (Windows 전용) |
| `log` | 진단 로그 보기 |
| `jobs` | 백그라운드 작업 나열 (내부 모드) |
| `fg <jobId>` | 백그라운드 작업을 포그라운드로 가져오기 (내부 모드) |
| `library` | 라이브러리 파일 관리 (목록, 업로드, 다운로드, 삭제) |
| `status` | 세션 상태 및 진단 표시 |

### 명령 별칭

| 별칭 | 대상 |
|------|------|
| `ls` | `dir` |
| `ps` | `processes` |
| `download` | `getfile` |
| `process` | `processes` |
| `netstat` | `connections` |

### 임의 명령

기본 제공 명령과 일치하지 않는 모든 입력은 임의 명령으로 처리되어 B64 실행기 스텁을 통해 원격 머신에서 실행됩니다. 예: `whoami`, `ipconfig`, `cat /etc/hostname`.

- Windows 대상: 명령은 UTF-16-LE Base64로 인코딩되어 `executor_b64.ps1` (PowerShell ScriptBlock)을 통해 실행됩니다.
- Linux/macOS 대상: 명령은 UTF-8 Base64로 인코딩되어 `executor_b64.sh` (bash)를 통해 실행됩니다.

**파이프라인 감지**: 첫 번째 단어가 기본 LR 동사인 경우에도 파이프(`|`), 세미콜론(`;`), 리디렉션(`>>`), 또는 하위 표현식(`$()`)이 포함된 명령은 항상 B64로 래핑됩니다. 예를 들어, `dir C:\ | Select-Object`는 기본 `dir`이 아닌 B64를 통해 실행됩니다.

### 라이브러리 관리

| 명령 | 설명 |
|------|------|
| `library` | MDE 라이브러리의 모든 파일 나열 |
| `library refresh` | API에서 라이브러리 목록 강제 새로고침 |
| `library upload <path>` | 로컬 파일을 라이브러리에 업로드 |
| `library delete <name>` | 이름으로 라이브러리에서 파일 삭제 |
| `library download <name>` | 라이브러리에서 파일 내용 다운로드 (내부 API: 직접; 공식 API: 머신이 선택된 후 엔드포인트의 라이브러리 캐시에서 `getfile`을 통해 -- 동기화는 최대 10분 소요 가능) |

### 작업 관리

| 명령 | 설명 |
|------|------|
| `actions` | 현재 머신의 보류 중/진행 중 작업 나열 |
| `actions all` | 모든 머신의 최근 작업 모두 나열 |
| `actions cancel <id>` | ID로 작업 취소 (부분 일치 지원) |

---

## 아키텍처

### 내부 API vs 공식 API

LaraC2 Shell은 동일한 MDE Live Response 백엔드에 대해 두 개의 독립적인 API 경로를 제공합니다. 내부 API는 포털의 WebSocket 유사 세션 모델을 미러링하며 거의 실시간에 가까운 응답을 제공합니다. 공식 API는 Microsoft의 문서화된 REST 엔드포인트를 사용하며 자동화에 적합합니다.

| | 내부 API | 공식 API |
|---|---|---|
| 기본 URL | `security.microsoft.com/apiproxy/mtp/liveResponseApi/` | `api.securitycenter.microsoft.com/api/` |
| 세션 | 지속적 (30분 연결 유지, 자동 재연결) | 명령별 (상태 비저장) |
| 폴링 간격 | ~1초 (거의 실시간) | 2초 |
| 다중 명령 | 공유 세션 내에서 순차적 | 배치 처리 (API 호출당 최대 5개) |
| 인증 | 자체 포함 (ESTS/패스키/TOTP -> sccauth) | OAuth2 클라이언트 자격 증명 또는 디바이스 코드 |
| 기본 시간 초과 | 1800초 (서버가 결정, 클라이언트가 아님) | 1800초 (서버가 결정, 클라이언트가 아님) |

#### LaraC2가 원시 API에 비해 추가하는 기능

| 단계 | 원시 공식 API | LaraC2 쉘 |
|------|---------------|------------|
| 스텁 업로드 | 수동: 멀티파트 구성, POST, 충돌 처리 | 연결 시 자동, 409 재정의 |
| B64 인코딩 | 수동: OS별 UTF-16LE/UTF-8 선택 | OS 자동 감지, 자동 인코딩 |
| RunScript 구성 | 수동: ScriptName + Args 매개 변수가 포함된 JSON | 명령을 직접 입력 |
| 폴링 + 가져오기 | 수동: 루프 + 다운로드 링크 + JSON 구문 분석 | 투명: 깨끗한 출력 반환 |
| 오류 처리 | 수동: 400/401/403/409/429/503 확인 | 자동: 재시도, 백오프, 안내 |
| 다중 명령 | 수동: Commands[] 배열 구성 | 최대 5개의 자동 배치 처리 |

### 주요 제약 조건

공식 API와 내부 API는 머신별 작업 큐를 공유합니다. 동일한 머신에서 동시에 실행할 수 없습니다.

### 속도 제한 (투명)

| 제한 | 값 | 처리 |
|------|-----|------|
| 분당 LR 명령 | 10 | Retry-After 헤더와 함께 429 응답 |
| 분당 라이브러리 업로드 | 100 | 슬라이딩 윈도우 큐 |
| 시간당 라이브러리 업로드 | 1500 | 시간별 카운터 |
| HTTP 429 Too Many Requests | -- | Retry-After 헤더만큼 대기 (기본값 35초) |
| ActiveRequestAlreadyExists | -- | 충돌하는 작업 취소 + 고정 백오프 (10초, 이후 15초로 최대 12회 재시도) |
| Bearer 토큰 만료 (공식) | ~1시간 | 만료 전 자동 갱신 |
| sccauth 만료 (내부) | ~1시간 | 자격 증명이 저장된 경우 무음 재인증 |
| LR 세션 비활성 | 30분 | 자동 재연결 |
| XSRF 교체 | 4분 | 투명 갱신 |

---

## 거의 실시간 쉘 가능성

프로덕션 MDE 테넌트에서 Windows, Linux, macOS 대상에 걸쳐 측정된 대기 시간:

| 작업 | 내부 API | 공식 API |
|------|----------|----------|
| `whoami` (B64) | 4-9초 | 20-46초 |
| `dir` (기본) | 2-4초 | 14-25초 |
| `processes` (기본) | 3-15초 | 20-175초 |
| `connections` (기본) | 2-4초 | ~15초 |
| `services` (기본) | 2-5초 | ~15초 |
| `hostname` (B64) | 4-7초 | 11-16초 |
| 세션 연결 (첫 번째 명령) | 9-15초 | 해당 없음 (상태 비저장) |
| 머신 간 전환 | 7-10초 | 15-30초 |

**내부 API: 거의 실시간 가능.** 세션 재사용 시 기본 명령이 2-5초 내에 응답합니다. 이는 MDE가 허용하는 한 실시간에 가깝습니다. 병목 현상은 프레임워크가 아닌 대상의 SenseIR 에이전트입니다.

**공식 API: 자동화 등급.** 상태 비저장 아키텍처(제출, 폴링, 가져오기)로 인해 명령당 최소 ~15초가 소요됩니다. 대화식 사용이 아닌 스크립트 기반 자동화 및 CI/CD에 적합합니다.

---

## 크로스 OS 지원

Linux 및 macOS 엔드포인트는 두 API 모드를 통해 완전히 지원됩니다.

| 대상 OS | 내부 API 평균 | 공식 API 평균 |
|---------|---------------|---------------|
| Windows | ~7초 | ~30초 |
| Linux | ~6초 | ~26-33초 |
| macOS | ~6초 | ~26-33초 |

**주의 사항**:

1. `.sh` 스텁은 **반드시** Unix 줄 끝(LF, CRLF 아님)이어야 합니다. 그렇지 않으면 bash에서 "ambiguous redirect" 오류가 발생합니다.
2. 공식 API 라이브러리 업로드는 Linux/macOS 엔드포인트에 `.sh` 파일을 **동기화하지 않습니다**. 먼저 내부 API(포털) 또는 Defender 포털 UI를 통해 업로드하세요. 업로드되면 공식 API RunScript가 정상적으로 작동합니다.
3. `executor_b64.sh`는 적절히 업로드되면 Linux 및 macOS에서 작동합니다.

---

## 테스트

테스트 스위트에는 712개의 오프라인 단위 테스트, 301개의 공식 API 통합 테스트, 251개의 내부 API 통합 테스트, 그리고 구성 가능한 부하 테스트 드라이버가 포함되어 있습니다.

### 사전 요구 사항```powershell
Install-Module -Name Pester -MinimumVersion 5.0.0 -Force -Scope CurrentUser

### 내부 API 테스트 (포털 쿠키 필요)

sccauth auth, 세션 수명 주기, 모든 기본 명령, B64 실행, 크로스 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)

| 작업 | 트리거 | 플랫폼 | 요구 사항 |
|-----|---------|-----------|--------------|
| PSScriptAnalyzer Lint | 모든 push/PR | Ubuntu | 없음 |
| 오프라인 테스트 | 모든 push/PR | Ubuntu + Windows + macOS | 없음 |
| 온라인 테스트 (공식) | 조건부 | Ubuntu | `LARAC2_ONLINE_TESTS` 변수 + `LARAC2_CONFIG` 시크릿 |
| 스트레스 테스트 | 수동 실행 | Ubuntu | `LARAC2_CONFIG` 시크릿 |

---

## 문제 해결

| 오류 | 원인 | 해결 방법 |
|-------|-------|------------|
| `ActiveRequestAlreadyExists` | 대상에서 다른 LR 명령이 실행 중임 | 자동 처리 (공식 모드): 충돌 동작 취소 + 10초/15초 고정 백오프 최대 12회 재시도. 내부 모드: 대기 전용. 사용자 작업 불필요. |
| HTTP 429 | 속도 제한 초과 (분당 10개 명령) | 자동 처리: Retry-After 기간 동안 대기 후 재시도. |
| Linux/macOS에서 "script not found" | .sh 스텁이 엔드포인트에 동기화되지 않음 | 내부 API 또는 Defender 포털 UI를 통해 업로드. 공식 API 업로드는 .sh 파일을 동기화하지 않음. |
| Linux/macOS에서 "ambiguous redirect" | .sh 스텁에 CRLF 줄 바꿈이 있음 | LF 줄 바꿈으로 다시 저장하고 재업로드. |
| 대용량 명령에서 HTTP 400 | B64 페이로드가 약 30KB 초과 | 대신 `library upload` + `run <script>` 사용. |
| HTTP 401 | 토큰/세션 만료 | 셸이 클라이언트 자격 증명, TOTP 및 패스키에 대해 자동으로 갱신. 다른 방법은 `connect` 입력. |
| HTTP 403 | 권한 부족 | 공식: `Machine.LiveResponse` + `Library.Manage` 범위 확인. 내부: Security Operator 역할 확인. |
| HTTP 404 | 컴퓨터를 찾을 수 없음 | `machines refresh`를 실행하여 다시 로드. |

---

## 요구 사항

| 요구 사항 | 세부 사항 |
|-------------|--------|
| PowerShell Core | 7.0 이상 (`pwsh`) |
| MDE 앱 등록 | 공식 모드에 필요 (`Machine.LiveResponse` + `Library.Manage` 권한) |
| 운영 체제 | Windows, Linux 또는 macOS (셸은 모든 OS에서 실행 가능; 대상은 MDE에 등록된 모든 OS 가능) |

모든 인증은 자체 포함되어 있습니다. 외부 모듈이 필요하지 않습니다. 내부 모드 인증 흐름은 Fabian Bader & Nathan McNulty의 [XDRInternals](https://github.com/MSCloudInternals/XDRInternals)를 기반으로 합니다.

---

## 파일 레이아웃```
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