security-advisory

Handling a security advisory

Private vulnerability reporting is enabled on this repository and 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). 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'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). 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):

# --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, 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 @modelcontextprotocol/sdk (typescript-sdk), the Python servers on mcp (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.

# 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.

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). 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.
• The credits. A privately reported advisory already credits its reporter (GitHub adds the credit on submission; it may still be pending the reporter's acceptance), so confirm it is there rather than adding it. An advisory a maintainer opened directly has no credits until someone is added, and an unadded finder is simply never credited.
• A CVE, if one is wanted: optional, and the advisory is the only place to request one.

6. After publication, convert the card into public tracking

The trigger is publication, not the release. The release ships the fix while the advisory can still be private, and a public issue opened in that gap describes a vulnerability the advisory has not disclosed yet.

⚠️ Convert the draft; do not file a new issue. "Convert to issue" creates a new issue from the draft card, and there is no way to point an existing card at an issue filed separately, so filing by hand and then converting produces two issues and two cards.

1. Give the card its public title first, [GHSA-xxxx-yyyy-zzzz] - <published summary> (edit the draft's title on the card), since the issue takes the card's title. Only now, with the advisory public, may the summary appear.
2. Convert the draft card to an issue in modelcontextprotocol/servers (the card keeps its place and its field values). The recipe is in /board-ops.
3. Apply the labels and milestone from /issue-create (steps 1 and 2): v2, one type label (normally bug), the server's scope label, and the milestone of the release the fix shipped in. Skip its board step: the converted card is already on #43.
4. Replace the body's triage lines with a link to the now-public advisory, and close the issue: the work shipped before the issue existed.
5. Move the card to Done, which is right here because the fix shipped.

API facts worth not re-deriving

Thing	Fact
States	triage → draft (accepted) → published; or closed
Accepted?	submission.accepted on the advisory object, alongside state
Listing	GET repos/{owner}/{repo}/security-advisories, 30 per page, so always --paginate
Private fork	POST …/security-advisories/{ghsa_id}/forks → 202, a private repo servers-ghsa-xxxx-yyyy-zzzz (lowercase) in the org; exact name in .private_fork.full_name
Fork idempotency	Read .private_fork first; the POST creates, it does not probe
Fork deletion	Needs the delete_repo OAuth scope, which a default gh token lacks
Comments	No API at all, REST or GraphQL; UI-only
Credits	credits_detailed on the advisory; a private report carries the reporter's credit (type reporter, state pending or accepted) from submission
Board writes	Not automatable from Actions: GITHUB_TOKEN cannot hold organization projects: write
SDK routing	Both SDK repos have private vulnerability reporting enabled; use their advisory forms