Skip to content

Commit 72ad22c

Browse files
authored
Merge pull request #5411 from modelcontextprotocol/v2/docs/5334-advisory-public-pr
docs(security-advisory): bring the fix to v2/main through an opaque public PR
2 parents 7e12ca3 + 11f64f9 commit 72ad22c

6 files changed

Lines changed: 178 additions & 82 deletions

File tree

‎.claude/skills/board-ops/SKILL.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -299,8 +299,10 @@ fi
299299
# Then the two chained item-edit calls from "Add a card and set its fields".
300300
```
301301

302-
**Convert** it to an issue only after the advisory is **published**. The web UI
303-
has "Convert to issue" on the card; the API equivalent is:
302+
**Convert** it to an issue when its fix is ready to merge, keeping its opaque
303+
title; a follow-up card converts only after the advisory is **published**. When
304+
each happens, and what the issue gets, is the `/security-advisory` flow. The web
305+
UI has "Convert to issue" on the card; the API equivalent is:
304306

305307
```sh
306308
REPO_ID=$(gh api repos/modelcontextprotocol/servers --jq .node_id) || REPO_ID=

‎.claude/skills/release/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -599,8 +599,8 @@ added to the draft by hand:
599599

600600
- **Every advisory this release fixes**, as `--advisory GHSA-xxxx-yyyy-zzzz`,
601601
once each: the `[GHSA-…]` cards on the board for the milestone's work
602-
(`security-advisory`). Its fix shipped from a private fork with no public
603-
issue, so its reporters are no issue's author. A draft advisory works.
602+
(`security-advisory`). Its issue is converted from the card by a
603+
maintainer, so its reporters are no issue's author. A draft advisory works.
604604
- **Every outside contributor credited on one of the milestone's issues**, as
605605
`--thank "@login (#PR), <what it prototyped>, for #ISSUE"`, once per line
606606
of the prototype paragraph. The preview lists each candidate (below).

‎.claude/skills/security-advisory/SKILL.md‎

Lines changed: 132 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -26,15 +26,18 @@ things safe to say in public about the backlog are **aggregate counts** (how
2626
many are in each state). A branch named after the bug, or a commit message that
2727
describes it, discloses it as surely as an issue would.
2828

29-
Related: `/board-ops` holds the board IDs and the draft-card recipes, and
30-
`/issue-create` gives public tracking its labels and milestone **after
31-
publication**, never merely after the release (step 6).
32-
33-
⚠️ **The PR flow does not apply to the fix itself.** It needs a public issue
34-
and a public PR against `v2/main`, which is the disclosure this flow exists to
35-
delay. The fix is reviewed inside the private fork (step 4), and `AGENTS.md`
36-
records that fork PR as an exception to its PR rules (no public issue link, no
37-
labels, tracked by the draft card).
29+
Related: `/board-ops` holds the board IDs and the draft-card recipes,
30+
`/issue-create` gives the converted issue its labels and milestone (step 5),
31+
and `/pr-flow` opens the public PR that brings the fix to `v2/main` (step 5).
32+
33+
⚠️ **The fix is written and reviewed in the private fork, then merged through
34+
an opaque public PR.** The fork's PR (step 4) links no public issue, carries no
35+
labels and is tracked by the draft card; it is never merged. When the fix is
36+
ready to merge, the card converts to an issue that keeps its opaque title, and
37+
a public PR from the same opaque branch closes it (step 5). That PR follows
38+
`/pr-flow` except that **nothing in it describes the vulnerability** and it
39+
gets **no Copilot review**. `AGENTS.md` records both PRs as an exception to
40+
its PR rules.
3841

3942
## The flow
4043

@@ -44,8 +47,8 @@ labels, tracked by the draft card).
4447
| 2 | **Verify the claim**: which server, and does the code belong to it or to an SDK? | Judgment |
4548
| 3 | Valid and ours → **accept** (`triage` → `draft`); otherwise close with a reason | **Human only** |
4649
| 4 | Create the **private fork**, fix and review there | Mechanical |
47-
| 5 | Merge to `v2/main`, milestone merge, **release**, close the fork's PR, then **publish** | **Human only** (closing the fork's PR is mechanical) |
48-
| 6 | **After publication**, convert the draft card into a public issue | Mechanical |
50+
| 5 | Close to the release: **convert the card** to an opaque issue, open the opaque **public PR**, merge it, close the fork's PR; then milestone merge, **release**, **publish** | **Human only** for merging, releasing and publishing (converting, the PR and closing the fork's PR are mechanical) |
51+
| 6 | **After publication**, give the issue its public title and the advisory link | Mechanical |
4952

5053
There is **one release line**. Every fix lands on `v2/main` and ships through
5154
the next milestone merge to `main` and a release, as any other change does
@@ -197,7 +200,8 @@ moves the advisory `triage` → `draft`. The API shows it as `state` and
197200
normally assigning a milestone, and a draft card cannot carry one, so for an
198201
advisory draft **accepting the advisory is the approval**. `AGENTS.md` records
199202
this as the advisory exemption to its `Incoming` ⇔ milestone rule. The milestone
200-
arrives with the public issue in step 6, where the ordinary rule resumes.
203+
arrives when the card converts to an issue in step 5, where the ordinary rule
204+
resumes.
201205

202206
**Invalid, out of scope, a duplicate, or an SDK's → close** with a comment
203207
saying which, and why; for an SDK's, say where it was routed. A reporter who is
@@ -249,8 +253,10 @@ any other change: a regression test that fails before the fix, and the gate
249253
under **Before pushing**. Name the branch
250254
`v2/fix/<ghsa-id>` (lowercase, **no descriptive slug**, since a branch name
251255
outlives the fork once merged), and keep commit messages equally opaque until
252-
publication. **The fork's PR targets `v2/main`**, never `main`: check its base
253-
before anyone merges it.
256+
publication. **The fork's PR targets `v2/main`**, never `main`, so the diff
257+
reviewed there is the diff that lands. It is where the review happens; it is
258+
**not merged**. The same branch is pushed to this repository and merged
259+
through a public PR (step 5), and the fork's PR is then closed.
254260

255261
⚠️ **Move the card as the work moves.** `In Progress` when the fix is started,
256262
`In Review` when the fork's PR is open. The fork is invisible to everyone not on
@@ -290,8 +296,10 @@ body nobody will read again.
290296
already accepted, and asking for the work approves it. Otherwise it goes in
291297
`Incoming`. Score its Priority with step 1's table, using the severity of the
292298
residual exposure rather than the advisory's.
293-
- **Say in the fix PR's body what the fix leaves open**, and link the
294-
follow-up. The advisory's text must say it too when it is published (step 5).
299+
- **Say in the fork PR's body what the fix leaves open**, and name the
300+
follow-up card. The public PR (step 5) says nothing about it, since
301+
describing the gap describes the vulnerability. The advisory's text must say
302+
it too when it is published (step 5).
295303

296304
Create it with `/board-ops`'s draft-card recipe, using the follow-up title in
297305
place of `[$GHSA]`.
@@ -308,35 +316,114 @@ of three cases:
308316
- It is non-security work outside the advisory's scope, which gets a public
309317
issue **after publication**, like any other finding.
310318

311-
### 5. Merge, release, publish (human only)
319+
### 5. Bring the fix to `v2/main`, release, publish
312320

313321
Publish **after** the fix has shipped in a release, never before: publishing
314322
discloses the vulnerability, and doing it while users have no upgrade hands out
315323
a working exploit. **Shipped** means the fixed version of that server is on npm
316324
or PyPI.
317325

318-
⚠️ **The patch stops being secret at MERGE, not at publish.** Merging the fork
319-
puts an ordinary public commit on `v2/main`, readable by anyone, and it then
320-
travels through the milestone merge to `main` before `release.yml` publishes it.
321-
The time between merge and publish is not a period of secrecy; it is a period
322-
of **exposure to anyone reading commits**, so keep it short: merge close to the
323-
release, and publish as soon as the release is out.
326+
⚠️ **The patch stops being secret when its branch reaches this repository, not
327+
at publish.** Pushing the fork's branch here (below) makes its commits readable
328+
by anyone, the public PR shows the diff, and the merge then travels through the
329+
milestone merge to `main` before `release.yml` publishes it. The time between
330+
that push and the publish is not a period of secrecy; it is a period of
331+
**exposure to anyone reading commits**, so keep it short: start this step close
332+
to the release, merge as soon as CI passes, and publish as soon as the release
333+
is out.
324334

325335
The release itself is a maintainer action (`release.yml` runs only when a
326336
maintainer publishes a GitHub Release, behind the `release` environment's
327337
approval; see [`RELEASING.md`](../../../RELEASING.md)). Say which server needs a release and
328338
stop there.
329339

330-
⚠️ **Publishing is irreversible and human-only.** It makes the advisory public,
331-
with no undo. Same rule as accepting: recommend, never perform.
340+
⚠️ **Merging, releasing and publishing are human-only.** Publishing is also
341+
irreversible: it makes the advisory public, with no undo. Same rule as
342+
accepting: recommend, never perform. Converting the card, opening the public
343+
PR and closing the fork's PR are mechanical.
344+
345+
#### Convert the card to an opaque issue
346+
347+
When the fix's review in the fork is done and the release is near, convert the
348+
draft card to an issue, so the public PR has an issue to close and a card that
349+
tracks it.
350+
351+
⚠️ **Convert the draft; do not file a new issue.** "Convert to issue" creates a
352+
**new** issue from the draft card, and there is no way to point an existing card
353+
at an issue filed separately, so filing by hand and then converting produces two
354+
issues and two cards.
355+
356+
1. **Keep the opaque title**, `[GHSA-xxxx-yyyy-zzzz]`, and the
357+
link-and-triage body (step 1). The issue takes the card's title and body,
358+
and the advisory is still private, so no summary may appear yet (step 6
359+
adds it). The advisory link in the body opens only for people on the
360+
advisory.
361+
2. **Convert the draft card to an issue** in `modelcontextprotocol/servers`
362+
(the card keeps its place and its field values). The recipe is in
363+
`/board-ops`.
364+
3. Apply the labels and milestone from `/issue-create` (steps 1 and 2): `v2`,
365+
one type label (normally `bug`), the server's scope label, and the milestone
366+
of the release the fix will ship in. **Skip its board step**: the converted
367+
card is already on #43.
368+
369+
A **follow-up card stays a draft** here: its write-up describes the gap, so it
370+
converts only after publication (step 6).
371+
372+
#### Open the public PR
373+
374+
Push the fork's branch to this repository under the **same opaque name**,
375+
`v2/fix/<ghsa-id>`, and open the PR with `/pr-flow` steps 4 and 6. The fork has
376+
no CI, so run the gate on exactly what you push:
377+
378+
```sh
379+
GHSA=<GHSA_ID>
380+
BRANCH="v2/fix/$(tr '[:upper:]' '[:lower:]' <<<"$GHSA")"
381+
FORK=$(gh api repos/modelcontextprotocol/servers/security-advisories/$GHSA \
382+
--jq '.private_fork.full_name // empty') || FORK=
383+
[ -n "$FORK" ] || echo "no private fork for $GHSA (or the lookup failed)" >&2
384+
WT="../$(basename "$PWD")-${BRANCH#v2/fix/}"
385+
git fetch origin v2/main
386+
# The push runs only after the gate exits 0, from the worktree holding the fork's head.
387+
[ -n "$FORK" ] && git fetch "https://github.com/$FORK.git" "$BRANCH" \
388+
&& git worktree add --detach "$WT" FETCH_HEAD \
389+
&& cd "$WT" && npm install && npm run local:gate \
390+
&& git push origin "HEAD:refs/heads/$BRANCH"
391+
```
392+
393+
If the branch no longer merges cleanly onto `origin/v2/main`, resolve that in
394+
the fork, where the review is, before pushing.
395+
396+
The worktree is on a detached `HEAD`, so `gh pr create` cannot infer the
397+
branch: add `--head "$BRANCH"` to `/pr-flow`'s create command.
398+
399+
- **Title**: `fix(<server>): GHSA-xxxx-yyyy-zzzz`, and nothing more.
400+
- **Body**: `Closes #<N>` (the converted issue) on the first line, then
401+
`/pr-flow`'s sections, **describing no part of the vulnerability**: what it
402+
is ("the fix for GHSA-xxxx-yyyy-zzzz, reviewed in the advisory's private
403+
fork; details stay with the advisory until it is published"), the gate's
404+
result, and each checklist item answered. Client evidence stays with the
405+
advisory; say so under **How Has This Been Tested?** rather than recording
406+
scenarios that describe the attack.
407+
- Label it `v2`, link it with `addCloseIssueReferences` and read the link back
408+
(`/pr-flow` step 6), and move the card to **In Review** if it is not there
409+
already.
410+
- ⚠️ **No Copilot review: skip `/pr-flow` steps 7 to 9.** Review comments on a
411+
public PR are public, and a reviewer's findings would describe the
412+
vulnerability. The review happened in the fork. Do not request one.
413+
414+
#### Merge it, then close the issue
415+
416+
A maintainer merges it once CI passes. Then close the issue by hand and move
417+
its card to **Done** (`/pr-flow` step 10), as for any PR into `v2/main`:
418+
`Done` means the work shipped, and it has.
332419

333420
#### Close the fork's PR once its fix is on `v2/main`
334421

335422
**GitHub will not publish an advisory while its private fork has an open pull
336423
request.** The advisory page says "you must merge or close outstanding pull
337424
requests" and **Publish advisory** stays disabled. The fix reaches `v2/main`
338-
through a PR in this repository, so the fork's own PR is left open with
339-
nothing still to merge, and blocks publication until someone closes it.
425+
through the public PR above, so the fork's own PR is left open with nothing
426+
still to merge, and blocks publication until someone closes it.
340427

341428
Closing it is mechanical and reversible (a PR can be reopened), and it neither
342429
closes nor publishes the advisory. Close a PR **only once its head is on
@@ -381,9 +468,10 @@ fork, so check each of these first:
381468
- **Nothing that matters lives only in the fork.** Publishing deletes it.
382469
Review findings worth keeping, a residual-exposure note, a follow-up's
383470
write-up: copy each onto the advisory (if it belongs in what is published) or
384-
onto the draft card that tracks it (a follow-up's write-up goes in **its
385-
follow-up card's** `## Write-up` section, where step 6 reads it), within step
386-
4's confidentiality limits, before the button is pressed.
471+
onto the follow-up draft card that tracks it (a follow-up's write-up goes in
472+
**its follow-up card's** `## Write-up` section, where step 6 reads it), within
473+
step 4's confidentiality limits, before the button is pressed. Never onto the
474+
converted issue, which is public.
387475

388476
- **The affected product**: ecosystem (`npm` or `pip`) and package name, as
389477
published (`@modelcontextprotocol/server-filesystem`, `mcp-server-git`).
@@ -402,33 +490,25 @@ fork, so check each of these first:
402490
platforms or cases are still exposed, so a user who upgrades does not believe
403491
they are fully covered.
404492

405-
### 6. After publication, convert the card into public tracking
493+
### 6. After publication, give the issue its public title
406494

407-
**The trigger is publication, not the release.** The release ships the fix
408-
while the advisory can still be private, and a public issue opened in that gap
495+
**The trigger is publication, not the merge or the release.** Both happen while
496+
the advisory can still be private, and a summary added to the issue in that gap
409497
describes a vulnerability the advisory has not disclosed yet.
410498

411-
⚠️ **Convert the draft; do not file a new issue.** "Convert to issue" creates a
412-
**new** issue from the draft card, and there is no way to point an existing card
413-
at an issue filed separately, so filing by hand and then converting produces two
414-
issues and two cards.
499+
1. **Retitle the issue** `[GHSA-xxxx-yyyy-zzzz] - <published summary>`. Only
500+
now, with the advisory public, may the summary appear.
501+
2. **Replace the body's triage lines** with a link to the now-public advisory.
415502

416-
1. **Give the card its public title first**, `[GHSA-xxxx-yyyy-zzzz] - <published
417-
summary>` (edit the draft's title on the card), since the issue takes the
418-
card's title. Only now, with the advisory public, may the summary appear.
419-
2. **Convert the draft card to an issue** in `modelcontextprotocol/servers`
420-
(the card keeps its place and its field values). The recipe is in
421-
`/board-ops`.
422-
3. Apply the labels and milestone from `/issue-create` (steps 1 and 2): `v2`,
423-
one type label (normally `bug`), the server's scope label, and the milestone
424-
of the release the fix shipped in. **Skip its board step**: the converted
425-
card is already on #43.
426-
4. Replace the body's triage lines with a link to the now-public advisory, and
427-
**close** the issue: the work shipped before the issue existed.
428-
5. Move the card to **`Done`**, which is right here because the fix shipped.
503+
```sh
504+
gh issue edit <N> --repo modelcontextprotocol/servers \
505+
--title "[GHSA-xxxx-yyyy-zzzz] - <published summary>" --body-file <file>
506+
```
507+
508+
The issue is already closed and its card in `Done` (step 5); neither changes.
429509

430-
**A follow-up card converts at the same time, but stays open**, because its
431-
work has not shipped:
510+
**A follow-up card converts now, and stays open**, because its work has not
511+
shipped:
432512

433513
1. Retitle it `[GHSA-xxxx-yyyy-zzzz follow-up] - <summary>`.
434514
2. Convert it.

0 commit comments

Comments
 (0)