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

Runbook: Feed Connector - GitHub Security Advisories (GHSA) Failures

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

Metadata

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

---

Symptoms

• GHSA feed sync failing or stale
• Alert ConnectorGhsaSyncFailed firing
• Error: "GitHub API rate limit exceeded" or "GraphQL query failed"
• GitHub Advisory Database vulnerabilities missing
• Metric connector_sync_failures_total{source="ghsa"} increasing

---

Impact

Impact Type	Description
User-facing	GitHub ecosystem vulnerabilities may be missed
Data integrity	Data becomes stale; no data loss
SLA impact	Vulnerability currency SLO violated for GitHub packages

---

Diagnosis

Quick checks

1. Check Doctor diagnostics:

   stella doctor --check check.connector.ghsa-health
   

2. Check GHSA sync status:

   stella admin feeds status --source ghsa
   

3. Test GitHub API connectivity:

   stella connector test ghsa
   

Deep diagnosis

1. Check GitHub API rate limit:

   stella connector ghsa rate-limit-status
   

   Problem if: Remaining = 0, rate limit exceeded

2. Check GitHub token permissions:

   stella connector credentials show ghsa --check-scopes
   

   Required scopes: public_repo, read:packages (for private advisory access)

3. Check sync logs:

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

   Look for: GraphQL errors, pagination issues, timeout

4. Check for GitHub API outage:

   stella connector ghsa api-status
   

   Also check: https://www.githubstatus.com/

---

Resolution

Immediate mitigation

1. If rate limited, wait for reset:

   stella connector ghsa rate-limit-status
   # Note the reset time, then:
   stella admin feeds refresh --source ghsa
   

2. Use secondary token if available:

   stella connector credentials rotate ghsa --to secondary
   stella admin feeds refresh --source ghsa
   

3. Load from offline bundle:

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

Root cause fix

If rate limit consistently exceeded:

1. Increase sync interval:

   stella connector config set ghsa.sync_interval 4h
   

2. Enable incremental sync:

   stella connector config set ghsa.incremental_sync true
   

3. Use authenticated requests (10x rate limit):

   stella connector credentials update ghsa --token <github-pat>
   

If token expired or invalid:

1. Generate new GitHub PAT at https://github.com/settings/tokens

2. Update token:

   stella connector credentials update ghsa --token <new-token>
   

3. Verify scopes:

   stella connector credentials show ghsa --check-scopes
   

If GraphQL query failing:

1. Check for API schema changes:

   stella connector ghsa schema-check
   

2. Update connector if schema changed:

   stella upgrade --component connector-ghsa
   

If pagination broken:

1. Reset sync cursor:

   stella connector ghsa reset-cursor
   

2. Force full resync:

   stella admin feeds refresh --source ghsa --full
   

Verification

# Force sync
stella admin feeds refresh --source ghsa

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

# Verify recent advisories present
stella vuln query GHSA-xxxx-xxxx-xxxx  # Use a recent GHSA ID

# Check no errors
stella connector logs ghsa --level error --last 1h

---

Prevention

• Authentication: Always use authenticated requests for 5000/hr rate limit
• Monitoring: Alert on last sync > 12h or sync failures
• Redundancy: Use NVD/OSV as backup for GitHub ecosystem coverage
• Token rotation: Rotate tokens before expiration

---

Related Resources

• Architecture: docs/modules/concelier/connectors.md
• Connector config: docs/modules/concelier/operations/connectors/ghsa.md
• Related runbooks: connector-nvd.md, connector-osv.md
• GitHub API docs: https://docs.github.com/en/graphql