119 lines
4.7 KiB
Markdown
119 lines
4.7 KiB
Markdown
# Federated Telemetry Architecture
|
|
|
|
## Overview
|
|
|
|
The Federated Telemetry subsystem enables privacy-preserving sharing of runtime exploit intelligence across Stella Ops instances in a federation mesh. It uses differential privacy (Laplacian noise) and k-anonymity to ensure that individual tenant data cannot be reconstructed from shared aggregates.
|
|
|
|
## Data Flow
|
|
|
|
```
|
|
Tenant Runtime -> TelemetryFact Buffer -> TelemetryAggregator
|
|
-> k-Anonymity Filter -> Laplacian Noise -> AggregationResult
|
|
-> ConsentManager Check -> BundleBuilder -> DSSE-Signed Bundle
|
|
-> EgressPolicy Check -> Federation Mesh Sync
|
|
-> ExploitIntelligenceMerger <- Incoming Bundles from Peers
|
|
```
|
|
|
|
## Privacy Model
|
|
|
|
### Differential Privacy (Epsilon Budget)
|
|
|
|
Each aggregation cycle consumes a portion of the total epsilon budget. The budget resets on a configurable period (default: 24 hours).
|
|
|
|
- **Epsilon per bucket**: `total_budget / number_of_buckets`
|
|
- **Laplacian noise**: `-(sensitivity / epsilon) * sign(u) * ln(1 - 2|u|)` where u ~ Uniform(-0.5, 0.5)
|
|
- **Budget exhaustion**: When remaining epsilon reaches zero, all further aggregation is suppressed until the next reset period.
|
|
|
|
### K-Anonymity
|
|
|
|
Buckets (grouped by CVE ID) with fewer than `k` distinct artifact digests are suppressed entirely. The default threshold is k=5, configurable via `FederatedTelemetryOptions.KAnonymityThreshold`.
|
|
|
|
## Consent Lifecycle
|
|
|
|
1. **Not Granted** (default) -- no federation data leaves the instance.
|
|
2. **Granted** -- admin explicitly grants consent with optional TTL. A DSSE-signed consent proof is created.
|
|
3. **Expired** -- consent with a TTL automatically reverts to Not Granted after expiry.
|
|
4. **Revoked** -- admin explicitly revokes consent.
|
|
|
|
Consent state is checked at the start of each sync cycle. No bundles are built or transmitted without active consent.
|
|
|
|
## Sync Service
|
|
|
|
`FederatedTelemetrySyncService` is a `BackgroundService` that runs on a configurable interval (default: 15 minutes).
|
|
|
|
Each cycle:
|
|
1. Check sealed mode -- skip if active.
|
|
2. Check privacy budget -- skip if exhausted.
|
|
3. Check consent -- skip if not granted.
|
|
4. Drain fact buffer.
|
|
5. Aggregate facts with k-anonymity and Laplacian noise.
|
|
6. Build DSSE-signed bundle.
|
|
7. Check egress policy.
|
|
8. Transmit to federation mesh.
|
|
|
|
## Intelligence Merging
|
|
|
|
Incoming bundles from federation peers are processed by `ExploitIntelligenceMerger`:
|
|
- Entries are normalized (CVE ID uppercase, timestamps UTC, site IDs lowercase).
|
|
- Deduplication by `(CveId, SourceSiteId)` composite key.
|
|
- Conflict resolution: latest `ObservedAt` wins.
|
|
|
|
## Bundle Format
|
|
|
|
A `FederatedBundle` contains:
|
|
- Unique ID (GUID)
|
|
- Source site identifier
|
|
- Aggregation result (buckets with noisy counts, suppression flags)
|
|
- Consent DSSE digest (proof that consent was active)
|
|
- Bundle DSSE digest (integrity verification)
|
|
- DSSE envelope (signed payload)
|
|
- Creation timestamp
|
|
|
|
## Sealed Mode
|
|
|
|
When `FederatedTelemetryOptions.SealedModeEnabled` is true:
|
|
- Sync service skips all cycles.
|
|
- No outbound traffic is generated.
|
|
- Local aggregation still functions for internal analytics.
|
|
- Intelligence merging is paused.
|
|
|
|
## Configuration
|
|
|
|
```json
|
|
{
|
|
"FederatedTelemetry": {
|
|
"KAnonymityThreshold": 5,
|
|
"EpsilonBudget": 1.0,
|
|
"BudgetResetPeriod": "24:00:00",
|
|
"AggregationInterval": "00:15:00",
|
|
"SealedModeEnabled": false,
|
|
"ConsentPredicateType": "stella.ops/federatedConsent@v1",
|
|
"BundlePredicateType": "stella.ops/federatedTelemetry@v1",
|
|
"SiteId": "site-001"
|
|
}
|
|
}
|
|
```
|
|
|
|
## API Surface
|
|
|
|
See `src/Platform/StellaOps.Platform.WebService/Endpoints/FederationTelemetryEndpoints.cs` for the full REST API.
|
|
|
|
| Method | Path | Auth Policy | Description |
|
|
|--------|------|-------------|-------------|
|
|
| GET | /api/v1/telemetry/federation/consent | FederationRead | Get consent state |
|
|
| POST | /api/v1/telemetry/federation/consent/grant | FederationManage | Grant consent |
|
|
| POST | /api/v1/telemetry/federation/consent/revoke | FederationManage | Revoke consent |
|
|
| GET | /api/v1/telemetry/federation/status | FederationRead | Federation status |
|
|
| GET | /api/v1/telemetry/federation/bundles | FederationRead | List bundles |
|
|
| GET | /api/v1/telemetry/federation/bundles/{id} | FederationRead | Bundle detail |
|
|
| GET | /api/v1/telemetry/federation/intelligence | FederationRead | Exploit corpus |
|
|
| GET | /api/v1/telemetry/federation/privacy-budget | FederationRead | Budget snapshot |
|
|
| POST | /api/v1/telemetry/federation/trigger | FederationManage | Trigger aggregation |
|
|
|
|
## Source Files
|
|
|
|
- Project: `src/Telemetry/StellaOps.Telemetry.Federation/`
|
|
- Tests: `src/Telemetry/StellaOps.Telemetry.Federation.Tests/`
|
|
- API: `src/Platform/StellaOps.Platform.WebService/Endpoints/FederationTelemetryEndpoints.cs`
|
|
- UI: `src/Web/StellaOps.Web/src/app/features/platform-ops/federation-telemetry/`
|