themed the bulk of advisories
This commit is contained in:
StellaOps Bot
@@ -0,0 +1,291 @@
|
||||
# Rekor Integration Technical Reference
|
||||
|
||||
**Source Advisories**:
|
||||
- 30-Nov-2025 - Rekor Receipt Checklist for Stella Ops
|
||||
|
||||
**Last Updated**: 2025-12-14
|
||||
|
||||
---
|
||||
|
||||
## 1. REQUIREMENTS
|
||||
|
||||
- Rekor receipts must be deterministic, tenant-scoped, and verifiable offline
|
||||
- For Authority/Sbomer/Vexer flows
|
||||
- Field-level ownership map for receipts and bundles
|
||||
- Offline verifier expectations
|
||||
- Mirror snapshot rules
|
||||
- DSSE/receipt schema pointers
|
||||
|
||||
## 2. DETERMINISM & OFFLINE
|
||||
|
||||
- Bundle TSA/time anchors with receipts
|
||||
- Prefer mirror snapshots
|
||||
- Avoid live log fetches in examples
|
||||
|
||||
## 3. DELIVERABLES
|
||||
|
||||
- Schema draft
|
||||
- Offline verifier stub
|
||||
- Module dossier updates
|
||||
|
||||
## 4. REKOR ENTRY STRUCTURE
|
||||
|
||||
```json
|
||||
{
|
||||
"dsseSha256": "sha256:...",
|
||||
"rekor": {
|
||||
"uuid": "...",
|
||||
"logIndex": 12345,
|
||||
"logId": "...",
|
||||
"integratedTime": 1733736000,
|
||||
"inclusionProof": {
|
||||
"rootHash": "...",
|
||||
"hashes": ["...", "..."],
|
||||
"checkpoint": "..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. REKOR CLIENT INTERFACE
|
||||
|
||||
```csharp
|
||||
public interface IRekorClient
|
||||
{
|
||||
Task<RekorEntry> SubmitDsseAsync(
|
||||
DsseEnvelope envelope,
|
||||
CancellationToken ct = default
|
||||
);
|
||||
|
||||
Task<bool> VerifyInclusionAsync(
|
||||
RekorEntry entry,
|
||||
byte[] payloadDigest,
|
||||
byte[] rekorPublicKey,
|
||||
CancellationToken ct = default
|
||||
);
|
||||
}
|
||||
|
||||
public record RekorEntry(
|
||||
string Uuid,
|
||||
long LogIndex,
|
||||
string LogId,
|
||||
long IntegratedTime,
|
||||
InclusionProof Proof
|
||||
);
|
||||
|
||||
public record InclusionProof(
|
||||
string RootHash,
|
||||
string[] Hashes,
|
||||
string Checkpoint
|
||||
);
|
||||
```
|
||||
|
||||
## 6. CLI VERIFICATION
|
||||
|
||||
### 6.1 Rekor CLI Commands
|
||||
|
||||
```bash
|
||||
rekor-cli verify --rekor_server https://rekor.sigstore.dev \
|
||||
--signature artifact.sig \
|
||||
--public-key cosign.pub \
|
||||
--artifact artifact.bin
|
||||
```
|
||||
|
||||
### 6.2 Persistence per Entry
|
||||
|
||||
- Rekor UUID
|
||||
- Log index
|
||||
- Integrated time
|
||||
- Inclusion proof data
|
||||
|
||||
## 7. OFFLINE REKOR MIRROR
|
||||
|
||||
### 7.1 Mirror Structure
|
||||
|
||||
```
|
||||
/evidence/tlog/
|
||||
checkpoint.sig # signed tree head
|
||||
entries/ # *.jsonl (Merkle leaves) + proofs
|
||||
```
|
||||
|
||||
### 7.2 Verification Steps
|
||||
|
||||
```
|
||||
1. Recompute Merkle root from entries
|
||||
2. Check matches `checkpoint.sig` (after verifying signature with tlog root key)
|
||||
3. For each attestation:
|
||||
- Verify UUID/digest appears in entry pack
|
||||
- Verify inclusion proof resolves
|
||||
```
|
||||
|
||||
## 8. REKOR STORAGE SCHEMA
|
||||
|
||||
```sql
|
||||
CREATE TABLE rekor_entries (
|
||||
dsse_sha256 VARCHAR(64) PRIMARY KEY,
|
||||
log_index BIGINT NOT NULL,
|
||||
log_id TEXT NOT NULL,
|
||||
integrated_time BIGINT NOT NULL,
|
||||
inclusion_proof JSONB NOT NULL,
|
||||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_rekor_log_index ON rekor_entries(log_index);
|
||||
CREATE INDEX idx_rekor_integrated_time ON rekor_entries(integrated_time);
|
||||
```
|
||||
|
||||
## 9. REKOR FAILURE HANDLING
|
||||
|
||||
### 9.1 Rekor Unavailable
|
||||
|
||||
```
|
||||
If Rekor unavailable:
|
||||
- Store DSSE envelope locally
|
||||
- Queue for retry
|
||||
- Mark proof chain as "rekorStatus: pending"
|
||||
- Internal-only until Rekor sync succeeds
|
||||
- Flag in verification results
|
||||
```
|
||||
|
||||
### 9.2 Rekor Verification Failed
|
||||
|
||||
```
|
||||
If verification fails:
|
||||
- Log error with structured fields (rekorUuid, dsseDigest, failureReason)
|
||||
- Mark envelope as "rekor_verification_failed"
|
||||
- Do not accept as valid proof
|
||||
- Alert security team
|
||||
```
|
||||
|
||||
## 10. INTEGRATION POINTS
|
||||
|
||||
### 10.1 Authority Module
|
||||
|
||||
- Submit signed attestations to Rekor
|
||||
- Store receipts with DSSE envelopes
|
||||
- Verify inclusion proofs on retrieval
|
||||
|
||||
### 10.2 Sbomer Module
|
||||
|
||||
- Submit SBOM attestations to Rekor
|
||||
- Link Rekor UUID to SBOM entries
|
||||
|
||||
### 10.3 Vexer Module
|
||||
|
||||
- Submit VEX statements to Rekor
|
||||
- Store receipts with VEX decisions
|
||||
|
||||
## 11. METRICS & OBSERVABILITY
|
||||
|
||||
```
|
||||
rekor_submit_total{status="success|failed"}
|
||||
rekor_submit_latency_seconds
|
||||
rekor_verify_total{result="pass|fail"}
|
||||
rekor_verify_latency_seconds
|
||||
rekor_queue_depth (pending submissions)
|
||||
rekor_retry_attempts_total
|
||||
```
|
||||
|
||||
## 12. CONFIGURATION
|
||||
|
||||
```yaml
|
||||
rekor:
|
||||
server_url: https://rekor.sigstore.dev
|
||||
public_key_path: /etc/stellaops/rekor-pub.pem
|
||||
offline_mode: false
|
||||
retry:
|
||||
max_attempts: 3
|
||||
initial_delay_ms: 1000
|
||||
max_delay_ms: 10000
|
||||
timeout_seconds: 30
|
||||
```
|
||||
|
||||
## 13. OFFLINE BUNDLE INTEGRATION
|
||||
|
||||
### 13.1 Rekor Receipt in Offline Kit
|
||||
|
||||
**rekor-receipt.json**:
|
||||
```json
|
||||
{
|
||||
"uuid": "string",
|
||||
"logIndex": int,
|
||||
"rootHash": "string",
|
||||
"hashes": ["string"],
|
||||
"checkpoint": "string"
|
||||
}
|
||||
```
|
||||
|
||||
### 13.2 Offline Verification
|
||||
|
||||
```
|
||||
1. Load Rekor public key from offline bundle
|
||||
2. Verify checkpoint signature
|
||||
3. Recompute Merkle root from inclusion proof
|
||||
4. Verify root hash matches checkpoint
|
||||
5. Verify DSSE envelope hash appears in proof
|
||||
```
|
||||
|
||||
## 14. SECURITY CONSIDERATIONS
|
||||
|
||||
### 14.1 Trust Model
|
||||
|
||||
- Rekor provides transparency, not trust
|
||||
- Trust derives from key verification
|
||||
- Inclusion proof demonstrates timestamp
|
||||
- Does not prove correctness of content
|
||||
|
||||
### 14.2 Key Pinning
|
||||
|
||||
- Pin Rekor public key via out-of-band distribution
|
||||
- Verify checkpoint signatures before trusting
|
||||
- Maintain key version history
|
||||
|
||||
### 14.3 Replay Protection
|
||||
|
||||
- Use integrated_time to detect backdated entries
|
||||
- Compare with local clock (within reasonable skew)
|
||||
- Alert on time anomalies
|
||||
|
||||
## 15. TESTING REQUIREMENTS
|
||||
|
||||
### 15.1 Integration Tests
|
||||
|
||||
- Submit DSSE to Rekor (staging)
|
||||
- Verify inclusion proof
|
||||
- Offline verification with mirror
|
||||
- Retry on failure
|
||||
- Timeout handling
|
||||
|
||||
### 15.2 Failure Scenarios
|
||||
|
||||
- Rekor unavailable
|
||||
- Network timeout
|
||||
- Invalid inclusion proof
|
||||
- Signature verification failure
|
||||
- Malformed response
|
||||
|
||||
## 16. OPERATIONAL PROCEDURES
|
||||
|
||||
### 16.1 Rekor Mirror Sync
|
||||
|
||||
```bash
|
||||
# Download latest checkpoint
|
||||
curl https://rekor.sigstore.dev/api/v1/log/checkpoint > checkpoint.sig
|
||||
|
||||
# Verify checkpoint signature
|
||||
rekor-cli verify --checkpoint checkpoint.sig --public-key rekor-pub.pem
|
||||
|
||||
# Sync entries since last update
|
||||
rekor-cli sync --since <last_log_index> --output ./entries/
|
||||
```
|
||||
|
||||
### 16.2 Monitoring
|
||||
|
||||
- Alert on Rekor submission failures >1% over 5 minutes
|
||||
- Alert on verification failures >0.1% over 5 minutes
|
||||
- Alert on queue depth >1000 for >10 minutes
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Target Platform**: .NET 10, PostgreSQL ≥16, Angular v17
|
||||
Reference in New Issue
Block a user