24.2 Responding to Vulnerability Reports¶

The email arrives unexpectedly: a security researcher has found a vulnerability in your project. What you do next—and how quickly you do it—determines whether this becomes a controlled security improvement or a chaotic scramble after public disclosure. Most maintainers receive vulnerability reports rarely, which means they're often unprepared when one arrives. Having a clear process in place transforms what could be an overwhelming situation into a manageable series of steps.

Effective vulnerability response balances multiple concerns: protecting your users from exploitation, treating reporters respectfully, coordinating fixes across affected versions, and communicating clearly without creating panic. This section provides a complete workflow for handling vulnerability reports from initial receipt through public disclosure.

Setting Up a Private Reporting Channel¶

Before you receive your first vulnerability report, establish channels for private communication. Public issue trackers are inappropriate for security reports—they expose vulnerabilities before fixes exist.

Private reporting channel options:

GitHub Private Vulnerability Reporting:

GitHub's built-in feature is the easiest option for GitHub-hosted projects:

1. Navigate to Settings → Code security and analysis
2. Enable "Private vulnerability reporting"
3. Customize the intake form (optional)

Reporters can then use Security → Report a vulnerability. You receive notifications like other GitHub alerts, and all communication stays within GitHub.

Dedicated email setup:

For projects not on GitHub, or as an alternative channel:

security@yourproject.org
- or -
yourproject-security@maintainer-email.com

Configure the email to: - Forward to all maintainers who handle security - Avoid auto-responders that leak report details - Use PGP encryption for sensitive projects

Security.md should list your channels:

# Reporting a Vulnerability

**Preferred**: Use [GitHub Security Advisories](repo-link/security/advisories/new)

**Alternative**: Email security@yourproject.org
- PGP key: [link to key]
- Fingerprint: XXXX XXXX XXXX XXXX XXXX

Triage: Assessing Severity and Impact¶

When a report arrives, your first task is understanding what you're dealing with. Not every report describes a real vulnerability; not every vulnerability requires emergency response.

Initial triage steps:

1. Acknowledge receipt: Reply within 48 hours, even if just to say you're looking into it
2. Reproduce the issue: Can you confirm the vulnerability exists?
3. Assess severity: How bad is this if exploited?
4. Determine affected scope: Which versions? Which configurations?
5. Estimate timeline: How long will a fix take?

Severity assessment methodology:

Use CVSS (Common Vulnerability Scoring System) for consistent severity assessment:

Severity translation:

Common triage outcomes:

• Valid vulnerability: Proceed with fix coordination
• Not a vulnerability: Explain why (configuration issue, intended behavior, theoretical only)
• Duplicate: Already reported; update reporter on status
• Out of scope: Issue in dependency, not your code; help redirect
• Insufficient information: Ask for reproduction steps, affected versions

Example triage response:

Thank you for reporting this issue. I've confirmed the vulnerability 
and assessed it as High severity (CVSS 7.8).

Affected versions: 2.0.0 through 2.3.4
Not affected: 1.x series (different code path)

I estimate 1-2 weeks to develop and test a fix. I'll keep you 
updated on progress. Would you like to be credited in the advisory?

Thanks for helping keep our users safe.

Coordinating Fixes: Timeline, Testing, Backports¶

Once you've confirmed a vulnerability, coordinate the fix carefully. Rushed fixes can introduce new bugs; slow fixes leave users exposed.

Fix coordination timeline template:

Day 0:     Report received, acknowledged
Day 1-3:   Reproduce, assess severity, determine scope
Day 3-7:   Develop fix
Day 7-10:  Test fix, review with reporter
Day 10-14: Prepare release, advisory, CVE request
Day 14:    Release fixed version, publish advisory
Day 14+:   Monitor for issues, support users

Adjust based on severity: - Critical: Compress to days, not weeks - Medium/Low: Can extend to match regular release cycles

Developing the fix:

1. Work privately: Use GitHub's temporary private fork feature (available through Security Advisories) or a private branch

2. Focus on the vulnerability: Resist the urge to include other changes—keep the fix minimal and auditable

3. Consider backports: Determine which supported versions need fixes

   v3.x (current) - will receive fix
   v2.x (supported) - will receive backport
   v1.x (end of life) - no fix, note in advisory
   

4. Involve the reporter: If they're willing, they can help review the fix for completeness

Testing considerations:

• Does the fix actually address the vulnerability?
• Does the fix introduce regressions?
• Does the fix work across all affected versions?
• Are there edge cases the fix doesn't cover?

Coordinating with the reporter:

Hi [Reporter],

I've developed a fix and would appreciate your review:
[Link to private PR or patch]

Does this adequately address the vulnerability you reported?
Are there any edge cases you think we should test?

I'm planning to release on [date]. Does this timeline work for you?

CVE Assignment and Advisory Publication¶

CVEs (Common Vulnerabilities and Exposures) provide unique identifiers that help users track vulnerabilities across tools and databases. Not every vulnerability needs a CVE, but they're recommended for significant issues in widely-used projects.

CVE request process:

Option 1: GitHub CNA (Easiest for GitHub projects)

GitHub is a CVE Numbering Authority (CNA) and can assign CVEs for projects hosted there:

1. Create a Security Advisory draft in your repository
2. Fill in vulnerability details
3. Check "Request CVE"
4. GitHub typically reviews requests within 72 hours

Option 2: MITRE CVE Request

For projects not on GitHub or when GitHub CNA doesn't apply:

1. Go to cveform.mitre.org
2. Select "Request a CVE ID"
3. Fill in vulnerability details
4. Wait for assignment (can take days to weeks)

CVE request information needed:

• Affected product and versions
• Vulnerability type (CWE ID if known)
• Attack vector and impact
• Discoverer/reporter information
• References (advisory URL, patches)

Advisory publication checklist:

Before publishing:

• Fix is complete and tested
• Fixed version is ready for release
• CVE assigned (if requesting one)
• Advisory text is clear and accurate
• Affected versions are correct
• Severity assessment is complete
• Credit is correct (with reporter approval)
• Downstream users notified (if applicable)

Advisory content template:

## Summary

[Brief description of the vulnerability]

## Severity

**CVSS Score**: 7.8 (High)
**Vector**: CVSS:3.1/AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H

## Affected Versions

- 2.0.0 through 2.3.4

## Patched Versions

- 2.3.5 (recommended)
- 2.2.8 (for 2.2.x users)

## Description

[More detailed technical description]

## Impact

[What an attacker could do]

## Mitigation

Update to a patched version immediately.

If you cannot update, [describe workarounds if any].

## Credit

This vulnerability was discovered and reported by [name/handle] 
through [coordinated disclosure / bug bounty program].

## References

- [Link to patch commit]
- [Link to release notes]
- CVE-YYYY-XXXXX

Communicating with Downstream Users¶

Your direct users need to know about the vulnerability, but your code may also be embedded in other projects. Effective communication reaches both audiences.

Downstream notification approaches:

Direct users (use your project):

Downstream maintainers (depend on your project):

GitHub Security Advisories automatically trigger Dependabot alerts for dependent projects—this is the most effective downstream notification mechanism.

For critical vulnerabilities, consider additional outreach: - Contact known large dependents directly - Post to relevant security mailing lists (oss-security) - Coordinate with distribution maintainers (Debian, Fedora, etc.)

Notification timing:

T-0:    Fixed version released
T-0:    Security advisory published
T-0:    GitHub Security Advisory creates automatic alerts
T+1:    Social media announcement (if warranted)
T+1:    Mailing list notification (if available)
T+7:    Check NVD publication, correct if needed

Balancing disclosure:

Effective advisories give users enough information to act without providing attackers a roadmap. Describe what's affected and how to fix it; avoid publishing exploit code in your advisory.

What to include in notifications: - Which versions are affected - Which versions are fixed - How to update - Severity assessment - Workarounds if update isn't immediately possible

What NOT to include: - Detailed exploitation steps - Proof-of-concept code - Specifics that make exploitation easier

Crediting Reporters and Fostering Good Relationships¶

Security researchers who report vulnerabilities responsibly are doing you and your users a favor. How you treat them affects whether they—and others—will report to you in the future.

Reporter acknowledgment best practices:

1. Respond promptly: Acknowledge receipt within 48 hours, even if you can't immediately triage

2. Keep them informed: Regular updates, even if just "still working on it"

   Weekly status update:
   "Fix is in development, estimating release next week. 
   Will share patch for your review soon."
   

3. Ask about credit preferences: Some want public credit; others prefer anonymity

   "Would you like to be credited in the advisory? If so, how 
   would you like to be named? (Name, handle, affiliation)"
   

4. Thank them publicly: In the advisory and release notes

   "Thanks to @researcher for responsibly disclosing this issue"
   

5. Consider additional recognition:

6. Hall of fame page on project website
7. Swag or merchandise (if available)
8. Letter of appreciation (for employment purposes)
9. Bug bounty payment (if you have a program)

Building long-term relationships:

Good experiences create ongoing relationships:

• Researchers who had positive experiences report again
• They may become contributors or security reviewers
• Word spreads in the security community

Handling difficult situations:

Sometimes coordination doesn't go smoothly:

Reporter wants faster disclosure:

"I understand your timeline concerns. Here's where we are and 
why: [explanation]. Can we agree on [specific date]? I'm working 
as fast as I can while ensuring the fix is solid."

Reporter threatens public disclosure:

"I'd strongly prefer coordinated disclosure to protect users. 
Can you share your concerns about the timeline? I'm open to 
discussing an earlier date if we can prepare adequately."

Reporter is unresponsive:

Proceed with your timeline. Document attempts to coordinate.
Publish advisory noting you were unable to coordinate timing
with the reporter.

Reporter publishes before you're ready:

Shift to emergency mode. Release whatever fix you have (even
partial). Publish advisory immediately. Consider workarounds.
Don't burn bridges—they may have had reasons for their timing.

Complete Vulnerability Response Workflow¶

Putting it all together:

PHASE 1: INITIAL RESPONSE (Day 0-3)
├── Receive report
├── Acknowledge within 48 hours
├── Reproduce vulnerability
├── Assess severity and scope
├── Communicate initial assessment to reporter
└── Agree on preliminary timeline

PHASE 2: FIX DEVELOPMENT (Day 3-10)
├── Develop fix in private
├── Test fix thoroughly
├── Request CVE if appropriate
├── Share fix with reporter for review
├── Prepare backports for supported versions
└── Draft security advisory

PHASE 3: RELEASE COORDINATION (Day 10-14)
├── Notify downstream maintainers (if needed)
├── Finalize advisory text
├── Prepare release artifacts
├── Coordinate disclosure date with reporter
└── Prepare communication (social, mailing list)

PHASE 4: DISCLOSURE (Day 14)
├── Release fixed version(s)
├── Publish security advisory
├── Announce via appropriate channels
├── Credit reporter
└── Monitor for issues

PHASE 5: POST-DISCLOSURE (Day 14+)
├── Support users with questions
├── Monitor for in-the-wild exploitation
├── Correct any advisory errors
├── Verify NVD entry accuracy
└── Document lessons learned

Recommendations¶

We recommend the following practices for vulnerability response:

1. Enable private reporting before you need it: Set up GitHub Security Advisories or a security email now. You don't want to figure this out during your first report.

2. Acknowledge reports quickly: Even "I received this and am looking into it" within 48 hours shows the reporter you're engaged.

3. Use CVSS for consistent severity assessment: Subjective severity leads to under- or over-reactions. CVSS provides a framework for consistent evaluation.

4. Work privately until ready: Use GitHub's temporary private fork feature. Don't let your fix commits reveal the vulnerability before users can update.

5. Request CVEs for significant vulnerabilities: CVEs help users track issues across tools and databases. GitHub makes this easy for GitHub-hosted projects.

6. Communicate clearly and appropriately: Tell users what's affected and how to fix it. Don't provide exploitation details that help attackers more than defenders.

7. Treat reporters as partners: They're helping you protect your users. Prompt communication, credit, and respect encourage future responsible reporting.

8. Document your process: After each vulnerability, note what worked and what didn't. Your process will improve with experience.

Vulnerability response is stressful, especially the first few times. Having a clear process transforms chaos into manageable steps. With each report you handle, you'll become more confident—and your users will be more secure.