morluto/rea

Fork 0

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

[PR #7010] [MERGED] feat(elf): inspect Linux kernel module metadata #7572

New issue

Closed

opened 2026-11-03 13:38:48 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:38:48 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7010
Author: @mvanhorn
Created: 10/24/2026
Status: ✅ Merged
Merged: 10/24/2026
Merged by: @morluto

Base: main ← Head: fix/kernel-module-modinfo

📝 Commits (4)

2cb558d feat(elf): inspect Linux kernel module metadata
c2e73da fix(elf): bound kernel module ksymtab listing and tighten contracts
2d07520 Merge main into kernel module inspection
51e4301 fix: resolve merge integration errors

📊 Changes

57 files changed (+3160 additions, -14 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+10 -0)
📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+19 -0)
📝 README.md (+1 -0)
📝 docs/.vitepress/config.ts (+1 -0)
📝 docs/cli.md (+16 -0)
📝 docs/index.md (+14 -13)
➕ docs/kernel-modules.md (+163 -0)
📝 docs/readme/README_ar.md (+1 -0)
📝 docs/readme/README_de.md (+1 -0)
📝 docs/readme/README_el.md (+1 -0)
📝 docs/readme/README_es.md (+1 -0)
📝 docs/readme/README_fa.md (+1 -0)
📝 docs/readme/README_fr.md (+1 -0)
📝 docs/readme/README_id.md (+1 -0)
📝 docs/readme/README_it.md (+1 -0)
📝 docs/readme/README_ja.md (+1 -0)
📝 docs/readme/README_ko.md (+1 -0)
📝 docs/readme/README_ml.md (+1 -0)
📝 docs/readme/README_pl.md (+1 -0)
📝 docs/readme/README_pt-BR.md (+1 -0)

...and 37 more files

📄 Description

Summary

Linux kernel modules (.ko) carry their identity in ELF sections: .modinfo key/value strings, __versions symbol CRCs, and an appended PKCS#7 signature trailer. REA admits relocatable ELF but had no static reader for this metadata. This adds inspect-kernel-module (CLI) and inspect_kernel_module (MCP) for ELF32/ELF64 ET_REL modules, read without loading the module or opening a disassembler. No related issue; this is a new static inspection within existing native authority.

Problem and expected behavior

An analyst triaging a driver today needs modinfo, readelf and a separate signature script. Expected: REA reports ordered .modinfo entries with duplicates preserved (alias, softdep, parm), __versions CRCs, presence of .gnu.linkonce.this_module and __ksymtab, .init.text/.exit.text sizes, and the signature trailer's module_signature fields with the PKCS#7 byte range and SHA-256.

Change and scope

src/native/elf/KernelModuleParser.ts reads section headers through the shared ELF reader, decodes .modinfo and __versions for both word sizes and byte orders, and parses the ~Module signature appended~ trailer. A missing section is observed absence when section names are known.

gzip, xz and zstd containers are reported unsupported with external_decompression as the next probe; neither this tool nor extract_artifact decodes those codecs. Malformed headers and exhausted entry budgets return no partial success. Not included: decoding struct module, validating the signature or certificate chain. AI was used for assistance.

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".
Draft PRs may leave the scope decision pending and the readiness and merge checklists
unchecked. Maintainers can help resolve open questions.

Contract and boundary impact

Semantic owner and earliest changed stage: native ELF inspection (src/native/elf/) and the binary diagnostics service.
Contribution scope fit and linked maintainer decision: static format inspection of a local file within existing native authority; separate scope decision not applicable.
CLI and MCP/tool-catalog contract: new inspect-kernel-module command and inspect_kernel_module tool.
Provider, bridge, target-format, or platform compatibility: portable TypeScript, no provider; runs on any supported Node host.
Evidence, artifact, provenance, or reconstruction contract: Evidence carries artifact SHA-256, section locations and hashes, and the signature byte range.
Target selection, authority, upstream behavior, and cleanup details (if applicable): unchanged; reads a stable regular file.
Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): catalog builder entry, a capability row in each translated README (as in #6509), and authored skill guidance in .agents/skills/reverse-engineer-anything/. No committed build outputs.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

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: src/native/elf/KernelModuleParser.test.ts (ELF32/ELF64, both byte orders, duplicate keys, __versions layouts, signature trailers, compressed containers, truncation and budgets), kernelModule.test.ts, KernelModuleService.test.ts, BinaryDiagnosticsCancellation.test.ts, tests/acceptance/kernelModuleCli.test.ts, tests/boundary/mcp/kernelModuleMcp.test.ts, tests/boundary/filesystem/kernelModule.test.ts, and the shared path-admission, tool-contract and stable-artifact lists. Fixtures are synthetic; no binaries are committed.
Base reproduction or other evidence: the released CLI has no kernel module reader. Executed against Debian 13 arm64 vfat.ko and btrfs.ko (not committed) and compared with modinfo output.
User-visible CLI/MCP output (if applicable): see below.
Remaining proof gaps: ELF32 and big-endian modules were exercised with synthetic fixtures only. Signatures are located and hashed, not verified.

$ rea inspect-kernel-module vfat.ko --json | jq ...
modinfo: 8 entries   versions: 68 CRCs   this_module: present
signature: PKCS#7  sig_len 263

$ rea inspect-kernel-module btrfs.ko --json | jq ...
modinfo: 13 entries (duplicate softdep and alias preserved)   versions: 575 CRCs

$ rea inspect-kernel-module vfat.ko.xz --json | jq ...
applicability: unsupported   compression: xz
next_probe: external_decompression

modinfo vfat.ko and modinfo btrfs.ko list the same keys and values in the same order.

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

Head 2cb558d21 on main d361c53c5; macOS arm64, Node 26.5.0, npm 12.2.0:

npx --no-install vitest run src/application/binaryDiagnostics/BinaryDiagnosticsCancellation.test.ts src/application/binaryDiagnostics/KernelModuleService.test.ts src/contracts/toolEffects.test.ts src/domain/native/kernelModule.test.ts src/native/elf/KernelModuleParser.test.ts tests/acceptance/kernelModuleCli.test.ts tests/acceptance/localPathAdmissionCli.test.ts tests/acceptance/tools/localToolContracts.test.ts tests/boundary/filesystem/kernelModule.test.ts tests/boundary/mcp/kernelModuleMcp.test.ts tests/process-global/stableArtifactConsumers.test.ts - passed.
Real Debian 13 vfat.ko, btrfs.ko and vfat.ko.xz inspected as shown above.

Compatibility, safety, and release

Breaking changes or migration steps: none; new command and tool only.
Real Hopper/Ghidra, browser, or OS coverage: macOS arm64 with Linux arm64 module inputs; no provider involved.
Package or release metadata impact: none beyond the generated catalogs.
Security, privacy, process, or containment review: the module is never loaded; reads are bounded and malformed input fails closed.

Author readiness

Human owner: @mvanhorn

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.

Demo

_{🔄 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/7010 **Author:** [@mvanhorn](https://github.com/mvanhorn) **Created:** 10/24/2026 **Status:** ✅ Merged **Merged:** 10/24/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `fix/kernel-module-modinfo` --- ### 📝 Commits (4) - [`2cb558d`](https://github.com/morluto/rea/commit/2cb558d210606891102c2cb5fdb751bda1e6e2fb) feat(elf): inspect Linux kernel module metadata - [`c2e73da`](https://github.com/morluto/rea/commit/c2e73da18a3eb0d87385e8f84e5dd2593c4dce2e) fix(elf): bound kernel module ksymtab listing and tighten contracts - [`2d07520`](https://github.com/morluto/rea/commit/2d07520a5a8ec5c31638a1c29c10fdee8c22eccf) Merge main into kernel module inspection - [`51e4301`](https://github.com/morluto/rea/commit/51e43012f1ec77b3059d416051a3da2cf9526e10) fix: resolve merge integration errors ### 📊 Changes **57 files changed** (+3160 additions, -14 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+10 -0) 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+19 -0) 📝 `README.md` (+1 -0) 📝 `docs/.vitepress/config.ts` (+1 -0) 📝 `docs/cli.md` (+16 -0) 📝 `docs/index.md` (+14 -13) ➕ `docs/kernel-modules.md` (+163 -0) 📝 `docs/readme/README_ar.md` (+1 -0) 📝 `docs/readme/README_de.md` (+1 -0) 📝 `docs/readme/README_el.md` (+1 -0) 📝 `docs/readme/README_es.md` (+1 -0) 📝 `docs/readme/README_fa.md` (+1 -0) 📝 `docs/readme/README_fr.md` (+1 -0) 📝 `docs/readme/README_id.md` (+1 -0) 📝 `docs/readme/README_it.md` (+1 -0) 📝 `docs/readme/README_ja.md` (+1 -0) 📝 `docs/readme/README_ko.md` (+1 -0) 📝 `docs/readme/README_ml.md` (+1 -0) 📝 `docs/readme/README_pl.md` (+1 -0) 📝 `docs/readme/README_pt-BR.md` (+1 -0) _...and 37 more files_ </details> ### 📄 Description ## Summary Linux kernel modules (`.ko`) carry their identity in ELF sections: `.modinfo` key/value strings, `__versions` symbol CRCs, and an appended PKCS#7 signature trailer. REA admits relocatable ELF but had no static reader for this metadata. This adds `inspect-kernel-module` (CLI) and `inspect_kernel_module` (MCP) for ELF32/ELF64 `ET_REL` modules, read without loading the module or opening a disassembler. No related issue; this is a new static inspection within existing native authority. ## Problem and expected behavior An analyst triaging a driver today needs `modinfo`, `readelf` and a separate signature script. Expected: REA reports ordered `.modinfo` entries with duplicates preserved (`alias`, `softdep`, `parm`), `__versions` CRCs, presence of `.gnu.linkonce.this_module` and `__ksymtab`, `.init.text`/`.exit.text` sizes, and the signature trailer's `module_signature` fields with the PKCS#7 byte range and SHA-256. ## Change and scope `src/native/elf/KernelModuleParser.ts` reads section headers through the shared ELF reader, decodes `.modinfo` and `__versions` for both word sizes and byte orders, and parses the `~Module signature appended~` trailer. A missing section is observed absence when section names are known. gzip, xz and zstd containers are reported `unsupported` with `external_decompression` as the next probe; neither this tool nor `extract_artifact` decodes those codecs. Malformed headers and exhausted entry budgets return no partial success. Not included: decoding `struct module`, validating the signature or certificate chain. AI was used for assistance. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. ## Contract and boundary impact - Semantic owner and earliest changed stage: native ELF inspection (`src/native/elf/`) and the binary diagnostics service. - Contribution scope fit and linked maintainer decision: static format inspection of a local file within existing native authority; separate scope decision not applicable. - CLI and MCP/tool-catalog contract: new `inspect-kernel-module` command and `inspect_kernel_module` tool. - Provider, bridge, target-format, or platform compatibility: portable TypeScript, no provider; runs on any supported Node host. - Evidence, artifact, provenance, or reconstruction contract: Evidence carries artifact SHA-256, section locations and hashes, and the signature byte range. - Target selection, authority, upstream behavior, and cleanup details (if applicable): unchanged; reads a stable regular file. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): catalog builder entry, a capability row in each translated README (as in #6509), and authored skill guidance in `.agents/skills/reverse-engineer-anything/`. No committed build outputs. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [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: `src/native/elf/KernelModuleParser.test.ts` (ELF32/ELF64, both byte orders, duplicate keys, `__versions` layouts, signature trailers, compressed containers, truncation and budgets), `kernelModule.test.ts`, `KernelModuleService.test.ts`, `BinaryDiagnosticsCancellation.test.ts`, `tests/acceptance/kernelModuleCli.test.ts`, `tests/boundary/mcp/kernelModuleMcp.test.ts`, `tests/boundary/filesystem/kernelModule.test.ts`, and the shared path-admission, tool-contract and stable-artifact lists. Fixtures are synthetic; no binaries are committed. - Base reproduction or other evidence: the released CLI has no kernel module reader. Executed against Debian 13 arm64 `vfat.ko` and `btrfs.ko` (not committed) and compared with `modinfo` output. - User-visible CLI/MCP output (if applicable): see below. - Remaining proof gaps: ELF32 and big-endian modules were exercised with synthetic fixtures only. Signatures are located and hashed, not verified. ```text $ rea inspect-kernel-module vfat.ko --json | jq ... modinfo: 8 entries versions: 68 CRCs this_module: present signature: PKCS#7 sig_len 263 $ rea inspect-kernel-module btrfs.ko --json | jq ... modinfo: 13 entries (duplicate softdep and alias preserved) versions: 575 CRCs $ rea inspect-kernel-module vfat.ko.xz --json | jq ... applicability: unsupported compression: xz next_probe: external_decompression ``` `modinfo vfat.ko` and `modinfo btrfs.ko` list the same keys and values in the same order. 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 Head `2cb558d21` on main `d361c53c5`; macOS arm64, Node 26.5.0, npm 12.2.0: - `npx --no-install vitest run src/application/binaryDiagnostics/BinaryDiagnosticsCancellation.test.ts src/application/binaryDiagnostics/KernelModuleService.test.ts src/contracts/toolEffects.test.ts src/domain/native/kernelModule.test.ts src/native/elf/KernelModuleParser.test.ts tests/acceptance/kernelModuleCli.test.ts tests/acceptance/localPathAdmissionCli.test.ts tests/acceptance/tools/localToolContracts.test.ts tests/boundary/filesystem/kernelModule.test.ts tests/boundary/mcp/kernelModuleMcp.test.ts tests/process-global/stableArtifactConsumers.test.ts` - passed. - Real Debian 13 `vfat.ko`, `btrfs.ko` and `vfat.ko.xz` inspected as shown above. ## Compatibility, safety, and release - Breaking changes or migration steps: none; new command and tool only. - Real Hopper/Ghidra, browser, or OS coverage: macOS arm64 with Linux arm64 module inputs; no provider involved. - Package or release metadata impact: none beyond the generated catalogs. - Security, privacy, process, or containment review: the module is never loaded; reads are bounded and malformed input fails closed. ## Author readiness Human owner: @mvanhorn - [x] 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. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] 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. ## Demo ![demo](https://raw.githubusercontent.com/mvanhorn/pr-demo-assets/main/rea/2026-10-24-014-feat-kernel-module-modinfo/preview.gif) <video src="https://mvanhorn.github.io/pr-demo-assets/rea/2026-10-24-014-feat-kernel-module-modinfo/out.mp4" controls width="720"></video> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:38:48 +00:00

closed this issue
added the
pull-request
label

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#7572

No description provided.

Rows
Columns