akefallonitis/larac2shell

# LaraC2 Shell -- MDE Live Response 交互式 Shell [](https://github.com/akefallonitis/larac2shell/actions/workflows/test.yml) [](LICENSE) [](https://github.com/PowerShell/PowerShell) [](#) **用于 Microsoft Defender for Endpoint Live Response 的跨平台交互式 shell。** | 特性 | 详情 | |---------|--------| | 平台 | PowerShell Core 7.0+ (Windows, Linux, macOS) | | API 模式 | Internal (门户，近实时) 和 Official (公开，无状态) | | 执行 | 任意命令 + 25 个原生 LR 命令 | | 认证 | 7 种身份验证方法，统一菜单，自动刷新 | | 许可证 | MIT | LaraC2 Shell 通过两条独立的 API 路径连接到 MDE Live Response —— 内部门户 API (持久会话，约 2-5 秒延迟) 和官方公共 API (单次命令，约 20-60 秒延迟)。它会自动上传执行器存根，透明地处理速率限制，并提供完整的 REPL，包括机器管理、库管理和内置帮助系统。 ## 文档 | 文档 | 用途 | |-----|---------| | [用户指南](docs/USER_GUIDE.md) | 逐步的设置、身份验证和操作说明 | | [命令参考](docs/COMMAND_REFERENCE.md) | 所有命令、路由、批处理、Tab 补全 | | [错误参考](docs/ERROR_REFERENCE.md) | HTTP 状态码、shell 错误、认证错误及修复方法 | | [性能](docs/PERFORMANCE_COMPARISON.md) | Internal 与 Official 延迟对比、吞吐量、限制 | | [架构](ARCHITECTURE.md) | 内部原理、认证链、端点、文件布局 | | [贡献](.github/CONTRIBUTING.md) | 如何贡献、测试、提交 PR | | [安全策略](SECURITY.md) | 如何私下报告漏洞 | | [参考](REFERENCES.md) | 先前成果、相关研究、致谢 | | [免责声明](DISCLAIMER.md) | 授权与致谢 | ## 功能特性 - **两种 API 模式**: Internal (门户，约 2-5 秒/命令，近实时) + Official (公开，约 20-60 秒/命令，适配 CI/CD) - **统一菜单下的 7 种认证方法**: 客户端凭据、设备代码、凭据+TOTP、passkey/HSM、ESTS cookie、TAP、直接 sccauth —— 模式根据认证选择自动推导 - **25 个原生 LR 命令** + 通过自动上传的 B64 执行器存根执行任意命令 - **跨操作系统目标**: Windows, Linux, macOS 端点 (自动选择执行器 + 编码) - **透明的速率限制**: 429 退避、ActiveRequest 智能冲突解决 (12 次重试，取消外部请求 / 等待自身请求) - **会话生命周期**: 自动连接、30 分钟不活动后自动重连、过期会话清理、跨机器切换 - **认证生命周期**: OAuth2 自动刷新、XSRF 自动刷新 (4 分钟 TTL)、TOTP/passkey 的静默重新认证；会话过期时通过 `connect` 命令重新认证 - **会话复用**: 透明的自动连接、自动重连和跨机器切换，无需用户干预 - **多机执行**: 带有名称模式过滤和 Top-N 限制的 `multi` 命令 - **多命令批处理**: 每次 Official API 调用最多 5 个命令，更大的命令集会自动拆分 - **库管理**: 列出、上传、删除、下载、自动上传执行器存根、409 冲突覆盖 - **操作管理**: 列出、取消 (支持部分 ID 匹配)、状态详情 - **交互式用户体验**: Tab 补全、命令别名 (ls/ps/netstat)、工作目录跟踪、帮助系统 - **错误指导**: 上下文感知消息 (400->语法, 401->重新认证, 403->权限范围, 429->速率限制) - **CLI 中无秘密信息**: 凭据来自配置文件或交互式提示，绝不进入命令历史 ## 快速开始 ### 前置条件 - [PowerShell Core 7.0+](https://github.com/PowerShell/PowerShell/releases) (Windows, Linux, 或 macOS) - 拥有 Live Response 访问权限的门户账号 (**内部模式**) 或具有 `Machine.LiveResponse` + `Library.Manage` 权限的 MDE 应用注册 (**官方模式**) ### 启动 ``` git clone https://github.com/akefallonitis/larac2shell.git cd larac2shell pwsh -File shell/Invoke-MDEShell.ps1 ``` 就是这样。Shell 在首次启动时会显示一个统一的 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): ``` 选项 1-5 设置内部模式，6-7 设置官方模式。你可以稍后在不重启的情况下切换模式 —— 参见下文的 **[内联切换模式](#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 ' to select one. ``` `mode ` 会断开任何当前的 LR 会话，清除旧的认证状态，并为目标模式重新运行认证流程。当它返回时，你已在新模式下完成认证，但尚未选择机器 —— 运行 `machines` 进行列出，或运行 `connect ` 直接跳转到目标。无需重启。 ### CLI 快捷方式 (可选) 用于脚本编写或当你想跳过统一菜单时： ``` # 预选模式（将 auth 菜单缩小至 1-5 或 6-7） pwsh -File shell/Invoke-MDEShell.ps1 -Mode internal pwsh -File shell/Invoke-MDEShell.ps1 -Mode official # 预选机器（跳过选择器） pwsh -File shell/Invoke-MDEShell.ps1 -Machine myhost # Software passkey 路径（internal 模式） pwsh -File shell/Invoke-MDEShell.ps1 -PasskeyPath ./keys/passkey.json # 非交互式单命令（以远程命令的退出代码退出） pwsh -File shell/Invoke-MDEShell.ps1 -Machine myhost -Command 'whoami' ``` ### 配置文件 (可选) 仅用于 **一种** 场景：非交互式下使用客户端密钥的官方模式。其他每种认证方法都会以交互方式提示你，并且不会在磁盘上存储任何内容。如果你不需要无人值守的客户端凭据认证，你可以完全跳过本节。 ``` Copy-Item shell/config/shell-config.example.json shell/config/shell-config.json # 编辑文件：设置 official.tenantId，official.clientId，official.clientSecret pwsh -File shell/Invoke-MDEShell.ps1 -Config shell/config/shell-config.json ``` 配置结构 (使用客户端凭据时，除 `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` | Official API 轮询间隔 (秒，默认为 2) | | `defaults` | `pollIntervalInternal` | Internal API 轮询间隔 (秒，默认为 1) | **安全性**：限制包含 `clientSecret` 的任何配置文件的文件系统权限。命令行永远不会接受 `clientSecret` —— 仅限配置文件。所有内部模式的凭据 (用户名、密码、TOTP 密钥、cookies) 都是通过交互式提示输入的，绝不会持久化到磁盘。 ## 身份验证方法 Shell 在启动时会显示一个统一的 7 种方式认证菜单。模式 (内部/官方) 根据你的选择自动推导。 | # | 模式 | 方法 | 方式 | 自动刷新 | |---|------|--------|-----|--------------| | 1 | Internal | 凭据 + TOTP | 交互式提示 | 是 (静默) —— 仅在提供了 TOTP 密钥时。使用推送/短信 MFA 时，会话无法自动刷新。| | 2 | Internal | 软件 passkey | `-PasskeyPath` 参数或提示 | 是 (静默) | | 3 | Internal | ESTS cookie | 交互式提示 | 否 (约 24 小时) | | 4 | Internal | 临时访问通行码 | 交互式提示 | 否 (一次性) | | 5 | Internal | 直接 sccauth + XSRF | 交互式提示 | 否 (约 1 小时) —— XSRF 自动刷新不适用；shell 不会自动刷新直接提供的 cookies。| | 6 | Official | 设备代码 | 浏览器登录 | 否 (约 1 小时) | | 7 | Official | 客户端凭据 | 配置文件 | 是 (静默) | 当会话过期时，`connect` 命令会使用最初选择的相同方法重新进行身份验证。不支持自动刷新的方法将再次以交互方式提示。 **内存中的凭据处理**：对于方法 1，提供的密码和 TOTP 密钥会在 Shell 进程的整个生命周期内保留在内存中 (作为纯字符串，位于 `$script:Int_ReauthParams` 内)，以便静默重新认证可以在无人值守的情况下运行。字符串对象存在于 PowerShell runspace 中；它们不会被序列化到磁盘或在命令行中传递。如果这种暴露在你的威胁模型中不可接受，请改用方法 2 (passkey/HSM) 或方法 7 (客户端凭据)。 ## Shell 命令 ### Shell 控制 | 命令 | 描述 | |---------|-------------| | `help [command]` | 显示帮助 (可选择针对特定命令) | | `help commands` | 列出所有带有描述的原生 LR 命令 | | `status` | 显示连接状态、认证状态、机器信息 | | `config` | 显示 Live Response 配置 | | `connect [name\|id]` | 重新认证 (如果已过期) 并选择一台机器 | | `disconnect` | 断开当前的 LR 会话并清除机器信息 | | `multi [options] ` | 在多台机器上运行命令 (`-top N`, `-filter pattern`) | | `session [list]` | 显示当前会话信息或所有缓存的会话 | | `mode` | 显示当前的 API 模式 | | `mode internal\|official` | 内联切换 API 模式 —— 断开当前会话，拆除旧认证状态，并为目标模式重新运行认证菜单。之后可使用 `machines` 或 `connect` 继续 | | `exit` / `quit` / `q` | 退出 shell | ### 机器管理 | 命令 | 描述 | |---------|-------------| | `machines [refresh]` | 列出机器并选择一台 (refresh = 强制重新加载) | | `connect [name\|id]` | 通过名称子串或 ID 前缀连接到机器 | ### 原生 Live Response 命令 (共 25 个) | 命令 | 描述 | |---------|-------------| | `run