それだけです。シェルは初回起動時に統一された7つの方法のauthメニューを表示します — 1つを選び、認証し、マシンを選択すると、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` を除き、すべてのフィールドはオプション）:

| Section | Field | Description |
|---------|-------|-------------|
| `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 シークレット、Cookie）は対話的に要求され、ディスクに永続化されることはありません。

---

## 認証方法

シェルは起動時に統一された7つの認証方法メニューを表示します。モード（内部/公式）は選択に基づいて決定されます。

| # | モード | 方法 | 方法詳細 | 自動更新 |
|---|------|--------|-----|--------------|
| 1 | 内部 | 認証情報 + TOTP | 対話型プロンプト | はい（サイレント）-- TOTP シークレットが提供された場合のみ。プッシュ/SMS MFA ではセッションは自動更新できません。 |
| 2 | 内部 | ソフトウェアパスキー | `-PasskeyPath` パラメータまたはプロンプト | はい（サイレント） |
| 3 | 内部 | ESTS Cookie | 対話型プロンプト | いいえ（約24時間） |
| 4 | 内部 | 一時アクセスパス | 対話型プロンプト | いいえ（1回限り） |
| 5 | 内部 | 直接 sccauth + XSRF | 対話型プロンプト | いいえ（約1時間）-- XSRF 自動更新は適用されません。シェルは直接指定された Cookie を自動更新しません。 |
| 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` | セッションステータスと診断を表示 |

### コマンドエイリアス

| Alias | Resolves To |
|-------|-------------|
| `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 と公式 API

LaraC2 Shell は、同じ MDE Live Response バックエンドに対して2つの独立した 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 Shell |
|------|-----------------|-------------|
| スタブのアップロード | 手動: マルチパートを構築、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 コマンド（1分あたり） | 10 | Retry-After ヘッダー付きの 429 応答 |
| ライブラリアップロード（1分あたり） | 100 | スライディングウィンドウキュー |
| ライブラリアップロード（1時間あたり） | 1500 | 時間単位カウンター |
| HTTP 429 Too Many Requests | -- | Retry-After ヘッダーの間スリープ（デフォルト35秒） |
| ActiveRequestAlreadyExists | -- | 競合するアクションをキャンセル + 固定バックオフ（10秒、その後最大12回のリトライで15秒） |
| ベアラートークンの有効期限（公式） | 約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秒 | N/A (ステートレス) |
| マシン間の切り替え | 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のライブラリアップロードは `.sh` ファイルを Linux/macOS エンドポイントに同期 **しません**。最初に内部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認証、セッションライフサイクル、すべてのネイティブコマンド、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 | 毎回のプッシュ/PR | Ubuntu | なし |
| Offline Tests | 毎回のプッシュ/PR | Ubuntu + Windows + macOS | なし |
| Online Tests (Official) | 条件付き | Ubuntu | `LARAC2_ONLINE_TESTS` 変数 + `LARAC2_CONFIG` シークレット |
| Stress Tests | 手動ディスパッチ | Ubuntu | `LARAC2_CONFIG` シークレット |

---

## トラブルシューティング

| エラー | 原因 | 解決方法 |
|-------|-------|------------|
| `ActiveRequestAlreadyExists` | ターゲットで別のLRコマンドが実行中 | 自動処理（公式モード）：競合アクションのキャンセル＋固定10秒/15秒のバックオフ（最大12回リトライ）。内部モード：待機のみ。ユーザー操作は不要。 |
| HTTP 429 | レート制限超過（1分あたり10コマンド） | 自動処理：Retry-After期間だけスリープしてリトライ。 |
| "script not found" on Linux/macOS | .shスタブがエンドポイントに同期されていない | 内部APIまたはDefenderポータルUIからアップロード。公式APIのアップロードでは.shファイルは同期されません。 |
| "ambiguous redirect" on Linux/macOS | .shスタブにCRLFの改行コードが含まれている | LF改行コードで保存し直してアップロード。 |
| HTTP 400 on large command | B64ペイロードが約30 KBを超えている | 代わりに `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（シェルはいずれでも動作します。ターゲットは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