127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
# Predicate Schema: stella.ops/federatedTelemetry@v1
|
|
|
|
## Overview
|
|
|
|
This predicate type represents a privacy-preserving telemetry bundle produced by a Stella Ops instance participating in federated exploit intelligence sharing. Each bundle contains differentially private aggregated CVE observation data.
|
|
|
|
## Predicate Type
|
|
|
|
```
|
|
stella.ops/federatedTelemetry@v1
|
|
```
|
|
|
|
## Schema
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"type": "object",
|
|
"required": ["id", "siteId", "predicateType", "aggregatedAt", "totalFacts", "suppressedBuckets", "epsilonSpent", "buckets", "consentDigest", "createdAt"],
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"format": "uuid",
|
|
"description": "Unique bundle identifier"
|
|
},
|
|
"siteId": {
|
|
"type": "string",
|
|
"description": "Identifier of the originating federation site"
|
|
},
|
|
"predicateType": {
|
|
"type": "string",
|
|
"const": "stella.ops/federatedTelemetry@v1"
|
|
},
|
|
"aggregatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Timestamp of the aggregation cycle"
|
|
},
|
|
"totalFacts": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Total number of telemetry facts processed"
|
|
},
|
|
"suppressedBuckets": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Number of buckets suppressed by k-anonymity or budget exhaustion"
|
|
},
|
|
"epsilonSpent": {
|
|
"type": "number",
|
|
"minimum": 0,
|
|
"description": "Total epsilon consumed in this aggregation"
|
|
},
|
|
"buckets": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["cveId", "noisyCount", "artifactCount"],
|
|
"properties": {
|
|
"cveId": {
|
|
"type": "string",
|
|
"description": "CVE identifier (e.g., CVE-2024-12345)"
|
|
},
|
|
"noisyCount": {
|
|
"type": "number",
|
|
"minimum": 0,
|
|
"description": "Observation count with Laplacian noise applied"
|
|
},
|
|
"artifactCount": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Number of distinct artifacts contributing to this bucket"
|
|
}
|
|
}
|
|
},
|
|
"description": "Non-suppressed aggregation buckets"
|
|
},
|
|
"consentDigest": {
|
|
"type": "string",
|
|
"description": "DSSE digest of the active consent proof at time of aggregation"
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Timestamp when the bundle was created"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Validation Rules
|
|
|
|
1. `id` must be a valid UUID v4.
|
|
2. `siteId` must be non-empty and match the originating site's configured identifier.
|
|
3. `epsilonSpent` must not exceed the site's total epsilon budget.
|
|
4. `consentDigest` must reference a valid, non-expired consent proof.
|
|
5. Each bucket's `artifactCount` must be >= the configured k-anonymity threshold.
|
|
6. `noisyCount` values are non-negative (noise-adjusted, may differ from true counts).
|
|
|
|
## Example Payload
|
|
|
|
```json
|
|
{
|
|
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
"siteId": "site-production-us-east",
|
|
"predicateType": "stella.ops/federatedTelemetry@v1",
|
|
"aggregatedAt": "2026-02-20T14:30:00Z",
|
|
"totalFacts": 1547,
|
|
"suppressedBuckets": 3,
|
|
"epsilonSpent": 0.0833,
|
|
"buckets": [
|
|
{
|
|
"cveId": "CVE-2024-21626",
|
|
"noisyCount": 42.7,
|
|
"artifactCount": 12
|
|
},
|
|
{
|
|
"cveId": "CVE-2024-3094",
|
|
"noisyCount": 8.2,
|
|
"artifactCount": 6
|
|
}
|
|
],
|
|
"consentDigest": "sha256:abc123def456...",
|
|
"createdAt": "2026-02-20T14:30:05Z"
|
|
}
|
|
```
|