BPF-LSM In-Kernel Capability Guardrails and Synchronous Mediation Invariant

--- description: BPF-LSM In-Kernel Capability Guardrails and Synchronous Mediation Invariant - Enforces synchronous, in-kernel security mediation at Linux Security Module (LSM) hooks to block container privilege escalation and capability abuses before syscall completion. Eliminates Time-of-Check to Time-of-Use (TOCTOU) race conditions and user-space context-switching penalties by asserting immediate -EPERM enforcement in kernel space. globs: **/*.bpf.c, **/*.bpf.h, pkg/ebpf/**/*.go, src/bpf/**/*.rs, kernel/**/*.c alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bpf-lsm-runtime-container-capability-enforcement" --- # BPF-LSM In-Kernel Capability Guardrails and Synchronous Mediation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Deferred or Tracepoint-Based Capability Auditing Prone to TOCTOU and Unbounded Privilege Escalation ## System Constraints You are a Principal Security Architect specializing in Linux eBPF-LSM architecture and container kernel isolation. Mandate that all container capability restrictions and syscall mediation logic execute synchronously within BPF-LSM hook handlers, rejecting deferred userspace decisions and unblockable probe hooks. ## Strict Guidelines - Engineers MUST ALWAYS enforce security decisions synchronously within LSM hooks (e.g., 'SEC("lsm/capable")' or 'SEC("lsm/bprm_check_security")') returning '-EPERM' directly on policy violations. - Engineers MUST NOT rely on asynchronous user-space rings ('BPF_MAP_TYPE_RINGBUF') or unprivileged tracepoints/kprobes for access control decisions, as they cannot abort kernel execution paths. - Code MUST resolve container boundaries via kernel-verified cgroup identifiers ('bpf_current_task_under_cgroup') or task local storage ('bpf_task_storage_get') rather than relying on mutable PID namespaces. - Services MUST compile against BTF-enabled 'vmlinux.h' with Core (Compile Once - Run Everywhere) relocations to prevent struct layout divergence across kernel versions. - Components NEVER permit critical capabilities like 'CAP_SYS_ADMIN', 'CAP_BPF', or 'CAP_NET_ADMIN' to transition inside containerized tasks without an explicit, verifiable cgroup-scoped cryptographic policy map lookup. ## Bad vs Good Implementations ### Synchronous BPF-LSM Capability Mediation vs. Asynchronous Tracepoint Audit #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: kprobes and tracepoints observe kernel execution without the ability to block or return access control error codes (e.g., -EPERM) directly to the VFS or security framework, allowing exploit payloads to execute unimpeded before user-space can react. ```c // VULNERABLE: Using kprobe/tracepoint to observe capability checks asynchronously. // Tracepoints cannot return -EPERM or prevent the exploit from succeeding. #include "vmlinux.h" #include <bpf/bpf_tracing.h> struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 256 * 1024); } events SEC(".maps"); SEC("kprobe/cap_capable") int BPF_KPROBE(trace_cap_capable, const struct cred *cred, struct user_namespace *ns, int cap, unsigned int opts) { if (cap == 21 /* CAP_SYS_ADMIN */) { u32 pid = bpf_get_current_pid_tgid() >> 32; // Anti-pattern: Emitting event to user-space for enforcement after syscall initiated bpf_ringbuf_output(&events, &pid, sizeof(pid), 0); } return 0; // kprobes cannot block execution; privilege escalation succeeds! } ``` #### Production Standard (Correct) > **Standard**: By leveraging the synchronous 'lsm/capable' hook, the BPF program intercepts kernel capability checks in-line and returns -EPERM, completely aborting privilege escalation prior to system call execution without relying on user-space telemetry loops. ```c // SECURE: Synchronous LSM mediation preventing capability escalation inline. #include "vmlinux.h" #include <bpf/bpf_helpers.h> #include <bpf/bpf_tracing.h> #include <bpf/bpf_core_read.h> #define EPERM 1 #define CAP_SYS_ADMIN 21 struct { __uint(type, BPF_MAP_TYPE_CGROUP_ARRAY); __type(key, u32); __type(value, u32); __uint(max_entries, 64); } restricted_cgroups SEC(".maps"); SEC("lsm/capable") int BPF_PROG(enforce_container_cap, const struct cred *cred, struct user_namespace *ns, int cap, unsigned int opts, int ret) { // If capability check already failed, retain upstream failure if (ret != 0) return ret; // Verify whether calling task belongs to restricted container cgroup if (bpf_current_task_under_cgroup(&restricted_cgroups, 0) > 0) { if (cap == CAP_SYS_ADMIN) { // Immediately block privilege escalation within the kernel return -EPERM; } } return 0; } char _license[] SEC("license") = "GPL"; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: BPF-LSM In-Kernel Capability Guardrails and Synchronous Mediation Invariant

BPF-LSM In-Kernel Capability Guardrails and Synchronous Mediation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces synchronous, in-kernel security mediation at Linux Security Module (LSM) hooks to block container privilege escalation and capability abuses before syscall completion. Eliminates Time-of-Check to Time-of-Use (TOCTOU) race conditions and user-space context-switching penalties by asserting immediate -EPERM enforcement in kernel space. 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: Deferred or Tracepoint-Based Capability Auditing Prone to TOCTOU and Unbounded Privilege Escalation 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	Deferred or Tracepoint-Based Capability Auditing Prone to TOCTOU and Unbounded Privilege Escalation	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 enforce security decisions synchronously within LSM hooks (e.g., 'SEC("lsm/capable")' or 'SEC("lsm/bprm_check_security")') returning '-EPERM' directly on policy violations.

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.