git.stella-ops.org/docs/operations/runbooks/connector-osv.md

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:

   stella doctor --check check.connector.osv-health
   

2. Check OSV sync status:

   stella admin feeds status --source osv
   

3. Test OSV API connectivity:

   stella connector test osv
   

Deep diagnosis

1. Check ecosystem-specific status:

   stella connector osv ecosystems status
   

   Look for: Failed ecosystems, stale ecosystems

2. Check sync logs:

   stella connector logs osv --last 1h --level error
   

   Look for: API errors, parsing failures, timeout

3. Check for OSV API outage:

   stella connector osv api-status
   

   Also check: https://osv.dev/

4. Check GCS bucket access (OSV uses GCS for bulk data):

   stella connector osv gcs-status
   

---

Resolution

Immediate mitigation

1. Retry sync for specific ecosystem:

   stella admin feeds refresh --source osv --ecosystem npm
   

2. Sync from GCS bucket directly (faster for bulk):

   stella connector osv sync-from-gcs
   

3. Load from offline bundle:

   stella offline load --source osv --package osv-bundle-latest.tar.gz
   

Root cause fix

If API request failing:

1. Check API endpoint:

   stella connector osv api-test
   

2. Verify no proxy blocking:

   stella connector config set osv.proxy <proxy-url>
   

If GCS access failing:

1. Check GCS connectivity:

   stella connector osv gcs-test
   

2. Enable anonymous access (default):

   stella connector config set osv.gcs_auth anonymous
   

3. Or configure service account:

   stella connector config set osv.gcs_credentials /path/to/sa-key.json
   

If specific ecosystem failing:

1. Disable problematic ecosystem temporarily:

   stella connector config set osv.ecosystems.disabled <ecosystem>
   

2. Check ecosystem data format:

   stella connector osv ecosystem-check <ecosystem>
   

If parsing errors:

1. Check for schema changes:

   stella connector osv schema-check
   

2. Update connector:

   stella upgrade --component connector-osv
   

Verification

# 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/