Concelier GHSA Connector - Operations Runbook

Last updated: 2026-05-08

This runbook is for operators who run the GitHub Security Advisories (GHSA) connector in a Stella Ops Concelier instance. It covers rate-limit telemetry, configuration, optional credential acquisition, the default job schedule, and the recovery steps to take when GitHub throttles the connector.

1. Overview

The GitHub Security Advisories (GHSA) connector pulls advisory metadata from the GitHub REST API /advisories endpoint. Public global advisories can be fetched anonymously; a GitHub token is optional and mainly raises rate limits or supports enterprise routing. GitHub enforces both primary and secondary rate limits, so operators must monitor usage and configure retries to avoid throttling incidents.

2. Rate-limit telemetry

The connector surfaces rate-limit headers on every fetch and exposes the following metrics via OpenTelemetry:

Dashboards and alerts:

• Alert when ghsa.ratelimit.remaining stays below RateLimitWarningThreshold for more than 5 minutes.
• Page if ghsa.ratelimit.headroom_pct_current remains below 10% for longer than a reset window.
• Alert on increase(ghsa.ratelimit.exhausted[15m]) > 0.

3. Configuration paths

The persisted source configuration is the primary operator path; see Advisory source credential entry for the shared workflow across connectors.

Primary operator path:

• Web UI: Security Posture -> Configure Sources or Ops -> Operations -> Feeds & Airgap -> Configure Sources
• CLI:

  stella db connectors configure ghsa \
    --server https://concelier.example.internal \
    --set apiToken=github_pat_xxx
  

The persisted source configuration key is apiToken. This field is optional for public global advisories. Secrets are retained server-side and are not echoed back after storage.

Compatibility fallback (concelier.yaml):

concelier:
  sources:
    ghsa:
      apiToken: "${GITHUB_PAT}"
      pageSize: 10
      maxPagesPerFetch: 1
      requestDelay: "00:00:00.200"
      failureBackoff: "00:05:00"
      rateLimitWarningThreshold: 500
      secondaryRateLimitBackoff: "00:02:00"

Recommendations:

• Increase requestDelay in burst-heavy or mirrored deployments.
• Anonymous deployments should keep the default small batch (pageSize=10, maxPagesPerFetch=1) to stay below GitHub’s unauthenticated REST quota. Tokened deployments can raise these values after confirming rate-limit headroom.
• Lower rateLimitWarningThreshold only if dashboards already page on the telemetry above.
• Keep secondaryRateLimitBackoff at 60 seconds or more for low-privilege tokens.

4. Credential acquisition

Where to sign in:

• https://github.com/settings/personal-access-tokens

What to create:

• Optional: a GitHub personal access token or a GitHub App token that can call the security advisories REST endpoints

Upstream notes:

• GitHub documents that the global security advisories endpoint can serve public reviewed advisories anonymously and works with fine-grained PATs.
• Stella Ops treats apiToken as optional for this connector path. Configure a token only when anonymous rate limits are too low, when routing through enterprise GitHub, or when an operator policy requires authenticated API use.
• If the target organization uses SAML SSO, authorize the PAT for that org after creation.
• Some organizations restrict classic PATs or require PAT approval. That policy is external to Stella Ops.

Legacy host/env distribution remains available for older deployments, but it is no longer the preferred operator path.

5. Default job schedule

These defaults spread GHSA stages across the hour so fetch completes before parse/map fire.

6. Runbook steps when throttled

1. Check ghsa.ratelimit.exhausted for the affected phase.
2. Check the latest source:ghsa:fetch job error. Primary anonymous REST quota exhaustion before any list data is fetched is expected to fail fast and rely on the next scheduled run or a manual retry after reset.
3. If quota is exhausted during detail fetches after a list page was read, the connector preserves already-fetched document ids in the cursor so later parse/map jobs can process partial progress and the next fetch can resume the same window.
4. If exhaustion persists:
   • Verify no unrelated jobs are sharing the token.
   • Temporarily reduce MaxPagesPerFetch or PageSize.
   • Consider provisioning a dedicated token.
5. After quota resets, return settings to their normal values and monitor for at least one hour.

7. Canonical metric fallback analytics

When GitHub omits CVSS vectors or scores, the connector assigns a deterministic canonical metric ID in the form ghsa:severity/<level> and publishes it to Merge so severity precedence still resolves against GHSA even without CVSS data.