docs: security contacts adr [CM-1325]#4375
Conversation
Signed-off-by: Mouad BANI <mouad-mb@outlook.com>
Signed-off-by: Mouad BANI <mouad-mb@outlook.com>
PR SummaryLow Risk Overview The ADR documents the chosen design: Temporal daily batch ingestion plus an on-demand single-purl workflow, a tiered extractor hierarchy (A > B > D) with shared git-tree probing, reconciliation/noise filtering,
Reviewed by Cursor Bugbot for commit b85fa0b. Bugbot is set up for automated code reviews on this repo. Configure here. |
|
|
There was a problem hiding this comment.
Pull request overview
Adds ADR-0009 documenting the security-contacts worker architecture and links it from the ADR index.
Changes:
- Documents extraction, scoring, persistence, scheduling, and reconciliation decisions.
- Records alternatives, consequences, and risks.
- Updates the ADR index.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
docs/adr/0009-security-contacts-worker.md |
Adds the security-contacts ADR. |
docs/adr/README.md |
Links ADR-0009. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| comes back empty, 24 h execution timeout across the chain), plus a separate **on-demand | ||
| single-purl workflow** invoked by the akrites API when it hits a never-evaluated repo. Each repo |
| | A4 | RFC 9116 `security.txt` on the project homepage | `securityTxt.ts` | | ||
| | B1 | `SECURITY.md` (root, `.github/`, `docs/`) | `securityMd.ts` | | ||
| | B2 | Registry manifests — npm, PyPI, Maven, Cargo, NuGet, RubyGems, Composer | `extractors/registry/` | | ||
| | D | Top-3 committers (last 90 days) + repo owner profile; static Go ecosystem fallback | `topCommitters.ts`, `repoOwner.ts`, `registry/go.ts` | |
| - **Partial passes merge only**: when an extractor failed, the soft-delete step is skipped — a | ||
| source that wasn't consulted cannot wipe contacts it didn't see. Stale rows are cleaned on the | ||
| next fully-successful pass. |
| - Idempotent, self-advancing sweep: failed repos are marked attempted, failed chunks re-extract in | ||
| isolation, and re-runs converge instead of duplicating. | ||
| - The on-demand path fills coverage for non-critical purls lazily, exactly when the API needs them. | ||
| - Pure scoring/reconcile functions are unit-tested in isolation (`__tests__/`). |
| - **Single-writer assumption** — `writeContacts` takes no lock; correctness relies on the Temporal | ||
| schedule (SKIP overlap) and heartbeat-based supersession keeping one writer per repo. A future | ||
| second caller (e.g. a backfill script) must respect this or add locking. |
| - **Go packages get a static ecosystem fallback**: Go has no registry manifest carrying contact | ||
| metadata (the module proxy and pkg.go.dev expose none), so the Go fetcher makes no HTTP call and | ||
| always emits two tier-D `security-team` contacts per the Go security policy — | ||
| `security@golang.org` and the `https://g.co/vulnz` report form. At tier D they never outrank a |
This pull request adds a new architecture decision record (ADR-0009) that documents the design and implementation details for the security-contacts worker, which extracts, scores, and ingests security contact information for critical repositories. The ADR covers the tiered extraction hierarchy, confidence scoring, data reconciliation, GitHub API usage, write semantics, scheduling, and the on-demand ingestion path, as well as alternatives considered and associated risks. Additionally, the ADR is linked in the ADR index.
New ADR documenting security-contacts worker:
docs/adr/0009-security-contacts-worker.mdto comprehensively describe the architecture and decision process for the security-contacts worker, including extraction tiers, scoring, reconciliation, and operational details.docs/adr/README.mdto reference ADR-0009 in the ADR index.