A comprehensive guide for vulnerability reporters.
As a vulnerability reporter, you play an important and valuable role in the open source ecosystem. In this guide, I will provide our recommended four-step process for vulnerability disclosure and make suggestions along the way to foster a positive experience.
On top of the many tasks open source maintainers do to continually improve their project and keep it running, they are also responsible for monitoring and correcting issues and bugs. They rely on vulnerability reporters, just like you, to help discover and patch vulnerabilities before bad actors can exploit them.
Correcting security flaws is a sensitive process. Publicly disclosing a vulnerability before releasing a patch could expose users to attacks. For this reason, coordinated disclosure, which I’ll discuss below, is typically the recommended approach for open source projects.
While I’ll also outline some best practices for open source maintainers, I will mainly focus on the vulnerability reporter’s role. For instructions catered to maintainers, please see the OpenSSF guide to coordinated vulnerability disclosure for open source software projects.
CVD is the process through which a reporter privately initiates a dialog with a project maintainer through their security contact. This allows both parties to confidentially coordinate and work together to publicly disclose the full details of a vulnerability once a patch is made available.
GitHub Security Lab conducted research among maintainers to understand their experience of the vulnerability disclosure process. Through this data, we discovered many opportunities to improve collaboration between security researchers and maintainers, which I’ll touch on throughout this guide.
If a project has a listed security policy, review it to learn how to properly engage their security contact. Following the rules of engagement described in the policy improves the chances that your issue will be addressed quickly and confidentially.
On GitHub, you’ll find a repository’s security policy in a SECURITY.md file in the root, docs, or .github folder.
The second step in reporting a vulnerability to an open source project is to find the security contact. Some projects might have a dedicated vulnerability management team (VMT), typically a small number of individuals who are responsible for promptly responding to vulnerability reports, keeping them confidential while they’re being addressed, and ensuring that the coordinated disclosure process is being followed. But the security contact can also be a maintainer, or even a specific contributor for a project. For the purposes of this guide, we will refer to the security contact as the VMT.
Security contact information, where available, will typically be included in a project’s security policy.
If there is no clear security contact defined, reaching out to the project owner, maintainer, or most active contributor are viable alternatives. If all else fails, requesting security contact information via a project issue is another option.
If you use an alternative contact methods, avoid disclosing sensitive information until you are confident that the right person will receive your report.
Not all open source projects operate the same way, and many projects don’t have vulnerability management processes. When documented, however, the vulnerability management process describes what the project team does when it is notified of a potential security issue. Reviewing this process will help you understand how to best communicate and collaborate with them.
A typical vulnerability management process consists of the following steps:
When available, you’ll likely find the details of a project’s vulnerability management process within its security policy.
Maintainers looking for guidance on how to build their own vulnerability management process should consult the OpenSSF guide to coordinated vulnerability disclosure for open source software projects.
Once you know how to get in touch with the VMT and are familiar with its response process, send in a report containing the details of the vulnerability.
Often, the security report will be handled by developers who do not have a security background. Make your report easy for maintainers to verify, triage, and fix by avoiding security jargon and clearly and concisely explaining the vulnerability and its impact.
An effective report includes a detailed description of the newly found vulnerability with reproducible steps and/or a working proof of concept (PoC). A reproducible PoC helps maintainers verify the report and its impact.
Elements to include in your report:
You can also add remediation advice or a proposed fix. The GitHub Security Lab open sourced its own report template and you can use it as an inspiration for yours.
By following a few best practices, you can greatly enhance the effectiveness of your report and help resolve any issues.
Remember that you are reporting the vulnerability to help the project be successful. This can only happen if you provide the maintainer with everything they need to correct the problem.
Always remember that maintaining an open source project is hard work! Maintainers exhaust a lot of time and effort to keep their projects running smoothly. This isn’t easy. The more details and support you can provide, the less daunting the fix will be for the maintainer.
Respect and empathy can go a long way toward making the CVD process as painless as possible.
In any relationship, clear and effective communication is the cure for conflict. The relationship between maintainers and vulnerability reporters is no different.
Just as maintainers are expected to set clear expectations in their security policy, reporters should do the same by providing a disclosure policy. This can help you avoid misunderstandings, especially when the project’s CVD processes aren’t mature. Truthfully, open source projects that have clearly defined security policies and response processes are few and far between.
That said, a maintainer-first approach suggests that when a project has a clear and mature response process, you should do your best to follow it and to collaborate with the team.
A critical element to include in your disclosure policy is the disclosure deadline. It indicates the latest time by which you will keep the vulnerability report private before making it public. The industry standard is 90 days.
If the Github Security Lab’s disclosure policy resonates with you, feel free to copy it and use it for your own disclosures.
Unfortunately, vulnerability reporters are often viewed as bearers of bad news. During our research, maintainers shared that upon receiving vulnerability reports, they experience a range of emotions, including anxiety and stress.
As is the tradition in OSS, pull requests are always welcome. Similar to a feature pull request, maintainers are very appreciative when the reporter includes recommendations on how the issue could be mitigated or resolved.
You should act as a contributor and inform the project members that you can help during patch development and review and during the testing process. Your security research background can often provide additional insights that will result in stronger remediation.
It’s important to work on the fix in a private environment. A public issue or pull request would expose the project to potential exploitation by malicious actors looking to capitalize on so-called N-day vulnerabilities, that is, vulnerabilities that have been fixed in the project but not yet announced downstream via a security advisory and CVE ID allocation.
GitHub Security Advisories (GHSA) make it easy for repository maintainers to privately discuss and fix a security vulnerability in a project. With GHSA, maintainers can create a draft security advisory and use it to:
Not all maintainers know about GitHub Security Advisories and CVEs or the benefits they provide during the disclosure process and after, to the projects’ consumers. You can play an important role in awareness and education by making maintainers aware of tools like GHSA that simplify the coordinated disclosure process.
You should be recognized for your efforts and findings. Giving vulnerability researchers credit for their contributions is a great way for maintainers to acknowledge the value you brought to the project. Do not hesitate to remind maintainers to acknowledge your contributions by asking them to include your name in the credits for the CVE. GitHub Security Advisories make it easy for maintainers to credit the reporters.
Unless there is an explicit bug bounty or other such vulnerability reward program in place for a project, you should think of your report as a volunteer contribution, not unlike any other OSS contribution.
Despite your best efforts, the success of coordinated vulnerability disclosure is not solely in your hands. Here are a few problems you may encounter and suggestions to resolve them.
GitHub Security Lab researchers have found that the most successful way to contact a project when there are no contact details available is to open a public GitHub issue, mention that you found a security issue, and ask to be contacted without providing vulnerability details.
You can also look for a “Contact us” page or a security.txt file on their website. You may also get lucky if you write to generic email addresses starting with security@ or abuse@. Finally, as a last resort, social media platforms can be an alternative avenue. When employed with care, they can be useful for reaching out to communities, as someone on Twitter or other forums may very well have the information you are looking for.
Again, if you use an alternative contact methods, avoid disclosing sensitive information until you are confident that the right person will receive your report.
If a project can’t meet the set deadline but makes steady progress and has good justifications for delays, remain flexible and consider providing more time. Otherwise, when the deadline approaches, make sure to reiterate your intention to disclose all details at that date. Ultimately, you can disclose at the date set in your policy.
Regrettably, for a multitude of reasons, maintainers may become unresponsive. Remain patient and don’t assume that they are brushing you off or that they don’t care about security. Open source projects are often understaffed and underfunded. Competing priorities may prevent teams from communicating promptly. Even if the disclosure deadline approaches and you decide to move forward with a publication, remain professional and positive! There are no winners in a hostile disclosure process.
As a last resort, you have a few options:
If you’re unsure about how to proceed, we welcome you to contact the GitHub Security Lab for advice.
A strong partnership between open source developers and security researchers is tantamount to securing open source software. The Security Lab will continue to investigate effective methods to foster collaboration between these communities.
Vulnerability reporters can help by adopting a maintainer-first approach. We encourage you to show empathy by being flexible and helpful throughout the disclosure process.
Follow GitHub Security Lab on Twitter for the latest in security research.
We’ve dramatically increased 2FA adoption on GitHub as part of our responsibility to make the software ecosystem more secure. Read on to learn how we secured millions of developers and why we’re urging more organizations to join us in these efforts.
This blog post is an in-depth walkthrough on how we perform security research leveraging GitHub features, including code scanning, CodeQL, and Codespaces.
In this post, I’ll look at CVE-2023-6241, a vulnerability in the Arm Mali GPU that allows a malicious app to gain arbitrary kernel code execution and root on an Android phone. I’ll show how this vulnerability can be exploited even when Memory Tagging Extension (MTE), a powerful mitigation, is enabled on the device.
Nancy Gariché 
