git.stella-ops.org/docs/modules/concelier/operations/connectors/ghsa.md

Concelier GHSA Connector - Operations Runbook

Last updated: 2026-04-22

1. Overview

The GitHub Security Advisories (GHSA) connector pulls advisory metadata from the GitHub REST API /security/advisories endpoint. 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:

Metric	Description	Tags
ghsa.ratelimit.limit	Samples the reported request quota at fetch time.	phase, resource
ghsa.ratelimit.remaining	Remaining requests returned by X-RateLimit-Remaining.	phase, resource
ghsa.ratelimit.reset_seconds	Seconds until X-RateLimit-Reset.	phase, resource
ghsa.ratelimit.headroom_pct	Percentage of quota still available.	phase, resource
ghsa.ratelimit.headroom_pct_current	Latest headroom percentage per resource.	phase, resource
ghsa.ratelimit.exhausted	Incremented whenever GitHub returns zero remaining quota and the connector delays before retrying.	phase

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

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. Secrets are retained server-side and are not echoed back after storage.

Compatibility fallback (concelier.yaml):

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

Recommendations:

• Increase requestDelay in burst-heavy or mirrored deployments.
• 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:

• 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.
• The current StellaOps GHSA connector still validates that apiToken is present, so skipping the token is not supported for this connector path.
• 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 StellaOps.

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

5. Default job schedule

Job kind	Cron	Timeout	Lease
source:ghsa:fetch	1,11,21,31,41,51 * * * *	6 minutes	4 minutes
source:ghsa:parse	3,13,23,33,43,53 * * * *	5 minutes	4 minutes
source:ghsa:map	5,15,25,35,45,55 * * * *	5 minutes	4 minutes

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. Confirm the connector is delaying before retry.
3. If exhaustion persists:
   • Verify no unrelated jobs are sharing the token.
   • Temporarily reduce MaxPagesPerFetch or PageSize.
   • Consider provisioning a dedicated token.
4. 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.