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>
4.4 KiB
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 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
needed[]lists everyDT_NEEDEDstring in dynamic-table order, keeping duplicates.DT_SONAME,DT_RPATHandDT_RUNPATHare reported as written, with:-split entries that keep empties and$ORIGIN,$LIBand$PLATFORMtokens unexpanded, including${...}forms.DT_FLAGSandDT_FLAGS_1decode into namedDF_*andDF_1_*bits; unrecognized bits stay numeric.PT_INTERPis reported when present.version_requirementswalks.gnu.version_r/DT_VERNEEDwith each needed file's version names, hashes, weak flags and indices.version_definitionssummarizes.gnu.version_dandVER_FLG_BASE.derived_version_maximatakes the highestNAME_x.yrequirement per namespace and is labelledevidence_kind: "derived". Names outside that pattern stay out of the derived set, and maxima do not establish ABI compatibility.imports[]lists undefined.dynsymsymbols. With.gnu.version, each keeps its version index, hidden bit and a resolvedlibrary@versionwhen a matching verneed record exists. Indices 0 and 1 areunversioned; a missing record isunknownand an issue.DT_*entries are the load-time facts. A section header is used for a table only when it agrees with theDT_*address, file bytes, size and entry width; a disagreeing section is an issue and theDT_*declaration is used. Without section headers, tables are located fromPT_DYNAMICandDT_*addresses throughPT_LOAD.- A missing
PT_DYNAMICis an observed empty inventory. A table that cannot be located, an unreadable string, an unterminatedPT_INTERP, a hash-table symbol count past the located.dynsym, or a GNU version chain whose links and count disagree make coveragepartialwith issues. Complete coverage never retains issues. - Budgets bound the file size (64 MiB default, 512 MiB maximum),
DT_NEEDEDentries, 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. detail: "summary"retains the complete Evidence and returns identity, counts and coverage.inspect_analysis_viewwithkind: "elf-dependencies"pagesneeded,versions,definitions,maxima,importsandissues. CLI summary requires--evidence_output.- 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_viewcollections. - CLI acceptance, filesystem boundary and MCP boundary tests exercise the public contract.
Non-goals
- Resolving
DT_NEEDEDnames 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_moduleandinspect_recorded_crashcover.