# Runbook: Attestor - Rekor Transparency Log Unreachable

> **Sprint:** SPRINT_20260117_029_DOCS_runbook_coverage
> **Task:** RUN-005 - Attestor Runbooks

## Metadata

| Field | Value |
|-------|-------|
| **Component** | Attestor |
| **Severity** | High |
| **On-call scope** | Platform team |
| **Last updated** | 2026-01-17 |
| **Doctor check** | `check.attestor.rekor-connectivity` |

---

## Symptoms

- [ ] Attestation transparency logging failing
- [ ] Alert `AttestorRekorUnavailable` firing
- [ ] Error: "Rekor server unavailable" or "transparency log submission failed"
- [ ] Attestations created but not anchored to transparency log
- [ ] Verification failing due to missing log entry

---

## Impact

| Impact Type | Description |
|-------------|-------------|
| **User-facing** | Attestations not publicly verifiable via transparency log |
| **Data integrity** | Attestations still valid locally; transparency reduced |
| **SLA impact** | Compliance may require transparency log anchoring |

---

## Diagnosis

### Quick checks

1. **Check Doctor diagnostics:**
   ```bash
   stella doctor --check check.attestor.rekor-connectivity
   ```

2. **Check Rekor connectivity:**
   ```bash
   stella attest rekor status
   ```

3. **Test Rekor endpoint:**
   ```bash
   stella attest rekor ping
   ```

### Deep diagnosis

1. **Check Rekor server URL:**
   ```bash
   stella attest config get rekor.url
   ```
   Default: https://rekor.sigstore.dev

2. **Check for public Rekor outage:**
   ```bash
   stella attest rekor api-status
   ```
   Also check: https://status.sigstore.dev/

3. **Check network/proxy issues:**
   ```bash
   stella attest rekor test --verbose
   ```
   Look for: TLS errors, proxy blocks, timeout

4. **Check pending log entries:**
   ```bash
   stella attest rekor pending-entries
   ```

---

## Resolution

### Immediate mitigation

1. **Queue attestations for later submission:**
   ```bash
   stella attest config set rekor.queue_on_failure true
   stella attest reload
   ```

2. **Disable Rekor requirement temporarily:**
   ```bash
   stella attest config set rekor.required false
   stella attest reload
   ```
   **Warning:** Reduces transparency guarantees

3. **Use private Rekor instance if available:**
   ```bash
   stella attest config set rekor.url https://rekor.internal.example.com
   stella attest reload
   ```

### Root cause fix

**If public Rekor outage:**

1. Wait for Sigstore to resolve the issue
2. Check status at https://status.sigstore.dev/
3. Process queued entries when service recovers:
   ```bash
   stella attest rekor process-queue
   ```

**If network/firewall issue:**

1. Verify outbound HTTPS to rekor.sigstore.dev:
   ```bash
   stella attest rekor connectivity --verbose
   ```

2. Configure proxy if required:
   ```bash
   stella attest config set rekor.proxy https://proxy:8080
   ```

3. Add Rekor endpoints to firewall allowlist:
   - rekor.sigstore.dev:443
   - fulcio.sigstore.dev:443 (for certificate issuance)

**If TLS certificate issue:**

1. Check certificate validity:
   ```bash
   stella attest rekor cert-check
   ```

2. Update CA certificates:
   ```bash
   stella crypto ca update
   ```

**If private Rekor instance issue:**

1. Check private Rekor server status
2. Verify Rekor database health
3. Check Rekor signer availability

### Verification

```bash
# Test Rekor connectivity
stella attest rekor ping

# Submit test entry
stella attest rekor test-submit

# Process any queued entries
stella attest rekor process-queue

# Verify recent attestation in log
stella attest rekor lookup --attestation <attestation-id>
```

---

## Prevention

- [ ] **Redundancy:** Configure private Rekor instance as fallback
- [ ] **Queuing:** Enable queue-on-failure for resilience
- [ ] **Monitoring:** Alert on Rekor submission failures
- [ ] **Offline:** Document attestation validity without Rekor for air-gap scenarios

---

## Related Resources

- **Architecture:** `docs/modules/attestor/transparency-log.md`
- **Related runbooks:** `attestor-signing-failed.md`, `attestor-verification-failed.md`
- **Sigstore docs:** https://docs.sigstore.dev/
- **Rekor setup:** `docs/operations/rekor-configuration.md`