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