What to do when you receive a vulnerability report: A step-by-step guide for maintainers

Security reports don’t have to be panic-inducing

Finding a vulnerability report in your inbox can feel overwhelming, especially if it’s your first. But the process doesn’t have to be chaotic. With a clear workflow and the free security tooling GitHub provides for open source projects, maintainers can move from report to resolution without exposing users to risk.

The core idea: coordinated disclosure

Vulnerabilities should not be discussed in public threads the way ordinary bugs are. An unpatched issue can serve as a blueprint for attackers, so the fix should be developed privately before anything goes public. This is the essence of Coordinated Vulnerability Disclosure (CVD): researchers and maintainers work together behind the scenes until a patch is ready.

GitHub supports this workflow with three complementary tools:

• Private Vulnerability Reporting (PVR) – a private channel for researchers to submit findings
• Draft security advisories – a private workspace to develop and test the fix
• Dependabot alerts – automated notifications that push patched versions to affected users

The workflow in five steps

Handling a report comes down to a repeatable sequence:

1. Enable PVR to receive submissions confidentially
2. Work on the fix in a draft advisory
3. Request a CVE identifier where broader tracking is warranted
4. Publish the advisory when the fix is ready
5. Use Dependabot alerts and other channels to inform and protect users

Start by opening a secure channel

Security researchers who spot problems in your project need to know where to send them. Without a clear, private reporting path, they may post findings publicly, notify the wrong person, or abandon the report altogether. PVR solves this by giving every repository a built-in, confidential inbox for security issues.

Two configuration points matter:

• Enable PVR for your repository or organization
• Turn on notifications, because maintainers do not recieve them for new PVR reports by default

Set expectations with SECURITY.md

PVR tells researchers where to report. A SECURITY.md file tells them how to report well. Without it, you risk vague submissions that require significant back-and-forth to triage.

A good SECURITY.md should cover:

• The reporting channel, e.g., “Please submit reports through PVR”
• What details to include, such as reproduction steps and affected versions

Fix in private with a draft advisory

Once a report is confirmed as a valid vulnerability, the work begins — but it cannot happen in a public pull request. A visible patch tipsoff attackers before users have a chance to update. Instead, draft security advisories create a private workspace for the entire fix cycle.

• Discussions remain private, visible only to you and chosen collaborators
• Patches, plans, and conversation stay centralized in one secure place
• The draft converts to a public advisory when you’re ready

This puts the disclosure timeline in your hands, ensuring the issue is resolved before it becomes common knowledge. See how to create a draft advisory.

Request a CVE for wider tracking

Some vulnerabilities are minor and contained. Others affect the broader ecosystem and need an industry-standard reference. A Common Vulnerabilities and Exposures (CVE) identifier serves as that serial number.

GitHub lets you request a CVEIdentifier directly from a draft advisory. Why bother?

• It documents the issue in recognized security databases
• It validates the researcher’s finding as acknowledged and recorded
• Security tools, feeds, and automated systems use CVEs to standardize communication

A CVE does not change the severity of a vulnerability. It ensures that affected parties can consistently track and respond to it. Once assigned, the CVE stays private, linked to your advisory, until you publish. Request a CVE following these instructions.

Publish when the patch is out

With the fix in place, it’s time to go public. A security advisory is more than a disclosure — it’s a guide that tells users what happened and what to do next.

• It informs users about the issue and how to fix it
• It builds trust through proactive transparency
• It triggers automated alerts — Dependabot scans published advisories to warn developers using affected dependencies

Writing an effective advisory

• Use plain language accessible to technical and non-technical readers
• State the essentials: the vulnerability’s description and impact, affected versions, and remediation steps
• Link to resources: patched releases, workarounds for users who cannot update immediately, and extra documentation

See this advisory for a well-structured reference.

Publishing is not the final step

An advisory only protects users if they see it. Publication should trigger a broader communication effort.

• Announce through your usual channels — blog posts, release notes, mailing lists, community forums
• Keep it documented — future adopters may not know that older versions carried a security flaw

GitHub’s tooling amplifies your reach after publication:

• Dependabot alerts automatically notify developers using affected dependencies and nudge them toward patched versions
• Proactive prevention means using scanning tools to check whether similar problems exist elsewhere in your codebase and reviewing dependency health regularly
• CVE records are published to CVE.org after the advisory goes public, and eligible advisories are addedto the GitHub Advisory Database

Maintainer FAQ: Handling the edge cases

Why use Private Vulnerability Reporting?

Private Vulnerability Reporting (PVR) is generally a better channel than email or public issues for receiving vulnerability reports. The main advantages:

• Confidentiality: Sensitive details stay private, eliminating the risk of accidental disclosure through public channels or email threads.
• Centralization: All discussion, reports, and updates live in one place within the repository, rather than scattered across inboxes.
• Researcher experience: PVR gives security researchers a dedicated, structured pathway for reporting issues.

What if the report looks like a false positive?

Before dismissing any report, review it thoroughly. An apparent false positive may stem from a misunderstanding of how a feature works, so check the relevant code and documentation carefully. If details are unclear, ask the reporter clarifying questions through the PVR thread; most researchers will gladly provide more context. For uncertain cases, bring in a team member or a colleague with security experience to help validate the finding.

If the report does turn out to be a false positive, document your reasoning in the PVR thread before closing it. Transparent communication maintains a professional relationship and builds trust with the researcher.

Response timing and severity assessment

Acknowledge receipt as soon as possible, even if a fix isn't ready. A simple confirmation that the report is being reviewed keeps the reporter engaged. While there's no formal deadline, the common best practice among security professionals is to address verified vulnerabilities within 90 days.

For prioritizing work, the Common Vulnerability Scoring System (CVSS) provides a structured way to gauge severity. Use the CVSS calculator to evaluate impact and exploitability, but also consider real-world context. A vulnerability requiring special conditions to exploit may be lower risk than one triggerable by any user. The reporter can often provide useful insight into realistic exploitation scenarios.

CVE timing: before or after publishing an advisory?

The right order depends on urgency. CVE assignment can take one to three days, so for critical issues, publish the advisory first to avoid delaying the fix and request the CVE afterwards. For less urgent cases, request the CVE beforehand so it's included in Dependabot alerts from the start. Either sequence results in a published advisory and informed users.

Further resources

• GitHub security documentation: Detailed guidance on repository security advisories and coordinated disclosure.
• Open Source Security Foundation (OpenSSF): Community resources for open source security practices.

Next steps for your project

• Enable private vulnerability reporting for your repositories to establish an official reporting channel.
• Review GitHub Security Advisories documentation to streamline your disclosure workflow.
• Study coordinated vulnerability disclosure practices to build a security-first approach.