shared scripts, NUI webviews, events and native call graphs #1413

New issue

Open

opened 2026-10-16 21:05:13 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:13 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3700

Problem Statement & Context

Modern open-world multiplayer modifications and dedicated community frameworks structure extensions, gamemodes, and client/server add-ons into self-contained directory packages known as "resources". These resources run within a sandboxed runtime environment communicating across isolated client and server boundaries.

Auditing or reverse engineering a resource package requires understanding its multi-environment architecture:

Resource Manifest (fxmanifest.lua / legacy __resource.lua): Declares resource metadata (fx_version, game), dependencies, file declarations (files { ... }), and partitioned script execution environments:
- client_script / client_scripts: Scripts executed locally within the client process sandbox.
- server_script / server_scripts: Scripts executed on the dedicated server host.
- shared_script / shared_scripts: Utility libraries and configurations shared across both contexts.
NUI (Native User Interface) Webviews: Embedded Chromium/CEF panels configured via ui_page, exchanging asynchronous web messages with client scripts via SendNUIMessage and RegisterNUICallback.
Cross-Environment Network Events: Bidirectional messaging using RegisterNetEvent, TriggerServerEvent, TriggerClientEvent, and TriggerLatentServerEvent.
Export & Module Interfaces: Public module functions registered via exports('func_name', ...) and consumed by third-party resources via exports['res_name']:func_name().
Native Hash Calls: Invocations of platform engine functions identified either by uppercase string identifiers or 64-bit hexadecimal function hashes (Citizen.InvokeNative).

REA lacks a dedicated package analyzer that ingests a resource folder or archive, correlates client/server/NUI boundaries, resolves native call tables, and models the complete interaction graph.

Proposed Architecture

flowchart TD
    A["Multiplayer Resource Directory / Archive"] --> B["Resource Package Analyzer"]
    B --> C["Manifest Parser & Environment Splitter"]
    B --> D["Client / Server Script Inspector"]
    B --> E["NUI Webview & IPC Bridge Analyzer"]
    B --> F["Native Hash & Export Resolver"]
    
    C --> C1["fxmanifest.lua / __resource.lua Declarations"]
    C --> C2["Dependencies & File Assets Mapping"]
    
    D --> D1["Client-Side Scripts (Lua, JS, C#)"]
    D --> D2["Server-Side Scripts (Lua, JS, C#)"]
    D --> D3["Network Events (TriggerServerEvent / TriggerClientEvent)"]
    
    E --> E1["ui_page HTML, CSS & JavaScript Bundles"]
    E --> E2["NUI IPC: SendNUIMessage & RegisterNUICallback"]
    
    F --> F1["Export Declarations & Cross-Resource Calls"]
    F --> F2["Citizen.InvokeNative Hash Resolution"]
    
    C & D & E & F --> G["Synthesized Resource Interaction Graph & Security Map"]

Technical Capabilities & Modules

Manifest Parsing & Context Partitioning:
- Parse fxmanifest.lua and __resource.lua files.
- Extract fx_version, game compatibility flags, declared dependencies, and data file definitions.
- Categorize all files into client, server, shared, and UI asset domains.
Network Event Flow Analysis:
- Detect event listener registrations (RegisterNetEvent, AddEventHandler).
- Trace outbound event triggers: client-to-server (TriggerServerEvent) and server-to-client (TriggerClientEvent).
- Extract exchanged event names and infer argument schemas passed across the network boundary.
NUI Webview Interface Reconstruction:
- Resolve ui_page entrypoints and map referenced HTML, JavaScript, and stylesheet assets.
- Extract messages sent from client Lua/JS to webview via SendNUIMessage({ action = "...", data = ... }).
- Map NUI callbacks registered in client scripts (RegisterNUICallback('action', handler)) and correlate with webview fetch("https://<resource>/action", ...) calls.
Native Hash Lookup & Disambiguation:
- Identify direct native function calls and generic Citizen.InvokeNative(0xHASH, ...) invocations.
- Resolve 64-bit hexadecimal native hashes against a canonical native database (mapping hashes to readable C-like prototypes and names).
Export & Dependency Graphing:
- Index all public functions registered through exports declarations.
- Detect external resource consumption (exports['other_resource']:doSomething(...)) to generate an inter-resource dependency graph.

Acceptance Criteria

Automated detection and parsing of resource packages containing fxmanifest.lua or __resource.lua.
Clear partitioning and extraction of client, server, and shared scripts.
Bidirectional mapping of network events between client and server execution contexts.
Extraction of NUI webview assets and correlation of SendNUIMessage / RegisterNUICallback message flows.
Resolution of native hash invocations into human-readable native function prototypes.
Synthesis of an interactive architecture diagram depicting client, server, NUI, and external resource boundaries.

Complements #3684 (Microsoft WebView2 reverse engineering)
Complements #3685 (Chromium Embedded Framework reverse engineering)
Complements #3698 (Lua and LuaJIT bytecode reverse engineering)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3700 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Reverse Engineering](https://img.shields.io/badge/domain-reverse_engineering-blueviolet.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ### Problem Statement & Context Modern open-world multiplayer modifications and dedicated community frameworks structure extensions, gamemodes, and client/server add-ons into self-contained directory packages known as "resources". These resources run within a sandboxed runtime environment communicating across isolated client and server boundaries. Auditing or reverse engineering a resource package requires understanding its multi-environment architecture: 1. **Resource Manifest (`fxmanifest.lua` / legacy `__resource.lua`)**: Declares resource metadata (`fx_version`, `game`), dependencies, file declarations (`files { ... }`), and partitioned script execution environments: - `client_script` / `client_scripts`: Scripts executed locally within the client process sandbox. - `server_script` / `server_scripts`: Scripts executed on the dedicated server host. - `shared_script` / `shared_scripts`: Utility libraries and configurations shared across both contexts. 2. **NUI (Native User Interface) Webviews**: Embedded Chromium/CEF panels configured via `ui_page`, exchanging asynchronous web messages with client scripts via `SendNUIMessage` and `RegisterNUICallback`. 3. **Cross-Environment Network Events**: Bidirectional messaging using `RegisterNetEvent`, `TriggerServerEvent`, `TriggerClientEvent`, and `TriggerLatentServerEvent`. 4. **Export & Module Interfaces**: Public module functions registered via `exports('func_name', ...)` and consumed by third-party resources via `exports['res_name']:func_name()`. 5. **Native Hash Calls**: Invocations of platform engine functions identified either by uppercase string identifiers or 64-bit hexadecimal function hashes (`Citizen.InvokeNative`). REA lacks a dedicated package analyzer that ingests a resource folder or archive, correlates client/server/NUI boundaries, resolves native call tables, and models the complete interaction graph. ### Proposed Architecture ```mermaid flowchart TD A["Multiplayer Resource Directory / Archive"] --> B["Resource Package Analyzer"] B --> C["Manifest Parser & Environment Splitter"] B --> D["Client / Server Script Inspector"] B --> E["NUI Webview & IPC Bridge Analyzer"] B --> F["Native Hash & Export Resolver"] C --> C1["fxmanifest.lua / __resource.lua Declarations"] C --> C2["Dependencies & File Assets Mapping"] D --> D1["Client-Side Scripts (Lua, JS, C#)"] D --> D2["Server-Side Scripts (Lua, JS, C#)"] D --> D3["Network Events (TriggerServerEvent / TriggerClientEvent)"] E --> E1["ui_page HTML, CSS & JavaScript Bundles"] E --> E2["NUI IPC: SendNUIMessage & RegisterNUICallback"] F --> F1["Export Declarations & Cross-Resource Calls"] F --> F2["Citizen.InvokeNative Hash Resolution"] C & D & E & F --> G["Synthesized Resource Interaction Graph & Security Map"] ``` ### Technical Capabilities & Modules 1. **Manifest Parsing & Context Partitioning:** - Parse `fxmanifest.lua` and `__resource.lua` files. - Extract `fx_version`, `game` compatibility flags, declared dependencies, and data file definitions. - Categorize all files into client, server, shared, and UI asset domains. 2. **Network Event Flow Analysis:** - Detect event listener registrations (`RegisterNetEvent`, `AddEventHandler`). - Trace outbound event triggers: client-to-server (`TriggerServerEvent`) and server-to-client (`TriggerClientEvent`). - Extract exchanged event names and infer argument schemas passed across the network boundary. 3. **NUI Webview Interface Reconstruction:** - Resolve `ui_page` entrypoints and map referenced HTML, JavaScript, and stylesheet assets. - Extract messages sent from client Lua/JS to webview via `SendNUIMessage({ action = "...", data = ... })`. - Map NUI callbacks registered in client scripts (`RegisterNUICallback('action', handler)`) and correlate with webview `fetch("https://<resource>/action", ...)` calls. 4. **Native Hash Lookup & Disambiguation:** - Identify direct native function calls and generic `Citizen.InvokeNative(0xHASH, ...)` invocations. - Resolve 64-bit hexadecimal native hashes against a canonical native database (mapping hashes to readable C-like prototypes and names). 5. **Export & Dependency Graphing:** - Index all public functions registered through `exports` declarations. - Detect external resource consumption (`exports['other_resource']:doSomething(...)`) to generate an inter-resource dependency graph. ### Acceptance Criteria - [ ] Automated detection and parsing of resource packages containing `fxmanifest.lua` or `__resource.lua`. - [ ] Clear partitioning and extraction of client, server, and shared scripts. - [ ] Bidirectional mapping of network events between client and server execution contexts. - [ ] Extraction of NUI webview assets and correlation of `SendNUIMessage` / `RegisterNUICallback` message flows. - [ ] Resolution of native hash invocations into human-readable native function prototypes. - [ ] Synthesis of an interactive architecture diagram depicting client, server, NUI, and external resource boundaries. ### Related Issues & Dependencies - Complements #3684 (Microsoft WebView2 reverse engineering) - Complements #3685 (Chromium Embedded Framework reverse engineering) - Complements #3698 (Lua and LuaJIT bytecode reverse engineering)

bsakaguchi referenced this issue

2026-10-17 21:11:12 +00:00

[PR #1413] [MERGED] perf(cli): write compact JSON when output is not a terminal #2867

bsakaguchi referenced this issue

2026-10-31 00:38:54 +00:00

[GH-ISSUE #5435] [Bug] MCP doctor emits indented JSON when stdout is redirected #3297