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

{
  "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:

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.

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.

5.9 KiB Raw Blame History Unescape Escape