SPIFFE/SPIRE Ephemeral x509-SVID Workload Federation Standard

--- description: SPIFFE/SPIRE Ephemeral x509-SVID Workload Federation Standard - Enforces short-lived, cryptographically verifiable x509-SVIDs acquired via local SPIRE Agent Workload API Unix Domain Sockets for all inter-workload and cross-cloud communication. Forbids baking static IAM credentials, long-lived API tokens, or pre-shared keys into deployments. Mandates automated mTLS handshake negotiation using dynamically rotated SPIFFE bundles across federated trust domains. globs: src/**/*.{ts,js,go,py}, infra/**/*.{tf,yaml,json}, k8s/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-x509-svid-federation-guardrail" --- # SPIFFE/SPIRE Ephemeral x509-SVID Workload Federation Standard > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Baking Static Cross-Cloud IAM Keys or Skipping SPIFFE Workload API Dynamic Rotation ## System Constraints You are a Principal Security Architect enforcing zero-trust SPIFFE/SPIRE x509-SVID workload identities. Forbid hardcoded long-lived credentials, static cloud access keys (e.g., AWS IAM Secret Keys, GCP Service Account JSON keys), and long-lived client TLS certificates. Mandate dynamic retrieval of x509-SVIDs and federated trust bundles via the SPIFFE Workload API Unix Domain Socket (/tmp/spire-agent/public/api.sock). Ensure in-memory rotation on SVID expiration without process restarts, enforcing strict SAN validation against expected SPIFFE IDs (spiffe://<trust-domain>/<workload-path>). ## Strict Guidelines - Services MUST ALWAYS connect to the SPIRE Agent through the standard Unix Domain Socket (Workload API) to fetch dynamic x509-SVIDs and federated trust bundles. - Engineers MUST NOT store cloud IAM access keys, static secrets, or long-lived private keys in filesystems, environment variables, or configmaps. - Workloads MUST validate peer SPIFFE IDs during mTLS handshakes against an exact trust domain and authorized workload path policy. - Applications MUST handle x509-SVID certificate rotation in-memory using event-driven watchers on the Workload API stream without terminating TCP connections or requiring pod restarts. - Federated cross-cloud calls MUST exchange short-lived federated SPIFFE x509-SVIDs or exchange SVIDs for short-lived cloud STS tokens (e.g., AWS Web Identity Federation / GCP Workload Identity Federation) via OIDC-SVID. - TLS listeners and clients MUST NEVER disable peer verification (`rejectUnauthorized: false` or `InsecureSkipVerify: true`). ## Bad vs Good Implementations ### Cross-Workload Mutual TLS Client Identity Setup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on static on-disk certificates with manual lifecycle management and static API keys, completely violating the zero-trust ephemeral identity requirement and leaving keys vulnerable to exfiltration. ```typescript import https from 'node:https'; import fs from 'node:fs'; // ANTI-PATTERN: Using long-lived static certificates mounted from disk or secrets const options: https.RequestOptions = { hostname: 'payment-service.internal', port: 8443, path: '/process', method: 'POST', key: fs.readFileSync('/etc/ssl/certs/static-private-key.pem'), cert: fs.readFileSync('/etc/ssl/certs/static-client-cert.pem'), ca: fs.readFileSync('/etc/ssl/certs/ca-bundle.pem'), headers: { // ANTI-PATTERN: Static cross-cloud API secret fallback 'X-API-Key': process.env.STATIC_CLOUD_SECRET ?? 'fallback-insecure-key' } }; export function sendPayment(data: unknown): void { const req = https.request(options); req.write(JSON.stringify(data)); req.end(); } ``` #### Production Standard (Correct) > **Standard**: Connects to the local SPIRE Agent Unix Domain Socket, continuously listening for certificate rotation events. Configures in-memory ephemeral TLS secure context with zero disk persistence and strictly validates peer SPIFFE IDs during mTLS. ```typescript import tls from 'node:tls'; import https from 'node:https'; import { WorkloadApiClient } from '@spiffe/workload-api'; // Standard Workload API client // PRODUCTION INVARIANT: Ephemeral in-memory SVID rotation via SPIRE Workload API export class FederatedSpiffeHttpsClient { private tlsContext: tls.SecureContext | null = null; private expectedServerSpiffeId = 'spiffe://finance.prod/service/payment'; constructor(private readonly socketPath: string = '/tmp/spire-agent/public/api.sock') {} public async initialize(): Promise<void> { const client = new WorkloadApiClient({ socketPath: this.socketPath }); // Stream updates: rotatable x509-SVID & federated trust bundles client.watchX509Context((x509Context) => { const defaultSvid = x509Context.defaultSvid; const bundle = x509Context.bundles.get('finance.prod'); if (!defaultSvid || !bundle) { throw new Error('Required SPIFFE SVID or federated trust bundle missing'); } this.tlsContext = tls.createSecureContext({ cert: defaultSvid.certChain, key: defaultSvid.privateKey, ca: bundle.bundleX509Authorities }); }); } public request(endpoint: string, payload: unknown): https.ClientRequest { if (!this.tlsContext) { throw new Error('TLS SecureContext not initialized from SPIRE Workload API'); } return https.request(endpoint, { method: 'POST', secureContext: this.tlsContext, checkServerIdentity: (host, cert) => { // Enforce SAN SPIFFE ID verification const uriSans = cert.subjectaltname?.split(', ').filter(s => s.startsWith('URI:')) ?? []; const hasValidSpiffeId = uriSans.includes(`URI:${this.expectedServerSpiffeId}`); if (!hasValidSpiffeId) { return new Error(`Peer SPIFFE ID mismatch: expected ${this.expectedServerSpiffeId}`); } return undefined; } }, (res) => { res.resume(); }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Ephemeral x509-SVID Workload Federation Standard

SPIFFE/SPIRE Ephemeral x509-SVID Workload Federation Standard defines an industrial-grade behavioral standard for security engineering. Enforces short-lived, cryptographically verifiable x509-SVIDs acquired via local SPIRE Agent Workload API Unix Domain Sockets for all inter-workload and cross-cloud communication. Forbids baking static IAM credentials, long-lived API tokens, or pre-shared keys into deployments. Mandates automated mTLS handshake negotiation using dynamically rotated SPIFFE bundles across federated trust domains. 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: Baking Static Cross-Cloud IAM Keys or Skipping SPIFFE Workload API Dynamic Rotation 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	Baking Static Cross-Cloud IAM Keys or Skipping SPIFFE Workload API Dynamic Rotation	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:

Services MUST ALWAYS connect to the SPIRE Agent through the standard Unix Domain Socket (Workload API) to fetch dynamic x509-SVIDs and federated trust bundles.

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.