new two advisories and sprints work on them

2026-01-16 18:39:36 +02:00
parent 9daf619954
commit c3a6269d55
72 changed files with 15540 additions and 18 deletions
--- a/docs/modules/attestor/rekor-verification-design.md
+++ b/docs/modules/attestor/rekor-verification-design.md
@@ -866,6 +866,119 @@ curl https://rekor.sigstore.dev/api/v1/log/publicKey > fixtures/rekor-pubkey.pem

 ---

+## 9A. PERIODIC VERIFICATION (Background Job)
+
+**Sprint Reference**: `SPRINT_20260117_001_ATTESTOR_periodic_rekor_verification`
+
+### 9A.1 Overview
+
+The Periodic Verification system provides continuous validation of previously logged Rekor entries. This addresses the gap where entries are logged but never re-verified, enabling detection of:
+
+- Signature tampering or key compromise
+- Merkle tree rollbacks (split-view attacks)
+- Time skew violations indicating replay attempts
+- Root consistency drift between stored and remote state
+
+### 9A.2 Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                   Periodic Verification Job                         │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌─────────────────────┐    ┌─────────────────────┐                 │
+│  │ RekorVerification   │───►│ IRekorVerification  │                 │
+│  │ Job (Scheduler)     │    │ Service             │                 │
+│  └─────────┬───────────┘    └──────────┬──────────┘                 │
+│            │                           │                             │
+│            │ batch query               │ verify                      │
+│            ▼                           ▼                             │
+│  ┌─────────────────────┐    ┌─────────────────────┐                 │
+│  │ IRekorEntry         │    │ RekorVerification   │                 │
+│  │ Repository          │    │ Metrics             │                 │
+│  └─────────────────────┘    └──────────┬──────────┘                 │
+│                                        │                             │
+│                                        ▼                             │
+│                             ┌─────────────────────┐                 │
+│                             │ IRekorVerification  │                 │
+│                             │ StatusProvider      │                 │
+│                             └─────────────────────┘                 │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 9A.3 Configuration
+
+```yaml
+attestor:
+  rekor:
+    verification:
+      enabled: true
+      intervalMinutes: 60           # Run every hour
+      batchSize: 100                # Entries per batch
+      sampleRate: 0.1               # 10% sampling for large deployments
+      maxTimeSkewSeconds: 300       # 5 minute tolerance
+      alertOnRootInconsistency: true
+```
+
+### 9A.4 Verification Checks
+
+| Check | Description | Failure Severity |
+|-------|-------------|------------------|
+| Signature | Verify entry signature against stored public key | Critical |
+| Inclusion Proof | RFC 6962 Merkle inclusion proof verification | Critical |
+| Time Skew | Validate integrated_time within tolerance | Warning |
+| Root Consistency | Compare stored tree root with remote | Critical |
+
+### 9A.5 Metrics (OpenTelemetry)
+
+```
+# Meter: StellaOps.Attestor.RekorVerification
+
+attestor.rekor.verification.runs              # Counter
+attestor.rekor.verification.entries.verified  # Counter
+attestor.rekor.verification.entries.failed    # Counter
+attestor.rekor.verification.entries.skipped   # Counter
+attestor.rekor.verification.time_skew_violations # Counter
+attestor.rekor.verification.signature_failures   # Counter
+attestor.rekor.verification.inclusion_proof_failures # Counter
+attestor.rekor.verification.root_consistency_checks  # Counter
+attestor.rekor.verification.entry_duration    # Histogram
+attestor.rekor.verification.batch_duration    # Histogram
+```
+
+### 9A.6 Health Check Integration
+
+The `RekorVerificationHealthCheck` integrates with the Doctor diagnostic system:
+
+```
+Check ID: check.attestation.rekor.verification.job
+
+Status Levels:
+- Healthy: Last run within expected window, failure rate < 1%
+- Degraded: Failure rate 1-5%, or last run overdue
+- Unhealthy: Failure rate > 5%, root inconsistency detected, or job not running
+```
+
+### 9A.7 Alerting
+
+| Condition | Alert Level | Action |
+|-----------|-------------|--------|
+| Root inconsistency | P1 Critical | Immediate investigation required |
+| Signature failure rate > 5% | P2 High | Review key material |
+| Job not running > 3x interval | P3 Medium | Check scheduler |
+| Time skew violations > 10% | P3 Medium | Check NTP sync |
+
+### 9A.8 Offline Verification
+
+When network access to Rekor is unavailable, the system falls back to stored inclusion proofs:
+
+1. Read stored `inclusion_proof` from database
+2. Verify Merkle path locally against stored root
+3. Log verification as "offline" mode
+4. Schedule online re-verification when connectivity returns
+
+---
+
 ## 10. MIGRATION GUIDE

 ### 10.1 Database Migrations