remote-behavior-agent

跨平台(Windows/Linux/macOS)远程软件调试 (dbg) 代理。 控制端用 MCP/AI 远程驱动目标机(含虚拟机):启动软件 / 截图 / 下断点(命中抓现场)/ 读写内存 / 枚举模块符号。

架构(三层)

用户层  server/(MCP:stdio 或 HTTP+Bearer令牌)  +  adapters/(Frida/截图/启动 外部适配器)
业务层  service/orchestrator.py(会话编排 · 注册表 · 选后端 · 唯一持业务状态)
逻辑层  logic/(纯函数:事件格式化 / 解码 / 截图非空白判定)

• 调试内核:Frida(三系统通吃)。x64dbg/GDB/LLDB 为可选原生后端(能力探测式接入)。
• 断点模型:Frida 插桩式 —— 在函数/地址命中时抓参数+调用栈+(可选)缓冲并继续(非暂停)。
• 两种传输:stdio(本机,Claude Code 直接 spawn)/ http(局域网,Bearer 令牌)。

MCP 工具(14)

类别	工具
进程	launch screenshot list_processes
会话	attach(pid) spawn(path) resume teardown
断点	hook_api(符号[,buf_arg,len_arg]) hook_addr(地址) stream_events
内存/符号	read_mem write_mem modules resolve

---

A. 本机使用(stdio)

控制端 .mcp.json(本仓库已带):

{ "mcpServers": { "remote-behavior-agent": {
  "command": "python", "args": ["-m","agent.main","--transport","stdio"],
  "env": { "PYTHONUTF8":"1", "PYTHONPATH":"<项目绝对路径>" } } } }

pip install -r requirements.txt

重启 Claude Code → 工具可用(调试本机)。

---

B. 局域网远程使用(http + 令牌)—— 多台/虚拟机

思路:每台目标机(含 VM)各跑一个 HTTP agent;控制端按 IP 把它们都列进 .mcp.json。 哪台装 agent → 哪台就能被远程断点。

1) 目标机(VM/PC)起服务

Windows(管理员 PowerShell,项目根目录):

./scripts/run_agent.ps1 -Token "你的强令牌>=16位" -Port 8765

Linux:

sudo sysctl -w kernel.yama.ptrace_scope=0     # 允许 attach
RBA_TOKEN=你的强令牌 ./scripts/run_agent.sh 0.0.0.0 8765

脚本会 pip install -r requirements.txt 并以 --host 0.0.0.0 --allow-remote 启动。

2) 虚拟机网络要点

• VM 网卡用桥接(拿到局域网 IP)或 host-only + 端口转发;
• VM 内防火墙放行该端口(如 8765);
• frida 在 VM 内建议管理员/root 运行。

3) 控制端 .mcp.json(列多台,都可用)

{ "mcpServers": {
  "vm1": { "type":"http", "url":"http://192.168.1.51:8765/mcp",
           "headers": { "Authorization": "Bearer ${RBA_TOKEN}" } },
  "pc2": { "type":"http", "url":"http://192.168.1.52:8765/mcp",
           "headers": { "Authorization": "Bearer ${RBA_TOKEN}" } }
}}

设环境变量 RBA_TOKEN=你的强令牌 后启动 Claude Code,即可远程驱动各台。 加一台目标 = 加一行。

⚠️ 安全:令牌走明文 HTTP,仅适合可信局域网/隔离网。不可信网络请叠加 TLS (agent 前置反代,或后续 --tls;控制端用 https:// + NODE_EXTRA_CA_CERTS 信任自签 CA)。

测试

pytest        # 逻辑层 + 令牌中间件单测

详见 .pp/wiki/当前任务/远程跨平台行为分析代理/。