Documentation / Guide map

Choose a workflow, then follow its evidence

HydIR connects an ELF to source-linked program facts, intermediate representations, and generated artifacts. This guide maps the major workflows and explains what a result establishes.

On-site guides and technical manuals#

Start with a workflow, then use its reference for commands, artifact contracts, and explicit boundaries.

Start and inspect

• First run and the PRISM showcaseDesktop and CLI first run, automatic Ghidra analysis, call traces, stripped inputs, LLVM variants, and PRISM functions.
• Desktop workbench and local projectsFunction navigation, disassembly, IR and C views, analyst facts, local persistence, and explicit remote upload.
• Native analysis: ELF to CFunction discovery, machine effects, SSA, ABI recovery, C views, coverage, and batch output.
• Ghidra snapshots and executionRaw P-code snapshots, managed projects, seed validation, concrete paths, LLVM state ABI, and independent execution oracles.

Types and transformation

• Typed models and analyst evidenceCreate, import, infer, verify, and save digest-bound analysis models; inspect typed C locally and remotely.
• Scalar lifting and validationThe asserted scalar prototype, supported stack and call subset, region boundaries, and fixture comparisons.
• Transformation, patching, and region contractsLLVM experiments, scalar replacement, PatchBundle checks, freestanding rebuilds, protobuf interchange, and physical region boundaries.

Runtime and exploration

• Frida observation on WindowsWSL2 worker installation, argv and file sessions, isolation checks, source builds, packaging, and execution verification.
• Replay and captured-state investigationInputSpec, replay reports, GDB capture, origin probes, bounded return solving, and reproducible investigation recipes.
• Symbolic exploration with TritonOptional runtime setup, symbolic expressions, path conditions, candidate models, and desktop exploration.
• VM profiles and host/VPC explorationAnalyst-scoped VM facts, profile validation, virtual-PC-sensitive node identities, effect declarations, and explicit graph limits.

Automation and remote projects

• Python SDK and artifact APIsLocalGhidra and HydirClient examples, allocated memory, call tracing, observed-path comparison, typed models, and remote artifacts.
• Authenticated service and project lifecycleImmutable uploads, v3 jobs, artifact retrieval, revision checks, role-based authorization, TLS, and content storage.

Desktop workbench#

Open a local little-endian x86-64 ELF in the hydir app. The overview shows the program inventory and analysis status. Select a function to connect its machine address and bytes to disassembly, control flow, P-code effects, and generated views. The Ghidra worker starts automatically for local ELF analysis and its project is cached for later selections.

1. Pick a function. The checked-in demo/hydir-prism.elf includes named entry points. hydir_stage_decision shows branching control flow; hydir_stage_call_chain shows a direct call.
2. Inspect the evidence. Read the instruction and CFG views before interpreting a generated representation. A recovered function boundary or edge carries evidence and may still have unresolved targets.
3. Compare outputs. Open the available IR and C views and read diagnostics alongside them. A C rendering can preserve unknown effects explicitly without proving that it can be safely rewritten.

The Ghidra P-code article explains the imported operations behind one x86 instruction. For the native pipeline's control flow and SSA, see From Graphs to Code.

Observe a selected function with Frida#

Open a local ELF and select an analyzed function, then choose Frida → Session. Enter one program argument per line, or leave the editor empty. Use Observe selected function when analysis and runtime checks finish; successful observations open Events. Choose InputSpec file for file inputs or custom limits.

On Windows, install WSL2 separately and keep the release's workers/frida directory beside the executables. In Session, choose Recheck runtime then Install packaged worker. Source builds require a generated worker bundle; WSL2 alone is insufficient.

Observation and replay features · Setup, packaging, and diagnostics

Command line#

hydirctl makes the same analysis useful in scripts. Start with doctor to check the local toolchain, use discover to enumerate function candidates, and request a specific stage with lift or a C view with decompile. Ghidra commands can save a binary-bound snapshot for later verification and coverage inspection.

cargo run --locked --bin hydirctl -- doctor
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 native analysis guide lists stage contracts, limits, supported instruction families, and reproduction commands. The Python SDK reference covers local Ghidra operations and authenticated service workflows.

Artifact reference#

Read the result#

Look for separate structural, semantic, verification, and rewrite-readiness claims. partial control-flow recovery means some edges remain unresolved. unknown or conservative semantics mean the representation retains uncertainty. not_run verification means no execution comparison has been made. Exactness is relative to the recorded machine and environment model.

For the distinction between native C generation and the restricted scalar LLVM path, read the architecture guide. The compiler-theory article explains why control-flow joins, memory effects, and SSA matter to both paths.

More workflows#

Browse the full feature inventory for typed analysis models, DWARF import, call tracing, slices, replay and recipes, patch bundles, region interchange, and saved projects. The tools reference indexes all first-party documentation, and maps evidence and release gates.

Next steps#