46 lines
3.6 KiB
Markdown
46 lines
3.6 KiB
Markdown
# 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`
|