194 lines
4.1 KiB
Markdown
194 lines
4.1 KiB
Markdown
# 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/
|