Frida Stalker Android

# Editor / OS
.DS_Store
.idea/
.vscode/
*~
*.swp

# Logs / dumps
*.log
*.tmp

interface:
  display_name: "Frida Stalker (Android)"
  short_description: "Android native tracing with Frida Stalker"
  default_prompt: "Use $frida-stalker-android to trace a target thread/module on Android using Frida Stalker."

'use strict';

/*
 * Call-probe template: observe calls to a specific target address with low overhead.
 *
 * This is useful when you only care about a small set of call targets and do not
 * need full thread stalking.
 */

const TARGET_MODULE = 'libc.so';
const TARGET_EXPORT = 'open'; // TODO: change to your target

const target = Process.getModuleByName(TARGET_MODULE).getExportByName(TARGET_EXPORT);
send({ type: 'call-probe:installed', target: `${TARGET_MODULE}!${TARGET_EXPORT}`, address: target.toString() });

let callCount = 0;
const maxCalls = 5000;

function tryReadArgs(args, n) {
  const out = [];
  for (let i = 0; i < n; i++) {
    try {
      out.push(args[i].toString());
    } catch (_) {
      out.push(null);
    }
  }
  return out;
}

const probeId = Stalker.addCallProbe(target, function (args) {
  callCount++;
  if (callCount > maxCalls) return;

  send({
    type: 'call-probe:hit',
    tid: Process.getCurrentThreadId(),
    address: target.toString(),
    args: tryReadArgs(args, 6),
  });
});

rpc.exports = {
  remove() {
    Stalker.removeCallProbe(probeId);
    send({ type: 'call-probe:removed', probeId });
  },
};

'use strict';

/*
 * Low-overhead Stalker template for Android.
 *
 * What you get: call counts per target, over time windows.
 * What you DON'T get: ordering of calls.
 *
 * Tip: Keep the callback cheap. Symbolication can be done host-side.
 */

const defaultConfig = {
  symbolicate: false,
  trustThreshold: 1,
  queueCapacity: 16384,
  queueDrainInterval: 250,
  excludeModules: [
    'libart.so',
    'libc.so',
    'liblog.so',
    'libdl.so',
  ],
};

const state = {
  following: new Set(),
  config: { ...defaultConfig },
};

function applyConfig(cfg) {
  if (cfg.trustThreshold !== undefined) Stalker.trustThreshold = cfg.trustThreshold;
  if (cfg.queueCapacity !== undefined) Stalker.queueCapacity = cfg.queueCapacity;
  if (cfg.queueDrainInterval !== undefined) Stalker.queueDrainInterval = cfg.queueDrainInterval;
}

function excludeConfiguredModules(cfg) {
  for (const name of (cfg.excludeModules || [])) {
    try {
      const m = Process.getModuleByName(name);
      Stalker.exclude({ base: m.base, size: m.size });
    } catch (_) {
      // Module not present, ignore.
    }
  }
}

function maybeSymbolicateSummary(summary, enabled) {
  if (!enabled) return summary;

  const out = {};
  for (const [target, count] of Object.entries(summary)) {
    try {
      const sym = DebugSymbol.fromAddress(ptr(target)).toString();
      out[sym] = count;
    } catch (_) {
      out[target] = count;
    }
  }
  return out;
}

function start(threadId, config) {
  const tid = Number(threadId);
  if (!Number.isFinite(tid)) throw new Error('start(threadId): threadId must be a number');
  if (state.following.has(tid)) return;

  const cfg = { ...state.config, ...(config || {}) };
  applyConfig(cfg);
  excludeConfiguredModules(cfg);

  Stalker.follow(tid, {
    events: {
      call: true,
      ret: false,
      exec: false,
      block: false,
      compile: false,
    },
    onCallSummary(summary) {
      send({
        type: 'stalker:call-summary',
        tid,
        summary: maybeSymbolicateSummary(summary, cfg.symbolicate),
      });
    },
  });

  state.following.add(tid);
  state.config = cfg;
}

function stop(threadId) {
  const tid = Number(threadId);
  if (!Number.isFinite(tid)) throw new Error('stop(threadId): threadId must be a number');
  if (!state.following.has(tid)) return;

  Stalker.unfollow(tid);
  Stalker.flush();
  Stalker.garbageCollect();

  state.following.delete(tid);
}

function status() {
  return {
    frida: Frida.version,
    arch: Process.arch,
    platform: Process.platform,
    following: Array.from(state.following.values()),
    config: state.config,
  };
}

rpc.exports = {
  start,
  stop,
  status,
};

send({ type: 'frida-stalker-android:ready', ...status() });

'use strict';

/*
 * Helper functions for identifying app modules on Android.
 *
 * This is deliberately heuristic. Always print and validate on your target.
 */

function isProbablyAppModule(m) {
  const p = String(m.path || '').toLowerCase();
  if (p.includes('/data/app/')) return true;
  if (p.includes('/data/data/')) return true;

  // Some apps load libs from unpacked or relocated locations.
  if (p.includes('/data/')) {
    if (p.includes('/data/dalvik-cache/')) return false;
    return true;
  }

  return false;
}

function getAppModules() {
  return Process.enumerateModules().filter(isProbablyAppModule);
}

function toRange(m) {
  return { base: m.base, size: m.size, name: m.name, path: m.path };
}

function excludeModulesByName(names) {
  for (const name of names) {
    try {
      const m = Process.getModuleByName(name);
      Stalker.exclude({ base: m.base, size: m.size });
    } catch (_) {
      // ignore
    }
  }
}

rpc.exports = {
  getappmodules() {
    return getAppModules().map(toRange);
  },
  excludemodules(names) {
    excludeModulesByName(names || []);
  },
};

'use strict';

/*
 * Stalker template using onReceive() + Stalker.parse().
 *
 * Use this when you need ordered events and can afford more overhead.
 */

const defaultConfig = {
  trustThreshold: 1,
  queueCapacity: 16384,
  queueDrainInterval: 250,
  parse: {
    annotate: true,
    stringify: true,
  },
  maxDecodedEvents: 2000,
};

const state = {
  following: new Set(),
  config: { ...defaultConfig },
};

function applyConfig(cfg) {
  if (cfg.trustThreshold !== undefined) Stalker.trustThreshold = cfg.trustThreshold;
  if (cfg.queueCapacity !== undefined) Stalker.queueCapacity = cfg.queueCapacity;
  if (cfg.queueDrainInterval !== undefined) Stalker.queueDrainInterval = cfg.queueDrainInterval;
}

function start(threadId, config) {
  const tid = Number(threadId);
  if (!Number.isFinite(tid)) throw new Error('start(threadId): threadId must be a number');
  if (state.following.has(tid)) return;

  const cfg = { ...state.config, ...(config || {}) };
  applyConfig(cfg);

  Stalker.follow(tid, {
    events: {
      call: true,
      ret: true,
      exec: false,
      block: false,
      compile: false,
    },
    onReceive(events) {
      let decoded;
      try {
        decoded = Stalker.parse(events, cfg.parse);
        if (Array.isArray(decoded) && cfg.maxDecodedEvents > 0 && decoded.length > cfg.maxDecodedEvents) {
          decoded = decoded.slice(0, cfg.maxDecodedEvents);
        }
      } catch (e) {
        send({ type: 'stalker:parse-error', tid, error: String(e) });
        return;
      }

      send({ type: 'stalker:events', tid, decoded });
    },
  });

  state.following.add(tid);
  state.config = cfg;
}

function stop(threadId) {
  const tid = Number(threadId);
  if (!Number.isFinite(tid)) throw new Error('stop(threadId): threadId must be a number');
  if (!state.following.has(tid)) return;

  Stalker.unfollow(tid);
  Stalker.flush();
  Stalker.garbageCollect();

  state.following.delete(tid);
}

rpc.exports = { start, stop };

send({ type: 'frida-stalker-android:onreceive-ready', frida: Frida.version, arch: Process.arch });

'use strict';

/*
 * Start Stalker only while a specific native function executes.
 *
 * This pattern is the most practical way to stalk the "right" thread
 * without guessing thread ids.
 */

const TARGET_MODULE = 'libc.so';
const TARGET_EXPORT = 'open'; // TODO: change to your target

const cfg = {
  trustThreshold: 1,
  queueCapacity: 16384,
  queueDrainInterval: 0, // manual windows: drain on stop
  excludeModules: [
    'libart.so',
    'libc.so',
    'liblog.so',
    'libdl.so',
  ],
};

const depthByTid = new Map();

function applyConfig() {
  Stalker.trustThreshold = cfg.trustThreshold;
  Stalker.queueCapacity = cfg.queueCapacity;
  Stalker.queueDrainInterval = cfg.queueDrainInterval;
}

function excludeNoise() {
  for (const name of cfg.excludeModules) {
    try {
      const m = Process.getModuleByName(name);
      Stalker.exclude({ base: m.base, size: m.size });
    } catch (_) {
      // ignore
    }
  }
}

function startForCurrentThread() {
  const tid = Process.getCurrentThreadId();
  const depth = (depthByTid.get(tid) || 0) + 1;
  depthByTid.set(tid, depth);

  if (depth !== 1) return tid;

  applyConfig();
  excludeNoise();

  Stalker.follow(tid, {
    events: { call: true, ret: false, exec: false, block: false, compile: false },
    onCallSummary(summary) {
      send({ type: 'stalker:call-summary', tid, summary });
    },
  });

  return tid;
}

function stopForThread(tid) {
  const depth = (depthByTid.get(tid) || 0) - 1;
  if (depth > 0) {
    depthByTid.set(tid, depth);
    return;
  }
  depthByTid.delete(tid);

  Stalker.unfollow(tid);
  Stalker.flush(); // triggers summary window drain
  Stalker.garbageCollect();
}

const target = Process.getModuleByName(TARGET_MODULE).getExportByName(TARGET_EXPORT);
send({ type: 'hook:installed', target: `${TARGET_MODULE}!${TARGET_EXPORT}`, address: target.toString() });

Interceptor.attach(target, {
  onEnter(args) {
    this._stalkerTid = startForCurrentThread();
  },
  onLeave(retval) {
    stopForThread(this._stalkerTid);
  },
});

'use strict';

/*
 * Minimal transform(iterator) skeleton.
 *
 * Warning: This is advanced and easy to break. Keep it narrow, and filter to
 * app code ranges. Consider doing call summary/onReceive first.
 */

const defaultCfg = {
  trustThreshold: 1,
  queueCapacity: 16384,
  queueDrainInterval: 250,
};

function applyConfig(cfg) {
  Stalker.trustThreshold = cfg.trustThreshold;
  Stalker.queueCapacity = cfg.queueCapacity;
  Stalker.queueDrainInterval = cfg.queueDrainInterval;
}

function start(threadId, appRange) {
  const tid = Number(threadId);
  if (!Number.isFinite(tid)) throw new Error('start(threadId, appRange): bad threadId');
  if (!appRange || !appRange.base || !appRange.size) throw new Error('start(...): appRange must have base/size');

  const appStart = ptr(appRange.base);
  const appEnd = appStart.add(ptr(appRange.size));

  applyConfig(defaultCfg);

  Stalker.follow(tid, {
    transform(iterator) {
      let insn = iterator.next();

      /*
       * On ARM/ARM64, exclusive store sequences are fragile; only emit noisy
       * code/callouts when memory access is "open".
       */
      const canEmitNoisyCode = (iterator.memoryAccess === 'open');

      do {
        const pc = insn.address;
        const isAppCode = pc.compare(appStart) >= 0 && pc.compare(appEnd) < 0;

        if (isAppCode && canEmitNoisyCode) {
          // Example: emit a callout on every "ret" inside app code.
          if (insn.mnemonic === 'ret') {
            iterator.putCallout(onRet);
          }
        }

        iterator.keep();
      } while ((insn = iterator.next()) !== null);
    },
  });
}

function stop(threadId) {
  const tid = Number(threadId);
  if (!Number.isFinite(tid)) throw new Error('stop(threadId): bad threadId');

  Stalker.unfollow(tid);
  Stalker.flush();
  Stalker.garbageCollect();
}

function onRet(context) {
  send({
    type: 'stalker:ret',
    pc: context.pc.toString(),
    sp: context.sp ? context.sp.toString() : undefined,
  });
}

rpc.exports = { start, stop };