Deep host capture (eBPF)

See every process your agents actually run — at the kernel, with nothing to wire into your code.

What you get

Agents don't only call APIs. They shell out: they run git, curl, aws, kubectl, python, a one-off script someone dropped on the box. In-process SDK instrumentation can only see the calls your own code makes through the library you wrapped. Anything spawned underneath it — a subprocess, a binary the agent downloaded and executed, a tool launched by a framework you didn't instrument — is invisible to a library that lives inside your process.

Deep host capture closes that gap. The collector attaches an eBPF probe at the Linux kernel and records every execve on the host — every process start, no matter who launched it or how. You get:

  • Complete subprocess visibility. Every binary that runs on the host shows up as a traced step — including processes spawned by un-instrumented agents, background jobs, and tools launched outside any framework you wired up.
  • Ground truth, not guesses. Each exec carries the executable path, the process and parent-process IDs, the user it ran as, and the reconstructed command line — straight from the kernel, so it can't be spoofed by an agent that lies about what it did.
  • Zero code changes. This is host-level capture. You don't instrument your agents, import a library, or redeploy your app — you turn it on in the collector and every process on that host is covered.
  • It catches what in-process SDKs miss. Because it watches the kernel's own process-exec tracepoint, it sees statically-linked binaries and indirect exec paths that higher-level hooks routinely miss. If a process started, you see it.

The result: a host where your agents run becomes fully observable, and the traces you already get from the SDKs are joined by the system layer underneath them — the actual commands, the actual binaries, the actual network connections and file activity.

How to turn it on

Deep host capture ships in the default Linux collector build — there's no separate package or plugin to install. Enable the OS-layer input in your collector config:

inputs:
  os_layer:
    enabled: true
    mode: auto      # picks the best kernel backend for the platform

mode: auto selects kernel-level eBPF capture on a capable Linux host and falls back automatically otherwise (see Graceful fallback below). On macOS and Windows the collector uses each platform's own native backend — you don't need to configure anything different.

What the kernel probe needs (Linux)

To run the eBPF probe, the collector needs a few standard host capabilities:

  • Linux kernel 5.8 or newer
  • CAP_BPF + CAP_PERFMON capabilities — or CAP_SYS_ADMIN, or a privileged container
  • Kernel BTF present at /sys/kernel/btf/vmlinux (it is, on virtually every modern distro kernel)

Notably, it needs no debugfs/tracefs mount in the container — so you don't have to mount /sys/kernel/debug.

On Kubernetes, that's just a capability grant on the collector pod:

securityContext:
  capabilities:
    add: ["BPF", "PERFMON"]

Scope what gets captured

You stay in control of what the host capture emits. Path filters bound which file and exec events are produced:

inputs:
  os_layer:
    enabled: true
    mode: auto
    paths:
      includes: ["/srv/agents/*"]   # only capture under these paths
      excludes: ["/var/cache/*"]    # never capture under these

The collector also always excludes its own paths and obvious noise (e.g. temporary and pseudo-filesystem paths) so it never traces itself.

Privacy built in

Command lines sometimes carry secrets — a token passed as --api-key, a PASSWORD=… environment-style assignment, an inline --token=…. Before any event leaves the host, the collector scrubs the values of known secret-bearing arguments to [REDACTED] — long-form secret flags (--password / --token / --api-key / --secret / --auth), inline flag=value forms, and *_KEY / *_SECRET / *_TOKEN / PASSWORD= assignments. This happens on the host, before export — independent of, and in addition to, the redaction you can configure downstream.

Graceful fallback

Deep host capture is designed to never fail your deployment and never silently drop data:

  • If the kernel probe can't load — capabilities aren't granted, the kernel is older than 5.8, or BTF is missing — the collector logs a single clear warning and automatically falls back to fanotify-based exec and file capture (which needs CAP_SYS_ADMIN), or to a userspace shim on fully unprivileged hosts. Exec events are never silently dropped.
  • The fallback is seamless. The hand-off between backends is coordinated so there's no window where a process slips through uncaptured, and you don't see the same exec recorded twice.
  • macOS and Windows hosts use their own native capture backends and don't need any of the Linux capabilities above.

The single warning in your collector logs tells you exactly what to grant if you want full kernel-level capture:

oslayer/ebpf: kernel probe unavailable — exec capture falls back to fanotify
FAN_OPEN_EXEC (grant CAP_BPF + CAP_PERFMON on kernel>=5.8 for kernel-level capture)
Want a leaner binary? Operators who don't need the kernel probe can build a minimal collector that omits it; exec capture then runs on the fanotify or userspace fallback. The default release image includes the kernel probe.

Next