Nancy Gariché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.
What is coordinated vulnerability disclosure (CVD)?
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.
Step 1: review the security policy
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.
What is a security policy?
The security policy is a statement that instructs vulnerability reporters on how and where to report security vulnerabilities to the project’s security contact. It sets expectations of communication and response. Security policies may range from just listing a security contact email to elaborate instructions on how to submit to third-party bug bounty platforms.
Step 2: find the security contact information
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.
Step 3: review the vulnerability management process
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:
- Acknowledgment — In a perfect world, the VMT should acknowledge receipt of your report within a few days, but your experience may vary depending on the resources of the team you work with.
- Assessment — The VMT assesses your reported issue. If they determine it is not a security threat, they may stop the disclosure process and ask you to submit it as a public non-security issue instead.
- Patch creation — Once the vulnerability is confirmed, the project maintainers will begin developing a patch out of the public eye. At this step, they may reach out to you to help develop and test the patch.
- Common vulnerabilities and exposures (CVE) number request — The project may request a CVE entry if the vulnerability is eligible for one.
- Public disclosure — Once a patch is published, maintainers will notify users and direct them to update.
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.
Step 4: write an effective report
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:
- The impact of the vulnerability
- A list of the affected versions
- The code introducing the vulnerability
- A reproducible PoC
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.
Best practices when reporting a vulnerability
By following a few best practices, you can greatly enhance the effectiveness of your report and help resolve any issues.
Adopt a maintainer-first approach
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.
Set clear expectations in your disclosure policy
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.
Help remediate
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.
Ask to collaborate in a private environment
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:
- Privately discuss the impact of the vulnerability on the project.
- Privately collaborate to fix the vulnerability in a temporary private fork.
- Publish the final security advisory to alert the community once a patch is released.
- Obtain a CVE number from GitHub. The CVE details are published once the security advisory is made public.
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.
Ask for credit
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.
Do not expect payment
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.
How to address challenges when things don’t go as planned
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.
What if you can’t establish contact with the project team at all?
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.
There is a disagreement about the disclosure deadline
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.
The project team is unresponsive
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:
- Full disclosure – If it’s urgent that you act quickly to notify the consumers, then full disclosure can be the best solution. When reporters decide to take this route, it means that they will publicly release the vulnerability in its entirety. If the vulnerability doesn’t have a known fix, this leads to a zero-day vulnerability.
- Report to a third party – If the vulnerability is very easy to exploit and has big consequences, then full disclosure is dangerous. Consider reaching out to a third party for help, such as an industry regulator or data protection authority.
If you’re unsure about how to proceed, we welcome you to contact the GitHub Security Lab for advice.
Conclusion
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.
