Quick start

Start with a local ELF

Open the checked-in PRISM ELF for a tour of the workbench, or use the smaller max2 fixture for a focused CLI walkthrough. Analysis reads the ELF locally; execution comparisons are separate, explicit operations.

Prerequisites#

Clone the repository with its submodules. Rust 1.96 is pinned by rust-toolchain.toml, and Cargo.lock fixes Rust dependencies. The managed Ghidra path provisions a pinned container image; developers can use HYDIR_GHIDRA_HOME with a local Ghidra 12.1.4 installation. Native execution comparisons require Linux x86-64.

cargo run --locked --bin hydirctl -- doctor

doctor reports the relevant local setup before you begin. You can inspect the checked-in ELF on Windows; native execution and whole-executable rebuild use Linux x86-64.

Open the workbench#

cargo run --locked --bin hydir -- \
  --open-local demo/hydir-prism.elf hydir_stage_decision

The overview inventories the program and shows pipeline status. Select hydir_stage_decision to inspect a branch, hydir_stage_call_chain for a direct call, or hydir_stage_loop_sum for a loop. Select a function, then use the disassembly and CFG views to orient yourself before opening P-code, IR, or C output.

Opening an ELF starts bounded analysis. It does not run the input. A generated C view may still contain opaque operations or unresolved control flow; read its diagnostics and fidelity claim.

CLI tour#

Run the native workflow on the same showcase. discover returns function candidates and stable IDs, including entries without usable names. lift requests one IR stage; decompile requests a unit with C views and diagnostics.

cargo run --locked --bin hydirctl -- discover demo/hydir-prism.elf
cargo run --locked --bin hydirctl -- lift demo/hydir-prism.elf \
  --function hydir_stage_decision --ir state
cargo run --locked --bin hydirctl -- decompile demo/hydir-prism.elf \
  --function hydir_stage_decision --view unit

The artifact reference maps each IR to its purpose. The older scalar LLVM compatibility path uses an explicit --assume-u64x2 assertion for a restricted function; that prototype is supplied by the analyst.

Inspect the Ghidra path#

The GUI starts managed Ghidra analysis when opening a local ELF. The CLI can save and verify a raw P-code snapshot bound to the ELF, then report which operations the modeled subset covers.

cargo run --locked -p hydir-cli -- ghidra analyze demo/hydir-prism.elf \
  --output target/prism-ghidra.json --function 0x20137c
cargo run --locked -p hydir-cli -- ghidra-snapshot verify \
  demo/hydir-prism.elf target/prism-ghidra.json
cargo run --locked -p hydir-cli -- ghidra-snapshot coverage \
  demo/hydir-prism.elf target/prism-ghidra.json

Coverage describes the selected snapshot and modeled operations. It is not a whole-program equivalence result. The architecture guide shows how this Ghidra lane relates to native IR and output generation.

Start a Frida session#

Open an argv- or file-driven local ELF, select an analyzed function, and choose Frida → Session. Enter one argument per line and select Observe selected function after readiness checks complete. An InputSpec file is optional for custom limits and file inputs. Events open after a successful observation.

For the Windows release, install WSL2 separately, retain the bundled workers/frida files, and use Recheck runtime → Install packaged worker. A source checkout needs a generated worker bundle. See the Frida setup guide.

The interactive PRISM demo needs stdin, which Frida currently rejects. Use it for static analysis and choose an argv/file fixture for observation. Native replay and GDB capture have separate Linux requirements.

Read results and reproduce a comparison#

Read the source location, diagnostics, and coverage with each artifact. A successful import can be followed by a stopped lift when an operation, memory effect, or control target is outside the supported model. HydIR records that boundary rather than silently treating it as recovered.

For a reproducible first run on Linux x86-64, use the checked-in demo scripts. They build controlled inputs, save artifacts under target/, and compare finite cases with native execution.

bash scripts/demo-local.sh
bash scripts/demo-corpus.sh

The validation path executes its original fixture and requires --trusted-fixture. Use these scripts only with the repository's trusted samples. The compiler theory article explains how HydIR represents function control flow.

Further reference#

Continue with the guide map, the detailed first-run guide, or the Python SDK reference for local and authenticated service clients.