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-uretprobe-goroutine-stack-unwinding-guardrail

eBPF uretprobe Goroutine Stack Unwinding Trampoline Guardrail

Attaching standard kernel uretprobes to Go binaries corrupts runtime execution because the kernel trampoline overrides return addresses on non-standard, dynamically resized Go runtime stacks. In high-concurrency environments, this triggers fatal runtime panics such as 'runtime: g 1: frame SP out of range' or silent memory corruption during goroutine stack unwinding and growth. Telemetry agents must reject raw uretprobes on Go symbols and instead deploy dual-entry uprobes or uprobes paired with manual DWARF-based return-offset interception.

Prohibited Anti-Pattern: Attaching raw eBPF uretprobes to Go binaries causing corrupted goroutine stack pointers and fatal runtime panics

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: eBPF uretprobe Goroutine Stack Unwinding Trampoline Guardrail - Attaching standard kernel uretprobes to Go binaries corrupts runtime execution because the kernel trampoline overrides return addresses on non-standard, dynamically resized Go runtime stacks. In high-concurrency environments, this triggers fatal runtime panics such as 'runtime: g 1: frame SP out of range' or silent memory corruption during goroutine stack unwinding and growth. Telemetry agents must reject raw uretprobes on Go symbols and instead deploy dual-entry uprobes or uprobes paired with manual DWARF-based return-offset interception.
globs: **/ebpf/**/*.go, **/bpf/**/*.c, **/probes/**/*.go, **/telemetry/**/*.go, **/tracer/**/*.go
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/ebpf-uretprobe-goroutine-stack-unwinding-guardrail"
---

# eBPF uretprobe Goroutine Stack Unwinding Trampoline Guardrail

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Attaching raw eBPF uretprobes to Go binaries causing corrupted goroutine stack pointers and fatal runtime panics

## System Constraints
You are a Principal Systems Engineer and Kernel Telemetry Architect enforcing non-invasive tracing guardrails for high-concurrency Go binaries. You must prohibit the registration of standard uretprobes against Go applications due to runtime stack relocation and goroutine green-thread scheduling conflicts. Enforce manual return-address resolution via entry uprobes reading the function prologue and epilogue offsets, or reject probe attachment entirely when Go binaries are detected.

## Strict Guidelines
- Engineers MUST NEVER attach standard kernel uretprobes (BPF_PROG_TYPE_KPROBE with retprobe flag) to functions in Go ELF binaries.
- Engineers MUST inspect the target binary's ELF sections and build metadata for Go runtime symbols (.note.go.buildid or runtime.g) prior to probe attachment.
- Telemetry loaders MUST use entry uprobes on all function exit points (RET instructions identified via DWARF/disassembly) instead of kernel return trampolines.
- BPF programs MUST identify goroutine context using the runtime g pointer extracted from thread-local storage (FS/GS register base offsets) rather than OS thread PID/TID alone.
- Probe instrumentation MUST verify that goroutine stack growth boundaries (g.stackguard0) are not masked or desynchronized during stack unwinding.
- Instrumentation pipelines MUST fail closed and log a critical error if a dynamic probe configuration requests a uretprobe on an application runtime identified as Go.

## Bad vs Good Implementations
### Safe Function Exit Tracing in Go Binaries via Exit Disassembly vs Raw uretprobe

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Standard uretprobes rewrite the return address on the stack to point to a kernel trampoline. When Go moves or copies the segmented goroutine stack during runtime.morestack, the trampoline address breaks runtime stack verification and causes an unrecoverable process crash.
```go
package tracer

import (
	"github.com/cilium/ebpf/link"
	"debug/elf"
)

func AttachGoTrace(executable *link.Executable, sym string) (link.Link, error) {
	// CRITICAL FAILURE: Attaching standard uretprobe to Go binary.
	// Kernel injects trampoline return address into goroutine stack frame,
	// causing runtime panic during stack growth or runtime.morestack calls.
	return executable.Uretprobe(sym, bpfExitProgram, nil)
}
```

#### Production Standard (Correct)
> **Standard**: By locating native RET instructions via binary analysis and attaching standard uprobes at those explicit offsets, the kernel never modifies stack return pointers, preserving goroutine stack integrity during growth and context switching.
```go
package tracer

import (
	"fmt"
	"debug/elf"
	"github.com/cilium/ebpf/link"
)

func AttachGoTrace(executable *link.Executable, elfFile *elf.File, sym string) ([]link.Link, error) {
	// INVARIANT: Detect Go runtime signature
	if sec := elfFile.Section(".note.go.buildid"); sec == nil {
		return nil, fmt.Errorf("target is not a verified Go binary")
	}

	// Locate all native RET instructions within the target function boundary
	exitOffsets, err := findFunctionRetOffsets(elfFile, sym)
	if err != nil {
		return nil, fmt.Errorf("failed to locate RET instructions for %s: %w", sym, err)
	}

	var links []link.Link
	// Attach standard entry uprobes exclusively at function exit offsets
	for _, offset := range exitOffsets {
		l, err := executable.Uprobe(sym, bpfExitProgram, &link.UprobeOptions{
			Address: offset,
		})
		if err != nil {
			return nil, fmt.Errorf("failed uprobe at offset 0x%x: %w", offset, err)
		}
		links = append(links, l)
	}
	return links, nil
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

eBPF Binary & Symbol Analyzer
Inspects ELF headers, DWARF symbols, and goroutine layouts to validate eBPF probe safety before deployment.
Recommended Agent Skills (askills.dev)

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

bpftool Link Inspector
Audits active kernel uprobe and uretprobe attachments against target process PIDs and mount namespaces.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF uretprobe Goroutine Stack Unwinding Trampoline Guardrail

eBPF uretprobe Goroutine Stack Unwinding Trampoline Guardrail defines an industrial-grade behavioral standard for devops engineering. Attaching standard kernel uretprobes to Go binaries corrupts runtime execution because the kernel trampoline overrides return addresses on non-standard, dynamically resized Go runtime stacks. In high-concurrency environments, this triggers fatal runtime panics such as 'runtime: g 1: frame SP out of range' or silent memory corruption during goroutine stack unwinding and growth. Telemetry agents must reject raw uretprobes on Go symbols and instead deploy dual-entry uprobes or uprobes paired with manual DWARF-based return-offset interception. 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: Attaching raw eBPF uretprobes to Go binaries causing corrupted goroutine stack pointers and fatal runtime panics 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 DriftAttaching raw eBPF uretprobes to Go binaries causing corrupted goroutine stack pointers and fatal runtime panicsCritical
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 NEVER attach standard kernel uretprobes (BPF_PROG_TYPE_KPROBE with retprobe flag) to functions in Go ELF binaries.

Engineers MUST NEVER attach standard kernel uretprobes (BPF_PROG_TYPE_KPROBE with retprobe flag) to functions in Go ELF binaries.

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 inspect the target binary's ELF sections and build metadata for Go runtime symbols (.note.go.buildid or runtime.g) prior to probe attachment.

Engineers MUST inspect the target binary's ELF sections and build metadata for Go runtime symbols (.note.go.buildid or runtime.g) prior to probe attachment.

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

Telemetry loaders MUST use entry uprobes on all function exit points (RET instructions identified via DWARF/disassembly) instead of kernel return trampolines.

Telemetry loaders MUST use entry uprobes on all function exit points (RET instructions identified via DWARF/disassembly) instead of kernel return trampolines.

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

BPF programs MUST identify goroutine context using the runtime g pointer extracted from thread-local storage (FS/GS register base offsets) rather than OS thread PID/TID alone.

BPF programs MUST identify goroutine context using the runtime g pointer extracted from thread-local storage (FS/GS register base offsets) rather than OS thread PID/TID alone.

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

Probe instrumentation MUST verify that goroutine stack growth boundaries (g.stackguard0) are not masked or desynchronized during stack unwinding.

Probe instrumentation MUST verify that goroutine stack growth boundaries (g.stackguard0) are not masked or desynchronized during stack unwinding.

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

Instrumentation pipelines MUST fail closed and log a critical error if a dynamic probe configuration requests a uretprobe on an application runtime identified as Go.

Instrumentation pipelines MUST fail closed and log a critical error if a dynamic probe configuration requests a uretprobe on an application runtime identified as Go.

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 uretprobe Goroutine Stack Unwinding Trampoline Guardrail critical for AI coding assistants?

Attaching standard kernel uretprobes to Go binaries corrupts runtime execution because the kernel trampoline overrides return addresses on non-standard, dynamically resized Go runtime stacks. In high-concurrency environments, this triggers fatal runtime panics such as 'runtime: g 1: frame SP out of range' or silent memory corruption during goroutine stack unwinding and growth. Telemetry agents must reject raw uretprobes on Go symbols and instead deploy dual-entry uprobes or uprobes paired with manual DWARF-based return-offset interception. 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 (Attaching raw eBPF uretprobes to Go binaries causing corrupted goroutine stack pointers and fatal runtime panics) 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