morluto/rea

Fork 0

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

[GH-ISSUE #2369] [Feature] Inspect Linux BTF type and function metadata offline #783

New issue

Open

opened 2026-10-15 18:28:18 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

2026-10-15 18:28:18 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2369

Requested capability

The current contracts have no declared Linux BTF/BTF.ext inspection profile. The published BTF format contains type graphs, function metadata and line information that ordinary ELF section inventory does not decode. Issue #2003 targets Solana sBPF and does not provide a Linux BTF contract.

Acceptance criteria

Accept caller-selected BTF bytes or an explicitly identified ELF section and preserve original hash/source ranges.
Specify supported BTF versions, byte order, type kinds and BTF.ext function/line/relocation records.
Retain unknown kinds and unresolved references explicitly; bound strings, type references, records and graph traversal.
Verify original fixtures through CLI/MCP; do not load programs, attach probes, access live kernel state or invoke a verifier.

References and boundaries

https://docs.kernel.org/bpf/btf.html

This feature needs its own docs/specs//spec.md, plan.md and tasks.md before code. Current upstream sources and existing issues were searched before filing. A new REA provider or expanded execution authority requires the maintainer scope decision specified by CONTRIBUTING.md; this proposal does not supply that decision.

Originally created by @matbrgz on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2369 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Reverse Engineering](https://img.shields.io/badge/domain-reverse_engineering-blueviolet.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Requested capability The current contracts have no declared Linux BTF/BTF.ext inspection profile. The published BTF format contains type graphs, function metadata and line information that ordinary ELF section inventory does not decode. Issue #2003 targets Solana sBPF and does not provide a Linux BTF contract. ## Acceptance criteria - [ ] Accept caller-selected BTF bytes or an explicitly identified ELF section and preserve original hash/source ranges. - [ ] Specify supported BTF versions, byte order, type kinds and BTF.ext function/line/relocation records. - [ ] Retain unknown kinds and unresolved references explicitly; bound strings, type references, records and graph traversal. - [ ] Verify original fixtures through CLI/MCP; do not load programs, attach probes, access live kernel state or invoke a verifier. ## References and boundaries - https://docs.kernel.org/bpf/btf.html This feature needs its own docs/specs/<feature>/spec.md, plan.md and tasks.md before code. Current upstream sources and existing issues were searched before filing. A new REA provider or expanded execution authority requires the maintainer scope decision specified by CONTRIBUTING.md; this proposal does not supply that decision.

bsakaguchi added the

P3: low

area: native

enhancement

labels

2026-10-15 18:28:18 +00:00

bsakaguchi commented

2026-10-15 18:28:19 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

Implementation & Scope Notes

Objective (ELI5):
Parse BPF Type Format (BTF) data from Linux binaries and kernel modules offline, extracting struct definitions, types, and function prototypes.

Key Requirements:

Pure TypeScript parser for the .BTF ELF section and standalone BTF files (/sys/kernel/btf/vmlinux).
Decode kind tags (BTF_KIND_STRUCT, BTF_KIND_UNION, BTF_KIND_FUNC, BTF_KIND_FUNC_PROTO) into typed domain structures.

@matbrgz commented on GitHub (Oct 12, 2026): ### Implementation & Scope Notes **Objective (ELI5):** Parse BPF Type Format (BTF) data from Linux binaries and kernel modules offline, extracting struct definitions, types, and function prototypes. **Key Requirements:** - Pure TypeScript parser for the `.BTF` ELF section and standalone BTF files (`/sys/kernel/btf/vmlinux`). - Decode kind tags (`BTF_KIND_STRUCT`, `BTF_KIND_UNION`, `BTF_KIND_FUNC`, `BTF_KIND_FUNC_PROTO`) into typed domain structures.

bsakaguchi referenced this issue

2026-10-16 21:15:57 +00:00

[PR #764] [MERGED] fix(semantics): preserve empty string property keys #2225

bsakaguchi referenced this issue

2026-10-16 21:16:35 +00:00

[PR #836] [MERGED] fix(javascript): keep exact empty env keys and method names #2274

bsakaguchi added

enhancement

and removed

enhancement

labels

2026-10-31 00:29:36 +00:00

bsakaguchi commented

2026-10-31 00:29:36 +00:00

Author

Owner

@zaid646 commented on GitHub (Oct 28, 2026):

Quick scope proposal before I write code.

I'd like to take this as inspect_btf / inspect-btf, a static reader in the same lane as inspect_kernel_module and inspect_elf_notes.

First slice: one absolute path, either a standalone BTF blob (/sys/kernel/btf/* or a saved copy) or an ELF/.ko carrying .BTF. .BTF.ext is read when present. .BTF.base / split-BTF presence is reported, and base references stay unresolved — no relocation.

Result: byte order, version, flags and header lengths; section ranges with SHA-256; string-table statistics; a paged type inventory by 1-based id with the exact kind-specific facts (members and bitfields, params, enum/enum64, arrays, vars/datasecs, decl/type tags); a one-level named reference summary for the types used by the returned page; .BTF.ext func/line/CO-RE records grouped by ELF section, paged per section; explicit unknowns for unknown kinds, out-of-range string offsets, and truncated or overlapping ranges.

Effects: reads one selected file only. No BPF program load, no attach, no verifier, no live kernel or /sys access, no network, no writes.

Verification: owned fixtures compiled from a small C source with clang -target bpf -g (source and generator checked in), plus synthetic big-endian, unknown-kind, truncated and malformed fixtures; CLI and MCP boundary coverage; one real vmlinux .BTF run recorded as evidence and not committed.

Deferred: .BTF.base relocation, .BTF_ids, pretty-printing the type graph, BTF generation.

Two format details worth pinning:

The kernel docs describe info as vlen bits 0–23 / kind 24–30, while include/uapi/linux/btf.h and libbpf decode vlen as 16 bits, kind as 5 bits at 24–28 and bit 31 as kind_flag. I plan to follow the header macros and record the discrepancy rather than silently pick one.
The .BTF.ext header's core-relo fields are optional (hdr_len 24 vs 32), so both are admitted.

Is that slice in scope, and is inspect_btf the name you want? I'll put spec/plan/tasks/verification under docs/specs/btf-inspection/ before the implementation.

@zaid646 commented on GitHub (Oct 28, 2026): Quick scope proposal before I write code. I'd like to take this as `inspect_btf` / `inspect-btf`, a static reader in the same lane as `inspect_kernel_module` and `inspect_elf_notes`. **First slice:** one absolute path, either a standalone BTF blob (`/sys/kernel/btf/*` or a saved copy) or an ELF/`.ko` carrying `.BTF`. `.BTF.ext` is read when present. `.BTF.base` / split-BTF presence is reported, and base references stay unresolved — no relocation. **Result:** byte order, version, flags and header lengths; section ranges with SHA-256; string-table statistics; a paged type inventory by 1-based id with the exact kind-specific facts (members and bitfields, params, enum/enum64, arrays, vars/datasecs, decl/type tags); a one-level named reference summary for the types used by the returned page; `.BTF.ext` func/line/CO-RE records grouped by ELF section, paged per section; explicit unknowns for unknown kinds, out-of-range string offsets, and truncated or overlapping ranges. **Effects:** reads one selected file only. No BPF program load, no attach, no verifier, no live kernel or `/sys` access, no network, no writes. **Verification:** owned fixtures compiled from a small C source with `clang -target bpf -g` (source and generator checked in), plus synthetic big-endian, unknown-kind, truncated and malformed fixtures; CLI and MCP boundary coverage; one real `vmlinux` `.BTF` run recorded as evidence and not committed. **Deferred:** `.BTF.base` relocation, `.BTF_ids`, pretty-printing the type graph, BTF generation. Two format details worth pinning: - The kernel docs describe `info` as vlen bits 0–23 / kind 24–30, while `include/uapi/linux/btf.h` and libbpf decode vlen as 16 bits, kind as 5 bits at 24–28 and bit 31 as `kind_flag`. I plan to follow the header macros and record the discrepancy rather than silently pick one. - The `.BTF.ext` header's core-relo fields are optional (`hdr_len` 24 vs 32), so both are admitted. Is that slice in scope, and is `inspect_btf` the name you want? I'll put spec/plan/tasks/verification under `docs/specs/btf-inspection/` before the implementation.

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

No description provided.

Rows
Columns