Handling vulnerability reports: Recipe card

TLDR:

Set the Station: Define a clear reporting path in your README.md and SECURITY.md so reporters know where to deliver ingredients.

Taste Test First: Determine if a report is a real vulnerability or just a regular bug before starting the fire.

Plate for Everyone: Coordinate the patch release with a public CVE disclosure to serve your users safely.

The Recipe: Step-by-Step Instructions

This recipe card provides guidance for handling security vulnerabilities in open source projects. A security vulnerability is a flaw in a program that can be exploited by an attacker to compromise the confidentiality, integrity, or availability of a system. Security vulnerabilities often stem from bugs in a program, but not all bugs can be exploited. While many bugs appear in the kitchen, not all of them have the potential to compromise the confidentiality or integrity of your menu.

Spoiled ingredients can cause a lot of damage for patrons, in the same way that vulnerabilities can cause a lot of damage for end-users. So many users track & prioritize vulnerabilities to minimize impact. This process can generate a lot of work, so in this guide we aim to minimize the extra work needed for both project maintainers and end-users.

For more information about handling vulnerabilities, especially for larger projects, see the vulnerability disclosure guide from the OpenSSF.

Preparing to receive a vulnerability (prep the kitchen)

As a head chef, you want to hear from your customers when something is wrong, but you want them to reach out to you directly with the information, instead of posting it as a public review. Similarly, as a maintainer, you don’t want vulnerabilities to be reported to you through a plain bug issue, publicly visible to the world.
Make it as obvious and as easy as possible for people to find that path by including a security section directly in the README.md of the repository. This section can directly include the instructions, or point to the SECURITY.md file, which should also be at the root of the repository. 

The instructions for reporting a vulnerability should include:

• Threat model / accepted vulnerability bar
• Where to report: you can use Configuring private vulnerability reporting for a repository – GitHub Docs or a private email list
• Format for reporting
• Timelines
  • How long before the issue can be looked at
  • How long will it be before the disclosure
• Your bug bounty policy: if one exists. For small/medium sized projects, it is ok to not offer a bounty in exchange for finding vulnerabilities on your project.

After you get a report (the taste test)

Once you discover a vulnerability or have one reported, you will want to respond to the vulnerability without talking publicly about the vulnerability. This involves an “embargo” where key individuals from the project, usually maintainers, are made aware of the vulnerability and work with the reporter to address it.

Just as the first step with a questionable ingredient is to determine if it is actually spoiled, the first step when you get the report is to determine if it’s actually a vulnerability. Some reports may turn out to be a non-exploitable bug (meaning it can’t lead to an exploit) or a misunderstanding of the project’s expected behavior. To decide, discuss the report with the reporter and relevant project experts. Try to minimize the number of people involved in the discussion at this stage, and make sure everyone agrees to maintain confidentiality until the report becomes public. If you decide the report is not a vulnerability, direct the reporter to file a public issue instead, and you may follow any of the procedures in “publishing” to inform users. Think of it as adding a note to the menu that specific dishes contain cilantro.

If you are not sure whether a report is a bug, you can reach out to TAG Security and Compliance or CNCF staff for guidance. When reaching out, ask generally for guidance, or for the TAG leads to start a DM. Make sure to keep the contents of the report out of public channels at this stage. You can also consider the following questions:

• Is there a mitigation mechanism for users?
• Can this bug lead to compromise, data leaks, or other malicious activity?
• Is this a documentation error?

Use your judgement when adding someone to an embargo, and make sure they are aware that the vulnerability is not yet public, and that it needs to be handled appropriately and kept confidential, given the sensitivity of the matter. 

Just as a chef modifying a recipe avoids having too many extra cooks in the kitchen who might speak too loudly and be overheard, you should carefully manage who is informed about an embargo. Be intentional with your disclosures, involving only those essential contributors whose direct assistance is required to resolve the vulnerability. The embargo ensures that attackers do not have access to the vulnerability before it is patched.

Fixing a Vulnerability (cooking)

When patching a vulnerability, keep your preparation out of the public dining room. This means keeping the patch out of public conversations and pull requests until after it is public. People can guess at the vulnerability from the patch, and you want to give users a chance to update before the vulnerability becomes public. To do:

• If you are using the GitHub vulnerability reporting mechanism, you can create a private branch from the vulnerability report. If not, you can develop and review the patch over a private channel. 
• Test the fixes! Your existing CI may not work with private branches, so do your best to run tests locally. You are the maintainer, so use your best judgment about what testing needs to be done for the scope of the patch.
• Merge fast, be coordinated! Once you are confident that the patch fixes the vulnerability and is adequately tested, work to merge it fast. This is especially important if you are not using private branches. Ensure that enough maintainers were involved in the patch creation and testing to ensure speedy response. You can coordinate this with the publishing process to ensure that the patch and vulnerability are public at the same time. Just remember to check the code before publicizing the fix. Make sure to re-apply the taste test to ensure that the vulnerability is fixed.

Publishing the Disclosure (plating and serving)

Once the patch is fully baked, you want to plate it up and tell your users about it. It’s generally considered best practice to do this within 90 days of receiving the report.

One strategy is to have a list of users to disclose to privately. These users can be added to your embargo and patch before the vulnerability is public. But this requires long-term maintenance of this list of users. If this list already exists, or if you have the resources to maintain it, this is great, but most small projects will not be able to keep a list of users and their contact information up to date.

Just as food needs to be plated just before service, a common strategy is to make the patch available and announce the vulnerability at the same time so that users can patch quickly. This gives everyone the patch at the same time, and is much easier to coordinate a safe meal. To do so:

• Once the patch is landed in the codebase, you’ll need to build a new release. Use your normal process, but do so right away.

• You also need to publish a CVE. If you used GitHub private reporting, you can do so from within the GitHub UI for the report.
  • To get a CVE number, it must be assigned by a CNA (CVE Numbering Authority). GitHub is a CNA and can handle this for you, or you and the reporter can report directly to one of the listed CNAs to get a number.
  • The CVE severity score is assigned based on a list of questions. Work with the reporter to ensure the answers are accurate and that you agree on the assigned severity score.  
• Once published, CVEs go into OSV and other vulnerability databases. It will then show up in users’ vulnerability scans, which will help them know to update to your latest release.
• Consider publishing any proof of concept after the fix has been available for a while. This may be hard to do with private vulnerability reporting, but can give users extra time to patch.