Files
reverse-engineering-anything/docs/elf-dependencies.md
T
Matt Van Hornandgensokyo-dev e9c72dbd1f feat(elf): inspect dynamic dependencies and required symbol versions
Add offline ELF dependency, search-path, symbol-version and import inspection with retained Evidence summaries and pages. Bound GNU-hash work and preserve cancellation, stable identity and caller-selected parameters across CLI/MCP.

Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning)
Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2026-11-17 08:19:52 +00:00

114 lines
6.0 KiB
Markdown

# ELF dynamic dependencies
`inspect_elf_dependencies` / `inspect-elf-dependencies` answers which libraries
one selected local ELF32/ELF64 `ET_EXEC` or `ET_DYN` image declares it needs to
load, which search paths and interpreter it names, which GNU symbol versions it
requires, and which undefined `.dynsym` imports carry a `library@version` when
that join is known. It reads the file without executing it and does not invoke
the dynamic loader, `ldd`, or a disassembler.
```bash
rea inspect-elf-dependencies /absolute/path/to/program --json
```
The CLI resolves relative paths against the caller's working directory. MCP
requires an absolute filesystem path and preserves that exact selection:
```json
{
"name": "inspect_elf_dependencies",
"arguments": { "path": "/artifacts/program" }
}
```
The [feature specification](specs/native/elf-dependencies/spec.md),
[plan](specs/native/elf-dependencies/plan.md) and
[tasks](specs/native/elf-dependencies/tasks.md) record the requirements and
verification.
Relocatable objects are not this inventory; use `inspect_kernel_module` for
Linux kernel modules. Core dumps are not this inventory; use
`inspect_recorded_crash`.
## Observations
The inline Evidence result contains the artifact path, SHA-256, and byte length.
`needed[]` lists every `DT_NEEDED` string in dynamic-table order, including
duplicate names. `dynamic.soname` is the `DT_SONAME` string when that tag is
present. `dynamic.rpath` and `dynamic.runpath` keep the raw `DT_RPATH` /
`DT_RUNPATH` string, the `:`-split entries without dropping empties, and any
`$ORIGIN`, `$LIB`, or `$PLATFORM` tokens as written, including `${...}` forms.
Those tokens are not expanded against the host filesystem.
`dynamic.flags` and `dynamic.flags_1` decode `DT_FLAGS` and `DT_FLAGS_1` into
named bits (`BIND_NOW` / `NOW`, `ORIGIN`, `PIE`, `NODEFLIB`, and the other
documented `DF_*` / `DF_1_*` names). Unrecognized bits stay numeric.
`interpreter` is the `PT_INTERP` path when that program header is present.
`version_requirements` walks `.gnu.version_r` / `DT_VERNEED`: each needed file
and its required version names, hashes, weak flags, and version indices.
`derived_version_maxima` is a derived per-namespace maximum over GNU-style
`NAME_x.y` requirement strings (for example the highest `GLIBC_x.y`) and is
labelled `evidence_kind: "derived"`. Names that do not match that pattern stay
out of the derived set. `version_definitions` summarizes the image's own
`.gnu.version_d` names and the `VER_FLG_BASE` flag.
`imports[]` lists undefined `.dynsym` symbols. When `.gnu.version` is present,
each import keeps its version index, hidden bit, and a resolved
`library@version` when a matching verneed record exists. Index 0 and 1 stay
`unversioned`. A missing matching record is `unknown` and is an issue.
A missing `PT_DYNAMIC` is an observed empty load-time dependency inventory. It
is not proof another overlay or container carried dynamic linking metadata.
`DT_*` entries are the load-time facts. A section header is used for a table
only when it names the same address, maps to the same file bytes, and agrees
on any declared size or entry width; a disagreeing section is reported as an
issue and the `DT_*` declaration is used. When section headers are stripped,
tables are located from `PT_DYNAMIC` and `DT_*` virtual addresses through
`PT_LOAD`. Coverage is `partial` when a table
cannot be located or a string cannot be read. Complete coverage never retains
issues.
## Limits and failures
The selected file is limited to 64 MiB by default (512 MiB maximum). At most
1024 `DT_NEEDED` entries, 4096 GNU version records, and 65536 undefined
dynamic symbols are examined by default (65536 / 65536 / 262144 maximum).
Omitted budgets use these defaults during analysis and stay omitted in
Evidence parameters. Explicitly selecting a default value records that choice.
GNU hash decoding has a fixed allowance of 262144 bucket, bloom, or symbol
entries per table component; it yields between bounded steps so cancellation
can stop the walk. This work allowance has no runtime override.
Exceeding a named budget fails with no partial success. Decoded dynamic
strings share one scan and retained-text budget fixed by the admitted image
length, so names repeated by many rows cannot expand past the input size; this
budget has no runtime override. A failure after the file was read keeps its
path, SHA-256, and byte count as a partial observation. Cyclic `vn_next` /
`vna_next` chains, duplicate unique dynamic tags, malformed ELF headers, and
unsupported ELF extended numbering return no complete inventory.
Each dynamic string and `PT_INTERP` path is scanned for its terminator across at
most 65536 bytes. Unreadable dynamic strings, `PT_INTERP` paths that are
unterminated or end past that limit, and tables that cannot be located from
section headers or `DT_*` tags are reported as partial coverage with `issues`.
When the symbol count from `DT_HASH` or `DT_GNU_HASH` exceeds the located
`.dynsym` table, only the symbols inside that table are read and coverage is
partial. A GNU version chain whose links and declared count
disagree keeps the records read before the conflict, marks that table
`unreadable`, and reports partial coverage. `$ORIGIN`, `$LIB`, and `$PLATFORM` remain unexpanded.
Derived version maxima do not establish ABI compatibility.
Omitted or `complete` detail returns the inventory inline. `detail: "summary"`
retains the complete Evidence and returns identity, counts, and source
coverage. Query `inspect_analysis_view` with `kind: "elf-dependencies"` and
collection `needed`, `versions`, `definitions`, `maxima`, or `imports`, using
exact names (namespaces for `maxima`) or original indices, selected fields, and
matching-row pagination. Collection `issues` accepts original indices and
pagination only; its rows are returned whole and have no name filter. Summaries and pages report
version-definition and derived-maximum counts; those rows are paged through
their own collections. CLI summary
requires `--evidence_output`.
This workflow does not execute the image, invoke the dynamic loader, or resolve
`DT_NEEDED` paths against the host filesystem.