Frida 插桩¶

REA 通过 CLI 和 MCP 提供 Frida 设备与进程发现、附加（attach）或生成（spawn）会话，以及调用者编写的 JavaScript 插桩。Node 绑定是一个可选的包依赖项，并且仅在 Frida 操作运行时加载。REA 不会在目标上安装 Frida server。

对于远程设备，请在相应操作中传入带有可选端口的主机（host[:port]；IPv6 地址使用方括号），以及任何令牌、证书、origin 或 keepalive 选项。Keepalive 间隔以秒为单位，与 Frida Core 17.23.2 一致。认证值仅在该活动调用或会话期间保留，并且被排除在 Evidence 之外。请勿将凭据嵌入端点地址中。

MCP 提供 list_frida_devices、list_frida_processes、start_frida_session、load_frida_script、resume_frida_session、unload_frida_script、frida_session_status 和 close_frida_session。生成的进程会以暂停状态启动，以便先加载脚本。关闭会卸载会话脚本并分离。如果生成的进程仍处于暂停状态，REA 只会在脚本清理或会话分离确认插桩已释放后恢复它；如果两条清理路径都失败，目标将保持暂停，并保留清理错误。REA 从不杀死目标。MCP 会话随服务器进程的结束而结束。一次性 CLI 命令 instrument-with-frida 接受一个内联脚本或脚本文件，在限定时间内观察消息，并返回包含源哈希和所捕获消息的 Evidence。

instrument-with-frida --json 直接返回 Evidence 记录，与 MCP 一致。使用较早的 {evidence, cleanup_error} CLI 包装器的使用者，应从 JSON 根读取记录，并从 normalized_result.cleanup_error 读取会话清理观察结果。如果最终提供程序清理失败，或清理期间发生取消，类型化错误会在 details.partial_observation 中保留已完成的 Evidence。发现命令会在同一字段中保留其设备或进程报告。

要进行状态和捕获覆盖范围检查，请向 frida_session_status 传入 {"session_id":"SESSION_ID","detail":"summary"}。每次调用都会读取所观察到的会话状态，并保留完整的观察结果。回复是一个 inspect_analysis_view Evidence 摘要，包含会话身份、状态、脚本、messages_retained 和 messages_truncated；消息负载保留在其 parent_evidence_id 中。该计数涵盖保留的排队消息，而非每个目标事件。省略 detail 或使用 detail=complete 会保留现有的完整回复。

摘要的选中字段示例如下（摘录）：

{
  "summary": {
    "state": "running",
    "messages_retained": 50,
    "messages_truncated": false
  }
}

使用 get_evidence_bundle 并设置 detail="summary" 和 filters={"evidence_id":"PARENT_ID"}，可以在不包含消息负载的情况下发现父元数据。过滤器仅适用于摘要交付。使用 export_evidence_bundle 获取完整的规范包，然后从状态摘要中选择 evidence_id 与 normalized_result.parent_evidence_id 匹配的记录。要使用现有的 CLI inspect-analysis-view，请将该记录提取为独立的 Evidence JSON 文件，并将其作为 Evidence 文件源，同时设置 view={"kind":"summary"}。读取已保留的 Evidence 不会刷新活动会话，也不会在进程退出或 PID 复用后验证进程状态。

失败的启动清理会保留已获取的 Frida 句柄，包括尚未附加的暂停生成进程，以便后续重试清理。其远程连接会保持租用状态，直到会话分离和目标恢复完成。CLI 命令在返回前会等待提供程序清理完成；MCP 会在其服务器关闭时保留这些资源以便清理。服务器关闭会停止接受新的 Frida 操作，并等待已接受的启动、发现和排队工作完成后再释放其资源。失败的清理仍会被报告，并且可以通过再次关闭服务器重试，而不是将未注册的会话视为已完全释放。

Frida 脚本在所选目标内部执行，并拥有该进程的内存、文件系统和网络权限。本地设备查找等待 1000 ms。此版本没有针对该查找的运行时覆盖；其他 REA 超时不会提高该值。远程端点不使用该查找。消息捕获上限为 16 MiB，并会报告截断。元数据、类型、文本字段上限以及 JSON 节点上限也是固定的。当观察结果确实丢弃了数据时，Evidence 会指出对应的上限。此版本没有针对这些捕获上限的运行时覆盖。脚本源代码不会存储在 Evidence 中；其选定路径和 SHA-256 摘要会被存储。对于文件，source_sha256 标识原始所选字节。无效的 UTF-8 仍使用替换解码；Evidence 随后会记录该限制，以及 raw_result.source_representation（包含传给 Frida 的 UTF-8 字符串的编码、解码模式和 loaded_source_sha256）。有效的 UTF-8 文件和内联脚本不需要这一额外的表示事实。Evidence 会保留非认证类目标选择信息，例如设备或端点、模式、程序或 PID，以及 spawn 参数。认证值仍被排除在外。结果报告所观察到的会话和消息，而不受支持的平台元数据仍为未知。

在 Frida 操作开始前被取消的请求不会对提供程序产生任何影响。如果取消发生在原生 Frida 调用期间，REA 会等待该调用返回，然后关闭它创建的任何会话，并将观察到的会话作为部分观察结果返回。在现有会话上取消脚本加载，只会在排队操作运行前释放其新脚本；该会话和先前加载的脚本仍保持可用。如果在原生调用返回时观察到取消，部分 Evidence 会保留源身份和捕获的消息，即使该调用被拒绝，也包括在等待清理期间发出的消息。调用者的取消原因仍然是主要信息，原生拒绝则作为经净化的诊断信息保留。如果取消发生在清理期间，则清理前已观察到的失败仍然是主要信息。取消截止点是 REA 对原生完成状态的观察，而非对不可观察的原生事件顺序的断言。

script_id 是 REA 的加载尝试标识。当创建被拒绝且未返回句柄时，script_cleanup: "no_handle" 表示 REA 没有获得可供卸载的句柄；这并不证明引擎没有做任何工作。提供程序一旦确认加载成功，后续的请求取消不会卸载该脚本；请使用 unload_frida_script 来释放它。如果脚本清理失败，该脚本仍归提供程序所有，并且已暂停的目标在待处理的插桩被释放之前无法恢复。排队的脚本加载、恢复和卸载操作在调度原生效果之前会检查取消状态。取消 Evidence 会分别报告是否观察到了目标恢复、插桩清理是否完成，以及最终目标存活状态是否仍未知。REA 不会杀死目标。远程发现会保留其观察结果，并在无法移除临时连接时报告单独的清理错误。

Frida Core API 记录了设备管理、会话和脚本加载；JavaScript API 记录了目标端插桩。Luma 是 Frida 的独立 GUI；REA 不自动操作或控制它。npm run verify:frida 需要一个带有可选 Frida 绑定的 Linux 主机，并使用由验证器创建的临时本地 Node.js 测试夹具。添加 -- --address HOST:PORT --pid PID 可针对调用者选择的目标运行单独的远程附加通道。Mock 测试无法证明真实的设备/服务器兼容性。