@windypro-rourou/dsh-logcat 0.3.0 → 0.4.1

package/README.md

@@ -18,19 +18,22 @@ DSH Web GUI 的安卓实机调试面板（类似 Android Studio 的 Logcat 视
   - 暂停/继续（暂停时缓冲，恢复自动回放）、清空、复制、导出 .txt
   - 窗口化渲染 + 自动滚动（滚动手动上翻时自动停用）
   - 未授权设备提示「请在手机上点击允许 USB 调试」
-- **Agent 工具**（共 18 个，全部对 agent 开放，前置提示中已明示可调用）：
+- **Agent 工具**（共 21 个，全部对 agent 开放，前置提示中已明示可调用）：
   - 设备：`logcat_devices`（列出设备）、`device_info`（型号/版本/SDK/分辨率/内存/电量）、`device_stats`（CPU/内存/电量实时采样）
   - 执行：`adb_exec`（shell）、`adb_install`（本地 APK 装真机）、`adb_pull`（拉文件）
   - 输入：`input_tap` / `input_swipe` / `input_text`（真机 UI 自动化）、`ui_dump`（界面层级 XML）
   - 日志：`logcat_recent`（按包名/级别/关键词过滤）、`logcat_crash`（崩溃/ANR 自动捕获 + 上下文）、
     `logcat_set_package`（锁定当前测试包名）
   - 逆向/内存：`proc_list`（进程列表）、`proc_maps`（内存映射 + so 模块基址）、`proc_status`（进程状态/内存摘要）、
-    `mem_dump`（指定地址读内存 hex）、`frida_server`（frida-server 部署/启停）
+    `proc_smaps`（smaps 明细，Pss Top 区域）、`mem_dump`（指定地址读内存 hex）、
+    `mem_search`（内存搜 hex 模式/字符串）、`frida_server`（frida-server 部署/启停）、
+    `frida_script`（hook/trace/scan/bypass/dump 常用脚本模板生成）
 - **实机调试工作流**：构建安卓应用时，agent 的通告会动态列出当前已连接设备（serial + 型号）与当前测试包名，
   可先向用户确认后：`adb_install` 部署 APK → `adb_exec` 启动 → `logcat_set_package` 锁包 →
   `logcat_recent` / `logcat_crash` 看崩溃 → `ui_dump` + `input_*` 做界面自动化 → `adb_pull` 取证，闭环真机调试。
-- **逆向工作流**：`proc_list` 定位进程 → `proc_maps` 拿模块基址/权限 → `mem_dump` 读目标地址 →
-  `frida_server` 起 frida 做动态插桩。读其他应用内存/maps 需要 root 或 debuggable 应用（run-as），工具会给出明确提示。
+- **逆向工作流**：`proc_list` 定位进程 → `proc_maps` 拿模块基址 → `mem_dump` 读目标地址 / `mem_search` 搜特征模式 →
+  `proc_smaps` 看内存占用明细 → `frida_script` 生成脚本 + `frida_server` 起 frida 做动态插桩。
+  读其他应用内存/maps 需要 root 或 debuggable 应用（run-as），工具会给出明确提示。
 - **附加能力**：`POST /api/dsh-logcat/exec` 执行 shell、`POST /api/dsh-logcat/package` 设置包名、
   `GET /api/dsh-logcat/screenshot` 截屏、`POST /api/dsh-logcat/install-adb` 一键装 adb。
 

package/lib/index.js

@@ -17,7 +17,7 @@
 import { spawn, execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { createInterface } from 'node:readline'
 import { WebSocket, WebSocketServer } from 'ws'
 import { defineTool } from '@deepseek-ai/dsh-tools'
@@ -41,7 +41,7 @@ export const LOGCAT_GUIDANCE =
   '设备与状态：logcat_devices（列出设备）、device_info（型号/版本/SDK/分辨率/内存/电量）、device_stats（CPU/内存/电量采样）；' +
   '部署与执行：adb_install（本地 APK 装真机）、adb_exec（任意 adb shell 命令）、adb_pull（拉文件）、input_tap/input_swipe/input_text（模拟点击/滑动/输入）、ui_dump（界面层级 XML）；' +
   '日志与崩溃：logcat_recent（按级别/关键词/包名读日志）、logcat_crash（崩溃/ANR 捕获+上下文）、logcat_set_package（锁定当前测试包名）；' +
-  '逆向与内存：proc_list（进程列表）、proc_maps（内存映射+so 模块基址）、proc_status（进程状态/内存摘要）、mem_dump（指定地址读内存 hex）、frida_server（frida-server 部署/启停）。' +
+  '逆向与内存：proc_list（进程列表）、proc_maps（内存映射+so 模块基址）、proc_status（进程状态/内存摘要）、proc_smaps（内存占用明细 Top 区域）、mem_dump（指定地址读内存 hex）、mem_search（内存搜 hex 模式/字符串）、frida_server（frida-server 部署/启停）、frida_script（hook/trace/scan/bypass/dump 常用脚本模板）。' +
   '工作流建议：构建安卓应用 → 确认设备在线后 adb_install 部署、adb_exec 启动、logcat_set_package 锁包、logcat_recent/logcat_crash 看崩溃、ui_dump+input_* 做界面自动化；' +
   '逆向分析 → proc_list 找进程、proc_maps 拿模块基址、mem_dump 读内存、frida_server 起 frida。' +
   '限制：需设备开启 USB 调试并授权本机；读其他应用内存/maps 需要 root 或 debuggable 应用（run-as）；logcat 输出可能含敏感信息；' +
@@ -1520,6 +1520,284 @@ function fridaServerTool(engine) {
   })
 }
 
+/** The mem_search agent tool: search process memory for a byte pattern. */
+function memSearchTool(engine) {
+  return defineTool({
+    name: 'mem_search',
+    description: 'Search a process\'s memory for a byte pattern — plain ASCII string or hex bytes ("hex:48656c6c6f") — and return byte offsets. ' +
+      'Requires root (or a debuggable app via run-as). Scans with grep -aob over /proc/<pid>/mem; very large processes can be slow.',
+    parameters: {
+      serial: { type: 'string', description: 'Device serial from logcat_devices (optional; defaults to the first attached device).' },
+      pid: { type: 'integer', description: 'Process id (from proc_list).' },
+      pattern: { type: 'string', description: 'Pattern to search: ASCII string ("hello") or hex bytes ("hex:48656c6c6f").' },
+      maxResults: { type: 'integer', description: 'Max matches to return (default 20).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          pid: { type: 'integer', required: true },
+          pattern: { type: 'string' },
+          offsets: { type: 'array', required: true, items: { type: 'integer' } },
+          truncated: { type: 'boolean' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (value?.error) return [{ type: 'text', text: value.error }]
+        const offs = value?.offsets ?? []
+        if (offs.length === 0) return [{ type: 'text', text: `(no match for "${value?.pattern ?? ''}" in pid ${value?.pid ?? '?'})` }]
+        const hex = offs.map((o) => '0x' + o.toString(16)).join('\n')
+        return [{ type: 'text', text: `pattern "${value.pattern}" in pid ${value.pid}:\n${hex}${value.truncated ? '\n(truncated)' : ''}` }]
+      },
+    },
+    async execute(args) {
+      const devices = engine.deviceList()
+      const serial = typeof args.serial === 'string' && args.serial !== '' ? args.serial : devices[0]?.serial ?? ''
+      const pid = Number(args.pid)
+      const pattern = typeof args.pattern === 'string' ? args.pattern.trim() : ''
+      const max = Math.min(Math.max(Number(args.maxResults ?? 20) || 20, 1), 200)
+      if (serial === '' || engine.adb === null || !Number.isInteger(pid) || pid <= 0) return { pid: 0, offsets: [], error: 'a valid pid is required' }
+      if (pattern === '') return { pid, offsets: [], error: 'pattern is required (string or hex:...)' }
+      // Normalize to a byte sequence emitted by printf '\xNN\xNN...'
+      const bytes = pattern.startsWith('hex:')
+        ? pattern.slice(4).replace(/\s+/g, '').match(/[0-9a-f]{2}/gi)?.map((b) => b.toLowerCase()) ?? []
+        : [...Buffer.from(pattern, 'utf8')].map((b) => b.toString(16).padStart(2, '0'))
+      if (bytes.length === 0) return { pid, offsets: [], error: 'could not parse pattern into bytes' }
+      const printfArg = "\\x" + bytes.join("\\x")
+      const sh = `grep -aob -F "$(printf '${printfArg}')" /proc/${pid}/mem 2>&1 | head -${max}`
+      const result = await runAdbFull(engine.adb, ['-s', serial, 'shell', sh], 30000)
+      const out = result.stdout ?? ''
+      if (!result.ok || /Permission denied|No such file|No such process/.test(out)) {
+        return { pid, offsets: [], error: `cannot search pid ${pid} memory (need root / debuggable app); output: ${out.slice(0, 200)}` }
+      }
+      const offsets = []
+      for (const line of out.split(/\r?\n/)) {
+        const m = /^(\d+):/.exec(line)
+        if (m !== null) offsets.push(Number.parseInt(m[1], 10))
+      }
+      return { pid, pattern, offsets, truncated: offsets.length >= max }
+    },
+  })
+}
+
+/** The proc_smaps agent tool: per-region memory detail (top Pss regions). */
+function procSmapsTool(engine) {
+  return defineTool({
+    name: 'proc_smaps',
+    description: 'Read /proc/<pid>/smaps and return the top memory regions by Pss (size/rss/pss per mapping) — detailed memory footprint analysis. ' +
+      'Requires root or matching permissions.',
+    parameters: {
+      serial: { type: 'string', description: 'Device serial from logcat_devices (optional; defaults to the first attached device).' },
+      pid: { type: 'integer', description: 'Process id (from proc_list).' },
+      top: { type: 'integer', description: 'Number of top regions to return (default 10, max 50).' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          pid: { type: 'integer', required: true },
+          regions: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                start: { type: 'string', required: true },
+                end: { type: 'string' },
+                perms: { type: 'string' },
+                path: { type: 'string' },
+                sizeKb: { type: 'integer' },
+                rssKb: { type: 'integer' },
+                pssKb: { type: 'integer' },
+              },
+            },
+          },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (value?.error) return [{ type: 'text', text: value.error }]
+        const regs = value?.regions ?? []
+        if (regs.length === 0) return [{ type: 'text', text: `(pid ${value?.pid ?? '?'}: no regions)` }]
+        const lines = regs.map((r) => `${r.start}${r.end ? '-' + r.end : ''} ${(r.perms ?? '').padEnd(4)} pss=${r.pssKb ?? '?'}kB rss=${r.rssKb ?? '?'}kB ${r.path ?? ''}`)
+        return [{ type: 'text', text: lines.join('\n') }]
+      },
+    },
+    async execute(args) {
+      const devices = engine.deviceList()
+      const serial = typeof args.serial === 'string' && args.serial !== '' ? args.serial : devices[0]?.serial ?? ''
+      const pid = Number(args.pid)
+      const top = Math.min(Math.max(Number(args.top ?? 10) || 10, 1), 50)
+      if (serial === '' || engine.adb === null || !Number.isInteger(pid) || pid <= 0) return { pid: 0, regions: [], error: 'a valid pid is required' }
+      const result = await runAdbFull(engine.adb, ['-s', serial, 'shell', `cat /proc/${pid}/smaps 2>&1; true`], 30000)
+      const text = result.stdout ?? ''
+      if (!result.ok || /Permission denied|No such file|No such process/.test(text) || text.trim() === '') {
+        return { pid, regions: [], error: `cannot read /proc/${pid}/smaps (need root or matching perms); output: ${text.slice(0, 200)}` }
+      }
+      const regions = []
+      let current = null
+      for (const line of text.split(/\r?\n/)) {
+        const header = /^([0-9a-f]+)-([0-9a-f]+)\s+([rwxps-]{4})\s+\S+\s+\S+\s+\d+\s*(.*)$/.exec(line)
+        if (header !== null) {
+          current = { start: header[1], end: header[2], perms: header[3], path: header[4] ?? '', sizeKb: 0, rssKb: 0, pssKb: 0 }
+          regions.push(current)
+          continue
+        }
+        if (current === null) continue
+        const field = /^(Size|Rss|Pss):\s+(\d+) kB$/.exec(line.trim())
+        if (field !== null) {
+          if (field[1] === 'Size') current.sizeKb = Number.parseInt(field[2], 10)
+          else if (field[1] === 'Rss') current.rssKb = Number.parseInt(field[2], 10)
+          else current.pssKb = Number.parseInt(field[2], 10)
+        }
+      }
+      const topRegions = regions
+        .filter((r) => r.pssKb > 0)
+        .sort((a, b) => b.pssKb - a.pssKb)
+        .slice(0, top)
+        .map(({ start, end, perms, path, sizeKb, rssKb, pssKb }) => ({ start, end, perms, path, sizeKb, rssKb, pssKb }))
+      return { pid, regions: topRegions }
+    },
+  })
+}
+
+/** frida script templates (reverse engineering quick starts). */
+const FRIDA_TEMPLATES = {
+  hook_method: (target, method) => `// hook_method: log args + return of a Java method
+// usage: frida -U -f <package> -l hook.js   (or attach to a running app)
+Java.perform(function () {
+  var clsName = "${target ?? 'com.example.Class'}";
+  var methodName = "${method ?? 'method'}";
+  var cls = Java.use(clsName);
+  cls[methodName].overloads.forEach(function (ov) {
+    ov.implementation = function () {
+      var args = Array.prototype.slice.call(arguments).map(String).join(", ");
+      console.log("[" + clsName + "." + methodName + "] called(" + args + ")");
+      var ret = ov.apply(this, arguments);
+      console.log("[" + clsName + "." + methodName + "] => " + ret);
+      return ret;
+    };
+  });
+  console.log("[*] hooked " + clsName + "." + methodName);
+});`,
+  trace_native: (target) => `// trace_native: trace a native export, target "libfoo.so!func"
+var spec = "${target ?? 'libfoo.so!func'}";
+var sep = spec.indexOf("!");
+if (sep < 0) { console.log("usage: lib.so!func"); throw 0; }
+var moduleName = spec.slice(0, sep);
+var funcName = spec.slice(sep + 1);
+var base = Module.findBaseAddress(moduleName);
+if (!base) { console.log("[!] module not loaded: " + moduleName); throw 0; }
+var addr = Module.findExportByName(moduleName, funcName);
+if (!addr) { console.log("[!] export not found: " + funcName); throw 0; }
+Interceptor.attach(addr, {
+  onEnter: function (args) {
+    var a = [];
+    for (var i = 0; i < 8; i++) a.push(args[i]);
+    console.log("[+] " + funcName + "(" + a.join(", ") + ")");
+  },
+  onLeave: function (retval) { console.log("[+] " + funcName + " => " + retval); }
+});
+console.log("[*] tracing " + spec + " @ " + addr);`,
+  scan_memory: (target) => `// scan_memory: scan all modules for a hex pattern ("hex:48 65 6c 6c 6f" or raw hex)
+var pattern = "${target ?? 'hex:48 65 6c 6c 6f'}";
+if (pattern.indexOf("hex:") === 0) pattern = pattern.slice(4);
+var bytes = pattern.split(/\\s+/).filter(Boolean).map(function (b) { return parseInt(b, 16); });
+if (bytes.some(function (b) { return isNaN(b); })) { console.log("[!] bad hex pattern"); throw 0; }
+Process.enumerateModules().forEach(function (m) {
+  try {
+    Memory.scan(m.base, m.size, bytes, {
+      onMatch: function (addr, size) {
+        console.log("found @ " + addr + " in " + m.name + " (+0x" + addr.sub(m.base).toString(16) + ")");
+      },
+      onComplete: function () {}
+    });
+  } catch (e) {}
+});
+console.log("[*] scanning " + Process.enumerateModules().length + " modules");`,
+  bypass_debug: () => `// bypass_debug: basic anti-debug / anti-frida helpers
+// 1) observe ptrace (self-attach tricks), 2) hide common frida markers
+var ptrace = Module.findExportByName(null, "ptrace");
+if (ptrace) {
+  Interceptor.attach(ptrace, {
+    onEnter: function (args) { console.log("[*] ptrace called, request=" + args[0]); },
+    onLeave: function (retval) { if (retval.toInt32() === -1) console.log("[*] ptrace denied (anti-debug active)"); }
+  });
+}
+try {
+  Java.perform(function () {
+    // neutralize common "is frida running" checks by spamming hooks is out of scope;
+    // this template focuses on ptrace observation.
+  });
+} catch (e) {}
+console.log("[*] basic anti-debug helpers installed (ptrace observer)");`,
+  dump_class: (target) => `// dump_class: list methods and fields of a Java class
+Java.perform(function () {
+  var clsName = "${target ?? 'com.example.Class'}";
+  var cls = Java.use(clsName);
+  console.log("[*] " + clsName + " methods:");
+  cls.class.getDeclaredMethods().forEach(function (m) { console.log("  " + m.toString()); });
+  console.log("[*] fields:");
+  cls.class.getDeclaredFields().forEach(function (f) { console.log("  " + f.toString()); });
+});`,
+}
+
+/** The frida_script agent tool: generate ready-to-use frida scripts. */
+function fridaScriptTool(engine) {
+  return defineTool({
+    name: 'frida_script',
+    description: 'Generate a ready-to-use frida JavaScript script from a built-in template (hook_method / trace_native / scan_memory / bypass_debug / dump_class) ' +
+      'and optionally write it to a local file, then use with frida_server + "frida -U -f <pkg> -l <script>".',
+    parameters: {
+      template: { type: 'string', enum: ['hook_method', 'trace_native', 'scan_memory', 'bypass_debug', 'dump_class'], description: 'Which template to generate.' },
+      target: { type: 'string', description: 'Template-specific target: class name (hook_method/dump_class), "lib.so!func" (trace_native), hex pattern (scan_memory).' },
+      method: { type: 'string', description: 'Method name for hook_method (optional; hooks the given method of the target class).' },
+      output: { type: 'string', description: 'Optional local file path to write the script to, e.g. "F:/tools/hook.js".' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          script: { type: 'string', required: true },
+          wroteTo: { type: 'string' },
+          error: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (value?.error) return [{ type: 'text', text: value.error }]
+        return [{ type: 'text', text: value?.script ?? '' }]
+      },
+    },
+    async execute(args) {
+      const template = typeof args.template === 'string' ? args.template : ''
+      const target = typeof args.target === 'string' ? args.target.trim() : ''
+      const method = typeof args.method === 'string' ? args.method.trim() : ''
+      const generator = FRIDA_TEMPLATES[template]
+      if (generator === undefined) {
+        return { script: '', error: `unknown template: ${template}; pick one of ${Object.keys(FRIDA_TEMPLATES).join(' / ')}` }
+      }
+      const script = generator(target || undefined, method || undefined)
+      const output = typeof args.output === 'string' ? args.output.trim() : ''
+      if (output !== '') {
+        try {
+          const { writeFileSync, mkdirSync } = await import('node:fs')
+          mkdirSync(dirname(output), { recursive: true })
+          writeFileSync(output, script, 'utf8')
+          return { script, wroteTo: output }
+        } catch (error) {
+          return { script, error: `failed to write ${output}: ${error instanceof Error ? error.message : String(error)}` }
+        }
+      }
+      return { script }
+    },
+  })
+}
+
 /** ------------------------------------------------------------------ */
 
 /** Mount the adb engine, routes, tool, and announcement. */
@@ -1603,6 +1881,9 @@ export function apply(ctx, config) {
         procStatusTool(engine),
         memDumpTool(engine),
         fridaServerTool(engine),
+        memSearchTool(engine),
+        procSmapsTool(engine),
+        fridaScriptTool(engine),
       ].map((tool) => ctx.tools.register(tool))
       return () => { for (const dispose of disposers) dispose() }
     }, 'dsh-logcat: tools')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@windypro-rourou/dsh-logcat",
   "description": "Android Logcat viewer for the dsh web GUI: auto-connects to any adb device in debug mode, live logcat stream with level/keyword filters, pause/clear/export, plus agent tools (logcat_recent). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules copy, no dsh source changes.",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "packageManager": "pnpm@11.22.0",
   "engines": {