stella-ops.org/git.stella-ops.org

Fork 0

Files

StellaOps Bot 9202cd7da8 themed the bulk of advisories

2025-12-14 19:58:38 +02:00

5.9 KiB

Raw Permalink Blame History

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

{
  "dsseSha256": "sha256:...",
  "rekor": {
    "uuid": "...",
    "logIndex": 12345,
    "logId": "...",
    "integratedTime": 1733736000,
    "inclusionProof": {
      "rootHash": "...",
      "hashes": ["...", "..."],
      "checkpoint": "..."
    }
  }
}

5. REKOR CLIENT INTERFACE

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

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

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

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:

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

# 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

5.9 KiB Raw Permalink Blame History