Files

master 90c244948a Update AGENTS.md files across multiple modules to standardize task status update instructions and introduce a new document for Secret Leak Detection operations.

- Modified task status update instructions in AGENTS.md files to refer to corresponding sprint files as `/docs/implplan/SPRINT_*.md` instead of `docs/implplan/SPRINTS.md`.
- Added a comprehensive document for Secret Leak Detection operations detailing scope, prerequisites, rule bundle lifecycle, enabling the analyzer, policy patterns, observability, troubleshooting, and references.

2025-11-05 11:58:32 +02:00

3.3 KiB

Raw Blame History

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 concelier:merge:precedence:ranks (dictionary of source → rank, lower wins). Absent entries fall back to defaults.
Operator workflow: update etc/concelier.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.Concelier.Merge.Tests.
Shared fixtures (e.g., MongoIntegrationFixture, ConnectorTestHarness) live in ../StellaOps.Concelier.Testing.
Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.

Required Reading

docs/modules/concelier/architecture.md
docs/modules/platform/architecture-overview.md

Working Agreement

1. Update task status to DOING/DONE in both correspoding sprint file /docs/implplan/SPRINT_*.md and the local TASKS.md when you start or finish work.
1. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
1. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
1. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
1. Revert to TODO if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

3.3 KiB Raw Blame History