stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
aaad8104cb17d6c44d54763b9a727a1e21312f20
git.stella-ops.org/docs/features/dropped/dsse-gateway-traversal.md

3.6 KiB
Raw Blame History

DSSE Gateway Traversal (mTLS + provenance headers)

Module

Scanner

Status

PARTIALLY_IMPLEMENTED

Description

HMAC-based DSSE envelope signing exists in the scanner worker for authenticating scan artifacts through gateway proxies. The feature envisions full mTLS gateway traversal with provenance headers injected by middleware, allowing scanner-to-registry and scanner-to-evidence-locker communication through reverse proxies (NGINX, Envoy, WAF) while maintaining attestation chain integrity.

What's Implemented

  • HMAC DSSE Envelope Signing:
    • src/Scanner/StellaOps.Scanner.Worker/Processing/Surface/HmacDsseEnvelopeSigner.cs - HmacDsseEnvelopeSigner producing HMAC-signed DSSE envelopes for scan artifacts, providing integrity verification during transit through intermediary proxies
  • DSSE Signing Infrastructure:
    • src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/ProofChainSigner.Verification.cs - DSSE signature verification pipeline used downstream for validating signed envelopes
    • src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/DsseEnvelope.cs - DsseEnvelope model representing Dead Simple Signing Envelope structures
    • src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Signing/DsseSignature.cs - DsseSignature model for individual signatures within envelopes

What's Missing

  • Gateway Configuration: No NGINX/Envoy/WAF gateway configuration templates or middleware for injecting provenance headers (X-Stella-Provenance, X-Stella-Scan-Id) into proxied requests
  • mTLS Certificate Management: No scanner-specific mTLS certificate provisioning, rotation, or trust store configuration for gateway traversal
  • Provenance Header Middleware: No ASP.NET Core middleware for reading/validating provenance headers on the receiving side (WebService, EvidenceLocker endpoints)
  • Gateway Health Probes: No health check endpoints specifically designed for gateway liveness/readiness through proxy chains
  • Configuration Schema: No structured configuration for declaring gateway topology (proxy chain depth, intermediate certificate authorities, header propagation rules)

Implementation Plan

  1. Create GatewayProvenanceMiddleware in StellaOps.Scanner.WebService that reads and validates X-Stella-Provenance headers from proxied requests
  2. Create MtlsCertificateProvider in StellaOps.Scanner.Worker for provisioning and rotating scanner client certificates
  3. Add gateway configuration templates (NGINX, Envoy) under devops/ with provenance header injection rules
  4. Extend HmacDsseEnvelopeSigner to embed gateway hop metadata in DSSE envelope payloads
  5. Add integration tests verifying envelope integrity through simulated proxy chains
  6. Add configuration schema for gateway topology in StellaOps.Scanner.Core

E2E Test Plan

  • Configure a scanner worker behind an NGINX reverse proxy and verify HMAC-signed DSSE envelopes are produced and transit successfully to the evidence locker
  • Verify provenance headers (X-Stella-Provenance, X-Stella-Scan-Id) are injected by the gateway and validated by the receiving service
  • Verify mTLS client certificate authentication between scanner worker and gateway proxy
  • Verify DSSE envelope signature remains valid after traversing a multi-hop proxy chain (scanner -> proxy -> WAF -> service)
  • Verify gateway health probes report correct status through the proxy chain
  • Verify the system rejects requests with missing or tampered provenance headers

Related Documentation

  • Source: See feature catalog
  • Architecture: docs/modules/scanner/architecture.md