From b11fe63bf4d9c4ea375b071599c374429f0b54e7 Mon Sep 17 00:00:00 2001 From: Avocado Date: Wed, 14 Oct 2026 12:21:11 +1100 Subject: [PATCH] docs(installation): document Linux procps prerequisite Document the Linux procps-compatible ps prerequisite before quick start and in the installation/provider guides. Scope it to shared process-supervision workflows and give recovery guidance for generic provider startup errors. Actual JavaScript CLI analysis passed with ps and refused an empty PATH with capability_unavailable and retained partial evidence. Real Chrome scenario launch succeeded without ps, confirming the need for qualified wording. Docs checks, formatting, typecheck/lint and diff checks passed. Five English documentation files; no runtime changes. Native Ghidra/JADX/firmware execution was not performed. Fixes #2763 Co-authored-by: Avocado <93173363+HeadmasterEggy@users.noreply.github.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com> Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --- README.md | 7 ++++++- docs/android-analysis.md | 4 ++++ docs/firmware-analysis.md | 4 ++++ docs/ghidra-provider.md | 2 ++ docs/installation.md | 14 ++++++++++++++ 5 files changed, 30 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0088640d07..3395cd3cb5 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,11 @@ Setup registers REA with your agent and installs matching workflow instructions. ## Quick start +On Linux, Ghidra, JADX, firmware tool launches and static JavaScript/Electron +analysis require a procps-compatible `ps` on REA's `PATH` for process ownership +checks. Recovery steps are in `docs/installation.md` under +"Linux owned-process prerequisite". + ### Set up your agent With Node.js and npm installed, run: @@ -167,7 +172,7 @@ Additional tools and host support depend on the target: | EVM bytecode | Dispatch selectors, byte offsets, inferred arguments and mutability | Local raw/hex carrier on Linux x64; [offline EVM guide](docs/evm-bytecode.md) | | SQLite databases | Tables, columns, indexes, views, triggers and selected ordinary-table rows | Local database/WAL snapshot; Node.js 24.x >=24.15 or 26+ with native SQLite limits | | Recorded Linux crashes | Raw notes, every recorded thread's registers/signals and optional mapping candidates | Caller-supplied pwntools on Linux x64; optional GDB/pwndbg; [recorded crashes](docs/recorded-crashes.md) | -| JavaScript / Electron | Modules, imports, source maps, routes, IPC and native add-on relationships | Node.js and npm; [application analysis](https://rea.tools/guides/javascript/) | +| JavaScript / Electron | Modules, imports, source maps, routes, IPC and native add-on relationships | Node.js and npm; Linux: procps-compatible `ps`; [application analysis](https://rea.tools/guides/javascript/) | | Websites | Page structure, scripts, network observations and requested screenshots | A Chrome-family browser; [browser analysis](https://rea.tools/guides/browser/) | | Saved network captures | Requests, responses, exposed payloads and source locations | HAR or Fiddler Everywhere SAZ; mitmdump on Linux for native mitmproxy; [capture guide](docs/web-network-captures.md) | | .NET assemblies | Metadata, CIL instructions, declared native dependencies and build comparisons | None (static only); [managed-code guide](docs/managed-code-analysis.md) | diff --git a/docs/android-analysis.md b/docs/android-analysis.md index 668bcbffb4..1bad043531 100644 --- a/docs/android-analysis.md +++ b/docs/android-analysis.md @@ -9,6 +9,10 @@ This family is present on repository main and in npm 4.1.0. Check the [released package boundary](installation.md#released-package-and-main) and the connected server's tool list before selecting it. +On Linux, JADX launches an REA-owned process and requires a procps-compatible +`ps` on REA's `PATH`; see the shared +[Linux process prerequisite](installation.md#linux-owned-process-prerequisite). + ## Optional package delivery The MCP `inspect_android_package` request keeps complete output when `detail` is diff --git a/docs/firmware-analysis.md b/docs/firmware-analysis.md index beab16400e..152819177f 100644 --- a/docs/firmware-analysis.md +++ b/docs/firmware-analysis.md @@ -9,6 +9,10 @@ No device, root privilege, mount, emulation or execution of extracted programs is needed. Arbitrary firmware bytes do not pass native executable admission; select a returned ELF separately for supported Ghidra analysis. +On Linux, Binwalk and Unblob run as REA-owned processes and require a +procps-compatible `ps` on REA's `PATH`; see the shared +[Linux process prerequisite](installation.md#linux-owned-process-prerequisite). + ## Caller-supplied tools Provide existing tools using absolute executable paths, scoped to your shell: diff --git a/docs/ghidra-provider.md b/docs/ghidra-provider.md index 2f70b48bc7..819d55ee56 100644 --- a/docs/ghidra-provider.md +++ b/docs/ghidra-provider.md @@ -7,6 +7,8 @@ Executable bytes remain unchanged. Use [installation](installation.md#ghidra) for supported hosts, prerequisites, configuration, startup deadlines, resource controls, and cleanup recovery. +[Linux Ghidra launches](installation.md#linux-owned-process-prerequisite) also +require a procps-compatible `ps` on REA's `PATH` for process ownership checks. [Windows P0](windows-ghidra-p0.md) has its own admission and lifecycle boundary; [NativeAOT observations](ghidra-nativeaot.md) include a built-in read-only PE snapshot parser and a separate optional annotation extension. Check the diff --git a/docs/installation.md b/docs/installation.md index bb6a2dd5c6..9b85430703 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -320,6 +320,20 @@ on `open_binary`. A `capability_unavailable` failure carries `details.candidate_ids`, while `provider_unavailable` asks you to repair the selected engine. See [provider selection](cli.md#choose-a-provider). +### Linux owned-process prerequisite + +On Linux, REA's shared process supervisor requires a procps-compatible `ps` +on REA's `PATH` for ownership checks before launching a child. Ghidra, JADX, +firmware tools and static JavaScript/Electron analysis use these checks. +Install `procps` or put another procps-compatible `ps` on `PATH` before +running those workflows. A missing or incompatible command causes a refusal +before the supervised child starts. + +The public error code varies by caller: `capability_unavailable`, +`provider_unavailable` or `execution_failure`. Some provider adapters report +only a generic startup error. Check this prerequisite before following +provider-specific recovery advice. + ## Diagnose, update, and remove `rea doctor --json` is strictly read-only. `rea update` updates only the npm or Bun global installation that owns the running CLI. Source checkouts and package-runner copies must be updated through the mechanism that owns them; a fresh package-runner invocation can use `npx rea-agents@latest` or `bunx rea-agents@latest`. `rea uninstall` removes only REA-owned agent registrations and skill files; `--purge-data` additionally removes REA cache and state paths.