[GH-ISSUE #4399] [Feature] Triage a desktop application install directory by runtime family and bundled components #1751

New issue

Closed

opened 2026-10-16 21:09:49 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:09:49 +00:00

Owner

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

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

Evidence, artifacts, or reconstruction

Current limitation

REA has no entry point for this kind of directory:

open_binary rejects any directory whose name does not end in .app with directory_requires_file (src/application/BinaryTargetResolver.ts). Its remediation points to analyze_javascript_application.
inspect_artifact and extract_artifact work on "an active archive or application package" (src/contracts/artifactToolContracts.ts). An unpacked desktop install directory is neither.
Runtime-family hints are derived from filenames only for mobile and Apple targets. src/domain/nativeConvention.ts recognizes React Native, Flutter, and Unity through names such as libunity.so and UnityFramework.framework, but not desktop layouts such as GameAssembly.dll, UnityPlayer.dll, <Name>_Data/, global-metadata.dat, Unreal .pak or .utoc files, Godot .pck packs, or GameMaker data.win.
inspect_managed_artifact classifies one PE at a time (dotnet-framework, modern-dotnet, unity-mono, mixed-clr-native). It cannot tell an IL2CPP build from a native program, and it does not scan a directory.

inspect_artifact already returns next_probes with an operation, rationale, and authority for each member format of an application bundle (src/domain/artifactInspection.ts). Those probes are keyed by container format, not by runtime family, so a directory of PE files gets the same advice whether it is a Unity Mono build, an IL2CPP build, or a native program.

As a result, an agent handed an install directory must pick files by hand before it can use any of REA's per-format tools. Per-engine requests already exist (#3607, #3625, #3631, #3632, #3633, among others), but each assumes the agent already knows which engine it is looking at.

Use cases

A user points an agent at an installed desktop program and asks how it is built. The agent needs to know whether the logic lives in managed assemblies, an IL2CPP native binary plus metadata, packed engine archives, or a JavaScript bundle before choosing tools.
Selecting which of several hundred files deserve inspect_managed_artifact or open_binary.
Recognizing early that a directory contains protection or anti-cheat components. The agent can then report the scope boundary instead of drifting toward analysis that CONTRIBUTING.md excludes.

Desired outcome and success criteria

Let REA accept a Windows or Linux desktop application install directory as a read-only target and report which runtime or engine families it uses (for example .NET, Unity Mono, Unity IL2CPP, Unreal, Godot, GameMaker, Electron), which notable third-party components it bundles (plugin or mod loaders, protection or anti-cheat components), the evidence for each, and which existing REA operations to run next on which files.

A read-only operation accepts a directory root and returns Evidence with:
- one or more runtime-family candidates, each with confidence (observed, derived, or inferred) and the exact files, offsets, or strings that support it;
- competing signals when more than one family is plausible;
- a list of recognized third-party components (category, matched paths, and evidence), labeled as observations only;
- bounded index coverage, with explicit truncation and limitations.
At minimum, the recognized signals cover:
- a PE CLR header (.NET);
- Unity Mono (<Name>_Data/Managed/*.dll with UnityEngine references);
- Unity IL2CPP (GameAssembly.dll or libil2cpp.so with global-metadata.dat);
- Unreal (.pak/.utoc containers or an engine version string);
- Godot (a GDPC pack, standalone or appended to the executable);
- GameMaker (FORM with GEN8 in data.win);
- Electron/ASAR.
Each suggested next step names an existing REA operation and the specific files it applies to, with a rationale tied to the cited evidence. For example, a Unity Mono build suggests inspect_managed_artifact on its managed assemblies. Suggestions are marked as inferences.
The operation never executes, extracts, or modifies files, and contacts no network service.
Fixture directories built from small synthetic files, one per supported family plus a mixed and an unrecognized case, produce the expected candidates. The unrecognized case returns no candidate rather than a guess.

Expected interaction with targets

Read existing files or captured data

Target and scope details (optional)

The operation reads directory listings, file headers, and bounded byte ranges only. Protection and anti-cheat components are identified and labeled under the "Static protection detection is distinct from defeating that protection" line in CONTRIBUTING.md. This request includes no guidance or workflow for disabling, bypassing, or evading them.

Non-goals:

deep parsing of any engine's formats, which the per-engine issues above own;
packer identification inside a single PE or ELF, which #3413 and PR #3775 own;
live process inspection.

Open scope question: maintainers may prefer to split third-party component labeling into a separate issue from runtime-family identification.

Verification available so far

I can suggest a sample or manual check

Verification details (optional)

Observed on the published release: open_binary on a synthetic directory containing Game.exe, GameAssembly.dll, Game_Data/il2cpp_data/Metadata/global-metadata.dat, and an empty protection-vendor folder returns target_unavailable with constraint: "directory_requires_file" and remediation pointing to analyze_javascript_application. With this feature, the same fixture should yield a Unity IL2CPP candidate, cite both files, and list the protection-vendor folder as a labeled component.

Alternatives considered

#3714 (open RFC, universal artifact discovery and analyzer routing): format-agnostic and broader. It proposes entropy and signature classification with ranked analyzer routing, but no runtime-family or component taxonomy. This request could become an engine-aware slice of it.
Extending inspect_artifact to admit arbitrary directories and extending directoryProbes with runtime-family probes: likely the smallest change, and a reasonable implementation of this request.
Leaving identification to the agent: works when the agent already knows the engines, but the evidence is not retained and is not consistent across agents.

Possible direction

Reuse the existing inventory classifier, which already records a directory root (src/artifacts/inventory/classify.ts), and extend the filename conventions in src/domain/nativeConvention.ts. Add a runtime-family field to inventory-derived Evidence rather than a new parallel vocabulary.

References

Checked against main at commit 8ab5024 (rea-agents 6.5.0).
Related: #3714, #3413, PR #3775, #3607, #3784, #3625, #3631, #3632, #3633.

Originally created by @coygeek on GitHub (Oct 16, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/4399 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area Evidence, artifacts, or reconstruction ### Current limitation REA has no entry point for this kind of directory: - `open_binary` rejects any directory whose name does not end in `.app` with `directory_requires_file` (`src/application/BinaryTargetResolver.ts`). Its remediation points to `analyze_javascript_application`. - `inspect_artifact` and `extract_artifact` work on "an active archive or application package" (`src/contracts/artifactToolContracts.ts`). An unpacked desktop install directory is neither. - Runtime-family hints are derived from filenames only for mobile and Apple targets. `src/domain/nativeConvention.ts` recognizes React Native, Flutter, and Unity through names such as `libunity.so` and `UnityFramework.framework`, but not desktop layouts such as `GameAssembly.dll`, `UnityPlayer.dll`, `<Name>_Data/`, `global-metadata.dat`, Unreal `.pak` or `.utoc` files, Godot `.pck` packs, or GameMaker `data.win`. - `inspect_managed_artifact` classifies one PE at a time (`dotnet-framework`, `modern-dotnet`, `unity-mono`, `mixed-clr-native`). It cannot tell an IL2CPP build from a native program, and it does not scan a directory. `inspect_artifact` already returns `next_probes` with an operation, rationale, and authority for each member format of an application bundle (`src/domain/artifactInspection.ts`). Those probes are keyed by container format, not by runtime family, so a directory of PE files gets the same advice whether it is a Unity Mono build, an IL2CPP build, or a native program. As a result, an agent handed an install directory must pick files by hand before it can use any of REA's per-format tools. Per-engine requests already exist (#3607, #3625, #3631, #3632, #3633, among others), but each assumes the agent already knows which engine it is looking at. ### Use cases - A user points an agent at an installed desktop program and asks how it is built. The agent needs to know whether the logic lives in managed assemblies, an IL2CPP native binary plus metadata, packed engine archives, or a JavaScript bundle before choosing tools. - Selecting which of several hundred files deserve `inspect_managed_artifact` or `open_binary`. - Recognizing early that a directory contains protection or anti-cheat components. The agent can then report the scope boundary instead of drifting toward analysis that `CONTRIBUTING.md` excludes. ### Desired outcome and success criteria Let REA accept a Windows or Linux desktop application install directory as a read-only target and report which runtime or engine families it uses (for example .NET, Unity Mono, Unity IL2CPP, Unreal, Godot, GameMaker, Electron), which notable third-party components it bundles (plugin or mod loaders, protection or anti-cheat components), the evidence for each, and which existing REA operations to run next on which files. - A read-only operation accepts a directory root and returns Evidence with: - one or more runtime-family candidates, each with confidence (observed, derived, or inferred) and the exact files, offsets, or strings that support it; - competing signals when more than one family is plausible; - a list of recognized third-party components (category, matched paths, and evidence), labeled as observations only; - bounded index coverage, with explicit truncation and limitations. - At minimum, the recognized signals cover: - a PE CLR header (.NET); - Unity Mono (`<Name>_Data/Managed/*.dll` with UnityEngine references); - Unity IL2CPP (`GameAssembly.dll` or `libil2cpp.so` with `global-metadata.dat`); - Unreal (`.pak`/`.utoc` containers or an engine version string); - Godot (a `GDPC` pack, standalone or appended to the executable); - GameMaker (`FORM` with `GEN8` in `data.win`); - Electron/ASAR. - Each suggested next step names an existing REA operation and the specific files it applies to, with a rationale tied to the cited evidence. For example, a Unity Mono build suggests `inspect_managed_artifact` on its managed assemblies. Suggestions are marked as inferences. - The operation never executes, extracts, or modifies files, and contacts no network service. - Fixture directories built from small synthetic files, one per supported family plus a mixed and an unrecognized case, produce the expected candidates. The unrecognized case returns no candidate rather than a guess. ### Expected interaction with targets Read existing files or captured data ### Target and scope details (optional) The operation reads directory listings, file headers, and bounded byte ranges only. Protection and anti-cheat components are identified and labeled under the "Static protection detection is distinct from defeating that protection" line in `CONTRIBUTING.md`. This request includes no guidance or workflow for disabling, bypassing, or evading them. Non-goals: - deep parsing of any engine's formats, which the per-engine issues above own; - packer identification inside a single PE or ELF, which #3413 and PR #3775 own; - live process inspection. Open scope question: maintainers may prefer to split third-party component labeling into a separate issue from runtime-family identification. ### Verification available so far I can suggest a sample or manual check ### Verification details (optional) Observed on the published release: `open_binary` on a synthetic directory containing `Game.exe`, `GameAssembly.dll`, `Game_Data/il2cpp_data/Metadata/global-metadata.dat`, and an empty protection-vendor folder returns `target_unavailable` with `constraint: "directory_requires_file"` and remediation pointing to `analyze_javascript_application`. With this feature, the same fixture should yield a Unity IL2CPP candidate, cite both files, and list the protection-vendor folder as a labeled component. ### Alternatives considered - #3714 (open RFC, universal artifact discovery and analyzer routing): format-agnostic and broader. It proposes entropy and signature classification with ranked analyzer routing, but no runtime-family or component taxonomy. This request could become an engine-aware slice of it. - Extending `inspect_artifact` to admit arbitrary directories and extending `directoryProbes` with runtime-family probes: likely the smallest change, and a reasonable implementation of this request. - Leaving identification to the agent: works when the agent already knows the engines, but the evidence is not retained and is not consistent across agents. ### Possible direction Reuse the existing inventory classifier, which already records a `directory` root (`src/artifacts/inventory/classify.ts`), and extend the filename conventions in `src/domain/nativeConvention.ts`. Add a runtime-family field to inventory-derived Evidence rather than a new parallel vocabulary. ### References - Checked against `main` at commit 8ab5024 (`rea-agents` 6.5.0). - Related: #3714, #3413, PR #3775, #3607, #3784, #3625, #3631, #3632, #3633.

bsakaguchi closed this issue

2026-10-31 00:32:34 +00:00

bsakaguchi referenced this issue

2026-10-31 00:55:14 +00:00

[PR #1763] [MERGED] fix(hopper): let failed one-shot commands exit while retaining a lease #4803

bsakaguchi referenced this issue

2026-10-31 00:56:02 +00:00

[PR #1841] [MERGED] fix(ida): let one-shot commands exit after retaining cleanup #4851