From fb35aabb7a3ba46a92495d7533464ed6fba81984 Mon Sep 17 00:00:00 2001 From: Toni Bergholm Date: Sat, 18 Jul 2026 13:44:20 +0300 Subject: [PATCH] =?UTF-8?q?docs(audit):=20correct=20final=20Scorecard=20st?= =?UTF-8?q?ate=20=E2=80=94=203=20open=20alerts,=20all=20non-gaps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit After the re-scan on the #91 merge commit, the honest picture: - BranchProtection 3->8/10 (config complete; top 2 pts need >=2 reviewers, impractical for a 2-person team). - CodeReview still 0 — a trailing 'N/25 approved changesets' history metric that self-heals as reviewed PRs accumulate, not a config switch. - CIIBestPractices — optional OpenSSF badge. Corrects the fifth-round projection that #4/#14 would 'clear on next scan': the configuration completed, but these two persist as a team-size scoring cap and a self-healing metric. G-032/T-16 is closed either way. --- docs/audit/gap-analysis-source.md | 31 ++++++++++++++++++------ docs/audit/ostif-best-practices-audit.md | 14 ++++++----- 2 files changed, 32 insertions(+), 13 deletions(-) diff --git a/docs/audit/gap-analysis-source.md b/docs/audit/gap-analysis-source.md index 4fc945da..8e3e690a 100644 --- a/docs/audit/gap-analysis-source.md +++ b/docs/audit/gap-analysis-source.md @@ -689,13 +689,30 @@ rule now has `required_approving_review_count: 1`, self-merge anymore; the two admin accounts review each other's PRs. **Follow-up (same day): `.github/CODEOWNERS` added and code-owner review -required.** The one residual branch-protection sub-item — `codeowners review -is not required` — is now closed: `.github/CODEOWNERS` names both admin -accounts as owners of everything (with explicit callouts for -`crates/crypto`, `crates/tlsio`, `.github`, and the security docs), and the -ruleset's `require_code_owner_review` was set to `true` (verified live). The -`BranchProtectionID` check now has no residual warnings to raise. Only the -optional OpenSSF badge remains. +required.** `.github/CODEOWNERS` names both admin accounts as owners of +everything (with explicit callouts for `crates/crypto`, `crates/tlsio`, +`.github`, and the security docs), and the ruleset's +`require_code_owner_review` was set to `true` (verified live; PR #91). + +**Actual post-remediation Scorecard scores (verified after the re-scan on the +#91 merge commit — corrects the earlier "will clear on next scan" projection):** + +- `BranchProtectionID` (#4): **score 3 → 8.** All configurable protections are + on; the single remaining warning is "required approving review count is 1" — + Scorecard reserves the top score for **≥2** required reviewers, which for a + two-maintainer team would force every PR through both people. 8/10 is the + sensible ceiling here, not an unmet gap. The config is complete. +- `CodeReviewID` (#14): **score 0, "2/25 approved changesets."** This is a + *trailing* metric over the last 25 merged PRs, not a config switch: only the + PRs merged under the new required-approval rule carry approvals, so it climbs + on its own as reviewed PRs accumulate. Nothing left to configure. +- `CIIBestPracticesID` (#16): optional OpenSSF badge, "InProgress" — not a + guide-required gap. + +Net: the branch-protection/code-review **configuration** is complete and +correct (G-032/T-16 closed); the three still-open alerts are a team-size +scoring artifact, a self-healing history metric, and an optional badge — +none require further change. Every non-deferred gap in the 35-gap set is now resolved. Remaining: the Deferred tier T-22…T-25 (gated on a first distribution channel) and the two diff --git a/docs/audit/ostif-best-practices-audit.md b/docs/audit/ostif-best-practices-audit.md index 35d5c4ac..b693b0f0 100644 --- a/docs/audit/ostif-best-practices-audit.md +++ b/docs/audit/ostif-best-practices-audit.md @@ -3,7 +3,7 @@ title: "Gap Analysis: src-control vs OSTIF Security Best Practices Guide" comparison_direction: "src-control repository (current state) -> OSTIF/Least Authority Security Best Practices Guide (desired state)" scope: "The whole repository (code, CI, docs, GitHub configuration via live API) compared against all six OSTIF practice areas; the guide's missing 08-what-next.md chapter and the external git-agentic.com website were excluded." generated: "2026-07-18" -updated: "2026-07-18 — fifth round: second maintainer + required PR approvals enabled, closing G-032/T-16; code-scanning now 1 open alert (the optional OpenSSF badge). Every non-deferred gap is resolved." +updated: "2026-07-18 — sixth round: CODEOWNERS + code-owner review added (#91); every non-deferred gap resolved. 3 Scorecard alerts remain open, all non-gaps — branch-protection at 8/10 (capped by 2-reviewer scoring), a self-healing code-review history metric, and the optional OpenSSF badge." generated_by: "han:gap-analysis" sections_included: - executive_summary @@ -42,7 +42,7 @@ Every gap has a stable ID. Sections 3–5 reference those IDs. The full evidence **Both actionable tiers of the work plan are done, and the one item that had been deferred for lack of a second reviewer is now also closed.** The Now tier (T-1…T-9, T-26) and the Soon tier (T-10…T-21) all shipped across pull requests #76–#87, plus repository-settings changes, an organization-wide two-factor-authentication requirement, and — as of later on 2026-07-18 — a second maintainer and required pull-request approvals (closing G-032/T-16). Only the **Deferred tier (T-22…T-25)** remains — OSS-Fuzz enrollment, reproducible builds, a release pipeline with supply-chain attestations, and a hardening guide for people who run the server component — and every one of those is deliberately parked behind a trigger that hasn't happened yet: the project still distributes nothing for a consumer to verify. -**The independent security scorecard tells the story in numbers: 17 open findings became 3, and after required reviews were enabled only 1 remains — the optional badge.** +**The independent security scorecard tells the story in numbers: 17 open findings became 3, and every one of those 3 is now a non-gap** — see the update at the end of this section for what each represents after required reviews and code-owner review were enabled. | Scorecard finding (first run) | Now/Soon fix | Status | |---|---|---| @@ -55,13 +55,15 @@ Every gap has a stable ID. Sections 3–5 reference those IDs. The full evidence The **automated code analysis is fully clean** — zero open findings — and now covers the desktop application's language as well as the core (T-3). -**Update (2026-07-18, later the same day): the two review-related findings are now resolved.** A second maintainer account was added, and the trunk protection was set to require **1 approval** from someone other than the last pusher, with stale approvals dismissed on push and last-push approval required. That closes gap G-032 / todo T-16 — it was the only remaining non-deferred gap — and the two Scorecard findings it drove (required review approvals, and branch-protection completeness) clear on the next weekly scan. Nobody self-merges now; the two admin accounts review each other's pull requests. +**Update (2026-07-18, later the same day): the review-related gap is fully closed and the protection is complete.** A second maintainer account was added, and the trunk protection was set to require **1 approval** from someone other than the last pusher, plus code-owner review (a `CODEOWNERS` file naming both accounts), with stale approvals dismissed on push and last-push approval required. That closes gap G-032 / todo T-16 — the only remaining non-deferred gap — and nobody self-merges now; the two admin accounts review each other's pull requests. -**That leaves one open code-scanning finding, and it is optional:** +**Three code-scanning findings remain open after the re-scan, and none is an unmet gap:** -- **An optional best-practices badge**, now showing "in progress." Completing it is nice-to-have, not a gap the guide requires. +- **Branch protection scored 3 → 8 of 10.** Every configurable protection is on; the top two points are reserved for *two or more* required reviewers, which for a two-person team would force every change through both people. 8/10 is the sensible ceiling, not a gap — the configuration is complete. +- **Code-review coverage is a trailing history metric**, counting approvals across the most recent merged changes. It climbs on its own as reviewed changes accumulate; only the ones merged under the new rule carry approvals yet. Nothing left to configure. +- **An optional best-practices badge**, showing "in progress." Nice-to-have, not required by the guide. -*(For the audit trail: these findings originally shared the root cause "review approvals set to zero," which was deliberately held because a lone maintainer cannot approve their own change under the platform's rules. Adding a second reviewer removed that blocker. The branch-protection finding had already improved once merge-gating on passing checks landed via T-9.)* +*(For the audit trail: the first two findings originally shared the root cause "review approvals set to zero," deliberately held because a lone maintainer cannot approve their own change under the platform's rules. Adding a second reviewer removed that blocker; the branch-protection finding had also improved earlier once merge-gating on passing checks landed via T-9. An earlier draft of this section projected both would "clear on the next scan" — the configuration did complete, but the two findings persist as a team-size scoring cap and a self-healing history metric respectively, which is why this note states the outcome precisely.)* **Two closing items still need a human and cannot be done from the repository:** deploying the machine-readable security-contact file to the project website (`/.well-known/security.txt`), and the maintainer personally confirming the security-feed subscriptions the documentation now lists. Both are noted in Section 5.