Coordinated vulnerability disclosure: a reporter’s guide
Vulnerability reporters play a critical role in the open source ecosystem. Maintainers juggle feature work, bug fixes, and project upkeep, and they rely on outside researchers to surface security flaws before attackers exploit them. Because publicly revealing a vulnerability before a fix exists can put users at risk, coordinated vulnerability disclosure (CVD) is the standard approach for open source projects.
CVD is the process whereby a reporter privately contacts a project’s security contact and works with the team to disclose the full technical details of a vulnerability only once a patch is available. The following four-step process outlines how to handle a disclosure from the reporter’s side. Maintainers looking for related guidance should consult the OpenSSF guide to coordinated vulnerability disclosure for open source software projects.
Step 1: read the security policy
A project’s security policy is the first place to look. It explains how to reach the security contact and what the team expects from reporters. Following the stated rules of engagement increases the likelihood that your report will be handled promptly and kept confidential. On GitHub, the policy usually lives in a SECURITY.md file in the repository root, docs, or .github folder.
Step 2: locate the security contact
Some projects maintain a dedicated vulnerability management team (VMT), typically a small group responsible for acknowledging, tracking, and coordinating the fix of incoming reports. In other projects, this responsibility falls to a single maintainer or active contributor. Where the project has a security policy, it usually lists the appropriate contact. If none is documented, reach out to the project owner or the most active contributor. As a last resort, request the contact information through a project issue.
When you use alternative contact routes, keep sensitive details to yourself until you are sure the right person is on the other end.
Step 3: understand the vulnerability management process
Not every project documents how it handles vulnerability reports, but those that do typically describe a workflow with these phases:
- Acknowledgment — An ideal team acknowledges your report within a few days. Response time varies with the size and resources of the maintainer team.
- Assessment — The team evaluates whether your finding is real and in scope. If not, they may redirect you to file it as an ordinary non-security issue.
- Patch creation — Once the vulnerability is confirmed, the maintainers develop a fix out of the public eye. They might bring you in to help write or test it.
- CVE request — If eligible, the project requests a Common Vulnerabilities and Exposures (CVE) identifier.
- Public disclosure — After the fix ships, the team publishes details and tells users to update.
Step 4: write a report maintainers can act on
Report handlers for open source projects are often core developers rather than security specialists. Make their job easy: skip the jargon and explain clearly what the bug is, what it allows, and how you reproduced it. A solid report covers the impact, affected versions, the code that introduces the flaw, and a reproducible proof of concept (PoC). Adding remediation suggestions or a proposed patch is a nice bonus; see the GitHub Security Lab’s report template for an example of how to structure yours.
Best practices for the disclosure process
Beyond the mechanics of writing a report, the tone and approach you take shape how fluently the whole process runs. Consider the practices below before you hit send.
Put the maintainer first
A vulnerability report should be something the project can grow from, not an adversarial problem delivered to an overworked maintainer. Information is only valuable when it’s actionable.
Maintainers put in substantial effort to run their projects. Your empathy and willingness to give complete, supportive details reduce the burden of the fix and make the entire exchange far more constructive.
Publish your own disclosure policy
Because many open source projects don’t have explicitly documented processes, you can remove guesswork by publishing yours. A core element to include is your disclosure deadline: how long you will wait before taking the report public. The industry-standard window is 90 days.
At the same time, a maintainer-first approach means deferring to the project’s workflow whenever it has an explicit, mature process. Feel free to borrow from the GitHub Security Lab’s disclosure policy to get started.
Offer hands-on help
Maintainers report that incoming vulnerability findings often provoke anxiety and stress. It doesn’t have to be that way.
Pull requests are the currency of open source, and security remediation is no different. Let the project know you can help develop and review the fix and test the release candidate. Your expertise as a security researcher often strengthens the eventual hardening.
Push for a private workspace
Collaborating on a fix in a public issue or pull request exposes users to N-day exploits — bugs already fixed upstream but not yet communicated downstream through a security advisory and CVE ID. Work with the maintainers to keep everything in a private venue until release day. GitHub Security Advisories (GHSA) provide exactly that: a draft advisory lets maintainers discuss impact, cooperate on a temporary private fork, publish the advisory once patched, and request a CVE number from GitHub that populates on public release.
Awareness matters more than you might think: many maintainers aren’t familiar with GHSAs or the benefits of CVEs and reserve codes. You can raise their understanding as part of the disclosure.
Ask for credit and set payment expectations
Attribution is a standard part of responsible research. Don’t hesitate to have your name listed on the CVE credit. And unless the project runs a formal bug bounty or rewards program, treat your research as community service, not billable labor.
When coordinated disclosure hits a wall
Even a well-run disclosure can stall. Maintainers can be hard to reach, miss deadlines, or go silent. Here is how to handle the common friction points without turning the process adversarial.
No contact details? Try these routes first
If the project publishes no security contact, GitHub Security Lab researchers recommend opening a public issue that states you found a security problem and asks for a private channel — without revealing any technical details. Check the project’s website for a “Contact us” page or a security.txt file. Generic addresses such as security@ and abuse@ sometimes work when the domain is the project’s own. As a final attempt, social media can connect you with community members who know the right person.
Until you are sure the report reaches the correct maintainer, keep sensitive information out of any alternative channel you use.
Deadline disputes
When a maintainer cannot meet the agreed date but shows steady progress and explains the delay, extend the deadline rather than forcing the issue. If you keep the original date, restate it clearly as it approaches: you will disclose everything on that day. Your policy, not the project’s convenience, ultimately governs when you publish.
Maintainers who go quiet
Unresponsive maintainers are often simply overloaded. Open source projects tend to be understaffed and underfunded, and competing work can push security communication down the list. Do not assume bad faith. If the deadline arrives and you proceed to publish, stay professional and constructive — a hostile exchange helps no one.
When you do reach the end of the road, two last-resort options remain:
- Full disclosure – Releasing the full vulnerability details protects consumers who need to act immediately. If no fix exists, this creates a zero-day vulnerability.
- Third-party reporting – For easy-to-exploit flaws with severe impact, full disclosure is risky. Contact a regulator or data protection authority instead and let them mediate.
Unsure which path fits your case? The GitHub Security Lab team can be reached at [email protected] for guidance.
Closing thoughts
Secure open source depends on a working relationship between maintainers and researchers. Reporters contribute most by taking a maintainer-first stance: be flexible, be helpful, and treat the people on the other side of the issue tracker as partners rather than obstacles.
