Skip to content
→ All work

Case study 20 / 37

eBPF-KernelTrace-MCP

Gives an AI assistant read-only, bounded access to Linux process and file activity: eBPF tracepoints, redaction and hard limits, served over MCP stdio.

Status
Experimental
Period
2026
Domain
Security · Tools
Language
Rust
Last push
26 OCT 2026
License
MIT OR Apache-2.0
Source of claims
README.md, docs/ARCHITECTURE.md, docs/KERNEL_COMPAT.md, docs/LIMITATIONS.md, CHANGELOG.md, crates/kerneltrace-core/src/live.rs, crates/kerneltrace-mcp/tests/live_kernel.rs, crates/kerneltrace-mcp/tests/mcp_stdio.rs, .github/workflows/ci.yml; release-gate verification 2026-10

A Rust MCP server with four read-only tools over process exec, exit and openat events. Aya eBPF programs write fixed 312-byte records to a ring buffer; a reader thread decodes, samples and redacts them into a bounded store. A seeded synthetic source emits byte-identical records, so the whole pipeline runs and is tested without root, on any OS.

01/The problem

Asked “what is this box doing?”, an assistant usually reaches for ps, lsof or strace through a shell tool: broad access, unbounded output and no redaction.

02/The system

A Rust MCP server with four read-only tools over process exec, exit and openat events. Aya eBPF programs write fixed 312-byte records to a ring buffer; a reader thread decodes, samples and redacts them into a bounded store. A seeded synthetic source emits byte-identical records, so the whole pipeline runs and is tested without root, on any OS.

Event path (README)7 components
  • Tracepoints to BPF ring buffer
  • BPF ring buffer to Reader thread
  • Synthetic source to Reader thread
  • Reader thread to Bounded queue
  • Bounded queue to Event store
  • Event store to MCP server

03/Implementation

  1. 01Three Aya tracepoint programs (exec, exit, openat) reserve and submit 312-byte records into a BPF ring buffer that is memory-mapped into the process.
  2. 02A safe field-by-field decoder with length, kind and path checks and control-character neutralisation, property-tested against arbitrary bytes.
  3. 03A reader that never blocks: a bounded queue with drop-oldest or drop-newest, deterministic 1-in-N sampling, redaction, and retention by count and age, with every drop counted.
  4. 04An MCP stdio server negotiating four protocol revisions (2024-11-05 to 2025-11-25), with response shapes, batching and error forms matched to each.
  5. 05Capability detection that names every unmet requirement; live mode never silently falls back to synthetic data.

04/Engineering

Found: a kernel backport that skipped CPUs

On Ubuntu's 7.0.0-1017-azure kernel, a backported hunk checks the per-CPU perf event list before the BPF call, and aya attaches tracepoints through one perf event on CPU 0, so the openat program ran only on CPU 0. kt_open moved to the raw sys_enter tracepoint.

Drop in userspace, where it is visible

If the reader blocked, the kernel ring buffer would fill and lose events invisibly. Dropping in userspace keeps every loss in a counter; kernel-side ring-full drops are counted by the probe too.

Private and bounded by default

File paths are not collected unless enabled, and with paths off the probe does not read path memory. Queues, retention, per-query results and 1 MiB input lines are all capped.

05/Interface

No product screenshots are published for this project. The visual above is a code-driven representation of how it behaves, built from the repository source — not a screenshot.

06/Tech stack

  • Rust
  • eBPF
  • Aya
  • BPF ring buffer
  • Model Context Protocol
  • JSON-RPC 2.0
  • TOML

07/Result

Verified outcomes

  • Release-gate verification (2026-10): with the workload pinned to every CPU, the live-kernel test went from 0/55 passes to 30/30 on 7.0.0-1017-azure under KVM, and passed 11/11 in CI.
  • The live path also passes on 6.8.0-117-generic/aarch64; CI on Linux, macOS and Windows; MIT OR Apache-2.0 (probe crate MIT OR GPL-2.0).

Known limitations

  • Live mode is tested on two kernels only; overhead and loss under load are unmeasured.
  • Fixed tracepoint offsets (no CO-RE), x86_64 and aarch64 only; 5 ms polling.
  • Not a security monitor: sampling, drops and redaction mean activity can be missed.

08/Links

GitHub repository ↗

Related work

Next case study

TimeMachine →