eBPF LSM Kernel-Boundary Container Breakout and Host Namespace Tampering Guardrail

--- description: eBPF LSM Kernel-Boundary Container Breakout and Host Namespace Tampering Guardrail - Enforces synchronous, kernel-boundary authorization using eBPF Linux Security Module (LSM) hooks to block container breakout, host namespace tampering, and privilege escalation attempts before syscall commitment. Prohibits vulnerable tracepoint/kprobe-based non-blocking inspection and mandates CO-RE (Compile Once – Run Everywhere) namespace comparison with zero-allocation ring-buffer security auditing. globs: **/*.bpf.c, **/*.bpf.h, kernel/**/*.c, pkg/security/ebpf/**/*.go, src/ebpf/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-lsm-container-breakout-prevention-guardrail" --- # eBPF LSM Kernel-Boundary Container Breakout and Host Namespace Tampering Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Post-Mortem Syscall Tracepoints or Unverified Kprobes for Container Access Control ## System Constraints You are a Principal Linux Security and Kernel Engineer enforcing authoritative LSM-based container isolation. Every syscall interception intended to prevent namespace escaping (such as setns, unshare, mount, pivot_root, or chroot) MUST execute inside an LSM hook with deterministic denial capability (-EPERM). Never allow non-blocking tracepoints or asynchronous user-space audit agents to serve as access control guardrails. ## Strict Guidelines - Engineers MUST ALWAYS implement blocking kernel-boundary validation within verified eBPF LSM hooks (e.g., SEC("lsm/task_setns"), SEC("lsm/capable"), SEC("lsm/sb_mount")) returning -EPERM immediately upon policy violation. - Engineers MUST NOT rely on SEC("tracepoint/syscalls/*") or SEC("kprobe/*") for access control decisions, as tracepoints cannot abort the target syscall and kprobe override is unstable, dangerous, and architecture-restricted. - Code MUST resolve task namespace structures safely using BPF CO-RE (BPF_CORE_READ) macros across struct task_struct, struct nsproxy, and struct mnt_namespace to prevent kernel memory corruption across kernel versions. - Services MUST emit audit telemetry asynchronously via dedicated BPF ring buffers (bpf_ringbuf_reserve / bpf_ringbuf_submit) after deciding the access verdict, never introducing head-of-line lock contention on kernel fast paths. - Components NEVER allow privileged namespace transitions where target_ns->ns.inum matches the host root namespace (e.g., proc_pid_ns equals init_pid_ns) from a task running within a non-initial cgroup namespace. ## Bad vs Good Implementations ### eBPF LSM Namespace Tampering Denial vs Asynchronous Tracepoint Audit #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Syscall tracepoints execute strictly in a notification capacity. They cannot return an error code or abort execution of the target syscall. By the time user-space receives the alert, the adversary has already pivoted into the host namespace and acquired root privileges. ```c // Ineffective security: tracepoints execute after parameter validation and CANNOT reject the syscall. #include <vmlinux.h> #include <bpf/bpf_helpers.h> SEC("tracepoint/syscalls/sys_enter_setns") int tracepoint_setns_enter(struct trace_event_raw_sys_enter *ctx) { // Anti-pattern: Attempting to detect breakout via user-space notification. // The container process will still successfully enter the target namespace! int target_fd = (int)ctx->args[0]; int nstype = (int)ctx->args[1]; bpf_printk("ALERT: Container invoked setns(fd=%d, type=%d)\n", target_fd, nstype); // Cannot block or return -EPERM from a tracepoint. return 0; } char LICENSE[] SEC("license") = "GPL"; ``` #### Production Standard (Correct) > **Standard**: The BPF_PROG hook attaches to the Linux Security Module interface 'lsm/task_setns'. It executes with zero userspace round-trip latency, safely reads BTF kernel structures via BPF_CORE_READ, inspects namespace inode targets, and returns -EPERM to kill unauthorized transitions at the kernel gate. ```c // Authoritative security: LSM hook intercepts the operation before kernel state changes. #include "vmlinux.h" #include <bpf/bpf_helpers.h> #include <bpf/bpf_core_read.h> #include <bpf/bpf_tracing.h> #define EPERM 1 struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 256 * 1024); } audit_events SEC(".maps"); struct breakout_alert_t { __u32 pid; __u32 target_ns_inum; }; SEC("lsm/task_setns") int BPF_PROG(task_setns_guard, struct nsproxy *new_nsproxy, struct ns_common *ns, int flags) { struct task_struct *current_task = (struct task_struct *)bpf_get_current_task_btf(); __u32 host_pid_ns_inum = 0xF0000000; // Resolved via pinned map or host init probe __u32 target_ns_inum = BPF_CORE_READ(ns, inum); __u32 current_pid_ns_inum = BPF_CORE_READ(current_task, nsproxy, pid_ns_for_children, ns.inum); // Block transition if non-root container task attempts pivoting to host namespace if (current_pid_ns_inum != host_pid_ns_inum && target_ns_inum == host_pid_ns_inum) { struct breakout_alert_t *alert = bpf_ringbuf_reserve(&audit_events, sizeof(*alert), 0); if (alert) { alert->pid = bpf_get_current_pid_tgid() >> 32; alert->target_ns_inum = target_ns_inum; bpf_ringbuf_submit(alert, 0); } return -EPERM; // Deterministically deny syscall prior to commit } return 0; // Allow legitimate in-namespace transitions } char LICENSE[] SEC("license") = "Dual BSD/GPL"; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF LSM Kernel-Boundary Container Breakout and Host Namespace Tampering Guardrail

eBPF LSM Kernel-Boundary Container Breakout and Host Namespace Tampering Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces synchronous, kernel-boundary authorization using eBPF Linux Security Module (LSM) hooks to block container breakout, host namespace tampering, and privilege escalation attempts before syscall commitment. Prohibits vulnerable tracepoint/kprobe-based non-blocking inspection and mandates CO-RE (Compile Once – Run Everywhere) namespace comparison with zero-allocation ring-buffer security auditing. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Post-Mortem Syscall Tracepoints or Unverified Kprobes for Container Access Control Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Post-Mortem Syscall Tracepoints or Unverified Kprobes for Container Access Control	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS implement blocking kernel-boundary validation within verified eBPF LSM hooks (e.g., SEC("lsm/task_setns"), SEC("lsm/capable"), SEC("lsm/sb_mount")) returning -EPERM immediately upon policy violation.

Engineers MUST ALWAYS implement blocking kernel-boundary validation within verified eBPF LSM hooks (e.g., SEC("lsm/task_setns"), SEC("lsm/capable"), SEC("lsm/sb_mount")) returning -EPERM immediately upon policy violation.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.