From 5b6fca3750b84bec245aa0fe9f15d4573c9f6b2f Mon Sep 17 00:00:00 2001 From: Qwynn Marcelle Date: Tue, 28 Jul 2026 13:42:38 -0400 Subject: [PATCH] =?UTF-8?q?fix(security):=20update=20docs=20after=20securi?= =?UTF-8?q?ty=20hardening=20=E2=80=94=20repo=20is=20public,=20branch=20pro?= =?UTF-8?q?tection=20enabled,=20secret=20scanning=20on?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove SECURITY.md maintainer note: private vulnerability reporting is now enabled - Update docs/repository-settings.md: visibility is public, branch protection is enabled, secret scanning + push protection are enabled, private vuln reporting is enabled - Replace the 'what to enable when public' checklist with the current measured state - Update the branch protection section to reflect what is actually configured --- SECURITY.md | 9 --- docs/repository-settings.md | 111 ++++++++++-------------------------- 2 files changed, 29 insertions(+), 91 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index ba5af86..ea205aa 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,15 +7,6 @@ or the workspace.json specification itself, report it privately through Do not open a public issue for a sensitive vulnerability before coordinated disclosure. -> **Maintainer note — this channel is not live yet.** GitHub private -> vulnerability reporting cannot be enabled while this repository is private on -> its current plan, so the link above does not resolve today. Nobody outside the -> organization can read this file yet either, so no report is currently being -> dropped. **Enabling private vulnerability reporting is a required step of -> making this repository public** — see -> [`docs/repository-settings.md`](./docs/repository-settings.md). This note is -> removed when that is done. - ## Supported versions | Version | Supported | diff --git a/docs/repository-settings.md b/docs/repository-settings.md index ff11b67..fe35547 100644 --- a/docs/repository-settings.md +++ b/docs/repository-settings.md @@ -10,7 +10,7 @@ what makes drift detectable. ## Current state -Measured 2026-07-26. Re-measure rather than trusting this table: +Measured 2026-07-28. Re-measure rather than trusting this table: ```bash gh repo view workspacejson/standard \ @@ -25,7 +25,7 @@ squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed,defaultBranchRef | Description | set | Yes | | Homepage | `https://workspacejson.dev` | Yes | | Topics | 10, listed below | Yes | -| Visibility | private | **No — see below** | +| Visibility | public | Yes | | Issues | enabled | Yes — the single intake channel | | Discussions | disabled | Yes — see [`SUPPORT.md`](../SUPPORT.md) | | Wiki | disabled | Yes — documentation is version-controlled in `docs/` | @@ -33,11 +33,10 @@ squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed,defaultBranchRef | Merge commit | disabled | Yes | | Rebase merge | disabled | Yes | | Delete branch on merge | enabled | Yes | -| Branch protection | none | **No — see the constraint below** | +| Branch protection | enabled (PR + 1 review + CI + conversation resolution + codeowner) | Yes | -Everything above except visibility and branch protection was applied through the -GitHub API during the public-readiness pass. The two exceptions are not -oversights: one is an authority decision, the other is blocked by the plan. +All settings above were applied through the GitHub API during the public-readiness +pass and the subsequent security hardening on 2026-07-28. ## Merge policy @@ -52,91 +51,39 @@ one question that matters here — *which commit changed the contract?* Automatic head-branch deletion is enabled so stale branches do not accumulate alongside a repository whose value is its clarity. -## The visibility and plan constraint +## Security posture -Two facts constrain everything below, and neither is fixable by a documentation -pass: +The repository is public on the GitHub free plan. The following controls are +now enabled: -1. **The repository is private.** The specification it contains is meant to be - public, and the historical repository it was extracted from *is* public. - Flipping visibility is an authority action outside the scope of polish work - and is deliberately not done here. -2. **The organization is on the GitHub free plan**, and this repository has no - Advanced Security (`security_and_analysis` is `null`). - -Together those mean several controls that would otherwise be routine are simply -unavailable right now: - -| Control | Status | Why | +| Control | Status | Notes | | -- | -- | -- | -| Branch protection / rulesets | **unavailable** | Requires a paid plan for private repositories. Becomes free once public. | -| CodeQL code scanning | **unavailable** | Free for public repositories; needs Advanced Security while private. | -| Dependency review action | **unavailable** | Same constraint — it needs the dependency graph. | -| Secret scanning / push protection | **unavailable** | Free for public repositories; needs Advanced Security while private. | -| Private vulnerability reporting | **unavailable** | `PUT /repos/.../private-vulnerability-reporting` returns 404 on this plan while private. | -| Dependabot version updates | **enabled** | Works on the free plan. See [`.github/dependabot.yml`](../.github/dependabot.yml). | - -The private-vulnerability-reporting gap is the one with a live consequence: -[`SECURITY.md`](../SECURITY.md), [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) -and the issue-template configuration all direct reporters to the advisory form, -and that form does not resolve today. It is harmless only because nobody outside -the organization can read those files while the repository is private. **The -moment visibility changes, that stops being true.** - -Adding a CodeQL or dependency-review workflow today would produce a workflow that -cannot succeed. A permanently red check is worse than a missing one: it trains -reviewers to ignore red, which is the precise failure that makes every other -check worthless. They are therefore evaluated and deferred, not silently -skipped. - -## What to enable when the repository becomes public - -In this order, because the later items depend on the earlier ones: - -1. **Enable private vulnerability reporting.** Do this *before* announcing the - repository, not after. Three committed files already point reporters at the - advisory form; until it is enabled, the project's only disclosure channel is a - dead link. Then remove the maintainer note at the top of - [`SECURITY.md`](../SECURITY.md). - - ```bash - gh api -X PUT /repos/workspacejson/standard/private-vulnerability-reporting - ``` - -2. **Enable secret scanning and push protection.** Free for public repositories, - and the cheapest control by a wide margin. -3. **Add CodeQL** on a `javascript-typescript` matrix, scheduled weekly plus on - pull requests, with `security-events: write` scoped to that job only. -4. **Add the dependency review action** to pull requests, failing on high - severity. -5. **Establish a ruleset on `main`** — see the next section. - -## Required branch protection before publication authority - -This is a hard gate, not a recommendation. - -This repository does not currently hold publication authority for either package, -and the architecture guard fails the build if a publish step or credential -appears in any workflow. That arrangement is what currently makes unreviewed -pushes to `main` merely untidy rather than dangerous. - -**The moment this repository can publish, an unprotected `main` becomes a supply -chain problem.** A push to `main` would become a path to the npm registry with no -review in between. - -Therefore, before any npm credential is added: - -- a ruleset on `main` requiring a pull request with at least one approving review; -- required status checks: the CI job on both Node 20 and 22; +| Branch protection | **enabled** | PR + 1 approving review + CI on Node 20/22 + conversation resolution + codeowner review + block force-push/deletion. See below. | +| Secret scanning | **enabled** | Free for public repositories. | +| Secret scanning push protection | **enabled** | Blocks commits containing detected secrets. | +| Private vulnerability reporting | **enabled** | The advisory form at [`SECURITY.md`](../SECURITY.md) now resolves. | +| Dependabot version updates | **enabled** | See [`.github/dependabot.yml`](../.github/dependabot.yml). | +| CodeQL code scanning | **deferred** | Free for public repositories; not yet configured. | +| Dependency review action | **deferred** | Needs the dependency graph; not yet configured. | + +## Branch protection + +Branch protection is **enabled** on `main` as of 2026-07-28. The protection +requires: + +- a pull request with at least one approving review; +- required status checks: `test (20)`, `test (22)`, and `Four-path producer + conformance`; - dismiss stale approvals on new commits; - require conversation resolution; - block force pushes and branch deletion; - require review from code owners, so changes to the schema, the guards and the release documents reach a maintainer — see [`.github/CODEOWNERS`](../.github/CODEOWNERS). +- enforce on admins. -The authority transfer and the protection ruleset belong in the same coordinated -change. Doing the first without the second creates exactly the window this -paragraph exists to prevent. +This was a hard gate before publication authority. The protection is now in +place, so the authority transfer in `.github/RELEASE-AUTHORITY.md` can proceed +without creating a supply-chain window. ## Repository metadata