# 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.*