stella-ops.org/git.stella-ops.org

Fork 0

Files

master 702a27ac83 synergy moats product advisory implementations

2026-01-17 01:32:20 +02:00

4.5 KiB

Raw Blame History

Runbook: Feed Connector - NVD Connector Failures

Sprint: SPRINT_20260117_029_DOCS_runbook_coverage Task: RUN-006 - Feed Connector Runbooks

Metadata

Field	Value
Component	Concelier / NVD Connector
Severity	High
On-call scope	Platform team
Last updated	2026-01-17
Doctor check	`check.connector.nvd-health`

Symptoms

NVD feed sync failing or stale (> 24h since last successful sync)
Alert ConnectorNvdSyncFailed firing
Error: "NVD API request failed" or "rate limit exceeded"
Vulnerability data missing or outdated
Metric connector_sync_failures_total{source="nvd"} increasing

Impact

Impact Type	Description
User-facing	Vulnerability scans may miss recent CVEs
Data integrity	Data becomes stale; no data loss
SLA impact	Vulnerability currency SLO violated (target: < 24h)

Diagnosis

Quick checks

Check Doctor diagnostics:

stella doctor --check check.connector.nvd-health

Check NVD sync status:
```
stella admin feeds status --source nvd
```
Look for: Last sync time, error message, sync state
Check NVD API connectivity:
```
stella connector test nvd
```

Deep diagnosis

Check NVD API key status:
```
stella connector credentials show nvd
```
Problem if: API key expired or rate limit exhausted
Check NVD API rate limit:
```
stella connector nvd rate-limit-status
```
Problem if: Remaining requests = 0, reset time in future
Check for NVD API outage:
```
stella connector nvd api-status
```
Also check: https://nvd.nist.gov/general/news
Check sync logs:
```
stella connector logs nvd --last 1h --level error
```
Look for: HTTP status codes, timeout errors, parsing failures

Resolution

Immediate mitigation

If rate limited, wait for reset:

stella connector nvd rate-limit-status
# Wait for reset time, then:
stella admin feeds refresh --source nvd

If API key expired, use anonymous mode (slower):

stella connector config set nvd.api_key_mode anonymous
stella admin feeds refresh --source nvd

Load from offline bundle if urgent:

# If you have a recent offline bundle:
stella offline load --source nvd --package nvd-bundle-latest.tar.gz

Root cause fix

If API key expired or invalid:

Generate new NVD API key at https://nvd.nist.gov/developers/request-an-api-key

Update API key:

stella connector credentials update nvd --api-key <new-key>

Verify connectivity:
```
stella connector test nvd
```

If rate limit consistently exceeded:

Increase sync interval to reduce API calls:

stella connector config set nvd.sync_interval 6h

Enable delta sync to reduce data volume:

stella connector config set nvd.delta_sync true

Request higher rate limit from NVD (if available)

If network/firewall issue:

Verify outbound connectivity to NVD API:
```
stella connector test nvd --verbose
```

Check proxy configuration if required:

stella connector config set nvd.proxy https://proxy:8080

If data parsing failures:

Check for NVD schema changes:
```
stella connector nvd schema-check
```

Update connector if schema changed:

stella upgrade --component connector-nvd

Verification

# Force sync
stella admin feeds refresh --source nvd --force

# Monitor sync progress
stella admin feeds status --source nvd --watch

# Verify recent CVEs are present
stella vuln query CVE-2026-XXXX  # Use a recent CVE ID

# Check no errors in recent logs
stella connector logs nvd --level error --last 1h

Prevention

API Key: Always use API key (not anonymous) for 10x rate limit
Monitoring: Alert on last sync > 24h or sync failure
Redundancy: Configure backup connector (OSV, GitHub Advisory) for overlap
Offline: Maintain weekly offline bundle for disaster recovery

Architecture: docs/modules/concelier/connectors.md
Connector config: docs/modules/concelier/operations/connectors/nvd.md
Related runbooks: connector-ghsa.md, connector-osv.md
Dashboard: Grafana > Stella Ops > Feed Connectors

4.5 KiB Raw Blame History