synergy moats product advisory implementations

2026-01-17 01:30:03 +02:00
parent 77ff029205
commit 702a27ac83
112 changed files with 21356 additions and 127 deletions
--- a/docs/operations/runbooks/connector-osv.md
+++ b/docs/operations/runbooks/connector-osv.md
@@ -0,0 +1,193 @@
+# Runbook: Feed Connector - OSV (Open Source Vulnerabilities) Failures
+
+> **Sprint:** SPRINT_20260117_029_DOCS_runbook_coverage
+> **Task:** RUN-006 - Feed Connector Runbooks
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Component** | Concelier / OSV Connector |
+| **Severity** | High |
+| **On-call scope** | Platform team |
+| **Last updated** | 2026-01-17 |
+| **Doctor check** | `check.connector.osv-health` |
+
+---
+
+## Symptoms
+
+- [ ] OSV feed sync failing or stale
+- [ ] Alert `ConnectorOsvSyncFailed` firing
+- [ ] Error: "OSV API request failed" or "ecosystem sync failed"
+- [ ] OSV vulnerabilities missing from database
+- [ ] Metric `connector_sync_failures_total{source="osv"}` increasing
+
+---
+
+## Impact
+
+| Impact Type | Description |
+|-------------|-------------|
+| **User-facing** | Open source ecosystem vulnerabilities may be missed |
+| **Data integrity** | Data becomes stale; no data loss |
+| **SLA impact** | Vulnerability currency SLO violated for affected ecosystems |
+
+---
+
+## Diagnosis
+
+### Quick checks
+
+1. **Check Doctor diagnostics:**
+   ```bash
+   stella doctor --check check.connector.osv-health
+   ```
+
+2. **Check OSV sync status:**
+   ```bash
+   stella admin feeds status --source osv
+   ```
+
+3. **Test OSV API connectivity:**
+   ```bash
+   stella connector test osv
+   ```
+
+### Deep diagnosis
+
+1. **Check ecosystem-specific status:**
+   ```bash
+   stella connector osv ecosystems status
+   ```
+   Look for: Failed ecosystems, stale ecosystems
+
+2. **Check sync logs:**
+   ```bash
+   stella connector logs osv --last 1h --level error
+   ```
+   Look for: API errors, parsing failures, timeout
+
+3. **Check for OSV API outage:**
+   ```bash
+   stella connector osv api-status
+   ```
+   Also check: https://osv.dev/
+
+4. **Check GCS bucket access (OSV uses GCS for bulk data):**
+   ```bash
+   stella connector osv gcs-status
+   ```
+
+---
+
+## Resolution
+
+### Immediate mitigation
+
+1. **Retry sync for specific ecosystem:**
+   ```bash
+   stella admin feeds refresh --source osv --ecosystem npm
+   ```
+
+2. **Sync from GCS bucket directly (faster for bulk):**
+   ```bash
+   stella connector osv sync-from-gcs
+   ```
+
+3. **Load from offline bundle:**
+   ```bash
+   stella offline load --source osv --package osv-bundle-latest.tar.gz
+   ```
+
+### Root cause fix
+
+**If API request failing:**
+
+1. Check API endpoint:
+   ```bash
+   stella connector osv api-test
+   ```
+
+2. Verify no proxy blocking:
+   ```bash
+   stella connector config set osv.proxy <proxy-url>
+   ```
+
+**If GCS access failing:**
+
+1. Check GCS connectivity:
+   ```bash
+   stella connector osv gcs-test
+   ```
+
+2. Enable anonymous access (default):
+   ```bash
+   stella connector config set osv.gcs_auth anonymous
+   ```
+
+3. Or configure service account:
+   ```bash
+   stella connector config set osv.gcs_credentials /path/to/sa-key.json
+   ```
+
+**If specific ecosystem failing:**
+
+1. Disable problematic ecosystem temporarily:
+   ```bash
+   stella connector config set osv.ecosystems.disabled <ecosystem>
+   ```
+
+2. Check ecosystem data format:
+   ```bash
+   stella connector osv ecosystem-check <ecosystem>
+   ```
+
+**If parsing errors:**
+
+1. Check for schema changes:
+   ```bash
+   stella connector osv schema-check
+   ```
+
+2. Update connector:
+   ```bash
+   stella upgrade --component connector-osv
+   ```
+
+### Verification
+
+```bash
+# Force sync
+stella admin feeds refresh --source osv
+
+# Monitor sync progress
+stella admin feeds status --source osv --watch
+
+# Verify ecosystem coverage
+stella connector osv ecosystems status
+
+# Query recent vulnerability
+stella vuln query OSV-2026-xxxx
+
+# Check no errors
+stella connector logs osv --level error --last 1h
+```
+
+---
+
+## Prevention
+
+- [ ] **Bulk sync:** Use GCS bulk sync for initial load and daily updates
+- [ ] **Monitoring:** Alert on ecosystem sync failures
+- [ ] **Redundancy:** NVD/GHSA provide overlapping coverage for major ecosystems
+- [ ] **Offline:** Maintain weekly offline bundle
+
+---
+
+## Related Resources
+
+- **Architecture:** `docs/modules/concelier/connectors.md`
+- **Connector config:** `docs/modules/concelier/operations/connectors/osv.md`
+- **Related runbooks:** `connector-nvd.md`, `connector-ghsa.md`
+- **OSV API docs:** https://osv.dev/docs/