Frida 设备调试工具mang0cola/frida_dsh_plugin

frida-dsh-plugin

将 Frida 作为一组受策略约束的工具接入 DeepSeek Harness。安装后，大模型可以发现已配置设备、枚举进程或应用、附加或拉起目标、加载 Frida Agent、调用 RPC、读取异步消息，并在会话结束时自动释放资源。

本插件只应用于你拥有或已明确获准测试的设备和程序。

设计概览

flowchart LR
M["DeepSeek Harness Agent"] --> T["9 个 Frida tools"]
T --> P["能力档位与审批策略"]
P --> R["FridaRuntime"]
R --> O["Agent 资源归属与限额"]
R --> E["有界事件缓冲"]
R --> N["官方 frida-node"]
N --> D["local / USB / remote device"]

关键约束：

- 模型只看到部署方配置的设备别名，不能自行提交远程地址或认证信息。
- Session 和 Script 使用不透明句柄，并绑定到创建它们的 Agent；其他 Agent 无法复用。
- 默认 discovery 档只允许发现设备、进程和应用，不允许注入。
- 注入操作默认进入 Harness 审批链；无审批服务时，ask 会失败关闭。
- 脚本消息使用游标式环形缓冲；二进制、事件 JSON 和 RPC JSON 均有字节上限。
- Agent 销毁、插件热替换或 Harness 退出时会清理 Script、Session 和未恢复的暂停进程。

环境要求

- Node.js 20 或更高版本。
- DeepSeek Harness 0.1.0-rc.6 兼容版本。
- 与目标端兼容的 Frida 环境。Android USB 场景通常需要目标设备上运行版本匹配的 frida-server；其他部署也可以使用 Frida Gadget 或远程 Frida 服务。

默认后端是当前 Node 进程中的 frida-node。如果设备端必须保留旧版 Frida，而旧版 frida-node 不支持宿主 Node 版本，可以选择 backend: python，让插件通过一个持久、可取消的 JSON-lines worker 复用版本匹配的 Python 虚拟环境；模型工具和安全策略保持不变。

先确认宿主机能够正常使用 Frida 连接目标设备，再让 Harness 接管调用。插件不会替你绕过设备授权、代码签名、越狱、root 或系统调试限制。

构建与安装

在本仓库中执行：

npm install
npm run build
npm test
dsh plugin --profile demo add .
dsh --profile demo --dump-config
dsh --profile demo

组合包安装后会插入三行：frida-runtime、frida-tools 和 frida-policy。默认配置是只读的 discovery 档。

Harness 的后置 patch 会按 id 覆盖前面的行，并整体替换该行的 config。要开启注入能力，请把下列某个示例加入目标 profile 的 cordis.patch.yml；仓库中的 examples 目录也提供了可复制版本。

能力档位

| 档位 | 发现设备/目标 | Attach | 内置模板 | 原始 JS | Spawn/Resume/Kill |
| --- | --- | --- | --- | --- | --- |
| discovery | 是 | 否 | 否 | 否 | 否 |
| templates | 是 | 是 | 是 | 否 | 否 |
| full | 是 | 是 | 是 | 是 | 是；Kill 还需 allowKill: true |

仅发现设备与目标（默认）

- id: frida-runtime
config:
backend: node
pythonExecutable: python3
capabilityProfile: discovery
approvalMode: ask
devices:
- alias: local
kind: local
- alias: usb
kind: usb
timeoutMs: 5000
defaultDevice: usb
targetAllowlist: []
allowKill: false
operationTimeoutMs: 30000
maxSessions: 8
maxScriptsPerSession: 8
maxScriptBytes: 262144
eventBufferSize: 1000
maxEventDataBytes: 65536

只允许审计过的模板

- id: frida-runtime
config:
backend: node
pythonExecutable: python3
capabilityProfile: templates
approvalMode: ask
devices:
- alias: usb
kind: usb
timeoutMs: 10000
defaultDevice: usb
targetAllowlist:
- 'com.example.'
- 'Example App'
allowKill: false
operationTimeoutMs: 30000
maxSessions: 4
maxScriptsPerSession: 4
maxScriptBytes: 262144
eventBufferSize: 1000
maxEventDataBytes: 65536

完整能力与远程设备

认证令牌只从宿主进程环境变量读取，不写入 Harness 配置或模型上下文：

- id: frida-runtime
config:
backend: node
pythonExecutable: python3
capabilityProfile: full
approvalMode: ask
devices:
- alias: lab-android
kind: remote
address: '10.20.0.15:27042'
tokenEnv: FRIDA_LAB_TOKEN
keepaliveInterval: 30
defaultDevice: lab-android
targetAllowlist:
- 'com.example.app'
allowKill: false
operationTimeoutMs: 30000
maxSessions: 4
maxScriptsPerSession: 4
maxScriptBytes: 262144
eventBufferSize: 1000
maxEventDataBytes: 65536

设备项支持：

| 字段 | 含义 |
| --- | --- |
| alias | 暴露给模型的稳定名称，必须唯一 |
| kind | local、usb、remote 或 id |
| id | id 设备必填；USB 多设备时也可指定 |
| address | remote 设备必填，由部署方固定 |
| tokenEnv | 包含远程认证令牌的环境变量名 |
| certificate / origin | Frida 远程连接参数 |
| keepaliveInterval | 远程连接保活间隔 |
| timeoutMs | 发现该设备时的等待上限 |

targetAllowlist 使用区分大小写的  通配符，匹配运行进程名或 Spawn 的程序/应用标识。空数组表示不额外限制目标；生产环境开启 templates 或 full 时建议显式列出目标。

approvalMode 的含义：

- ask：Attach、加载脚本、RPC、Spawn 和进程控制进入 Harness 审批流程。
- allow：策略层直接放行档位内的操作，适合隔离且已有外部授权控制的自动化环境。
- deny：保留发现工具，但拒绝所有注入和控制操作。

使用已有 Frida Python 虚拟环境

下面的配置适用于设备端 Frida 16.0.2、宿主 Node 版本无法加载同版本 frida-node 的场景：

- id: frida-runtime
config:
backend: python
pythonExecutable: '/absolute/path/to/frida-16/bin/python'
capabilityProfile: templates
approvalMode: ask
devices:
- alias: usb16
kind: usb
timeoutMs: 30000
defaultDevice: usb16
targetAllowlist:
- 'com.example.*'
allowKill: false
operationTimeoutMs: 30000
maxSessions: 4
maxScriptsPerSession: 4
maxScriptBytes: 262144
eventBufferSize: 1000
maxEventDataBytes: 65536

pythonExecutable 是部署方信任边界内的本机可执行文件路径，不会暴露为模型参数。该 Python 环境必须已经安装与设备端兼容的 frida 包。

模型工具

| 工具 | 用途 |
| --- | --- |
| frida_list_devices | 返回配置过的设备别名及可用状态 |
| frida_enumerate | 分页枚举进程或应用 |
| frida_attach | 按 PID 或精确进程名附加，返回 sessionId |
| frida_spawn | 暂停启动并立即附加，返回 sessionId |
| frida_load_script | 加载内置模板或原始 JavaScript，返回 scriptId |
| frida_call_rpc | 调用脚本的 rpc.exports 方法 |
| frida_read_events | 用游标读取 send()、错误和 console 日志 |
| frida_process_control | 恢复插件 Spawn 的暂停进程，或在允许时终止它 |
| frida_close | 卸载 Script 或关闭 Session |

典型 Attach 流程：

1. frida_list_devices
2. frida_enumerate
3. frida_attach
4. frida_load_script
5. frida_call_rpc 和/或 frida_read_events
6. frida_close

典型 Spawn 流程是 frida_spawn → frida_load_script → frida_process_control(action: resume)。如果在 Resume 前关闭 Session 或 Agent 被销毁，插件会尽力终止它创建的暂停进程，避免设备上遗留挂起目标。

内置模板

| 模板 | templateArgs | RPC |
| --- | --- | --- |
| enumerate-modules | 无 | run(offset?, limit?) |
| enumerate-exports | { "moduleName": "..." } | run(offset?, limit?) |
| java-classes | 无 | run(offset?, limit?) |
| objc-classes | 无 | run(offset?, limit?) |
| hook-native-export | { "moduleName": "...", "exportName": "..." } | 通过事件返回 enter/leave |

例如，枚举目标模块时依次调用：

{"sessionId":"frida-session-1","template":"enumerate-modules"}

然后：

{"scriptId":"frida-script-1","exportName":"run","args":[0,3]}

上述四个枚举模板返回 { items, total, offset, limit, truncated }；limit 默认为 100，最大为 500。模型可以直接读取总数并按游标分页，不需要借助 Shell 处理大型 RPC 结果。

frida_load_script 返回的 nextCursor 是模板加载完成后的游标。读取后续 hook 消息时把它传给 frida_read_events，并在下一次读取时继续使用新返回的 nextCursor。若缓冲区发生覆盖，droppedCount 会明确报告丢失数量。

开发命令

npm run typecheck
npm test
npm run build
npm pack --dry-run

对已经运行的授权测试目标执行 Python 后端端到端冒烟测试：

FRIDA_PYTHON=/absolute/path/to/frida-16/bin/python \
FRIDA_TARGET=com.example.app \
npm run test:device

该命令只 Attach 已运行目标，不负责启动或终止应用；它会完成设备/应用/进程枚举、原始脚本 RPC、事件回读、内置模块模板分页和 Session 清理。

测试中的 Runtime 使用 provider-neutral 假设备，因此不要求连接真实手机。真实部署仍应在授权测试设备上完成一次端到端验证，包括 Frida 主机端/目标端版本、Attach 权限、目标名称 allowlist 和 Harness 审批交互。

当前边界

- 原始 Agent 只接受 JavaScript；插件暂不负责 TypeScript 编译或 Frida Compiler 工程构建。
- 句柄和事件缓冲只存在于当前 Harness 进程，不跨重启恢复。
- 插件提供结构化工具，不模拟交互式 frida REPL。
- 高风险能力没有内置 Stalker、内存任意读写等模板；在 full 档中可通过经过审批的原始脚本显式实现。

License

MIT