AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
securitycritical PriorityID: spiffe-spire-hardware-attested-envoy-identity-invariant

Hardware-Attested SPIFFE/SPIRE SDS Invariant for Envoy Workload Identity

Mandates that Envoy proxies dynamically consume cryptographic identities exclusively via the Secret Discovery Service (SDS) backed by a local TPM/vTPM-attested SPIRE Agent Unix Domain Socket. Prohibits static TLS mounts, long-lived secrets, and non-hardware node attestations across multi-cluster service meshes. Enforces continuous wire-speed X.509 SVID rotation and exact SPIFFE ID Trust Domain SAN validation.

Prohibited Anti-Pattern: Static File-Mounted Certificates and Token-Attested Envoy Transport Sockets

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: Hardware-Attested SPIFFE/SPIRE SDS Invariant for Envoy Workload Identity - Mandates that Envoy proxies dynamically consume cryptographic identities exclusively via the Secret Discovery Service (SDS) backed by a local TPM/vTPM-attested SPIRE Agent Unix Domain Socket. Prohibits static TLS mounts, long-lived secrets, and non-hardware node attestations across multi-cluster service meshes. Enforces continuous wire-speed X.509 SVID rotation and exact SPIFFE ID Trust Domain SAN validation.
globs: **/envoy/**/*.{ts,js,json,yaml}, **/xds/**/*.{ts,js}, **/spire/**/*.{conf,yaml,ts}, **/mesh/**/*.{ts,js,yaml}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/spiffe-spire-hardware-attested-envoy-identity-invariant"
---

# Hardware-Attested SPIFFE/SPIRE SDS Invariant for Envoy Workload Identity

> **Severity**: CRITICAL | **Category**: security
> **Anti-Pattern Warning**: Static File-Mounted Certificates and Token-Attested Envoy Transport Sockets

## System Constraints
You are a Principal Security Architect enforcing the SPIFFE/SPIRE Hardware-Attested Workload Identity Invariant for Envoy. Mandate that all Envoy workloads dynamically acquire and rotate X.509 SVIDs over a local SPIRE Agent Unix Domain Socket (UDS) attested by hardware TPM 2.0 or vTPM. Forbid static certificate mounting, hardcoded certificates, unauthenticated SDS endpoints, and broad SAN wildcards.

## Strict Guidelines
- Engineers MUST ALWAYS configure Envoy SDS (`envoy.transport_sockets.tls`) referencing the SPIRE Agent Unix Domain Socket (`unix:///run/spire/sockets/agent.sock`) with SDS ApiConfigSource `api_type: GRPC` and `transport_api_version: V3`.
- Engineers MUST NOT mount static X.509 private keys, certificates, or Kubernetes Secret volumes into Envoy workloads or control-plane components.
- Services MUST attest host nodes using TPM 2.0 / vTPM hardware attestation plugins (e.g., `tpm` node attestor with verified endorsement keys) and NEVER rely on static join tokens in production clusters.
- Code SHOULD validate peer identities strictly using `combined_validation_context` with `match_typed_subject_alt_names` validating exact SPIFFE IDs (`spiffe://<trust-domain>/<workload-path>`) rather than wildcard DNS SANs.
- Components NEVER permit SDS communication over unauthenticated TCP loopbacks; communication MUST occur over a Unix Domain Socket with strict filesystem permissions (UID/GID boundary).

## Bad vs Good Implementations
### Configuring Envoy Downstream TLS via SPIRE SDS with Strict SPIFFE SAN Validation

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: This configuration uses static files from the filesystem instead of dynamic SDS. Certificates cannot rotate without container reloads, private keys are exposed on disk, and generic wildcard DNS matching fails to cryptographically bind identity to hardware-attested SPIFFE IDs.
```typescript
// Anti-pattern: Static file mounts, long-lived certificates, and unverified SAN
import { type envoy } from '@envoyproxy/envoy-definitions';

export function createDownstreamTlsContext(): Record<string, unknown> {
  return {
    common_tls_context: {
      tls_certificates: [
        {
          certificate_chain: { filename: '/etc/ssl/certs/tls.crt' },
          private_key: { filename: '/etc/ssl/certs/tls.key' }
        }
      ],
      validation_context: {
        trusted_ca: { filename: '/etc/ssl/certs/ca.crt' },
        match_subject_alt_names: [
          { exact: '*.mesh.internal' } // INSECURE: Wildcard SAN bypasses workload boundary
        ]
      }
    }
  };
}
```

#### Production Standard (Correct)
> **Standard**: Leverages dynamic Envoy SDS referencing the SPIRE agent's Unix Domain Socket. Workload certificates (SVIDs) and trust bundles rotate automatically at wire speed without restart. Invariant verification enforces TPM-backed node attestation and exact URI-based SPIFFE ID validation.
```typescript
// Production standard: Hardware-attested SPIRE SDS via UDS with SPIFFE SAN validation
import { type envoy } from '@envoyproxy/envoy-definitions';

const SPIRE_AGENT_SOCKET = 'unix:///run/spire/sockets/agent.sock';
const TRUST_DOMAIN = 'prod.mesh.company.internal';

export function createDownstreamTlsContext(): Record<string, unknown> {
  const sdsConfigSource = {
    api_config_source: {
      api_type: 'GRPC',
      transport_api_version: 'V3',
      grpc_services: [{
        envoy_grpc: {
          cluster_name: 'spire_agent'
        }
      }]
    },
    resource_api_version: 'V3'
  };

  return {
    common_tls_context: {
      tls_certificate_sds_secret_configs: [
        {
          name: `spiffe://${TRUST_DOMAIN}/ns/workload/sa/envoy-service`,
          sds_config: sdsConfigSource
        }
      ],
      combined_validation_context: {
        default_validation_context: {
          match_typed_subject_alt_names: [
            {
              san_type: 'URI',
              matcher: {
                exact: `spiffe://${TRUST_DOMAIN}/ns/workload/sa/authorized-client`
              }
            }
          ]
        },
        validation_context_sds_secret_config: {
          name: `spiffe://${TRUST_DOMAIN}`,
          sds_config: sdsConfigSource
        }
      }
    }
  };
}
```
Recommended MCP Servers (mcp-serverlist.com)

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

SPIFFE/SPIRE Cluster Verifier MCP
Verifies TPM 2.0 endorsement keys, node attestation records, and active SVID lease expirations across mesh clusters.
Envoy xDS Security Linter MCP
Audits dynamic xDS listener and cluster configurations to verify SDS compliance and prohibit insecure static TLS mounts.
Recommended Agent Skills (askills.dev)

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

SPIRE Agent Health and SVID Diagnostic Skill
CLI automation to validate UDS socket permissions, TPM PCR quotes, and active Envoy SDS stream subscriptions.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hardware-Attested SPIFFE/SPIRE SDS Invariant for Envoy Workload Identity

Hardware-Attested SPIFFE/SPIRE SDS Invariant for Envoy Workload Identity defines an industrial-grade behavioral standard for security engineering. Mandates that Envoy proxies dynamically consume cryptographic identities exclusively via the Secret Discovery Service (SDS) backed by a local TPM/vTPM-attested SPIRE Agent Unix Domain Socket. Prohibits static TLS mounts, long-lived secrets, and non-hardware node attestations across multi-cluster service meshes. Enforces continuous wire-speed X.509 SVID rotation and exact SPIFFE ID Trust Domain SAN validation. 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: Static File-Mounted Certificates and Token-Attested Envoy Transport Sockets 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 DriftStatic File-Mounted Certificates and Token-Attested Envoy Transport SocketsCritical
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 configure Envoy SDS (`envoy.transport_sockets.tls`) referencing the SPIRE Agent Unix Domain Socket (`unix

Engineers MUST ALWAYS configure Envoy SDS (`envoy.transport_sockets.tls`) referencing the SPIRE Agent Unix Domain Socket (`unix:///run/spire/sockets/agent.sock`) with SDS ApiConfigSource `api_type: GRPC` and `transport_api_version: V3`.

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 NOT mount static X.509 private keys, certificates, or Kubernetes Secret volumes into Envoy workloads or control-plane components.

Engineers MUST NOT mount static X.509 private keys, certificates, or Kubernetes Secret volumes into Envoy workloads or control-plane components.

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

Services MUST attest host nodes using TPM 2.0 / vTPM hardware attestation plugins (e.g., `tpm` node attestor with verified endorsement keys) and NEVER rely on static join tokens in production clusters.

Services MUST attest host nodes using TPM 2.0 / vTPM hardware attestation plugins (e.g., `tpm` node attestor with verified endorsement keys) and NEVER rely on static join tokens in production clusters.

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

Code SHOULD validate peer identities strictly using `combined_validation_context` with `match_typed_subject_alt_names` validating exact SPIFFE IDs (`spiffe

Code SHOULD validate peer identities strictly using `combined_validation_context` with `match_typed_subject_alt_names` validating exact SPIFFE IDs (`spiffe://<trust-domain>/<workload-path>`) rather than wildcard DNS SANs.

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

Components NEVER permit SDS communication over unauthenticated TCP loopbacks

Components NEVER permit SDS communication over unauthenticated TCP loopbacks; communication MUST occur over a Unix Domain Socket with strict filesystem permissions (UID/GID boundary).

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 Hardware-Attested SPIFFE/SPIRE SDS Invariant for Envoy Workload Identity critical for AI coding assistants?

Mandates that Envoy proxies dynamically consume cryptographic identities exclusively via the Secret Discovery Service (SDS) backed by a local TPM/vTPM-attested SPIRE Agent Unix Domain Socket. Prohibits static TLS mounts, long-lived secrets, and non-hardware node attestations across multi-cluster service meshes. Enforces continuous wire-speed X.509 SVID rotation and exact SPIFFE ID Trust Domain SAN validation. 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 (Static File-Mounted Certificates and Token-Attested Envoy Transport Sockets) 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 SECURITY Rules

View all rules →
security
105

OpenFGA Graph Invariants: Cyclic Relation Prevention & Contextual Tuple Hardening

Enforces strict directed acyclic graph (DAG) topology validation during relationship mutation writes and mandates strict server-side schema verification for ephemeral contextual tuples in OpenFGA evaluations. Prohibits persistent storage of ephemeral request attributes and guards against recursive relation loops causing graph expansion denial-of-service.

security
81

WebAuthn Conditional UI Mediation, Nonce Atomicity, and Assertion Cryptographic Verification

Enforces zero-trust cryptographic validation for FIDO2/WebAuthn Passkey authentication with Conditional UI autofill. Requires atomic single-use challenge consumption to eliminate replay attacks, strict RP ID hash and origin binding, authenticatorData flag verification (User Presence and User Verification), and monotonic signature counter enforcement to detect authenticator cloning.

security
111

Enforce Sigstore Keyless OIDC Attestation and Admission Controller Verification

Enforces immutable supply-chain security using Sigstore Cosign keyless signing via ephemeral OIDC tokens issued by Fulcio and verified against the Rekor transparency log. Container workloads must be signed and attested at build time by digest, and admission controllers (such as Kyverno or Sigstore Policy Controller) must strictly validate the OIDC issuer and subject identity before allowing image execution.

1 Rule in Stack

Hardware-Attested