Minimum Privileges ​

eCapture is a powerful security auditing tool that leverages eBPF to intercept function calls in userspace libraries. Because it interacts directly with the Linux kernel's BPF subsystem and attaches uprobes to other processes, it requires elevated privileges. This page details the specific Linux Capabilities required under different kernel versions and provides configuration examples for secure deployments.

Privilege Requirements by Kernel Version ​

The Linux kernel has evolved to provide more granular control over BPF and performance monitoring. eCapture implements runtime detection to verify these requirements.

Kernel >= 5.8 (Fine-Grained Capabilities) ​

In Linux 5.8 and later, BPF-related privileges were split from the monolithic CAP_SYS_ADMIN into specific capabilities docs/minimum-privileges.md:7-17.

Kernel < 5.8 (Legacy Mode) ​

On older kernels, the specialized CAP_BPF and CAP_PERFMON capabilities do not exist. Users must provide broader permissions docs/minimum-privileges.md:18-26.

Runtime Privilege Detection ​

eCapture performs environment checks during the command execution phase. The function detectEnv calls detectKernel and detectBpfCap to ensure the environment is suitable cli/cmd/env_detection.go:66-78.

Capability Validation Logic ​

The detectBpfCap function uses the unix.Capget system call to inspect the process's permitted capabilities cli/cmd/env_detection.go:47-64.

Sources: cli/cmd/env_detection.go:26-78, pkg/util/kernel/version.go:22-32

Configuration Examples ​

1. Host Binary (setcap) ​

Using setcap is the recommended way to follow the Principle of Least Privilege for local execution without using sudo docs/minimum-privileges.md:45-67.

For Kernel >= 5.8:

# Text or Keylog mode
sudo setcap 'cap_bpf,cap_perfmon,cap_sys_ptrace=eip' /usr/local/bin/ecapture

# Pcapng mode (requires networking caps)
sudo setcap 'cap_bpf,cap_perfmon,cap_net_admin,cap_sys_ptrace=eip' /usr/local/bin/ecapture

2. Docker Deployment ​

Avoid using --privileged=true in production as it grants the container full host access docs/minimum-privileges.md:104-105. Instead, use specific --cap-add flags and volume mounts docs/minimum-privileges.md:75-102.

docker run --rm \
  --cap-add=BPF \
  --cap-add=PERFMON \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_PTRACE \
  --pid=host \
  --net=host \
  -v /sys/kernel/debug:/sys/kernel/debug:ro \
  -v /sys/fs/bpf:/sys/fs/bpf \
  gojue/ecapture:latest tls

Required Mounts and Flags:

• /sys/kernel/debug: Required for uprobe attachment via debugfs docs/minimum-privileges.md:110.
• /sys/fs/bpf: Required for pinning BPF maps docs/minimum-privileges.md:111.
• --pid=host: Necessary to trace processes in the host namespace docs/minimum-privileges.md:117.

3. Kubernetes securityContext ​

For Kubernetes deployments, configure the securityContext of the container spec:

securityContext:
  capabilities:
    add:
      - BPF
      - PERFMON
      - NET_ADMIN
      - SYS_PTRACE
readinessProbe:
  # ...
volumeMounts:
  - name: sys-kernel-debug
    mountPath: /sys/kernel/debug
    readOnly: true

Data Flow and Permission Boundary ​

The following diagram illustrates how eCapture uses these privileges to bridge the gap between the userspace binary and the kernel's eBPF subsystem.

Sources: docs/minimum-privileges.md:5-34, docs/performance-benchmarks.md:7-12, cli/cmd/env_detection.go:47-64

Security Best Practices ​

1. Restrict Binary Access: Use group permissions to limit who can execute the eCapture binary with set capabilities docs/minimum-privileges.md:142-146.
2. Scope Capture: Always use the --pid flag to limit capture to specific target processes rather than system-wide auditing docs/minimum-privileges.md:137.
3. Cleanup: Remove the binary or clear capabilities (setcap -r) once the troubleshooting or auditing session is complete docs/minimum-privileges.md:139.

Sources:

• cli/cmd/env_detection.go:26-78
• docs/minimum-privileges.md:1-154
• pkg/util/kernel/version.go:1-50
• docs/defense-detection.md:117-138