AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: ebpf-tc-ringbuf-bounded-allocation-standard

eBPF TC Ingress Ring-Buffer Bounded Allocation Standard

Enforces verifier-guaranteed static memory caps and deterministic reservation lifecycles on eBPF Traffic Control (TC) ingress ring-buffers. Prevents kernel memory exhaustion (RLIMIT_MEMLOCK saturation) and page allocation stalls during 100GbE+ ingress packet floods by guaranteeing compile-time bounded sample reservation and strict paired discard/submit paths.

Prohibited Anti-Pattern: Unbounded or Dynamic skb Slicing in bpf_ringbuf_reserve Without Strict Verifier Bounds or Discard Guarantees

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: eBPF TC Ingress Ring-Buffer Bounded Allocation Standard - Enforces verifier-guaranteed static memory caps and deterministic reservation lifecycles on eBPF Traffic Control (TC) ingress ring-buffers. Prevents kernel memory exhaustion (RLIMIT_MEMLOCK saturation) and page allocation stalls during 100GbE+ ingress packet floods by guaranteeing compile-time bounded sample reservation and strict paired discard/submit paths.
globs: **/*.bpf.c, **/*.bpf.h, src/bpf/**/*.c, pkg/ebpf/**/*.go, bpf/**/*.rs
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/ebpf-tc-ringbuf-bounded-allocation-standard"
---

# eBPF TC Ingress Ring-Buffer Bounded Allocation Standard

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Unbounded or Dynamic skb Slicing in bpf_ringbuf_reserve Without Strict Verifier Bounds or Discard Guarantees

## System Constraints
You are a Principal Software Architect and Linux Kernel Networking specialist enforcing strict eBPF TC Ingress Ring-Buffer bounded allocation invariants. Ingress TC programs execute under SoftIRQ context at critical packet line rates; any memory bloat, dynamic ringbuf allocation without verifier-proven upper bounds, or leaked reservation will trigger memory lock starvation, ring-buffer drops, or kernel soft lockups. Mandate absolute static bounds, power-of-two page-aligned capacity, compile-time max reservation sizes, and rigorous paired submission/discard paths.

## Strict Guidelines
- Engineers MUST ALWAYS declare BPF_MAP_TYPE_RINGBUF max_entries as a power-of-two multiple of the target architecture page size (PAGE_SIZE), with hard upper bounds verified against production RLIMIT_MEMLOCK limits.
- Engineers MUST ALWAYS use compile-time constants or strict bitwise verifier masks (e.g., `payload_len & MAX_PAYLOAD_MASK`) when passing size parameters to bpf_ringbuf_reserve.
- Engineers MUST NOT attempt to reserve raw dynamic skb->len bytes in bpf_ringbuf_reserve without clamping against an invariant maximum truncated ceiling.
- Engineers MUST ALWAYS guarantee every successful bpf_ringbuf_reserve() invocation terminates in either bpf_ringbuf_submit() or bpf_ringbuf_discard() on ALL branching paths.
- Code SHOULD prefer static header allocations with fixed metadata buffers over dynamic-sized ring-buffer payload reservations.
- Services MUST drop or count dropped ingress events via BPF per-CPU telemetry counters when bpf_ringbuf_reserve returns NULL instead of blocking or retrying in kernel space.
- Components NEVER allocate memory exceeding 4096 bytes per single ring-buffer reservation within TC ingress to avoid packet processing latency spikes and ring cache thrashing.

## Bad vs Good Implementations
### TC Ingress Ring-Buffer Reservation: Dynamic Unbounded vs Verifier-Bounded Clamp

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: The map size is not power-of-two page aligned, violating BPF ring-buffer constraints. skb->len is passed directly without bounded verifier limits, allowing multi-kilobyte dynamic reservations during ingress bursts that exhaust ring space. If bpf_skb_load_bytes fails, the function returns without bpf_ringbuf_discard, causing permanent ring-buffer reservation leakage in kernel space.
```c
#include <linux/bpf.h>
#include <bpf/bpf_helpers.h>

struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, 1000000); // Anti-pattern: Non-power-of-two size violates kernel page alignment
} events SEC(".maps");

SEC("tc")
int tc_ingress_monitor(struct __sk_buff *skb) {
    __u32 len = skb->len; // Anti-pattern: Unbounded packet length from skb

    // Vulnerable: Variable length without verifier bounds causes ring memory starvation
    void *data = bpf_ringbuf_reserve(&events, len, 0);
    if (!data) {
        return BPF_OK;
    }

    // Anti-pattern: Error paths or partial writes leak reservation without discard
    if (bpf_skb_load_bytes(skb, 0, data, len) < 0) {
        return BPF_DROP; // Leaked ringbuf memory! Verifier/kernel leak
    }

    bpf_ringbuf_submit(data, 0);
    return BPF_OK;
}
```

#### Production Standard (Correct)
> **Standard**: Declares map capacity as an explicit power-of-two page-aligned size (16MB). Reserves a compile-time fixed struct size (`sizeof(*sample)`), precluding verifier range blowouts and unconstrained kernel allocations. Clamps the read payload to MAX_PAYLOAD_SIZE with strict verifier bounds. Accurately calls bpf_ringbuf_discard() on error paths to eliminate memory leaks.
```c
#include <linux/bpf.h>
#include <bpf/bpf_helpers.h>

#define MAX_PAYLOAD_SIZE 256
#define PAYLOAD_MASK     0x00FF
#define RINGBUF_SIZE     (1 << 24) /* 16MB: Power-of-two, page-aligned */

struct event_sample {
    __u32 pkt_len;
    __u16 capture_len;
    __u8  payload[MAX_PAYLOAD_SIZE];
};

struct {
    __uint(type, BPF_MAP_TYPE_RINGBUF);
    __uint(max_entries, RINGBUF_SIZE);
} events SEC(".maps");

SEC("tc")
int tc_ingress_monitor(struct __sk_buff *skb) {
    __u32 total_len = skb->len;
    // Invariant: Verifier-guaranteed static bound using bitwise mask
    __u16 capture_len = total_len > MAX_PAYLOAD_SIZE ? MAX_PAYLOAD_SIZE : (total_len & PAYLOAD_MASK);

    struct event_sample *sample = bpf_ringbuf_reserve(&events, sizeof(*sample), 0);
    if (!sample) {
        // Deterministic tail-drop on saturation: Never stall TC processing
        return BPF_OK;
    }

    sample->pkt_len = total_len;
    sample->capture_len = capture_len;

    // Guaranteed bounds-checked payload extraction
    if (bpf_skb_load_bytes(skb, 0, sample->payload, capture_len) < 0) {
        bpf_ringbuf_discard(sample, BPF_RB_NO_WAKEUP);
        return BPF_OK;
    }

    bpf_ringbuf_submit(sample, 0);
    return BPF_OK;
}
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

eBPF Verifier & Kernel Trace MCP
Validates eBPF bytecode against Linux kernel verifier constraints, memory limits, and map allocation parameters before compilation.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

bpftool Map & Program Inspector
CLI utility for inspecting BPF maps, memory lock quotas (RLIMIT_MEMLOCK), ringbuf consumption, and verifier assembly traces.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Ingress Ring-Buffer Bounded Allocation Standard

eBPF TC Ingress Ring-Buffer Bounded Allocation Standard defines an industrial-grade behavioral standard for devops engineering. Enforces verifier-guaranteed static memory caps and deterministic reservation lifecycles on eBPF Traffic Control (TC) ingress ring-buffers. Prevents kernel memory exhaustion (RLIMIT_MEMLOCK saturation) and page allocation stalls during 100GbE+ ingress packet floods by guaranteeing compile-time bounded sample reservation and strict paired discard/submit paths. 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: Unbounded or Dynamic skb Slicing in bpf_ringbuf_reserve Without Strict Verifier Bounds or Discard Guarantees 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftUnbounded or Dynamic skb Slicing in bpf_ringbuf_reserve Without Strict Verifier Bounds or Discard GuaranteesCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS declare BPF_MAP_TYPE_RINGBUF max_entries as a power-of-two multiple of the target architecture page size (PAGE_SIZE), with hard upper bounds verified against production RLIMIT_MEMLOCK limits.

Engineers MUST ALWAYS declare BPF_MAP_TYPE_RINGBUF max_entries as a power-of-two multiple of the target architecture page size (PAGE_SIZE), with hard upper bounds verified against production RLIMIT_MEMLOCK limits.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST ALWAYS use compile-time constants or strict bitwise verifier masks (e.g., `payload_len & MAX_PAYLOAD_MASK`) when passing size parameters to bpf_ringbuf_reserve.

Engineers MUST ALWAYS use compile-time constants or strict bitwise verifier masks (e.g., `payload_len & MAX_PAYLOAD_MASK`) when passing size parameters to bpf_ringbuf_reserve.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Engineers MUST NOT attempt to reserve raw dynamic skb->len bytes in bpf_ringbuf_reserve without clamping against an invariant maximum truncated ceiling.

Engineers MUST NOT attempt to reserve raw dynamic skb->len bytes in bpf_ringbuf_reserve without clamping against an invariant maximum truncated ceiling.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Engineers MUST ALWAYS guarantee every successful bpf_ringbuf_reserve() invocation terminates in either bpf_ringbuf_submit() or bpf_ringbuf_discard() on ALL branching paths.

Engineers MUST ALWAYS guarantee every successful bpf_ringbuf_reserve() invocation terminates in either bpf_ringbuf_submit() or bpf_ringbuf_discard() on ALL branching paths.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Code SHOULD prefer static header allocations with fixed metadata buffers over dynamic-sized ring-buffer payload reservations.

Code SHOULD prefer static header allocations with fixed metadata buffers over dynamic-sized ring-buffer payload reservations.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
6

Services MUST drop or count dropped ingress events via BPF per-CPU telemetry counters when bpf_ringbuf_reserve returns NULL instead of blocking or retrying in kernel space.

Services MUST drop or count dropped ingress events via BPF per-CPU telemetry counters when bpf_ringbuf_reserve returns NULL instead of blocking or retrying in kernel space.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
7

Components NEVER allocate memory exceeding 4096 bytes per single ring-buffer reservation within TC ingress to avoid packet processing latency spikes and ring cache thrashing.

Components NEVER allocate memory exceeding 4096 bytes per single ring-buffer reservation within TC ingress to avoid packet processing latency spikes and ring cache thrashing.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is eBPF TC Ingress Ring-Buffer Bounded Allocation Standard critical for AI coding assistants?

Enforces verifier-guaranteed static memory caps and deterministic reservation lifecycles on eBPF Traffic Control (TC) ingress ring-buffers. Prevents kernel memory exhaustion (RLIMIT_MEMLOCK saturation) and page allocation stalls during 100GbE+ ingress packet floods by guaranteeing compile-time bounded sample reservation and strict paired discard/submit paths. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded or Dynamic skb Slicing in bpf_ringbuf_reserve Without Strict Verifier Bounds or Discard Guarantees) 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.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

eBPF