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](./examples) 目录也提供了可复制版本。

能力档位

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

- 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

设备项支持：

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 包。

模型工具

典型 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 被销毁，插件会尽力终止它创建的暂停进程，避免设备上遗留挂起目标。

内置模板

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

{"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](./LICENSE)