Preface¶

When integrating dynamic analysis capabilities into an agent, a common approach is to give it a shell and let it call frida commands or write temporary scripts on its own. The trouble with this path lies in: Sessions and script handles are scattered across multiple commands, making it hard to guarantee correct release; injection-like operations lack strategic boundaries, and the target scope and approval timing can only rely on prompt constraints.

DeepSeek Harness (DSH) takes the approach that “everything is a plugin,” handing capabilities to the model via structured tools plus strategy configuration. Following this idea, frida-dsh-plugin breaks Frida down into 9 tools: the default level is read-only, injection operations go through the Harness approval chain, and resources are automatically cleaned up when the session ends. Below is an introduction to its features, installation, and typical usage.

What is it¶

frida-dsh-plugin is maintained by mang0cola under the MIT license. One-sentence positioning: Integrating Frida into DeepSeek Harness as a set of strategy-constrained tools. After installation, the Large Language Model (LLM) can discover configured devices, enumerate processes or applications with pagination, attach or spawn targets, load Frida Agents, call RPCs, read asynchronous messages, and automatically release resources when the session ends.

The overall pipeline is: The model calls the 9 tools, requests go through capability levels and approval strategies, executed by FridaRuntime, and the underlying layer uses the official frida-node to connect to local / USB / remote devices. Several key constraints:

• The model only sees device aliases configured by the deployer and cannot submit remote addresses or authentication information on its own.
• Sessions and Scripts use opaque handles bound to the Agent that created them; other Agents cannot reuse them.
• The default discovery level only allows discovering devices, processes, and applications, disallowing injection.
• Injection operations default to entering the Harness approval chain; when there is no approval service, ask will fail and close.
• When an Agent is destroyed, the plugin is hot-replaced, or Harness exits, Scripts, Sessions, and unresumed suspended processes will be cleaned up.

Core Functions¶

The Nine Model Tools¶

Both frida_enumerate and built-in enumeration templates support pagination, with limit defaulting to 100 and maxing out at 500. Events use a cursor-based circular buffer; if the buffer overflows, droppedCount will explicitly report the number of dropped items.

Built-in Templates¶

The four enumeration templates return { items, total, offset, limit, truncated }. The model can directly read the total count and paginate by cursor without needing to use a Shell to handle large RPC results.

Capability Levels and Approval¶

approvalMode has three levels: ask allows Attach, loading scripts, RPC, Spawn, and process control to enter the Harness approval process; allow allows operations within the level to pass directly at the strategy layer, suitable for isolated environments with existing external authorization controls; deny keeps discovery tools but rejects all injection and control operations. Kill is a separate switch and must be explicitly configured with allowKill: true.

Installation and Enablement¶

Environment Requirements¶

• Node.js 20 or higher.
• DeepSeek Harness 0.1.0-rc.6 compatible version.
• A Frida environment compatible with the target; for Android USB scenarios, a version-matched frida-server usually needs to be running on the target device.

Build and Install¶

Execute the following in sequence in the repository: install dependencies, build, run tests, add the plugin to the demo profile, export config for confirmation, and start.

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

After installing the bundle, three lines will be inserted: frida-runtime, frida-tools, and frida-policy. The default configuration is the read-only discovery level.

Enabling Injection via cordis.patch.yml¶

To enable injection capabilities, you need to configure frida-runtime with an id override in the target profile’s cordis.patch.yml. Harness’s post-patch will override the preceding lines by id and replace the entire config of that line. Below is the complete configuration for the “templates only” level; the repository examples directory also provides a copyable version:

- 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

targetAllowlist uses case-sensitive * wildcards to match running process names or program/application identifiers for Spawns; an empty array means no extra restriction on targets, and it is recommended to explicitly list them when enabling templates or full in production environments. Device items support fields such as alias, kind, id, address, tokenEnv, certificate, origin, keepaliveInterval, timeoutMs, etc. kind can be one of four types: local, usb, remote, id.

Remote Devices and Tokens¶

A remote device is written in devices as follows (use with capabilityProfile: full; for a complete example, see the repository’s examples):

devices:
  - alias: lab-android
    kind: remote
    address: '10.20.0.15:27042'
    tokenEnv: FRIDA_LAB_TOKEN
    keepaliveInterval: 30

Remote authentication tokens are only read from the host process environment variable specified by tokenEnv and are not written into Harness configuration or the model context.

Optional Python Backend¶

The default backend is frida-node in the current Node process. If the device side must retain an older version of Frida and the older frida-node does not support the host Node version, you can set backend to python and point pythonExecutable to a version-matched Python virtual environment (this environment must have a compatible frida package installed). The plugin will reuse it via a persistent, cancellable JSON-lines worker; model tools and security policies remain unchanged; pythonExecutable is a local path within the deployer’s trust boundary and will not be exposed as a model parameter.

Typical Usage¶

Attach Process¶

The complete steps to attach to a running target:

1. frida_list_devices
2. frida_enumerate
3. frida_attach
4. frida_load_script
5. frida_call_rpc and/or frida_read_events
6. frida_close

Spawn Process¶

The Spawn process is frida_spawn → frida_load_script → frida_process_control(action: resume). If the Session is closed or the Agent is destroyed before Resume, the plugin will make a best effort to terminate the suspended process it created to avoid leaving pending targets on the device.

Template Invocation Example¶

Taking enumerating target modules as an example, first load the template:

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

Then call the run method exposed by the template:

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

The nextCursor returned by frida_load_script is the cursor after the template finishes loading. When reading subsequent hook messages, pass it to frida_read_events, and use the newly returned nextCursor for the next read.

Device-side Smoke Test¶

For an authorized test target that is already running, you can perform an end-to-end smoke test:

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

This command only attaches to a running target and does not handle starting or terminating the app; the process covers device/application/process enumeration, raw script RPC, event readback, built-in module template pagination, and Session cleanup.

Suitable Scenarios and Considerations¶

Suitable scenarios: Letting the DSH agent perform dynamic analysis on authorized test devices while requiring the deployer to control the target scope, injection capabilities, and approval timing at the strategy layer.

Please note before use:

• Only apply to devices and programs you own or have explicitly approved for testing. The plugin runs with the permissions of the current dsh process; check the source code and license (MIT) before installation.
• The plugin does not bypass device authorization, code signing, jailbreak, root, or system debugging restrictions for the user. Confirm that the host machine can normally use Frida to connect to the target before letting Harness take over the calls.
• Handles and event buffers only exist within the current Harness process and do not persist across restarts.
• Raw Agents only accept JavaScript; the plugin is not responsible for TypeScript compilation or Frida Compiler project building, nor does it simulate the interactive frida REPL.
• There are no built-in high-risk templates like Stalker or arbitrary memory read/write; in the full level, they can be explicitly implemented via approved raw scripts.

Summary¶

frida-dsh-plugin breaks a dynamic analysis session into structured, enumerable, approvable, and releaseable steps: default read-only, injection goes through the approval chain, handles are bound to Agents and cleaned up automatically upon exit. If you need to use Frida in a controlled manner on DSH, it is recommended to start with a configuration matching your scenario from the repository’s examples directory, get the discovery level working first, and then open up capabilities as needed.

• Plugin directory page (community maintained): https://www.skillhub.cn/plugins/mang0cola/frida_dsh_plugin
• GitHub repository: https://github.com/mang0cola/frida_dsh_plugin