Files
reverse-engineering-anything/docs/specs/native/elf-dependencies/spec.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

83 lines
4.4 KiB
Markdown

# ELF dynamic dependencies
## Problem and outcome
An agent looking at a Linux program often needs to know what it loads before
it runs: the libraries it names, the paths it searches, its interpreter and the
GNU symbol versions it requires. Today that means `ldd`, which invokes the
dynamic loader, or `readelf`, which is not always installed and is not
Evidence.
This feature adds `inspect_elf_dependencies` and `inspect-elf-dependencies`.
They read the load-time dynamic-dependency inventory of one selected local
ELF32 or ELF64 `ET_EXEC` or `ET_DYN` image, without executing it, invoking the
dynamic loader or opening a disassembler.
[ELF dynamic dependencies](../../../elf-dependencies.md) describes the current
behavior and limitations. This directory is the feature specification,
implementation plan and task list. The guide does not replace these files.
## Requirements
1. `needed[]` lists every `DT_NEEDED` string in dynamic-table order, keeping
duplicates. `DT_SONAME`, `DT_RPATH` and `DT_RUNPATH` are reported as
written, with `:`-split entries that keep empties and `$ORIGIN`, `$LIB` and
`$PLATFORM` tokens unexpanded, including `${...}` forms.
2. `DT_FLAGS` and `DT_FLAGS_1` decode into named `DF_*` and `DF_1_*` bits;
unrecognized bits stay numeric. `PT_INTERP` is reported when present.
3. `version_requirements` walks `.gnu.version_r` / `DT_VERNEED` with each
needed file's version names, hashes, weak flags and indices.
`version_definitions` summarizes `.gnu.version_d` and `VER_FLG_BASE`.
4. `derived_version_maxima` takes the highest `NAME_x.y` requirement per
namespace and is labelled `evidence_kind: "derived"`. Names outside that
pattern stay out of the derived set, and maxima do not establish ABI
compatibility.
5. `imports[]` lists undefined `.dynsym` symbols. With `.gnu.version`, each
keeps its version index, hidden bit and a resolved `library@version` when a
matching verneed record exists. Indices 0 and 1 are `unversioned`; a
missing record is `unknown` and an issue.
6. `DT_*` entries are the load-time facts. A section header is used for a
table only when it agrees with the `DT_*` address, file bytes, size and
entry width; a disagreeing section is an issue and the `DT_*` declaration
is used. Without section headers, tables are located from `PT_DYNAMIC` and
`DT_*` addresses through `PT_LOAD`.
7. A missing `PT_DYNAMIC` is an observed empty inventory. A table that cannot
be located, an unreadable string, an unterminated `PT_INTERP`, a hash-table
symbol count past the located `.dynsym`, or a GNU version chain whose links
and count disagree make coverage `partial` with issues. Complete coverage
never retains issues.
8. Budgets bound the file size (64 MiB default, 512 MiB maximum), `DT_NEEDED`
entries, GNU version records and undefined dynamic symbols, and each string
scan to 65536 bytes. Decoded strings share one scan and retained-text budget
fixed by the admitted image length. Exceeding a named budget fails with no
partial success. Cyclic version chains, duplicate unique dynamic tags,
malformed headers and unsupported extended numbering return no complete
inventory.
9. `detail: "summary"` retains the complete Evidence and returns identity,
counts and coverage. `inspect_analysis_view` with `kind:
"elf-dependencies"` pages `needed`, `versions`, `definitions`, `maxima`,
`imports` and `issues`. CLI summary requires `--evidence_output`.
10. Library, symbol and version names are target-derived and untrusted. MCP
requires an absolute path; the CLI resolves relative paths against the
caller's working directory.
## Acceptance
- Parser unit tests cover both widths and endiannesses, duplicate needed
names, search-path tokens, flag decoding, verneed and verdef walks, import
version joins, stripped section headers, disagreeing sections, budgets and
partial coverage.
- Domain and service tests validate the report shape and the derived maxima.
- View tests and application acceptance tests cover summary delivery and the
`inspect_analysis_view` collections.
- CLI acceptance, filesystem boundary and MCP boundary tests exercise the
public contract.
## Non-goals
- Resolving `DT_NEEDED` names or expanding search-path tokens against the
host filesystem.
- Invoking the dynamic loader or `ldd`, or executing the image.
- Relocatable objects and core dumps, which `inspect_kernel_module` and
`inspect_recorded_crash` cover.