[GH-ISSUE #1192] [Feature] Diagnose a Ghidra native decompiler built for the wrong platform or architecture #424

New issue

Closed

opened 2026-10-15 18:24:56 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:24:56 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 9, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/1192

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I removed credentials, tokens, private paths, and sensitive target data.

Area

Provider or capability discovery

Current limitation

The existing admission check finds an executable path in the matching os/ or build/os/ directory. A copied or misplaced foreign binary can satisfy that check. In the executed macOS fixture, an official Linux x86-64 Ghidra decompiler placed at build/os/mac_arm_64/decompile made scoped doctor report healthy: true, while providers and capabilities reported Ghidra available with no rejection. A direct operating-system launch failed with errno 8, Exec format error. This leaves callers without a preflight explanation of an incompatible native component.

Use cases

Add native-executable compatibility diagnostics to Ghidra admission so doctor and provider discovery can identify a decompiler that exists at the expected path but cannot run on the selected host.

Today an analyst can inspect the native file with operating-system tools (for example file -L) and build or supply a compatible decompiler, but REA's own doctor and discovery report the provider available, so the mismatch surfaces only when analysis tries to launch the decompiler.

Desired outcome and success criteria

Doctor and discovery should inspect enough native-executable metadata to distinguish the configured file's platform and architecture from its directory name. If the file is incompatible with the host, they should mark Ghidra unavailable and explain the observed mismatch and the replacement or native-build action needed. Diagnostics should identify the candidate path and supported alternative location without modifying the installation, executing the analysis target, or automatically changing Gatekeeper settings. Any admitted translation or universal-binary path should retain an explicit supported compatibility explanation rather than relying only on the filename.

Success criteria:

On macOS arm64, a Linux x86-64 ELF decompiler at the otherwise valid native-decompiler path produces an unavailable Ghidra result with a reason that identifies the incompatible native file and the host requirement.
Scoped doctor, unscoped doctor's Ghidra inspection, providers --json, and capabilities --json agree on that incompatibility and do not report the file as a matching usable native prerequisite.
A compatible macOS arm64 decompiler remains available in either the os/ or build/os/ location, and a missing executable retains its existing missing-prerequisite diagnostic.
Inspection leaves the caller's Ghidra files, permissions, and quarantine attributes unchanged, and diagnostics describe any compatibility that could not be established as unknown.

Authority boundaries and non-goals

Affected area: Ghidra installation admission, doctor projection, provider-discovery availability, and the installation guide's native-component prerequisites.

Do not install or build native tools, automatically clear quarantine, validate all native dependencies, or claim that executable metadata proves successful decompilation. Runtime startup and real decompiler verification remain separate checks.

Alternatives considered

Keep the current pathname and executable-bit check and document its limit. That is inexpensive, but still gives no native-format explanation when the selected file is incompatible. Rely on a later analysis failure to identify the problem. That requires importing a target and launching Ghidra before a setup mistake can be diagnosed. The proposed metadata check gives a bounded preflight answer while retaining explicit runtime-verification limits.

Possible direction

No response

References

The observed baseline was rea-agents 6.1.0 and main commit b34bdcdb2877be394c59c9cbf70269dc1841ff78, using official Ghidra 12.1.4, 64-bit full Homebrew OpenJDK 21.0.12.1, Node 24.21.0, and macOS 27.0.1 arm64. Both builds reproduced the availability result. The minimal fixture copied only application.properties and symlinked the existing launcher and selected decompiler. Replacing the foreign file with the actual arm64 macOS decompiler passed the same admission checks, and removing it produced executable_missing in both builds.

The following steps reproduce the workflow gap without changing the real installation:

export GHIDRA_INSTALL_DIR=/path/to/ghidra_12.1.4_PUBLIC
export JAVA_HOME=/path/to/jdk-21
work_dir="$(mktemp -d /tmp/agent-work.XXXXXX)"
mkdir -p "$work_dir/fixture/support" "$work_dir/fixture/Ghidra/Features/Decompiler/build/os/mac_arm_64"
cp "$GHIDRA_INSTALL_DIR/Ghidra/application.properties" "$work_dir/fixture/Ghidra/application.properties"
ln -s "$GHIDRA_INSTALL_DIR/support/analyzeHeadless" "$work_dir/fixture/support/analyzeHeadless"
ln -s "$GHIDRA_INSTALL_DIR/Ghidra/Features/Decompiler/os/linux_x86_64/decompile" "$work_dir/fixture/Ghidra/Features/Decompiler/build/os/mac_arm_64/decompile"
GHIDRA_INSTALL_DIR="$work_dir/fixture" npx -y rea-agents@6.1.0 doctor --provider ghidra --json
GHIDRA_INSTALL_DIR="$work_dir/fixture" npx -y rea-agents@6.1.0 providers --json
GHIDRA_INSTALL_DIR="$work_dir/fixture" npx -y rea-agents@6.1.0 capabilities --json
file -L "$work_dir/fixture/Ghidra/Features/Decompiler/build/os/mac_arm_64/decompile"

file -L reported an ELF 64-bit x86-64 GNU/Linux executable. A Python subprocess.run launch of that same pathname with empty input raised OSError with errno 8, while the actual macOS arm64 decompiler launched and returned its EOF exit status. src/ghidra/GhidraInstallation.ts:247 selects the first candidate passing its executable check, and :352 passes the native-decompiler check solely because such a path exists. docs/installation.md:436 through :441 describes the host-native requirement and the current executable-prerequisite check. This request expands that preflight scope rather than claiming that today's documented lightweight check guarantees full runtime readiness.

Originally created by @coygeek on GitHub (Oct 9, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/1192 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Area Provider or capability discovery ### Current limitation The existing admission check finds an executable path in the matching `os/` or `build/os/` directory. A copied or misplaced foreign binary can satisfy that check. In the executed macOS fixture, an official Linux x86-64 Ghidra decompiler placed at `build/os/mac_arm_64/decompile` made scoped doctor report `healthy: true`, while `providers` and `capabilities` reported Ghidra available with no rejection. A direct operating-system launch failed with errno 8, `Exec format error`. This leaves callers without a preflight explanation of an incompatible native component. ### Use cases Add native-executable compatibility diagnostics to Ghidra admission so doctor and provider discovery can identify a decompiler that exists at the expected path but cannot run on the selected host. Today an analyst can inspect the native file with operating-system tools (for example `file -L`) and build or supply a compatible decompiler, but REA's own doctor and discovery report the provider available, so the mismatch surfaces only when analysis tries to launch the decompiler. ### Desired outcome and success criteria Doctor and discovery should inspect enough native-executable metadata to distinguish the configured file's platform and architecture from its directory name. If the file is incompatible with the host, they should mark Ghidra unavailable and explain the observed mismatch and the replacement or native-build action needed. Diagnostics should identify the candidate path and supported alternative location without modifying the installation, executing the analysis target, or automatically changing Gatekeeper settings. Any admitted translation or universal-binary path should retain an explicit supported compatibility explanation rather than relying only on the filename. Success criteria: - On macOS arm64, a Linux x86-64 ELF decompiler at the otherwise valid native-decompiler path produces an unavailable Ghidra result with a reason that identifies the incompatible native file and the host requirement. - Scoped doctor, unscoped doctor's Ghidra inspection, `providers --json`, and `capabilities --json` agree on that incompatibility and do not report the file as a matching usable native prerequisite. - A compatible macOS arm64 decompiler remains available in either the `os/` or `build/os/` location, and a missing executable retains its existing missing-prerequisite diagnostic. - Inspection leaves the caller's Ghidra files, permissions, and quarantine attributes unchanged, and diagnostics describe any compatibility that could not be established as unknown. ### Authority boundaries and non-goals Affected area: Ghidra installation admission, doctor projection, provider-discovery availability, and the installation guide's native-component prerequisites. Do not install or build native tools, automatically clear quarantine, validate all native dependencies, or claim that executable metadata proves successful decompilation. Runtime startup and real decompiler verification remain separate checks. ### Alternatives considered Keep the current pathname and executable-bit check and document its limit. That is inexpensive, but still gives no native-format explanation when the selected file is incompatible. Rely on a later analysis failure to identify the problem. That requires importing a target and launching Ghidra before a setup mistake can be diagnosed. The proposed metadata check gives a bounded preflight answer while retaining explicit runtime-verification limits. ### Possible direction _No response_ ### References The observed baseline was `rea-agents` 6.1.0 and main commit `b34bdcdb2877be394c59c9cbf70269dc1841ff78`, using official Ghidra 12.1.4, 64-bit full Homebrew OpenJDK 21.0.12.1, Node 24.21.0, and macOS 27.0.1 arm64. Both builds reproduced the availability result. The minimal fixture copied only `application.properties` and symlinked the existing launcher and selected decompiler. Replacing the foreign file with the actual arm64 macOS decompiler passed the same admission checks, and removing it produced `executable_missing` in both builds. The following steps reproduce the workflow gap without changing the real installation: ```sh export GHIDRA_INSTALL_DIR=/path/to/ghidra_12.1.4_PUBLIC export JAVA_HOME=/path/to/jdk-21 work_dir="$(mktemp -d /tmp/agent-work.XXXXXX)" mkdir -p "$work_dir/fixture/support" "$work_dir/fixture/Ghidra/Features/Decompiler/build/os/mac_arm_64" cp "$GHIDRA_INSTALL_DIR/Ghidra/application.properties" "$work_dir/fixture/Ghidra/application.properties" ln -s "$GHIDRA_INSTALL_DIR/support/analyzeHeadless" "$work_dir/fixture/support/analyzeHeadless" ln -s "$GHIDRA_INSTALL_DIR/Ghidra/Features/Decompiler/os/linux_x86_64/decompile" "$work_dir/fixture/Ghidra/Features/Decompiler/build/os/mac_arm_64/decompile" GHIDRA_INSTALL_DIR="$work_dir/fixture" npx -y rea-agents@6.1.0 doctor --provider ghidra --json GHIDRA_INSTALL_DIR="$work_dir/fixture" npx -y rea-agents@6.1.0 providers --json GHIDRA_INSTALL_DIR="$work_dir/fixture" npx -y rea-agents@6.1.0 capabilities --json file -L "$work_dir/fixture/Ghidra/Features/Decompiler/build/os/mac_arm_64/decompile" ``` `file -L` reported an ELF 64-bit x86-64 GNU/Linux executable. A Python `subprocess.run` launch of that same pathname with empty input raised `OSError` with errno 8, while the actual macOS arm64 decompiler launched and returned its EOF exit status. `src/ghidra/GhidraInstallation.ts:247` selects the first candidate passing its executable check, and `:352` passes the native-decompiler check solely because such a path exists. `docs/installation.md:436` through `:441` describes the host-native requirement and the current executable-prerequisite check. This request expands that preflight scope rather than claiming that today's documented lightweight check guarantees full runtime readiness.

bsakaguchi

2026-10-15 18:24:56 +00:00