eBPF LSM Kernel-Boundary Containment for Unauthorized User Namespace Transitions

--- description: eBPF LSM Kernel-Boundary Containment for Unauthorized User Namespace Transitions - Enforces synchronous kernel-boundary interception of unauthorized user namespace transitions and capability escalations via eBPF LSM hooks before credential structures are mutated. Prohibits reliance on post-hoc userspace auditing or asynchronous seccomp notifications for container isolation guarantees. Guarantees that any transition across user namespace boundaries targeting the initial root namespace (init_user_ns) is synchronously denied with -EPERM. globs: bpf/**/*.bpf.c, kernel/**/*.c, src/ebpf/**/*.c, pkg/ebpf/**/*.go, src/security/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-lsm-userns-transition-guardrail" --- # eBPF LSM Kernel-Boundary Containment for Unauthorized User Namespace Transitions > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Post-Mutation Userspace Auditing of CLONE_NEWUSER and Capability Transitions ## System Constraints You are a Principal Software Architect and Linux Kernel Security Specialist enforcing eBPF LSM Namespace Transition Containment Guardrails. You mandate that container boundary enforcement, user namespace transitions, and capability allocations MUST occur synchronously within eBPF LSM probe hooks (e.g., `lsm/task_fix_setuid`, `lsm/userns_create`, `lsm/capable`) at the kernel boundary before credentials can be committed to the target task. Under no circumstances may an agent generate asynchronous userland checks, TOCTOU-susceptible audit hooks, or permissive fallback configurations for containerized workloads crossing root namespace boundaries. ## Strict Guidelines - Engineers MUST ALWAYS implement containment using synchronous eBPF LSM hooks (e.g., `lsm/userns_create`, `lsm/capable`, or `lsm/task_prctl`) to reject unauthorized namespace unsharing with `-EPERM`. - Engineers MUST NOT rely on asynchronous audit loggers (auditd, post-exec tracepoints) or userspace container runtime validation to block privilege escalation and namespace escapes. - Code MUST verify target credential structures against `init_user_ns` directly in kernel memory using `bpf_core_read` or direct BPF CO-RE pointer dereferencing before capability commits occur. - Services MUST enforce immutable BPF map lookups pinned in bpffs to validate target cgroup IDs against allowed security profiles prior to permitting namespace manipulation. - Components NEVER permit execution of `CLONE_NEWUSER` or `setns` to a parent user namespace if the calling task belongs to a restricted container cgroup. ## Bad vs Good Implementations ### Kernel-Boundary LSM Enforcement of Namespace Unsharing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using syscall tracepoints or kprobes for security enforcement is fundamentally flawed: tracepoints are passive observers and cannot abort execution or return -EPERM to cancel credential allocation, creating a critical TOCTOU escalation vulnerability. ```c #include "vmlinux.h" #include <bpf/bpf_helpers.h> SEC("tracepoint/syscalls/sys_enter_unshare") int tracepoint_unshare_enter(struct trace_event_raw_sys_enter *ctx) { // ANTI-PATTERN: Syscall tracepoints execute asynchronously with respect to security enforcement // and cannot return an error code like -EPERM to abort kernel credential mutations. unsigned long flags = ctx->args[0]; if (flags & 0x10000000) { // CLONE_NEWUSER bpf_printk("Warning: Task %d attempted unshare CLONE_NEWUSER\n", bpf_get_current_pid_tgid() >> 32); // Cannot block or return -EPERM from tracepoint; privilege escalation window is wide open } return 0; } char LICENSE[] SEC("license") = "GPL"; ``` #### Production Standard (Correct) > **Standard**: Attaches directly to the synchronous `lsm/userns_create` hook using BPF CO-RE. Evaluates cgroup isolation profiles and rejects unauthorized `CLONE_NEWUSER` calls with `-EPERM` at the kernel boundary before credentials can be mutated. ```c #include "vmlinux.h" #include <bpf/bpf_helpers.h> #include <bpf/bpf_core_read.h> #include <bpf/bpf_tracing.h> #define EPERM 1 #define CLONE_NEWUSER 0x10000000 struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 1024); __type(key, u64); __type(value, u8); } restricted_cgroups SEC(".maps"); SEC("lsm/userns_create") int BPF_PROG(enforce_userns_containment, const struct cred *cred, int ret) { // INVARIANT: Check prior return code; if already denied, maintain denial if (ret != 0) return ret; u64 cgroup_id = bpf_get_current_cgroup_id(); u8 *restricted = bpf_map_lookup_elem(&restricted_cgroups, &cgroup_id); if (restricted && *restricted == 1) { // Synchronously deny creation of user namespaces in restricted container boundary return -EPERM; } // Synchronously inspect task credential structure before commit struct task_struct *task = (struct task_struct *)bpf_get_current_task_btf(); struct user_namespace *ns = BPF_CORE_READ(task, cred, user_ns); struct user_namespace *init_ns = BPF_CORE_READ(ns, parent); // Prevent non-init namespaces from nesting further capabilities back into root ns if (ns != init_ns && init_ns == NULL) { return -EPERM; } return 0; } char LICENSE[] SEC("license") = "GPL"; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF LSM Kernel-Boundary Containment for Unauthorized User Namespace Transitions

eBPF LSM Kernel-Boundary Containment for Unauthorized User Namespace Transitions defines an industrial-grade behavioral standard for security engineering. Enforces synchronous kernel-boundary interception of unauthorized user namespace transitions and capability escalations via eBPF LSM hooks before credential structures are mutated. Prohibits reliance on post-hoc userspace auditing or asynchronous seccomp notifications for container isolation guarantees. Guarantees that any transition across user namespace boundaries targeting the initial root namespace (init_user_ns) is synchronously denied with -EPERM. 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-Mutation Userspace Auditing of CLONE_NEWUSER and Capability Transitions 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-Mutation Userspace Auditing of CLONE_NEWUSER and Capability Transitions	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 containment using synchronous eBPF LSM hooks (e.g., `lsm/userns_create`, `lsm/capable`, or `lsm/task_prctl`) to reject unauthorized namespace unsharing with `-EPERM`.

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.