[GH-ISSUE #2688] [Provider proposal] Bounded Linux userspace function tracing with eBPF #981

New issue

Open

opened 2026-10-15 18:30:04 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:30:04 +00:00

Owner

Originally created by @LcokHcak on GitHub (Oct 13, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2688

Proposal: bounded Linux userspace function tracing with eBPF

Problem and proposed first slice

A static call graph cannot show whether one named userspace function actually ran. I propose a small optional eBPF provider for one explicitly selected, owned Linux process and one named function or offset. The first slice would observe uprobe entry and uretprobe return only, for a finite duration, with a PID filter and bounded raw/output records. It would report PID/TID, function identity, entry/return, clock domain, raw evidence, truncation, cancellation, cleanup, and event loss where measurable. Unknown loss would remain unknown. It would not claim whole-program flow or cross-provider total order.

Authority and limits

Probe attachment changes host tracing state and may require elevated Linux capabilities. The provider would use a bring-your-own tracer; no automatic install, privilege escalation, kernel configuration, default all-process tracing, arbitrary kernel probes, memory writes, or protection-bypass workflow. Target selection and process identity require explicit checks before attaching.

Evidence available now

A local pure parser prototype accepts only opt-in bpftrace NDJSON printf records with a version marker and maps them to a provider-neutral v1 trace batch. It verifies the claimed PID, preserves exact nsecs(monotonic) decimal values, and caps projected events at 10000. Protocol-level tests pass, including malformed frames and capacity. This Windows host has no Linux distro, bpftrace, or container runtime; no real eBPF probe has been run, so the prototype is not integration evidence. The parser is not in public CLI/MCP.

Verification required before integration

On an isolated Linux fixture: source-built executable and known call sequence; entry/return and concurrent threads; missing symbol and dynamic library cases; PID identity/reuse; privilege denial; finite-duration stop, early exit and cancellation; output pressure and observable loss; cleanup; public CLI/MCP and installed package. The target and any raw evidence should remain local to that fixture.

Maintainer decision requested

Is this restricted userspace uprobe/uretprobe lane in REA's scope? Which target-ownership, privilege, loss-reporting, and real-platform verification conditions are required? Should the result project to a separate provider-neutral trace batch while reusing existing native-call semantics where applicable?

Related context: Frida scope discussion #968. This proposal is separate because its kernel attachment and privilege effects differ.

Originally created by @LcokHcak on GitHub (Oct 13, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2688 # Proposal: bounded Linux userspace function tracing with eBPF ## Problem and proposed first slice A static call graph cannot show whether one named userspace function actually ran. I propose a small optional eBPF provider for one explicitly selected, owned Linux process and one named function or offset. The first slice would observe `uprobe` entry and `uretprobe` return only, for a finite duration, with a PID filter and bounded raw/output records. It would report PID/TID, function identity, entry/return, clock domain, raw evidence, truncation, cancellation, cleanup, and event loss where measurable. Unknown loss would remain unknown. It would not claim whole-program flow or cross-provider total order. ## Authority and limits Probe attachment changes host tracing state and may require elevated Linux capabilities. The provider would use a bring-your-own tracer; no automatic install, privilege escalation, kernel configuration, default all-process tracing, arbitrary kernel probes, memory writes, or protection-bypass workflow. Target selection and process identity require explicit checks before attaching. ## Evidence available now A local pure parser prototype accepts only opt-in bpftrace NDJSON `printf` records with a version marker and maps them to a provider-neutral v1 trace batch. It verifies the claimed PID, preserves exact `nsecs(monotonic)` decimal values, and caps projected events at 10000. Protocol-level tests pass, including malformed frames and capacity. This Windows host has no Linux distro, bpftrace, or container runtime; **no real eBPF probe has been run**, so the prototype is not integration evidence. The parser is not in public CLI/MCP. ## Verification required before integration On an isolated Linux fixture: source-built executable and known call sequence; entry/return and concurrent threads; missing symbol and dynamic library cases; PID identity/reuse; privilege denial; finite-duration stop, early exit and cancellation; output pressure and observable loss; cleanup; public CLI/MCP and installed package. The target and any raw evidence should remain local to that fixture. ## Maintainer decision requested Is this restricted userspace `uprobe/uretprobe` lane in REA's scope? Which target-ownership, privilege, loss-reporting, and real-platform verification conditions are required? Should the result project to a separate provider-neutral trace batch while reusing existing native-call semantics where applicable? Related context: [Frida scope discussion #968](https://github.com/morluto/rea/issues/968). This proposal is separate because its kernel attachment and privilege effects differ.

bsakaguchi added the

area: providers

provider-request

enhancement

labels

2026-10-15 18:30:04 +00:00

bsakaguchi commented

2026-10-15 18:30:05 +00:00

Author

Owner

@LcokHcak commented on GitHub (Oct 14, 2026):

Local exploratory update: the prepared, self-owned Linux x64 bpftrace fixture and offline parser now target the shared execution-trace batch v2 contract with required source identity. The bpftrace REA_TRACE_V1 printf line protocol stays v1; only the normalized batch changed. The Python acceptance parser and TypeScript projector reject the same malformed decimal/JSON/TID shapes.

The offline projector now writes normalized-ebpf-v2.json and rechecks the collector report, fixture/script source hashes, target PID, six E/X records, one TID and monotonic timestamps. A clearly synthetic contract test passed one accepted-looking input and rejected wrong-PID and mixed-TID inputs. A Windows host-gate run remained attempted=false, accepted=false; no Linux probe has been run. Producer/kernel loss stays unknown.

This does not propose enabling bpftrace in REA yet. Please advise whether the bounded, explicitly selected owned-process uprobe/uretprobe workflow is in scope and what real-host and privilege checks you would require before considering a provider.

@LcokHcak commented on GitHub (Oct 14, 2026): Local exploratory update: the prepared, self-owned Linux x64 bpftrace fixture and offline parser now target the shared execution-trace batch v2 contract with required source identity. The bpftrace `REA_TRACE_V1` printf line protocol stays v1; only the normalized batch changed. The Python acceptance parser and TypeScript projector reject the same malformed decimal/JSON/TID shapes. The offline projector now writes `normalized-ebpf-v2.json` and rechecks the collector report, fixture/script source hashes, target PID, six E/X records, one TID and monotonic timestamps. A clearly synthetic contract test passed one accepted-looking input and rejected wrong-PID and mixed-TID inputs. A Windows host-gate run remained `attempted=false`, `accepted=false`; no Linux probe has been run. Producer/kernel loss stays unknown. This does not propose enabling bpftrace in REA yet. Please advise whether the bounded, explicitly selected owned-process uprobe/uretprobe workflow is in scope and what real-host and privilege checks you would require before considering a provider.

bsakaguchi referenced this issue

2026-10-17 21:07:29 +00:00

[PR #981] [MERGED] fix(cli): preserve output and comparison input validation #2551

bsakaguchi added

enhancement

and removed

enhancement

labels

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

bsakaguchi referenced this issue

2026-10-31 00:39:37 +00:00

[GH-ISSUE #5531] [Bug] Invalid output-flag values emit TOON despite selecting JSON or JSONL #3367