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

8.6 KiB
Raw Blame History

生成客户端 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。