Files
SimpleRemoter/docs/Mcp_BuildClient_Design.md
T
yuanyuanxianganddeepseek-flash 7172ab376d Feature: add build_client MCP tool and improve build dialog linkage
Add a service-local MCP tool, build_client, that patches a client template
with this master's connect settings and writes the binary on the server.
It covers ghost/TestRun/ServerDll/TinyRun plus Linux, macOS and Android,
reusing the same byte path as CBuildDlg::OnBnClickedOk (CONNECT_ADDRESS
overwrite, build-date check, embedded TLS anchor before UPX/padding).
ShellCode AES and payload impersonation stay dialog-only.

The tool is gated by a new McpBuild switch (default 0) and McpReadonly=0.
It refuses to overwrite an existing file unless overwrite=true, protects
the server binaries/settings.ini/upx.exe, validates names strictly and
uses a unique UPX temp file so it cannot race the dialog. Results report
the path, size, target, TLS-anchor status and follow-up tips.

In the build dialog, Linux/macOS/Android targets now also grey out the
install-location combo/label and run mode, save and restore the Windows
compress choice, hide payload/download rows, grey the random-name and
run-as-admin menu items, and fix the TLS-anchor label for posix targets.
OnBnClickedOk is untouched; generated output is unchanged for every target.

New UI strings were added to the en_US, zh_TW and de_DE language packs.
McpBuild is off by default and changes require a server restart.
Verified on a Debug x64 instance: MCP generation for Linux is patched
correctly, Android and ghost anchor/error paths behave, and dialog-driven
Linux/TestRun/SC_AES generation still succeeds. mcp/tools.json regenerated
(55 tools); check_platform_table.py passes.

Co-Authored-By: deepseek-flash
2026-11-15 20:43:28 +01:00

136 lines
8.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 生成客户端 MCP 工具(build_client)设计
> 2026-11-15。让模型把「生成一个连 1.2.3.4:443 的 Linux 客户端」这类需求直接落成
> 服务端本机上的一个客户端文件。实现在 `server/2015Remote/McpBuildClient.{h,cpp}`。
## 1. 定位
`build_client` 是**服务端本地工具**,不针对任何在线主机:
- 入参没有 `id`,平台门禁(`CheckToolPlatform`)因拿不到主机而直接放行;
- `kToolPlatforms` 仍登记为全平台(`win|lnx|mac|apk`),与其它服务端本地工具一致;
- 工具只读模板资源、写服务端本机文件,不向任何客户端下发命令。
它复用「生成服务端」对话框(`BuildDlg.cpp::CBuildDlg::OnBnClickedOk`)的字节搬运路径:
```
读资源(res 目录优先,回退内嵌)
→ 构造 CONNECT_ADDRESS(地址/端口/类型/启动方式/分组/安装目录/主控 ID/pwdHash)
→ 模板发布日期校验(模板比主控新则拒绝)
→ 原地覆盖所有 FLAG_FINDEN 命中处
→ 内嵌 TLS 信任锚(在 UPX / 增肥之前)
→ 落盘
→ 可选 UPX / 增肥
```
对话框专属的 ShellCode AES / PE→ShellCode / 载荷伪装流程(需要额外的载荷文件与
图片容器)**不在本工具范围内**:传 `compress` 其他值会返回 `-32602` 并提示改用对话框。
## 2. 开关与错误码
| 条件 | 行为 |
|---|---|
| `McpBuild=1` 且 `McpReadonly=0` | 工具出现在 `tools/list`,可调用 |
| `McpBuild=0` | 不出现;直接调用返回 `-32006` |
| `McpReadonly=1` | 工具出现但调用返回 `-32006`(与 `host_set_remark` / `host_set_watch_level` 这类只改服务端本地数据的工具一致:列出、调用时拒绝) |
`McpBuild` 默认 `0`,改动需重启服务端生效。之所以不复用 `McpManage` / `McpFileWrite`:
生成的是**带主控凭据、可分发的客户端二进制**,风险等级与「操作在线主机」不同,需要能
单独关掉。工具同时要求只读模式关闭。
参数错误统一 `-32602`;文件已存在且 `overwrite=false`、输出路径是目录返回 `-32012`;
模板缺失 / 模板比主控新 / 找不到 `CONNECT_ADDRESS` / 写盘或 UPX 失败返回 `-32001`。
## 3. 参数
| 参数 | 必填 | 说明 |
|---|---|---|
| `target` | 是 | `ghost` / `ghost_service` / `ghost_system` / `testrun_dll` / `testrun_memdll` / `testrun_injsc` / `testrun_service` / `testrun_system` / `serverdll` / `tinyrun` / `linux` / `macos` / `android` |
| `arch` | 否 | `x64`(默认)/ `x86`;posix 固定架构,传 `x86` 返回 `-32602`;`testrun_injsc` 只支持 x64 |
| `host` | 否 | 主控地址,可含分号分隔的多地址;省略取服务端当前有效主控地址(含上级 FRP) |
| `port` | 否 | 省略取服务端当前有效端口 |
| `protocol` | 否 | `tcp`(默认)/ `udp` / `http` / `random` / `kcp` / `ws` / `wss` |
| `header_enc` | 否 | `hell`(默认)/ `shine` |
| `running` | 否 | `random`(默认)/ `parallel` |
| `group` | 否 | 分组名,≤23 字节 ANSI |
| `install_location` | 否 | `programdata`(默认)/ `programfiles` / `systemroot` / `appdata` / `localappdata` |
| `install_dir` / `install_name` | 否 | Windows 安装子目录/程序名,≤31 字节,按 Windows 文件名规则校验 |
| `run_as_admin` | 否 | 默认 `false`;安装 Windows 服务时通常需要 |
| `encrypt_address` | 否 | 默认 `true`;`testrun_injsc` 与 `tinyrun` 与对话框一致,不加密 |
| `compress` | 否 | `none`(默认)/ `upx`;仅 Windows 目标 |
| `tls_anchor` | 否 | 默认 `true`;见 §4 |
| `padding_mb` | 否 | 0–256,仅 Windows 目标 |
| `output_dir` | 否 | 默认主控程序目录;不存在会自动创建 |
| `output_name` | 否 | 默认按 target 取 `ghost.exe` / `TestRun.exe` / `ServerDll.dll` / `TinyRun.dll` / `ghost` / `ghost.apk` |
| `overwrite` | 否 | 默认 `false`;目标已存在时返回 `-32012`,确认后传 `true` 重试 |
字符串入参按 UTF-8 接收,落到 ANSI 结构体/路径前用 `Utf8ToCpExact` 严格转换;
服务端代码页表示不了的字符直接拒绝,不用 `?` 顶替(否则会写出路径或分组名都不对的
客户端)。
## 4. 内嵌 TLS 信任锚
只有 `ghost` / `ghost_service` / `ghost_system` / `serverdll` 的 Windows 模板里有
`EmbeddedTlsAnchor` 块(`client/EmbeddedTlsAnchor.cpp`)。工具按以下顺序判定,
结果写入 `tlsAnchor`:
| 状态 | 含义 |
|---|---|
| `disabled` | 入参 `tls_anchor=false` |
| `not_applicable` | TestRun / TinyRun:模板不含客户端代码(TestRun 的锚要生成进 ServerDll.dll) |
| `unsupported_platform` | Linux / macOS / Android 模板没有锚块,信任锚由主控在线下发 |
| `skipped_protocol` | 协议不是 tcp/http(ws/wss 的锚是反代那张证书) |
| `unavailable` | 服务端未启用可用 TLS 身份 |
| `no_block` | 模板里没有锚块(资源未重编),按普通客户端生成,不视为失败 |
| `embedded` | 已写入;`tlsAnchorSummary` 给出证书摘要 |
与对话框一致:`Ambiguous` / `TooLong` / `NoAnchor` 会中止生成(`-32001`),
`NoBlock` 只提示;锚必须在 UPX / 增肥之前写入。
## 5. 其它行为
- **版本校验**:模板 `szBuildDate` 比主控 `DLL_VERSION` 新时拒绝生成。
- **输出覆盖**:默认拒绝覆盖;`overwrite=true` 时才写。输出文件名不允许包含目录分隔符。
- **并发**:模块内用 `std::mutex` 串行化。`ReleaseUPX()` 固定把 `upx.exe` 释放到服务端
目录,两个并发生成会互相踩;串行化同时避免同一输出文件的写竞争。
- **审计**:每次成功/失败写一行 `[MCP] build_client ...` 到服务端日志(路径、目标、字节数)。
- **结果 tips**:KCP 需要主控 UDP 参数为 1、WS/WSS 需要反代、macOS 需 `install.sh`/codesign、
Android 需 apksigner、TestRun 需要 ServerDll.dll、锚未内嵌等。
- **UPX 失败**:返回 `-32001`,未压缩的文件保留在原路径(与对话框一致)。
## 6. 「生成服务端」对话框的联动改进
同一批改动还修了对话框里几个平台联动问题(`BuildDlg.cpp`):
1. 选 Linux / macOS / Android 时,「安装目录」下拉框(`IDC_COMBO_INSTALL_LOC`)及其
标签(`IDC_STATIC_LOCATION`)现在与安装目录/程序名一起置灰。此前它们不在禁用清单里,
看起来仍可设置,但生成时根本不会被使用。
2. 运行模式(`IDC_COMBO_RUNTYPE`)对非 Windows 客户端无意义(`runningType` 只有
Windows `ClientDll` 消费),一并置灰。
3. 加壳选择切到非 Windows 目标时暂存并显示「无」,切回 Windows 时恢复;避免
「控件置灰但显示 ShellCode AES」与实际生成结果(强制 NONE)不一致。
4. 载荷类型 / 下载服务几行在非 Windows 目标下隐藏,而不是留下置灰的空行。
5. 「随机名称」「以管理员权限运行」两个菜单项在非 Windows 目标下置灰。
6. 内嵌 TLS 锚复选框的文案对 Linux/macOS/Android 改为「仅Windows客户端模板支持」,
不再误报「该目标不含客户端」。
## 7. 验收记录(2026-11-15,Debug 实例)
- `tools/list` 出现 `build_client`(`McpBuild=1`),关闭开关时不出现、直接调用 `-32006`。
- Linux:生成 10,285,456 字节,`tlsAnchor=unsupported_platform`;`encrypt_address=false`
时二进制里能检索到明文 host/port/分组/安装目录,原 `FLAG_FINDEN` 命中数归零。
- ghost x64:`tlsAnchor=embedded`;生成的 PE 被本机 Defender 隔离,属测试环境现象。
- Android:生成 11,929,218 字节,`tlsAnchor=unsupported_platform`,tips 提示重签。
- `arch=x86` + Linux、`testrun_injsc` + x86、未知 target、非字符串 target、显式但解析不出
的 `port`(如 `"443 "`)均返回 `-32602`;同名文件不传 `overwrite` 返回 `-32012`,
传 `true` 后 `overwritten=true`。
- 保护主控自身文件:`output_dir=Bin` + `output_name=Yama_x64d.exe` + `overwrite=true`
返回 `-32012`,不会覆盖运行中的服务端;`settings.ini` / `upx.exe` 同样受保护。
- 省略 `group` 时与对话框一致写入 `default`;`protocol` 允许数字形式(5 → ws)。
- `padding_mb=3` 的 TinyRun 产物比模板大 3 MB(分块追加,不一次性分配 256 MB);
`compress=upx` 因 Defender 拒绝读取生成的 PE 而返回 `-32001`(UPX 自身报
`IOException: Invalid argument`),错误路径符合预期;UPX 临时文件按
`upx_mcp_<pid>_<tick>.exe` 释放,测后无残留,也不会与对话框的固定 `upx.exe` 抢文件。
- `mcp/tools.json` 已用 Debug 实例的 `McpMachine=1` / `McpMachine=0` 两份抓取重新生成
(55 个工具),`check_platform_table.py` PASS。