archive audit attempts

docs/contracts/beacon-attestation-v1.md

@@ -0,0 +1,132 @@
+# 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.*