133 lines
5.9 KiB
Markdown
133 lines
5.9 KiB
Markdown
# Beacon Attestation Predicate Contract
|
||
|
||
**Predicate Type:** `stella.ops/beaconAttestation@v1`
|
||
**Status:** Active
|
||
**Sprint:** SPRINT_20260219_014
|
||
|
||
Provides low-volume, signed proof that a specific artifact actually executed in a real environment. Beacon events are captured via eBPF uprobe (Linux), ETW DynamicTraceProvider (Windows), or dyld interpose (macOS) on a designated "beacon function" — without modifying the artifact.
|
||
|
||
## Overview
|
||
|
||
- **Execution proof:** Cryptographic attestation that an artifact ran in a specific environment.
|
||
- **Config-driven instrumentation:** Beacon functions are designated by configuration, not by modifying container entrypoints. Preserves image integrity.
|
||
- **Batched attestation:** Events collected over a configurable window (default: 5 minutes) produce a single attestation.
|
||
- **Nonce-protected:** Per-event nonces prevent replay attacks. Sequence numbers detect gaps.
|
||
- **Offline-first:** No external service dependencies.
|
||
|
||
## Schema
|
||
|
||
```json
|
||
{
|
||
"predicateType": "stella.ops/beaconAttestation@v1",
|
||
"subject": [{"name": "artifact", "digest": {"sha256": "<canonical_id>"}}],
|
||
"predicate": {
|
||
"artifact_id": "sha256:<image_or_binary_digest>",
|
||
"environment_id": "<env_identifier>",
|
||
"beacon_source": "ebpf_uprobe|etw_dynamic|dyld_interpose",
|
||
"beacon_function": "<symbol_name_or_address_range>",
|
||
"window_start": "2026-02-19T12:00:00Z",
|
||
"window_end": "2026-02-19T12:05:00Z",
|
||
"beacon_count": 47,
|
||
"first_sequence": 1,
|
||
"last_sequence": 50,
|
||
"sequence_gaps": 3,
|
||
"verification_rate": 0.94,
|
||
"timestamp": "2026-02-19T12:05:01Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Field Definitions
|
||
|
||
### Root Fields
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `predicateType` | string | yes | Always `stella.ops/beaconAttestation@v1` |
|
||
| `subject` | array | yes | Single-element array with artifact canonical ID |
|
||
|
||
### Predicate Fields
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `artifact_id` | string | yes | `sha256:<digest>` of the container image or binary |
|
||
| `environment_id` | string | yes | Identifier of the environment where beacon was observed |
|
||
| `beacon_source` | string | yes | Instrumentation source: `ebpf_uprobe`, `etw_dynamic`, or `dyld_interpose` |
|
||
| `beacon_function` | string | yes | Symbol name or address range of the designated beacon function |
|
||
| `window_start` | ISO 8601 | yes | Start of the batching window |
|
||
| `window_end` | ISO 8601 | yes | End of the batching window |
|
||
| `beacon_count` | int | yes | Number of verified beacon events in the window |
|
||
| `first_sequence` | long | yes | First sequence number in the window |
|
||
| `last_sequence` | long | yes | Last sequence number in the window |
|
||
| `sequence_gaps` | int | yes | Number of detected sequence gaps |
|
||
| `verification_rate` | double | yes | `verified_count / expected_count` (0.0–1.0) |
|
||
| `timestamp` | ISO 8601 | yes | When the attestation predicate was generated |
|
||
|
||
## Beacon Function Designation
|
||
|
||
Beacon functions are designated by **environment-level configuration**, not by modifying the artifact:
|
||
|
||
```yaml
|
||
Signals:
|
||
Beacon:
|
||
Enabled: true
|
||
Functions:
|
||
- ArtifactPattern: "myapp:*"
|
||
SymbolName: "healthCheck"
|
||
Source: "ebpf_uprobe"
|
||
- ArtifactPattern: "api-gateway:*"
|
||
AddressRange: "0x1000-0x1100"
|
||
Source: "etw_dynamic"
|
||
```
|
||
|
||
The eBPF/ETW probe attaches to the named symbol or address range externally. **No entrypoint injection or image modification is performed.** This preserves the attestation chain that Stella Ops signs and verifies.
|
||
|
||
## Nonce and Sequence Semantics
|
||
|
||
- **Nonce:** Random unique value per beacon event. The deduplication cache rejects events with duplicate `(artifact_id, environment_id, nonce)` tuples. Nonce TTL is configurable (default: 1 hour).
|
||
- **Sequence:** Monotonically increasing counter per `(artifact_id, environment_id)`. Gaps in the sequence indicate missed beacon events (probe failure, artifact restart, or instrumentation issue).
|
||
- **Verification rate:** `verified_beacons / (last_sequence - first_sequence + 1)` over the batch window.
|
||
|
||
## DSSE Signing
|
||
|
||
Beacon predicates are wrapped in DSSE envelopes and signed using the environment's configured crypto profile. Supported: EdDSA, ECDSA, RSA, GOST R 34.10, SM2, eIDAS QSealC, PQC (ML-DSA).
|
||
|
||
## Batching
|
||
|
||
Beacon events are lightweight and high-frequency. Rather than signing per-event, the pipeline collects events over a configurable window (default: 5 minutes) and produces a single attestation summarizing the window.
|
||
|
||
Early flush occurs if the batch reaches `MaxBatchSize` (default: 1000) before the window expires.
|
||
|
||
## Configuration
|
||
|
||
Section: `Signals:Beacon`
|
||
|
||
| Option | Type | Default | Description |
|
||
|--------|------|---------|-------------|
|
||
| `Enabled` | bool | `true` | Whether the beacon pipeline is active |
|
||
| `BatchWindowSeconds` | int | `300` | Batching window (5 minutes) |
|
||
| `MaxBatchSize` | int | `1000` | Max events per batch (triggers early flush) |
|
||
| `NonceTtlSeconds` | int | `3600` | Nonce deduplication cache TTL (1 hour) |
|
||
| `VerificationRateLookbackHours` | int | `24` | Lookback window for rate computation |
|
||
|
||
## API Endpoints
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| `POST` | `/signals/beacons` | Ingest beacon events |
|
||
| `GET` | `/signals/beacons/rate/{artifactId}/{environmentId}` | Query beacon verification rate |
|
||
|
||
## Audit Pack Export
|
||
|
||
Beacon attestation predicates are included in Evidence Bundle exports as `predicates/beacon-attestation.json`. The bundle's `checksums.sha256` manifest includes the beacon attestation entry for offline verification.
|
||
|
||
## Related Documents
|
||
|
||
- `docs/contracts/execution-evidence-v1.md` — Full execution evidence predicate (heavyweight complement)
|
||
- `docs/contracts/witness-v1.md` — Runtime witness predicate
|
||
- `docs/modules/policy/gates/beacon-rate-gate.md` — Policy gate consuming beacon verification rate
|
||
|
||
---
|
||
|
||
*Last updated: 2026-02-19.*
|