Skip to content

Guides

Connect eBPF backstop

Use the eBPF observer for non-cooperative file and network I/O signals, adding clean-tier coverage that does not rely on agent cooperation.

Last updated:

The eBPF backstop is the non-cooperative ground truth observer. It attaches to kernel syscall tracepoints and reports file and network I/O as access-map edges that no userspace agent can evade, disable, or misrepresent. Where cooperative telemetry trusts the agent to report honestly, the backstop does not — it watches the kernel, not the agent.

For the general source model and OLIVARES_SOURCES_CONFIG structure, see Connect a source. For the cooperative path that the backstop complements, see Connect Claude Code.

What it observes

The backstop instruments kernel-level syscalls — open, read, write, connect, sendto, recvfrom and their variants — and emits one observation per relevant I/O event. The read/write classification comes from the syscall itself, not from anything the agent claims, so it is authoritative in the same way pgAudit’s READ/WRITE class is authoritative: the kernel performed the operation, therefore the operation happened.

The result is a stream of access-map edges attributing file and network I/O to a process identity on the host. These edges feed the same access map as every other source.

Why it exists

Cooperative telemetry — OpenTelemetry exports, hook payloads, MCP introspection — is richer and higher-level, but it is cooperative: the agent is the one emitting it. An agent that disables its OTel exporter, or a runtime that never had one, produces no cooperative signal at all.

The eBPF backstop closes that gap. An agent that stops exporting telemetry still makes syscalls; the kernel still sees them; the backstop still reports them. This is the ground truth the Connect Claude Code doc references:

Ground truth for genuinely non-cooperative activity is the kernel/eBPF backstop, not this heuristic.

That heuristic — detecting a session that stops emitting OTel while its hooks are still firing — is a cooperative-side anomaly signal. The backstop makes the non-cooperative side observable.

Coverage tier

The backstop is clean tier in the fidelity model. Read vs write is determined from the syscall, not from what the agent claims. The fidelity doc lists it alongside pgAudit and CloudTrail: “the kernel-level eBPF ground truth.” Clean coverage does not imply clean attribution — see limits below.

When to use it vs cooperative observation

They compose; they do not replace each other.

  • Cooperative (OTel, hooks, MCP) — higher-level context: sessions, tools, models, cost. The richer map.
  • Non-cooperative (eBPF) — the anti-evasion guarantee: what actually happened at the kernel level, regardless of what the agent chose to report.

Run both. The cooperative path builds the rich map you govern against. The backstop provides the unforgeable floor that catches anything the cooperative path missed — evasion, misconfiguration, or a runtime with no telemetry.

Deployment model

The backstop runs on each host where agents execute, wired into stock serve as source kind ebpf alongside pgaudit, s3cloudtrail, runtime, mcp, and claude. Because eBPF programs attach to the host kernel, one instance per host covers every agent process. There is no per-agent installation step.

Linux capabilities

eBPF tracing requires elevated kernel privileges. At minimum, the process loading the eBPF programs needs capabilities in the CAP_BPF and CAP_PERFMON family (or equivalent, depending on kernel version — older kernels fold these into CAP_SYS_ADMIN).

:::caution The exact capability set depends on your kernel version, distribution, and security module (AppArmor, SELinux). Check the connector’s own documentation for the precise flags required — this page does not list a definitive set because it varies across environments. Running in a container requires explicit capability grants (and possibly a BPF filesystem mount); a locked-down Kubernetes pod needs securityContext overrides. :::

Configuration

Select kind: "ebpf" in OLIVARES_SOURCES_CONFIG, using the same source-entry structure as every other connector:

{
  "sources": [
    {
      "name": "host-backstop",
      "kind": "ebpf",
      "tenant": "acme",
      "config": {}
    }
  ]
}

The exact config keys are owned by the connector; read its descriptor rather than copy an unverified schema. The config object above is intentionally empty — this page follows the same rule as Connect a source: we document only keys we have verified, and we have not verified the eBPF connector’s config surface from these web docs.

Anti-evasion properties

The backstop does not depend on agent cooperation:

  • An agent that disables its OTel exporter still generates kernel syscalls — the backstop sees those.
  • An agent that lies in its cooperative telemetry cannot lie to the kernel. The syscall record is authoritative.
  • An MCP server that misreports readOnlyHint / destructiveHint does not affect what the backstop observes — those are cooperative signals it does not consume.

The cooperative-side heuristic in Connect Claude Code — a session whose OTel goes silent while hooks keep firing — is a detection signal. The backstop is the ground truth that signal points toward.

Honest limits

The backstop observes what the kernel sees, not what the agent intends. That distinction matters:

  • Attribution is process-level. I/O is attributed to a process identity (PID, UID, binary path). If multiple agents share one process, the backstop cannot separate their accesses — attribution is approximate, not firm. Per-agent attribution requires a per-agent identity signal; see Fidelity.
  • No session or tool context. The backstop sees syscalls, not sessions or tool names. It cannot tell you which tool call triggered a file write — only that the process wrote the file. The cooperative path carries that context.
  • Kernel-version dependence. eBPF tracepoint availability varies across kernel versions. Confirm the minimum kernel version against the connector’s own documentation.
  • No payload content. Like every source, the backstop emits identifiers and a read/write classification, never file contents or network payloads.

Search documentation