morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #4868] feat(objdump): add dynamic section facets for stripped binaries #6449

New issue

Open

opened 2026-10-31 01:14:32 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:14:32 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4868
Author: @BANTAM-ADMIN
Created: 10/17/2026
Status: 🔄 Open

Base: main ← Head: feat/objdump-dynamic-facets

📝 Commits (1)

fadac18 feat(objdump): add dynamic section facets for stripped binaries

📊 Changes

6 files changed (+83 additions, -19 deletions)

View changed files

📝 docs/reverse-engineering-tools.md (+1 -1)
📝 src/cli/reverseEngineeringCommands.ts (+2 -9)
📝 src/domain/reverseEngineering.ts (+20 -9)
📝 src/objdump/ObjdumpCommand.ts (+3 -0)
➕ tests/boundary/providers/objdumpDynamicFacets.test.ts (+39 -0)
➕ tests/composition/objdumpDynamicFacets.test.ts (+18 -0)

📄 Description

Summary

inspect_with_objdump can read an artifact's static symbol table (symbols, -t) and static relocations (relocations, -r), but not its dynamic section. Stripped executables, which are most shipped Linux binaries, keep only the dynamic section. So on a stripped ELF, REA cannot say which shared libraries the binary needs or which functions it imports unless the pwntools-backed inspect_binary_layout provider is configured.

This PR adds three objdump facets that read the dynamic section:

operation	objdump option	answers
`private_headers`	`-p`	program headers and dynamic section, including `NEEDED` libraries
`dynamic_symbols`	`-T`	imported/exported dynamic symbols
`dynamic_relocations`	`-R`	dynamic relocation records (PLT/GOT imports)

Problem and expected behavior

Smallest trigger: inspect_with_objdump on /bin/true (stripped, dynamically linked x86-64 ELF).

Before: symbols returns no symbols and relocations returns no entries. No allowed operation exposes libc.so.6 or the imported functions.
After: private_headers returns NEEDED libc.so.6, and dynamic_symbols / dynamic_relocations list the imports.

We found this while connecting an agent harness to REA. The agent correctly concluded it could not identify a stripped binary's libraries or imports, because the only tool that could (inspect_binary_layout) needed pwntools, which wasn't installed.

Change and scope

src/domain/reverseEngineering.ts: one exported OBJDUMP_ARTIFACT_OPERATIONS list now owns the artifact operations, with the three new facets added.
src/objdump/ObjdumpCommand.ts: maps the facets to -p, -T and -R. The satisfies Record<…> keeps the mapping exhaustive.
src/cli/reverseEngineeringCommands.ts: the CLI enum now uses the shared domain list instead of keeping a second hand-written copy, which would otherwise have needed the same edit.
docs/reverse-engineering-tools.md: documents the new operations and when to prefer them.

Out of scope: no parsing or normalization of the new output. As with the existing facets, the raw objdump output is authoritative. This is an ordinary extension within an existing boundary: read-only, same provider, same argv construction, same Evidence path. No scope decision is needed.

Contract and boundary impact

Semantic owner and earliest changed stage: domain operation enum (OBJDUMP_ARTIFACT_OPERATIONS), consumed by the objdump argv builder, MCP input schema and CLI.
Contribution scope fit and linked maintainer decision: fits an existing tool; not applicable.
CLI and MCP/tool-catalog contract: additive. Three new enum values for operation in inspect_with_objdump / rea inspect-with-objdump; existing values are unchanged.
Provider, bridge, target-format, or platform compatibility: GNU objdump -p, -T and -R are long-standing options. On a non-dynamic artifact, objdump reports that itself (raw output, as for the other facets).
Evidence, artifact, provenance, or reconstruction contract: unchanged. Same artifact digest before and after, same output limits.
Target selection, authority, upstream behavior, and cleanup details: unchanged.
Generated metadata, package, or installation impact: none committed. npm run docs:check passes.

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated:
- tests/composition/objdumpDynamicFacets.test.ts: each facet maps to its objdump option through the published input schema.
- tests/boundary/providers/objdumpDynamicFacets.test.ts: runs the real system objdump on /bin/true through createReverseEngineeringService and checks for NEEDED libc.so, DYNAMIC SYMBOL TABLE and DYNAMIC RELOCATION RECORDS. Skipped when the host is not Linux, objdump is missing, or /bin/true is absent.
Base reproduction: with src/ and docs/ reverted to the base revision, both new tests fail. The schema rejects the new operations.
User-visible CLI output (built from this branch):
```
$ rea inspect-with-objdump /bin/true private_headers --json
… "NEEDED               libc.so.6" …
```
An MCP inspect_with_objdump call with dynamic_symbols on a stripped gzip returns its imports (getopt_long, open, read, write, unlink, malloc, …).
Remaining proof gaps: the real-provider test was verified on Linux x86-64 with GNU binutils only. Not checked on macOS or Windows objdump builds, or on non-ELF formats.

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npx tsc --noEmit: passed.
npx oxfmt --check and npx oxlint on the changed files: format clean, no new lint findings. The three existing warnings in the touched files are also present on the base revision.
npx vitest run tests/composition/objdumpDynamicFacets.test.ts tests/boundary/providers/objdumpDynamicFacets.test.ts tests/composition/reverseEngineeringEdgeCases.test.ts tests/boundary/cli/reverseEngineeringCommands.test.ts tests/boundary/mcp/reverseEngineeringPartialMcp.test.ts: 91 passed. The real-objdump test ran and was not skipped.
npx vitest run --project conformance: 264 passed.
npm run docs:check: passed.
npm run compile, then rea inspect-with-objdump /bin/true private_headers --json: output contains NEEDED libc.so.6.
Pre-commit (oxfmt, oxlint) and pre-push (check:fast) hooks: passed.

Compatibility, safety, and release

Breaking changes or migration steps: none. Additive enum values only.
Real Hopper/Ghidra, browser, or OS coverage: GNU objdump on Linux x86-64 only.
Package or release metadata impact: none.
Security, privacy, process, or containment review: same objdump child-process path and limits as the existing facets. Read-only.

Author readiness

Human owner:

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4868 **Author:** [@BANTAM-ADMIN](https://github.com/BANTAM-ADMIN) **Created:** 10/17/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `feat/objdump-dynamic-facets` --- ### 📝 Commits (1) - [`fadac18`](https://github.com/morluto/rea/commit/fadac1851b55e7f07958a7493b787647b10b5c76) feat(objdump): add dynamic section facets for stripped binaries ### 📊 Changes **6 files changed** (+83 additions, -19 deletions) <details> <summary>View changed files</summary> 📝 `docs/reverse-engineering-tools.md` (+1 -1) 📝 `src/cli/reverseEngineeringCommands.ts` (+2 -9) 📝 `src/domain/reverseEngineering.ts` (+20 -9) 📝 `src/objdump/ObjdumpCommand.ts` (+3 -0) ➕ `tests/boundary/providers/objdumpDynamicFacets.test.ts` (+39 -0) ➕ `tests/composition/objdumpDynamicFacets.test.ts` (+18 -0) </details> ### 📄 Description ## Summary `inspect_with_objdump` can read an artifact's static symbol table (`symbols`, `-t`) and static relocations (`relocations`, `-r`), but not its dynamic section. Stripped executables, which are most shipped Linux binaries, keep only the dynamic section. So on a stripped ELF, REA cannot say which shared libraries the binary needs or which functions it imports unless the pwntools-backed `inspect_binary_layout` provider is configured. This PR adds three objdump facets that read the dynamic section: | operation | objdump option | answers | |---|---|---| | `private_headers` | `-p` | program headers and dynamic section, including `NEEDED` libraries | | `dynamic_symbols` | `-T` | imported/exported dynamic symbols | | `dynamic_relocations` | `-R` | dynamic relocation records (PLT/GOT imports) | ## Problem and expected behavior Smallest trigger: `inspect_with_objdump` on `/bin/true` (stripped, dynamically linked x86-64 ELF). - Before: `symbols` returns `no symbols` and `relocations` returns no entries. No allowed operation exposes `libc.so.6` or the imported functions. - After: `private_headers` returns `NEEDED libc.so.6`, and `dynamic_symbols` / `dynamic_relocations` list the imports. We found this while connecting an agent harness to REA. The agent correctly concluded it could not identify a stripped binary's libraries or imports, because the only tool that could (`inspect_binary_layout`) needed pwntools, which wasn't installed. ## Change and scope - `src/domain/reverseEngineering.ts`: one exported `OBJDUMP_ARTIFACT_OPERATIONS` list now owns the artifact operations, with the three new facets added. - `src/objdump/ObjdumpCommand.ts`: maps the facets to `-p`, `-T` and `-R`. The `satisfies Record<…>` keeps the mapping exhaustive. - `src/cli/reverseEngineeringCommands.ts`: the CLI enum now uses the shared domain list instead of keeping a second hand-written copy, which would otherwise have needed the same edit. - `docs/reverse-engineering-tools.md`: documents the new operations and when to prefer them. Out of scope: no parsing or normalization of the new output. As with the existing facets, the raw objdump output is authoritative. This is an ordinary extension within an existing boundary: read-only, same provider, same argv construction, same Evidence path. No scope decision is needed. ## Contract and boundary impact - Semantic owner and earliest changed stage: domain operation enum (`OBJDUMP_ARTIFACT_OPERATIONS`), consumed by the objdump argv builder, MCP input schema and CLI. - Contribution scope fit and linked maintainer decision: fits an existing tool; not applicable. - CLI and MCP/tool-catalog contract: additive. Three new enum values for `operation` in `inspect_with_objdump` / `rea inspect-with-objdump`; existing values are unchanged. - Provider, bridge, target-format, or platform compatibility: GNU objdump `-p`, `-T` and `-R` are long-standing options. On a non-dynamic artifact, objdump reports that itself (raw output, as for the other facets). - Evidence, artifact, provenance, or reconstruction contract: unchanged. Same artifact digest before and after, same output limits. - Target selection, authority, upstream behavior, and cleanup details: unchanged. - Generated metadata, package, or installation impact: none committed. `npm run docs:check` passes. Expected effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: - `tests/composition/objdumpDynamicFacets.test.ts`: each facet maps to its objdump option through the published input schema. - `tests/boundary/providers/objdumpDynamicFacets.test.ts`: runs the real system objdump on `/bin/true` through `createReverseEngineeringService` and checks for `NEEDED libc.so`, `DYNAMIC SYMBOL TABLE` and `DYNAMIC RELOCATION RECORDS`. Skipped when the host is not Linux, objdump is missing, or `/bin/true` is absent. - Base reproduction: with `src/` and `docs/` reverted to the base revision, both new tests fail. The schema rejects the new operations. - User-visible CLI output (built from this branch): ``` $ rea inspect-with-objdump /bin/true private_headers --json … "NEEDED libc.so.6" … ``` An MCP `inspect_with_objdump` call with `dynamic_symbols` on a stripped `gzip` returns its imports (`getopt_long`, `open`, `read`, `write`, `unlink`, `malloc`, …). - Remaining proof gaps: the real-provider test was verified on Linux x86-64 with GNU binutils only. Not checked on macOS or Windows objdump builds, or on non-ELF formats. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npx tsc --noEmit`: passed. - `npx oxfmt --check` and `npx oxlint` on the changed files: format clean, no new lint findings. The three existing warnings in the touched files are also present on the base revision. - `npx vitest run tests/composition/objdumpDynamicFacets.test.ts tests/boundary/providers/objdumpDynamicFacets.test.ts tests/composition/reverseEngineeringEdgeCases.test.ts tests/boundary/cli/reverseEngineeringCommands.test.ts tests/boundary/mcp/reverseEngineeringPartialMcp.test.ts`: 91 passed. The real-objdump test ran and was not skipped. - `npx vitest run --project conformance`: 264 passed. - `npm run docs:check`: passed. - `npm run compile`, then `rea inspect-with-objdump /bin/true private_headers --json`: output contains `NEEDED libc.so.6`. - Pre-commit (oxfmt, oxlint) and pre-push (`check:fast`) hooks: passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. Additive enum values only. - Real Hopper/Ghidra, browser, or OS coverage: GNU objdump on Linux x86-64 only. - Package or release metadata impact: none. - Security, privacy, process, or containment review: same objdump child-process path and limits as the existing facets. Read-only. ## Author readiness Human owner:  - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-31 01:14:32 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#6449

No description provided.

Rows
Columns