corellium-mcp

<div align="center"> # Corellium MCP ### 面向代码模式的模型上下文协议（MCP）服务器 - 适用于 Corellium 的移动安全平台 [](https://modelcontextprotocol.io) [](#%E4%B8%BA%E4%BB%80%E4%B8%8A%E4%BB%A3%E7%A0%81%E6%A8%A1%E5%BC%8F) [](https://www.typescriptlang.org) [](https://nodejs.org) [](https://github.com/laverdet/isolated-vm) [](./LICENSE) </div> --- Corellium 的 REST API 提供了 **206 种操作**，涵盖虚拟的 iOS/Android 设备、快照、设备上的代理、网络捕获、CoreTrace、HyperTrace、内核钩子以及 MATRIX 安全评估引擎。直接封装这些操作为 MCP 工具的一种天真方法是为每种操作创建一个 MCP 工具 - 这会在每次调用时向模型的上下文中注入 **约 90k+ 个 JSON 模式令牌**，甚至在读取请求之前，并将模型远远推过经验性的 **10-15 工具上限**，导致工具选择准确率急剧下降。 **Corellium MCP 采用 Anthropic 和 Cloudflare 都曾发表过的方法：代码执行**。模型编写针对类型化的 `corellium` 客户端的小型 TypeScript 代码片段，并在安全的 V8 沙盒中运行。206 种操作的目录成为一个发现步骤（`corellium_search`），而不是始终开启的上下文。最终结果：整个平台适合 **约 2k 个始终开启的表面令牌**，而模型在一个工具调用中编排多步骤的设备工作流。 ``` 模型（Claude / GPT / ...） │ 只看到 2 个工具 （~2k 令牌，而不是 ~90k） ┌────────────────┴─────────────────┐ ▼ ▼ ┌─────────────────┐ ┌────────────────────────┐ │ corellium_search│ 发现 │ corellium_run │ 执行 │ 查询 · 详情 │ （按需） │ 代码 · 允许破坏性操作│ （主力） └────────┬────────┘ └───────────┬────────────┘ │ 排名超过 │ 在沙盒中运行模型 TS ▼ ▼ ┌─────────────────┐ ┌───────────────────────────────────┐ │ 规范索引 │ │ 沙盒 （隔离的 vm · V8） │ │ • 206 操作 │ │ 无网络 · 无文件系统 · 无 Node │ │ • 人机工程学 │ │ 全局变量 · 内存 + 时钟上限 │ │ 包装器 │ │ 范围内：`corellium`、`console`、 │ │ • 食谱 │ │ `sleep`、`artifacts` │ └─────────────────┘ └────────────────┬────────────────────┘ │ __bridge(op,args) ═══════════ 安全边界 ═══════════ ▼ 令牌仅在此处存在 ┌───────────────────────────────────┐ │ 主机桥 │ │ • 注入 Bearer 令牌 │ │ • 破坏性操作防护栏 │ │ • 二进制 → 磁盘上的工件句柄 │ └────────────────┬────────────────────┘ ▼ HTTPS <tenant>.enterprise.corellium.com/api/v1/* ``` > 模型在隔离的 V8 沙盒中针对类型化的 `corellium` 客户端编写 JavaScript；它按需发现 206 操作的表面，而不是每次支付。 --- ## 目录 - [为什么选择代码模式](#%E4%B8%BA%E4%BB%80%E4%B8%8A%E4%BB%A3%E7%A0%81%E6%A8%A1%E5%BC%8F) - [两个工具](#%E4%B8%A4%E4%B8%AA%E5%B7%A5%E5%85%B7) - [安全模型](#%E5%AE%89%E5%85%A8%E6%A8%A1%E5%9E%8B) - [快速开始](#%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B) - [与 Claude Code 一起使用](#%E4%B8%8A%E4%BB%80%E4%B8%8AClaude%20Code) - [质量评估器](#%E8%B4%A8%E9%87%8F%E8%AF%84%E4%BC%B0%E5%99%A8) - [架构决策](#%E6%9E%84%E6%9E%AD%E5%86%B3%E7%AD%96) - [项目结构](#%E9%A1%B9%E7%9B%AE%E7%BB%93%E6%9E%84) - [状态和路线图](#%E7%8A%B6%E6%80%81%E5%92%8C%E8%B7%AF%E7%94%B1%E5%9B%BE) - [先前的工作和参考资料](#%E5%85%88%E5%89%8D%E7%9A%84%E5%B7%A5%E4%BD%9C%E5%92%8C%E5%8F%82%E9%A1%B5) --- ## 为什么选择代码模式 您为 MCP 客户端注册的每个工具都会在每次调用中加载到模型的上下文中，作为完整的 JSON 模式。两个累积问题随之而来： 1. **上下文税。** Corellium 的规范为 355 KB / 206 操作。作为单独的工具公开，这大约是 **90k-120k 个令牌的模式**，模型在每次回复之前都会重新读取 - 速度较慢，成本较高，并且挤占了您的实际任务。 2. **决策退化。** 随着选项数量的增加，工具选择准确率会下降；实际上限为 **~10-15 个工具**。一个 68 到 206 工具的服务器直接超过了它，并且误选急剧增加。 Anthropic（2025 年 11 月）和 Cloudflare（2026 年 2 月）都采用了相同的解决方案：**提供一个执行原语而不是类型化的 API，并使目录成为发现步骤。** Anthropic 报告称令牌减少了 150k → 2k（98.7%）；Cloudflare 报告称在一个 2,500 端点的 API 上减少了 99.9%。Corellium MCP 将此模式应用于移动安全工具。 | | 天真 MCP（每个操作一个工具） | **Corellium MCP（代码模式）** | | --- | --- | --- | | 始终开启的工具 | 206 | **2** | | 始终开启的上下文 | ~90k+ 令牌 | **~2k 令牌** | | 多步骤工作流 | 需要多次调用模型 | **1 次 `run` 调用** | | 中间数据（例如 200 个实例） | 通过上下文流动 | **在沙盒中过滤** | | 二进制大文件（截图、pcap、转储） | base64 进入上下文 | **保存到磁盘，返回句柄** | | 发现 | 始终加载 | **按需通过 `corellium_search`** | --- ## 两个工具 ### `corellium_search` - 发现（廉价，只读） 在固定的 OpenAPI 接口、手工编写的人机工程学包装器和精选的配方上进行排名。根据所选的详细程度返回签名，以便模型仅花费必要的令牌。 ```jsonc { "query": "安装一个 ipa 并启动它", "detail": "summary", // "name" | "summary" | "full" "kind": "wrapper" // 可选： "operation" | "wrapper" | "recipe" } ``` ### `corellium_run` - 执行（主力） 在沙盒中运行模型编写的异步函数，针对类型化的 `corellium` 客户端，并返回大小受限的 JSON 结果、捕获的 `console.log` 输出和任何工件句柄。 ```jsonc { "code": "async () => { /* TypeScript 针对 `corellium` */ }", "allow_destructive": false, // DELETE/erase 被限制在此选项后 "timeout_ms": 120000 } ``` **模型可能编写的示例** - 启动设备，安装应用，运行它，截图： ```js async () => { const [project] = await corellium.get('/v1/projects'); const device = await corellium.instances.createAndBoot({ project: project.id, flavor: 'iphone16pro', os: '18.0', }); const agent = await device.agent(); await agent.installApp('https://example.com/app.ipa'); await agent.runApp('com.example.app'); const shot = await device.screenshot(); // → 工件句柄，而不是 base64 字节 return { instance: device.id, screenshot: shot.path }; } ``` 模型看到 `{ instance, screenshot: "artifacts/<run>/screenshot.png" }` - 几个令牌 - 而 PNG 位于磁盘上。它在沙盒中过滤、循环和组合；只有提炼的结果才会传递回来。 --- ## 安全模型 该服务器持有实时 API 令牌并运行 **模型生成的代码**。设计将这两个事实分开。 ``` 模型代码 ──调用──▶ corellium.request(...) ──桥接──▶ 主机 ──HTTPS+Bearer──▶ Corellium （沙盒） （无令牌） （令牌位置） ``` - **令牌从未进入沙盒。** 它在 `src/primitives/client.ts` 中被读取和附加，仅在桥接的主机端。 在隔离环境中，`process`、`require`、`fetch` 和任何环境访问都为 **`undefined`** （由自动隔离探针验证）。 - **真正的隔离，而不是 `eval`。** 代码在 [`isolated-vm`](https://github.com/laverdet/isolated-vm) 中运行 - 一个专用的 V8 隔离环境，具有自己的堆、硬内存限制、时钟超时和 **无网络和无文件系统**。 唯一的出口是类型化的桥接。 - **破坏性操作防护栏。** `DELETE` （和 `erase`/`wipe`/`reset` 路径）**默认被阻止** 并返回清晰的消息；模型必须重新发出 `allow_destructive: true` 才能继续。 读取和创建操作是无限制的。 - **机密红化。** 令牌字符串从每个错误、日志行和结果中被清除，然后才能到达模型或转录本。 - **大文件不进入上下文。** 截图、pcap、CoreTrace/RAM 转储被写入 `artifacts/<run-id>/` 并表示为 `{ name, path, bytes, sha256, kind }` 句柄。 --- ## 快速开始 > 需要 Node ≥ 20 和 Corellium 账户（云、企业或本地）以及 API 令牌。 ```bash git clone https://github.com/H4RR1SON/corellium-mcp.git cd corellium-mcp npm install cp .env.example .env # 然后填写 CORELLIUM_API_HOST + CORELLIUM_API_TOKEN npm run spec:pull # 固定租户的 OpenAPI 规范（206 个操作） npm run gen:types # 从规范生成 TypeScript 类型 npm run smoke # 现场检查：列出项目 + 实例 ``` `.env`: ```ini CORELLIUM_API_HOST=your-instance.enterprise.corellium.com # 仅主机，不带方案 / 无 /api CORELLIUM_API_TOKEN=•••••••• # 设置 → API 令牌 CORELLIUM_INSECURE_TLS=0 # 仅为本地自签名设置 1 ``` `.env` 被 git 忽略。令牌从未被提交、记录或进入沙盒。 --- ## 与 Claude Code 一起使用 ```bash claude mcp add corellium -- npx -y tsx /absolute/path/to/corellium-mcp/src/server.ts ``` 然后，在会话中，模型只有两个工具 - `corellium_search` 和 `corellium_run` - 以及它们背后的整个平台。要求它 *“启动 iPhone 16，安装此 IPA，并捕获网络流量”，* 然后它会发现相关的原语，编写一个代码段并运行它。 --- ## 质量评估器 代码模式 MCP 只有在可衡量地帮助模型时才有价值。该存储库附带了一个 **可重现的 A/B 测试框架**，它量化了收益而不是断言它。 ``` TASK SUITE ──▶ RUNNER ─┬─▶ [ code-mode MCP ] （搜索 + 运行） ─┐ （声明， 按模型 └─▶ [ 天真 MCP ] （206 个工具） ─┤ 共享 oracle 操作） ▼ 记录的后端（重放） SCORERS ──▶ 报告（md + json） ── A/B + 排行榜 + 图表 令牌 · 工具选择 · 声明 · 成本 ``` - **按构造 A/B 测试。** 相同的任务套件针对此服务器 *和* 一个自动生成的、天真的服务器运行，该服务器公开所有 206 个操作作为单独的工具 - 在相同的、**记录的** 后端，因此比较隔离了代码模式效果并运行确定性和免费。 - **重要的指标：** - **令牌效率** - 始终开启的工具定义令牌（`S`）、每轮增长、工具结果令牌（`r`）和 **每个已完成任务的总令牌数** （暴露代码模式攻击的二次增长）。 - **工具选择准确率** - 模型是否调用了正确的 Corellium 操作？在两种模式下都进行了相同的测量（工具调用日志与生成的代码的 AST）。 - **任务成功率** - 基于声明的评分，带有部分积分，以及失败分类法（认知 vs. 执行 vs. 工具选择）。 - **成本和延迟** - 令牌 × 速率，和 p50/p95 墙上时钟，每个模型。 ```bash npm run eval # → eval/reports/<timestamp>.{md,json} ``` --- ## 架构决策 每一个非显而易见的选择，都带有推理和权衡。 **1. 两个工具（`search` + `run`），而不是 206 个。** 单一执行原语 *是* 论点；`search` 是廉价的发现伴侣，保持目录不常驻上下文。*权衡：* 模型必须在行动前发现 - 通过排名、详细程度和精选的配方来缓解。 **2. OpenAPI 规范的广度，手工包装器的舒适度。** 官方的 JS SDK **没有通用 `request()`**，因此它无法达到 100% 的表面积。我们从租户固定的 `openapi.json` （每个端点都可以通过 `corellium.request` 访问）生成类型化的客户端，并添加约 15 个包装器，用于尴尬的异步流程（创建和启动带有状态轮询、代理会话、捕获到工件）。*权衡：* 固定的规范可能会漂移 - `npm run spec:pull` 在一个命令中重新固定它。 **3. TypeScript / Node，沙盒语言为 JavaScript。** LLM 编写的 JS 远比它们生成的 JSON 调用工具更好；类型比 OpenAPI 更简洁；最强的进程内沙盒（`isolated-vm`，真正的 V8 隔离环境）是 Node 原生的。一种语言跨越服务器 + 评估器。*权衡：* `isolated-vm` 是一个原生插件 - 从常见平台上的预构建二进制文件安装。 **4. `isolated-vm`，而不是 `vm2`/`node:vm`/容器。** 我们运行模型生成的代码旁边一个实时凭证，因此我们需要一个真正的堆/CPU 边界，没有 Node 全局变量，没有网络，没有文件系统 - 不是可逃避的 `node:vm`，也没有每次调用的数百毫秒容器。`isolated-vm` 启动速度很快，只需几毫秒即可完成。*权衡：* 沙盒仅限 JavaScript，并且只能通过类型化的桥接器访问主机（按设计）。 **5. 令牌在主机上，桥接器在两者之间。** 沙盒内的 `corellium` 对象是一个薄代理；每个调用都跨越了 `isolated-vm` 引用到主机，主机附加了 `Authorization` 头 - Cloudflare 的 `globalOutbound` 想法，在进程内实现。模型永远无法读取、记录或泄露令牌。 **6. 二进制和大结果成为句柄。** 截图、pcap 和转储被写入磁盘，并作为小句柄返回；JSON 结果大小受限，并附有“在沙盒中过滤并返回较少内容”的提示。这直接最小化了主导多轮代理成本的工具结果令牌项。 **7. 破坏性操作需谨慎。** 默认安全姿态：`DELETE`/`erase`/`wipe`/`reset` 被限制在 `allow_destructive` 之后，因此探索性代理不会意外销毁设备、快照或用户。 **8. 评估器是首要交付物，而不是事后想法。** 整个前提 - “工具更少，代码更多，结果更好” - 是一个经验性主张，因此存储库提供了测试它的 A/B 测试框架，而不是事后想到的。 --- ## 项目结构 ``` corellium-mcp/ ├── src/ │ ├── server.ts # MCP 服务器：注册 corellium_search + corellium_run（stdio） │ ├── tools/ # search.ts（发现）· run.ts（执行） │ ├── primitives/ │ │ ├── client.ts # 主机 HTTP 客户端 - 唯一使用令牌的地方 │ │ ├── schema.d.ts # 从 openapi.json 生成的类型（按 operationId 键控） │ │ └── wrappers.ts # 约 15 个舒适的流程（创建和启动，代理，捕获） │ ├── sandbox/ │ │ ├── isolate.ts # isolated-vm 执行器 + 主机桥 + 防护栏 │ │ ├── preamble.ts # 沙盒内 `corellium`/`console`/`sleep` 定义 │ │ └── artifacts.ts # blob → 磁盘上的句柄存储 │ └── spec/openapi.json # 固定的 Corellium OpenAPI 3.0.3（206 个操作） ├── eval/ # A/B 测试框架：运行器 · 评估器 · 任务 · 天真基线 · 报告 └── scripts/ # 拉取规范 · 烟雾测试 · 沙盒烟雾测试 ``` --- ## 状态和路线图 在实时企业租户上构建和验证，逐步完成： - [x] **P0 - 搭建 + 固定规格。** 带有承载身份验证的主机客户端 + 原始 `request`；现场烟雾测试列出真实项目/实例；从 206 操作的规格中生成类型。 - [x] **P1 - 沙盒 + 桥接器。** `isolated-vm` 执行器，令牌隔离（探针验证），工件捕获，破坏性防护栏。 - [ ] **P2 - 原语 + 包装器。** 每个标签的命名空间 + 15 个舒适的异步包装器。 - [ ] **P3 - 发现。** 具有详细程度和混合排名的 `corellium_search`，在规范 + 包装器 + 配方之上。 - [ ] **P4 - 评估器。** 记录/重放后端，基于声明的任务套件，天真基线，评估器，报告。 - [ ] **P5 - 注册 + 调整。** 与 Claude Code 集成；根据评估数字迭代类型化表面。 --- ## 先前的工作和参考资料 - Anthropic - [代码执行与 MCP：构建更高效的代理](https://www.anthropic.com/engineering/code-execution-with-mcp) （2025 年 11 月） - Cloudflare - [代码模式：给代理整个 API，1000 个令牌](https://blog.cloudflare.com/code-mode-mcp/) （2026 年 2 月） - [模型上下文协议规范](https://modelcontextprotocol.io) - [Corellium REST API 和 SDK 文档](https://support.corellium.com/sdk/) - [`isolated-vm`](https://github.com/laverdet/isolated-vm) · [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) --- ## 许可证 [MIT](./LICENSE)。 不隶属于 Corellium，也不得到 Corellium 的认可。仅限于您有权访问的设备和租户使用。