git.stella-ops.org/src/StellaOps.Concelier.Connector.Ghsa/AGENTS.md

AGENTS

Role

Implement a connector for GitHub Security Advisories (GHSA) when we need to ingest GHSA content directly (instead of crosswalking via OSV/NVD).

Scope

• Determine the optimal GHSA data source (GraphQL API, REST, or ecosystem export) and required authentication.
• Implement fetch logic with pagination, updated-since filtering, and cursor persistence.
• Parse GHSA records (identifiers, summaries, affected packages, versions, references, severity).
• Map advisories into canonical Advisory objects with aliases, references, affected packages, and range primitives.
• Provide deterministic fixtures and regression tests for the full pipeline.

Participants

• Source.Common (HTTP clients, fetch service, DTO storage).
• Storage.Mongo (raw/document/DTO/advisory stores and source state).
• Concelier.Models (canonical advisory types).
• Concelier.Testing (integration harness, snapshot helpers).

Interfaces & Contracts

• Job kinds: ghsa:fetch, ghsa:parse, ghsa:map.
• Support GitHub API authentication & rate limiting (token, retry/backoff).
• Alias set must include GHSA IDs and linked CVE IDs.

In/Out of scope

In scope:

• Full GHSA connector implementation with range primitives and provenance instrumentation.

Out of scope:

• Repo-specific advisory ingest (handled via GitHub repo exports).
• Downstream ecosystem-specific enrichments.

Observability & Security Expectations

• Log fetch pagination, throttling, and mapping stats.
• Handle GitHub API rate limits with exponential backoff and Retry-After.
• Sanitize/validate payloads before persistence.

Tests

• Add StellaOps.Concelier.Connector.Ghsa.Tests with canned GraphQL/REST fixtures.
• Snapshot canonical advisories; enable fixture regeneration with env flag.
• Confirm deterministic ordering/time normalisation.