# 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.