# AGENTS
## Role
Implement the CISA Known Exploited Vulnerabilities (KEV) catalogue connector to ingest KEV entries for enrichment and policy checks.

## Scope
- Integrate with the official KEV JSON feed; understand schema, update cadence, and pagination (if any).
- Implement fetch job with incremental updates, checksum validation, and cursor persistence.
- Parse KEV entries (CVE ID, vendor/product, required actions, due dates).
- Map entries into canonical `Advisory` (or augmentation) records with aliases, references, affected packages, and range primitives capturing enforcement metadata.
- Deliver deterministic fixtures and regression tests.

## Participants
- `Source.Common` (HTTP client, fetch service, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Feedser.Models` (advisory + range primitive types).
- `Feedser.Testing` (integration fixtures & snapshots).

## Interfaces & Contracts
- Job kinds: `kev:fetch`, `kev:parse`, `kev:map`.
- Persist upstream `catalogLastUpdated` / ETag to detect changes.
- Alias list must include CVE ID; references should point to CISA KEV listing and vendor advisories.

## In/Out of scope
In scope:
- KEV feed ingestion and canonical mapping.
- Range primitives capturing remediation due dates or vendor requirements.

Out of scope:
- Compliance policy enforcement (handled elsewhere).

## Observability & Security Expectations
- Log fetch timestamps, updated entry counts, and mapping stats.
- Handle data anomalies and record failures with backoff.
- Validate JSON payloads before persistence.
- Structured informational logs should surface the catalog version, release timestamp, and advisory counts for each successful parse/map cycle.

## Operational Notes
- HTTP allowlist is limited to `www.cisa.gov`; operators should mirror / proxy that hostname for air-gapped deployments.
- CISA publishes KEV updates daily (catalogVersion follows `yyyy.MM.dd`). Expect releases near 16:30–17:00 UTC and retain overlap when scheduling fetches.

## Tests
- Add `StellaOps.Feedser.Source.Kev.Tests` covering fetch/parse/map with KEV JSON fixtures.
- Snapshot canonical output; allow fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
