OpenTelemetry Baggage Ingress Sanitization and Boundary Defense

--- description: OpenTelemetry Baggage Ingress Sanitization and Boundary Defense - Enforces strict boundary validation and stripping of untrusted W3C Baggage HTTP headers at API gateways and perimeter ingress proxies. Prevents trace context poisoning, privilege escalation via contextual spoofing, and memory exhaustion caused by unbounded baggage propagation across downstream distributed microservices. globs: src/middleware/**/*.{ts,js}, src/gateway/**/*.{ts,js}, src/tracing/**/*.{ts,js}, apps/api/src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-baggage-ingress-sanitization-standard" --- # OpenTelemetry Baggage Ingress Sanitization and Boundary Defense > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Blind Context Propagation of Untrusted Ingress Baggage Headers into Internal Tracing Spans ## System Constraints You are a Principal Software Architect enforcing the OpenTelemetry Baggage Header Ingress Sanitization Standard. Untrusted external clients must never dictate baggage state in internal service meshes. Ensure all edge and gateway layers explicitly drop, validate, or filter W3C baggage headers according to strict allowlists, maximum size constraints, and key-format specifications before propagating context downstream. ## Strict Guidelines - Edge API Gateways MUST drop untrusted external `baggage` headers by default unless the request is cryptographically authenticated and explicitly permitted. - Engineers MUST NOT pass raw `req.headers['baggage']` or `req.headers` directly to OpenTelemetry `propagation.extract()` at edge boundaries without an intermediary sanitization step. - When baggage pass-through is required, services MUST apply a strict allowlist matching expected key regex patterns (e.g., `^[a-z0-9_\-\.]{1,32}$`). - Services MUST enforce strict resource bounds on baggage payloads: maximum 8192 total bytes, maximum 16 key-value pairs, and maximum 256 bytes per value. - Components NEVER store sensitive internal tokens, PII, authorization scopes, or unhashed identifiers inside baggage entries propagated to external downstream destinations. - Sanitization layers MUST log security telemetry warnings with rate-limiting when malformed or oversized baggage headers are intercepted at ingress points. ## Bad vs Good Implementations ### Sanitizing W3C Baggage Headers at API Gateway Ingress #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw request headers are extracted without sanitization. An external attacker can inject arbitrary keys (e.g., internal-routing-flags, malicious baggage properties) or send an oversized payload that propagates to all downstream internal RPCs, causing context poisoning and high memory consumption. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation } from '@opentelemetry/api'; // ANTI-PATTERN: Blindly extracting untrusted baggage headers from public clients export function tracingMiddleware(req: Request, res: Response, next: NextFunction): void { // Directly extracting untrusted HTTP headers propagates arbitrary baggage // into the active context, enabling unbounded memory allocation and context spoofing. const extractedContext = propagation.extract(context.active(), req.headers); context.with(extractedContext, () => { next(); }); } ``` #### Production Standard (Correct) > **Standard**: Validates incoming baggage against strict security invariants: drops payloads exceeding 2KB, enforces an entry count cap of 8, strictly checks keys against an immutable allowlist, limits value length, and purges untrusted entry metadata before activating the OpenTelemetry execution context. ```typescript import { Request, Response, NextFunction } from 'express'; import { context, propagation, Baggage, BaggageEntry } from '@opentelemetry/api'; const ALLOWED_BAGGAGE_KEYS = new Set(['tenant_id', 'client_version', 'traffic_source']); const MAX_BAGGAGE_BYTES = 2048; const MAX_ENTRIES = 8; const MAX_VALUE_LENGTH = 128; export function sanitizeBaggageMiddleware(req: Request, res: Response, next: NextFunction): void { const rawBaggage = req.headers['baggage']; // Extract existing propagation context (traceparent) using only safe extractors const parentContext = propagation.extract(context.active(), req.headers); const currentBaggage = propagation.getBaggage(parentContext); if (!rawBaggage || !currentBaggage) { // No baggage or parsing yielded null: propagate parent context without baggage const cleanContext = propagation.deleteBaggage(parentContext); context.with(cleanContext, () => next()); return; } const rawBaggageString = Array.isArray(rawBaggage) ? rawBaggage.join(',') : rawBaggage; if (Buffer.byteLength(rawBaggageString, 'utf8') > MAX_BAGGAGE_BYTES) { // Exceeded maximum byte limit; discard completely to prevent memory exhaustion const cleanContext = propagation.deleteBaggage(parentContext); context.with(cleanContext, () => next()); return; } // Build a sanitized baggage instance conforming strictly to allowlists let sanitizedBaggage: Baggage = propagation.createBaggage(); let entryCount = 0; for (const [key, entry] of currentBaggage.getAllEntries()) { if (entryCount >= MAX_ENTRIES) break; if (ALLOWED_BAGGAGE_KEYS.has(key) && entry.value.length <= MAX_VALUE_LENGTH) { const sanitizedEntry: BaggageEntry = { value: entry.value, metadata: undefined, // Strip untrusted client metadata }; sanitizedBaggage = sanitizedBaggage.setEntry(key, sanitizedEntry); entryCount++; } } const safeContext = propagation.setBaggage(parentContext, sanitizedBaggage); context.with(safeContext, () => next()); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Baggage Ingress Sanitization and Boundary Defense

OpenTelemetry Baggage Ingress Sanitization and Boundary Defense defines an industrial-grade behavioral standard for devops engineering. Enforces strict boundary validation and stripping of untrusted W3C Baggage HTTP headers at API gateways and perimeter ingress proxies. Prevents trace context poisoning, privilege escalation via contextual spoofing, and memory exhaustion caused by unbounded baggage propagation across downstream distributed microservices. 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: Blind Context Propagation of Untrusted Ingress Baggage Headers into Internal Tracing Spans 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	Blind Context Propagation of Untrusted Ingress Baggage Headers into Internal Tracing Spans	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:

Edge API Gateways MUST drop untrusted external `baggage` headers by default unless the request is cryptographically authenticated and explicitly permitted.

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.