security-advisory

# Handling a security advisory Private vulnerability reporting is enabled on this repository and [`SECURITY.md`](../../../SECURITY.md) routes every report to it. A report therefore arrives as a **repository security advisory**, never as an issue, and for most of its life it must **not** become one: a public issue would disclose the vulnerability before a fix exists. Two steps in this flow are **outward-facing, and both stay human-only**: **accepting** an advisory (the reporter sees it) and **publishing** it (it becomes public, and there is no unpublish). Closing one as invalid, and every reply to a reporter, is outward-facing too. **An agent never takes any of these steps**: not once, not in bulk, not because a checklist said to. It investigates, prepares a recommendation, and a maintainer acts on it. Everything else here is mechanics. ⚠️ **Keep advisory details out of every public place**: issues, PRs, commit messages, branch names, and comments. Until an advisory is published, the only things safe to say in public about the backlog are **aggregate counts** (how many are in each state). A branch named after the bug, or a commit message that describes it, discloses it as surely as an issue would. Related: `/board-ops` holds the board IDs and the draft-card recipes, and `/issue-create` gives public tracking its labels and milestone **after publication**, never merely after the release (step 6). ⚠️ **The PR flow does not apply to the fix itself.** It needs a public issue and a public PR against `v2/main`, which is the disclosure this flow exists to delay. The fix is reviewed inside the private fork (step 4), and `AGENTS.md` records that fork PR as an exception to its PR rules (no public issue link, no labels, tracked by the draft card). ## The flow | # | Step | Gate | | --- | --- | --- | | 1 | Advisory in state `triage` → **draft card** on board #43 | Mechanical | | 2 | **Verify the claim**: which server, and does the code belong to it or to an SDK? | Judgment | | 3 | Valid and ours → **accept** (`triage` → `draft`); otherwise close with a reason | **Human only** | | 4 | Create the **private fork**, fix and review there | Mechanical | | 5 | Merge to `v2/main`, milestone merge, **release**, then **publish** | **Human only** | | 6 | **After publication**, convert the draft card into a public issue | Mechanical | There is **one release line**. Every fix lands on `v2/main` and ships through the next milestone merge to `main` and a release, as any other change does ([`RELEASING.md`](../../../RELEASING.md)). No older line is patched, so "which lines are affected" is never a question here. ### 1. Board it as a draft card An advisory gets a **draft card**, the one exception to [`AGENTS.md`](../../../AGENTS.md#issue-driven-work-style)'s "every board item is a real GitHub issue". - **Title:** the bare id, `[GHSA-xxxx-yyyy-zzzz]`, and **no summary until the advisory is published**. A summary can name the server or the attack class, and the card is read by a wider audience than the advisory (see the body's warning below). The `[GHSA-` prefix is not cosmetic: it is the only thing that tells an advisory draft apart from a stray draft card, which is still a defect to delete, so any audit of the board's drafts keys on it, and it is the exact lookup key. - **Body:** `**Advisory:** <html_url>` on the first line, then the severity the reporter claimed, the reported date, and the provisional Priority line below. The link comes first because a maintainer reading the card has no other route back to the private advisory. ⚠️ **Do not copy the vulnerability description onto the card.** Project access and advisory access are **separate permission sets**: anyone who can see board #43 reads the card, whether or not they are a collaborator on the advisory. The board is private, so this is a wider audience than intended rather than a public leak, but a reproduction or a proof of concept belongs only with the people handling it. The card carries the **link and triage metadata only**. - **Status `Incoming`**, with a **provisional Priority** from what the report claims. `Incoming` is right even though somebody looked at it to make the card: nobody has approved a fix yet, and a draft card has no milestone to carry that approval. ⚠️ **Provisional is the only honest score at this point.** Step 2 checks ownership **before** severity, and a report can look severe right up until it turns out to be an SDK's code, or no vulnerability at all. So score what the report claims now, and **re-score at the end of step 2**. Until the `issue-triage` rubric lands (#4868), map the advisory's severity with the table below. (`/issue-create`'s Priority table would put every security report at `Urgent`, which leaves the re-score nothing to change.) An unverified claim sits one level below a verified one: | Advisory severity | Provisional (step 1, as claimed) | Re-scored (step 2, verified and ours) | | --- | --- | --- | | `critical` | High | Urgent | | `high` | High | Urgent | | `medium` | Medium | High | | `low` | Low | Medium | Re-score by the severity you verified, which may differ from the claim. Write the result into the body as `Priority <level> (provisional, <YYYY-MM-DD>)`: a draft card has no comments, so the body is the only place the score can be recorded. When you re-score (step 2), keep that line, add `Priority <level> (verified, <YYYY-MM-DD>)` under it so the change of view is legible, and **set the card's Priority field to the verified level**. Numbers and level names only; the reasoning behind a score is the impact, which belongs in the private advisory. ⚠️ **Set both fields.** A draft card has no labels and no milestone, so its Status and Priority are all the triage state it carries. The create and lookup recipes are in `/board-ops` ([Advisory draft cards](../board-ops/SKILL.md#advisory-draft-cards)). The card is made **by hand** (by a maintainer, or an agent working for one), not by a workflow: a board write needs `organization projects: write`, which a workflow's `GITHUB_TOKEN` cannot hold. To see what is waiting (**output is private; never paste it into an issue or a PR**): ```sh # --paginate: the endpoint returns 30 per page, and an inventory that silently # stops at the first page reads as "nothing pending". gh api --paginate repos/modelcontextprotocol/servers/security-advisories \ --jq '.[] | select(.state=="triage") | "\(.ghsa_id)\t\(.severity)\t\([.vulnerabilities[]?.package.name] | join(","))\t\(.summary)"' # Aggregate counts by state: the only form that may appear in public. gh api --paginate repos/modelcontextprotocol/servers/security-advisories \ --jq '.[].state' | sort | uniq -c ``` ### 2. Verify the claim: which server, and whose code Before assessing severity, establish that the vulnerable code is **ours**, in this order: 1. **Is it one of the seven servers under `src/`?** Many servers once lived in this repository and were moved to [`servers-archived`](https://github.com/modelcontextprotocol/servers-archived), which is unmaintained and read-only. A report against one of those is **out of scope**: there is no code here to fix and nothing to release. Servers listed in the README or the Registry are third-party; their reports go to their own maintainers. 2. **Is the code path the server's, or an SDK's?** The TypeScript servers are built on the TypeScript SDK's v2 packages (`@modelcontextprotocol/server`, `@modelcontextprotocol/node` and the frozen `@modelcontextprotocol/server-legacy`) ([typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk)), the Python servers on `mcp` ([python-sdk](https://github.com/modelcontextprotocol/python-sdk)). Transport handling (Streamable HTTP, SSE, stdio framing, session management, Origin and DNS-rebinding checks) and message validation usually live in the SDK. A report can be entirely accurate about behavior a server merely exhibits because its SDK does it. Reproduce it, find the line that does the wrong thing, and check whether that line is in `src/<server>/` or reached through the dependency. 3. **Does the server claim the boundary that was crossed?** These are **reference implementations** (the README says so), and a server doing what its README documents is not a vulnerability. A way around a boundary the server _does_ claim (allowed directories, Roots, `robots.txt`) is one. The caveat bears on severity and scope; it is never a reason to skip reading a report. ⚠️ **"The SDK's problem" is not a reason to say it in public.** A genuine, unfixed vulnerability handed to a public SDK issue is disclosed, by us, on someone else's behalf, before they have a fix. Route it through **that SDK's private advisory form** (private reporting is enabled on both SDK repos), and reference a public SDK issue only once the SDK has published. Where the reporter would rather carry it over themselves, say so and let them. #### The reach classes Three servers act on the host, and nearly every real advisory lands in one of their classes. Know them before reading a report, because the report often names the symptom rather than the class: | Server | What it can reach | Classes to check | | --- | --- | --- | | `filesystem` | Reads and writes the local disk, limited to the allowed directories and the client's Roots | **Path traversal** (`..`, absolute paths, Windows drive and UNC forms, a prefix match that lets `/data` admit `/data-other`); **symlink escape** (a link inside an allowed directory pointing out of it, a link swapped in between check and use); **Roots bypass** (the allowed set not narrowed or refreshed as the client's Roots say) | | `git` | Runs git against repository paths it is given | **Path traversal** and **symlink escape** out of the configured repository; **Roots bypass**; **argument injection** (a value that starts with `-` read by git as an option) | | `fetch` | Makes outbound HTTP requests to URLs it is given | **SSRF** (loopback, private and link-local addresses, cloud metadata endpoints, a redirect or a DNS answer that lands on one); **robots bypass** (`robots.txt` not honored, or not re-checked after a redirect, when the server claims to honor it) | `everything`, `memory`, `sequentialthinking` and `time` reach much less: `memory` writes one file at a configured path, and `everything`'s HTTP transports are mostly SDK code (see ownership, above). **Now re-score the card's Priority**: add the `verified` line under the provisional one (step 1), and set the card's Priority field to match with the `/board-ops` edit recipe, so the board orders by the verified level. This is the first point where severity has anything solid under it: the code is ours, it reproduces, and you know which class and which server. ### 3. Accept, or close (human only) **Valid and ours → accept.** In the UI this is "Accept and open as draft"; it moves the advisory `triage` → `draft`. The API shows it as `state` and `submission.accepted`. **Then move the card `Incoming` → `Todo`.** On board #43 the approval act is normally assigning a milestone, and a draft card cannot carry one, so for an advisory draft **accepting the advisory is the approval**. `AGENTS.md` records this as the advisory exemption to its `Incoming` ⇔ milestone rule. The milestone arrives with the public issue in step 6, where the ordinary rule resumes. **Invalid, out of scope, a duplicate, or an SDK's → close** with a comment saying which, and why; for an SDK's, say where it was routed. A reporter who is told nothing reasonably assumes they were ignored. ⚠️ **Closing an advisory leaves its draft card behind: delete it.** Nothing shipped, so `Done` would be a false record, and `Incoming` would claim work is still queued. The delete recipe is in `/board-ops`. ⚠️ **Accepting, closing and replying are human acts, always.** Each is visible to the reporter, and accepting commits the project to treating the report as a real vulnerability. Nothing in this skill authorizes an agent to take them: write the recommendation (accept or close, the class, the owner, the evidence) and let a maintainer click. ⚠️ **There is no comment API for security advisories.** Not in REST (the advisory object has no comments endpoint) and not in GraphQL (no advisory comment mutation exists). Comments are **UI-only**, so every exchange with a reporter is manual, and the thread cannot be read back with `gh`. ### 4. The private fork An accepted advisory is fixed in a **private fork** GitHub creates for it: a private repository named `servers-ghsa-xxxx-yyyy-zzzz` (the id in lowercase) in the org; read the exact name from `.private_fork.full_name`. ⚠️ **Read `private_fork` FIRST. The POST is not a probe; it CREATES one.** Calling it to "check whether a fork exists" makes one, which then needs cleaning up. ```sh # Does one already exist? gh api repos/modelcontextprotocol/servers/security-advisories/<GHSA_ID> \ --jq '.private_fork // "none"' # Only if that printed "none": gh api -X POST \ repos/modelcontextprotocol/servers/security-advisories/<GHSA_ID>/forks # → 202 Accepted; the fork appears shortly afterwards. ``` ⚠️ **Deleting a private fork needs the `delete_repo` OAuth scope, which a default `gh` token does not carry.** A fork created by mistake cannot be quietly undone; it takes a re-scoped token or an admin in the UI. That asymmetry is the reason for the read-first rule. Fix and review inside the fork. The fix follows the rules in `AGENTS.md` like any other change: a regression test that fails before the fix, and the gate under **Before pushing**. Name the branch `v2/fix/<ghsa-id>` (lowercase, **no descriptive slug**, since a branch name outlives the fork once merged), and keep commit messages equally opaque until publication. **The fork's PR targets `v2/main`**, never `main`: check its base before anyone merges it. ⚠️ **Move the card as the work moves.** `In Progress` when the fix is started, `In Review` when the fork's PR is open. The fork is invisible to everyone not on the advisory, so this card is the only place the rest of the team can see the work exists at all. #### Work the fix leaves open: a follow-up card A fix can leave part of the problem open: a platform the fix cannot reach yet, or a residual exposure that needs a larger change. That work cannot become a public issue before publication either, because describing it describes the vulnerability. Track it with a **second draft card**, the advisory's **follow-up card**, rather than widening the fix or leaving the gap in a PR body nobody will read again. - **Title:** `[GHSA-xxxx-yyyy-zzzz follow-up]`, as opaque as the advisory's own card. The `[GHSA-` prefix keeps it inside the board audit's advisory exemption. The advisory card's lookup (`/board-ops`) matches `[GHSA-xxxx-yyyy-zzzz]` with its closing bracket, so it never finds the follow-up by mistake. A second follow-up for the same advisory is `[GHSA-xxxx-yyyy-zzzz follow-up 2]`. - **Body:** the same link-and-triage-only rule as step 1. Its lines, in order: - `**Advisory:** <html_url>` on the first line. - `Follow-up to the fix for this advisory. Convert to an issue only once the advisory is published.` - A link to the write-up. - The `Priority <level> (provisional, <YYYY-MM-DD>)` line. - **The write-up lives in the private fork**, where only the advisory's collaborators can read it. Draft it as the public issue it will become (problem, options, acceptance criteria), and post it as a `COMMENT` review on the fork's PR, since the fork refuses issue comments (see the API table). - **Status `Todo`** when a maintainer asked for the follow-up: the advisory is already accepted, and asking for the work approves it. Otherwise it goes in `Incoming`. Score its Priority with step 1's table, using the severity of the residual exposure rather than the advisory's. - **Say in the fix PR's body what the fix leaves open**, and link the follow-up. The advisory's text must say it too when it is published (step 5). Create it with `/board-ops`'s draft-card recipe, using the follow-up title in place of `[$GHSA]`. ⚠️ **The follow-up card is the only exception beyond the advisory's own card.** Any other untracked work an advisory's review turns up falls into one of three cases: - It is part of the fix. - It is a **separate vulnerability**, which goes through its own private advisory: this repository's for ours, or the SDK's advisory form for an SDK's (step 2). Publishing this advisory never makes another one safe to disclose. - It is non-security work outside the advisory's scope, which gets a public issue **after publication**, like any other finding. ### 5. Merge, release, publish (human only) Publish **after** the fix has shipped in a release, never before: publishing discloses the vulnerability, and doing it while users have no upgrade hands out a working exploit. **Shipped** means the fixed version of that server is on npm or PyPI. ⚠️ **The patch stops being secret at MERGE, not at publish.** Merging the fork puts an ordinary public commit on `v2/main`, readable by anyone, and it then travels through the milestone merge to `main` before `release.yml` publishes it. The time between merge and publish is not a period of secrecy; it is a period of **exposure to anyone reading commits**, so keep it short: merge close to the release, and publish as soon as the release is out. The release itself is a maintainer action (`release.yml` runs only when a maintainer publishes a GitHub Release, behind the `release` environment's approval; see [`RELEASING.md`](../../../RELEASING.md)). Say which server needs a release and stop there. ⚠️ **Publishing is irreversible and human-only.** It makes the advisory public, with no undo. Same rule as accepting: recommend, never perform. **Before publishing, check what publishing will show**, because a published advisory is what users and advisory tooling (Dependabot, `npm audit`, `pip-audit`) remediate from: - **The affected product**: ecosystem (`npm` or `pip`) and package name, as published (`@modelcontextprotocol/server-filesystem`, `mcp-server-git`). - **The vulnerable version range**, and the **first patched version**: the version the release actually published, which is known only once that release is out. An advisory with no patched version tells nobody how to remediate. - **The severity**, as verified in step 2 rather than as reported.