34 lines
2.6 KiB
Markdown
34 lines
2.6 KiB
Markdown
# AGENTS
|
|
## Role
|
|
Deterministic merge and reconciliation engine; builds identity graph via aliases; applies precedence (PSIRT/OVAL > NVD; KEV flag only; regional feeds enrich); produces canonical advisory JSON and merge_event audit trail.
|
|
## Scope
|
|
- Identity: resolve advisory_key (prefer CVE, else PSIRT/Distro/JVN/BDU/GHSA/ICSA); unify aliases; detect collisions.
|
|
- Precedence: override rules for affected ranges (vendor PSIRT/OVAL over registry), enrichment-only feeds (CERTs/JVN/RU-CERT), KEV toggles exploitKnown only.
|
|
- Range comparers: RPM NEVRA comparer (epoch:version-release), Debian EVR comparer, SemVer range resolver; platform-aware selection.
|
|
- Merge algorithm: stable ordering, pure functions, idempotence; compute beforeHash/afterHash over canonical form; write merge_event.
|
|
- Conflict reporting: counters and logs for identity conflicts, reference merges, range overrides.
|
|
## Participants
|
|
- Storage.Mongo (reads raw mapped advisories, writes merged docs plus merge_event).
|
|
- Models (canonical types).
|
|
- Exporters (consume merged canonical).
|
|
- Core/WebService (jobs: merge:run, maybe per-kind).
|
|
## Interfaces & contracts
|
|
- AdvisoryMergeService.MergeAsync(ids or byKind): returns summary {processed, merged, overrides, conflicts}.
|
|
- Precedence table configurable but with sane defaults: RedHat/Ubuntu/Debian/SUSE > Vendor PSIRT > GHSA/OSV > NVD; CERTs enrich; KEV sets flags.
|
|
- Range selection uses comparers: NevraComparer, DebEvrComparer, SemVerRange; deterministic tie-breakers.
|
|
- Provenance propagation merges unique entries; references deduped by (url, type).
|
|
|
|
## Configuration
|
|
- Precedence overrides bind via `feedser:merge:precedence:ranks` (dictionary of `source` → `rank`, lower wins). Absent entries fall back to defaults.
|
|
- Operator workflow: update `etc/feedser.yaml` or environment variables, restart merge job; overrides surface in metrics/logs as `AdvisoryOverride` entries.
|
|
## In/Out of scope
|
|
In: merge logic, precedence policy, hashing, event records, comparers.
|
|
Out: fetching/parsing, exporter packaging, signing.
|
|
## Observability & security expectations
|
|
- Metrics: merge.delta.count, merge.identity.conflicts, merge.range.overrides, merge.duration_ms.
|
|
- Logs: decisions (why replaced), keys involved, hashes; avoid dumping large blobs; redact secrets (none expected).
|
|
## Tests
|
|
- Author and review coverage in `../StellaOps.Feedser.Merge.Tests`.
|
|
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Feedser.Testing`.
|
|
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
|