eBPF TC Ring-Buffer Zero-Copy Packet Auditing Invariant

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Utilizing Legacy Perf-Event Arrays or Unchecked Ring-Buffer Allocations in High-Throughput TC Filters) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

eBPF TC Ring-Buffer Zero-Copy Packet Auditing Invariant

--- description: eBPF TC Ring-Buffer Zero-Copy Packet Auditing Invariant - Mandates kernel-space Traffic Control (TC) ingress/egress BPF-ringbuf allocations using zero-copy reservation primitives (bpf_ringbuf_reserve/bpf_ringbuf_submit) rather than legacy perf-event buffers. Guarantees container egress audits sustain high-rate network spikes with sub-microsecond latency, deterministic memory bounds, and zero socket packet drop rates under buffer saturation. globs: **/*.bpf.c, **/*.bpf.h, pkg/ebpf/**/*.go, src/bpf/**/*.c alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-tc-ringbuf-packet-auditing-standard" --- # eBPF TC Ring-Buffer Zero-Copy Packet Auditing Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Utilizing Legacy Perf-Event Arrays or Unchecked Ring-Buffer Allocations in High-Throughput TC Filters ## System Constraints You are a Principal Systems Architect enforcing kernel-space eBPF Traffic Control (TC) invariants. Mandate zero-copy ring-buffer allocations, explicit backpressure handling, and fail-open packet delivery to eliminate frame dropping and kernel contention during container egress spikes. ## Strict Guidelines - Engineers MUST ALWAYS use `BPF_MAP_TYPE_RINGBUF` instead of legacy `BPF_MAP_TYPE_PERF_EVENT_ARRAY` for multi-core packet auditing to prevent cross-CPU memory fragmentation and per-CPU ring exhaustion. - Engineers MUST ALWAYS allocate event payload memory with `bpf_ringbuf_reserve()` and finalize with `bpf_ringbuf_submit()`, avoiding intermediate stack copies and redundant `bpf_ringbuf_output()` memory duplication. - Code MUST strictly check the return pointer of `bpf_ringbuf_reserve()`; if allocation fails due to ring saturation, the filter MUST increment a dedicated atomic drop counter map and return `TC_ACT_OK` to preserve network flow. - Engineers MUST NOT abort or drop network packets with `TC_ACT_SHOT` due to telemetry buffer exhaustion or ring-buffer allocation failures. - Components MUST size ring buffers to a power-of-two page multiple (e.g., `1 << 24` bytes) and specify `BPF_RINGBUF_BUSY_BIT` considerations to guarantee lockless atomic page-boundary wrap-arounds. ## Bad vs Good Implementations ### Kernel TC Filter Ring-Buffer Reservation vs Perf Output #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using BPF_MAP_TYPE_PERF_EVENT_ARRAY incurs per-CPU buffer waste, requires copying data onto the eBPF stack, and triggers CPU cache contention. Returning TC_ACT_SHOT on logging failure drops customer socket frames when telemetry overflows. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h> struct event { __u32 src_ip; __u32 dst_ip; __u16 pkt_len; }; struct { __uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY); __uint(key_size, sizeof(__u32)); __uint(value_size, sizeof(__u32)); } audit_events SEC(".maps"); SEC("tc/egress") int audit_egress_bad(struct __sk_buff *skb) { struct event evt = {}; evt.pkt_len = skb->len; evt.src_ip = skb->remote_ip4; evt.dst_ip = skb->local_ip4; // ANTI-PATTERN: Heavy per-CPU perf buffer copies trigger high cache // bouncing and frame drops under burst spikes; dropping packet on buffer failure. long ret = bpf_perf_event_output(skb, &audit_events, BPF_F_CURRENT_CPU, &evt, sizeof(evt)); if (ret < 0) { return TC_ACT_SHOT; // FAILS INVARIANT: Network traffic dropped due to telemetry failure! } return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: Implements BPF_MAP_TYPE_RINGBUF with zero-copy bpf_ringbuf_reserve/submit, handles backpressure by incrementing an isolated per-CPU drop counter, and strictly returns TC_ACT_OK to guarantee non-blocking network throughput. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h> struct audit_event_t { __u32 src_ip; __u32 dst_ip; __u16 pkt_len; __u16 pad; }; struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 24); // 16MB ring buffer (power-of-2 pages) } audit_ringbuf SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __type(key, __u32); __type(value, __u64); __uint(max_entries, 1); } audit_drops SEC(".maps"); SEC("tc/egress") int audit_egress_good(struct __sk_buff *skb) { struct audit_event_t *evt; // Zero-copy reservation directly inside the shared multi-consumer ring buffer evt = bpf_ringbuf_reserve(&audit_ringbuf, sizeof(*evt), 0); if (!evt) { // Backpressure invariant: record drop metric and fail-open __u32 key = 0; __u64 *drop_count = bpf_map_lookup_elem(&audit_drops, &key); if (drop_count) { __sync_fetch_and_add(drop_count, 1); } return TC_ACT_OK; // GUARANTEE: Never drop production packets for telemetry } evt->pkt_len = (__u16)skb->len; evt->src_ip = skb->remote_ip4; evt->dst_ip = skb->local_ip4; evt->pad = 0; bpf_ringbuf_submit(evt, 0); return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Ring-Buffer Zero-Copy Packet Auditing Invariant

eBPF TC Ring-Buffer Zero-Copy Packet Auditing Invariant defines an industrial-grade behavioral standard for devops engineering. Mandates kernel-space Traffic Control (TC) ingress/egress BPF-ringbuf allocations using zero-copy reservation primitives (bpf_ringbuf_reserve/bpf_ringbuf_submit) rather than legacy perf-event buffers. Guarantees container egress audits sustain high-rate network spikes with sub-microsecond latency, deterministic memory bounds, and zero socket packet drop rates under buffer saturation. 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: Utilizing Legacy Perf-Event Arrays or Unchecked Ring-Buffer Allocations in High-Throughput TC Filters 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	Utilizing Legacy Perf-Event Arrays or Unchecked Ring-Buffer Allocations in High-Throughput TC Filters	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 use `BPF_MAP_TYPE_RINGBUF` instead of legacy `BPF_MAP_TYPE_PERF_EVENT_ARRAY` for multi-core packet auditing to prevent cross-CPU memory fragmentation and per-CPU ring exhaustion.

Engineers MUST ALWAYS use `BPF_MAP_TYPE_RINGBUF` instead of legacy `BPF_MAP_TYPE_PERF_EVENT_ARRAY` for multi-core packet auditing to prevent cross-CPU memory fragmentation and per-CPU ring exhaustion.

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.