20.1 Writing Effective Security Advisories¶

A security advisory is often the first communication users receive about a vulnerability affecting software they depend on. In those critical moments, the quality of the advisory directly impacts how quickly and effectively users can protect themselves. When the Log4Shell vulnerability was disclosed in December 2021, the initial advisory from Apache left many users uncertain about whether they were affected and what exactly they needed to do. Organizations scrambled to interpret version ranges, understand the attack vector, and determine appropriate mitigations. Clearer initial communication could have reduced the chaos that followed.

Security advisories serve as the authoritative source of information about vulnerabilities, bridging the gap between those who discovered and fixed the issue and those who must respond to it. A well-written advisory enables rapid triage, informs prioritization decisions, and provides clear remediation paths. A poorly written advisory generates confusion, support tickets, and delayed response—potentially leaving users exposed longer than necessary.

Advisory Structure and Content Elements¶

Effective advisories follow a consistent structure that allows readers to quickly find the information they need. Users approach advisories with specific questions: Am I affected? How severe is this? What do I need to do? Your structure should answer these questions efficiently.

Essential advisory elements:

1. Title: Clear, descriptive summary of the vulnerability
2. Identifier(s): CVE number, vendor-specific ID, advisory number
3. Severity rating: CVSS score and qualitative rating (Critical, High, Medium, Low)
4. Affected versions: Precise version ranges that contain the vulnerability
5. Fixed versions: Versions that contain the fix
6. Summary: Brief description of the vulnerability accessible to non-security experts
7. Technical details: Deeper explanation for those who need to understand the issue
8. Impact: What an attacker can achieve by exploiting this vulnerability
9. Remediation: Specific steps to address the vulnerability
10. Workarounds: Temporary mitigations if immediate upgrade is not possible
11. Timeline: Discovery, report, fix, and disclosure dates
12. Credit: Acknowledgment of the reporter (if they consent)
13. References: Links to patches, related advisories, and additional resources

Advisory template:

# [Project Name] Security Advisory: [Brief Description]

**Advisory ID**: [Project]-SA-2024-001
**CVE**: CVE-2024-XXXXX
**Severity**: [Critical|High|Medium|Low] (CVSS 3.1: X.X)
**Published**: 2024-XX-XX
**Updated**: 2024-XX-XX

# Summary
[2-3 sentence description of the vulnerability accessible to general technical audience]

## Affected Versions
- [package-name] ≥ 1.2.0, < 1.5.3
- [package-name] ≥ 2.0.0, < 2.1.1

## Fixed Versions
- [package-name] 1.5.3
- [package-name] 2.1.1

## Severity Assessment
**CVSS 3.1 Score**: X.X ([Vector String])
**Impact**: [Description of what attacker can achieve]
**Exploitability**: [How difficult is exploitation, prerequisites]

## Technical Details
[Detailed technical description for security professionals]

## Remediation
### Recommended: Upgrade
[Specific upgrade instructions]

### Workaround
[Temporary mitigation if upgrade not immediately possible]

## Timeline
- 2024-XX-XX: Vulnerability reported by [reporter]
- 2024-XX-XX: Fix developed
- 2024-XX-XX: Fix released
- 2024-XX-XX: Public disclosure

## Credit
[Reporter acknowledgment]

## References
- [Link to patch/commit]
- [Link to release notes]
- [Related advisories]

Severity Assessment and Communication¶

Severity ratings help users prioritize response. The Common Vulnerability Scoring System (CVSS) provides a standardized framework for assessing severity, producing a numerical score from 0.0 to 10.0 and corresponding qualitative ratings.

CVSS 3.1 severity ratings:

When communicating severity, include both the numerical score and the qualitative rating. The score provides precision; the rating provides quick triage guidance.

CVSS vector communication:

Include the full CVSS vector string to enable users to understand the scoring rationale:

CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H

This vector indicates: Network-accessible, Low complexity, No privileges required, No user interaction, Unchanged scope, High impact to Confidentiality, Integrity, and Availability. Users familiar with CVSS can quickly assess whether your scoring aligns with their risk context.

Contextualize severity:

Raw CVSS scores do not capture deployment context. A vulnerability in a library used in internal tooling differs from the same vulnerability in internet-facing production systems. Help users understand applicability:

"This vulnerability is most severe in deployments where untrusted users can submit input that is processed by the affected component. Deployments where input is strictly controlled may be at reduced risk."

Avoid both under-stating and over-stating severity. Under-statement leads to delayed response; over-statement leads to alert fatigue and eroded trust in future advisories.

Affected Version Identification¶

Precise version specification is critical. Users must determine whether their specific version is affected, often across multiple applications using different versions of the same dependency.

Version range specification:

Use clear, unambiguous notation that matches your ecosystem's conventions:

• npm/Node.js: ≥1.2.0 <1.5.3 or 1.2.0 - 1.5.2
• Python/PyPI: ≥1.2.0,<1.5.3
• Maven/Java: [1.2.0, 1.5.3) (inclusive start, exclusive end)
• Semantic versioning: ≥1.2.0 <1.5.3 || ≥2.0.0 <2.1.1

For complex version histories, provide explicit lists:

## Affected Versions
The following versions are affected:
- 1.x series: 1.2.0, 1.2.1, 1.3.0, 1.4.0, 1.4.1, 1.5.0, 1.5.1, 1.5.2
- 2.x series: 2.0.0, 2.1.0

**Not affected**: 1.0.x, 1.1.x (vulnerable code not yet introduced), 1.5.3+ (patched), 2.1.1+ (patched)

Backport information:

If fixes are backported to multiple release branches, clearly indicate which version in each branch contains the fix:

## Fixed Versions
- 3.x users: Upgrade to 3.2.1 or later
- 2.x users: Upgrade to 2.8.5 or later
- 1.x users: This branch is end-of-life; upgrade to supported version

Remediation Guidance Clarity¶

The remediation section is what users act on. Ambiguity here directly translates to delayed or incorrect response.

Effective remediation guidance:

1. Be specific about actions: Provide exact commands, not general directions.

❌ "Upgrade to the latest version"

✅ "Upgrade to version 2.1.1 or later: npm install package-name@2.1.1"

1. Address multiple scenarios: Users have different constraints; provide guidance for each:

### If you can upgrade immediately
Update your dependency to version 2.1.1:
- npm: `npm install package-name@2.1.1`
- yarn: `yarn add package-name@2.1.1`

### If you cannot upgrade immediately
Apply the following workaround until upgrade is possible:
[Specific workaround steps]

### If you use a bundled/vendored copy
Replace the affected file with the patched version from [link]

1. Explain verification: Tell users how to confirm remediation was successful:

### Verify remediation
After upgrading, verify you are running the patched version:

1. Acknowledge limitations: If the fix requires additional steps beyond package upgrade (configuration changes, cache clearing, service restart), document them.

CVE Assignment Process¶

Common Vulnerabilities and Exposures (CVE) identifiers provide a universal reference for vulnerabilities, enabling coordination across tools, databases, and organizations.

CVE assignment process:

1. Determine if a CVE is needed: CVEs are appropriate for vulnerabilities in software that others use. Internal application bugs, configuration issues, and non-security bugs typically do not warrant CVEs.

2. Request through appropriate CNA: CVE Numbering Authorities (CNAs) are authorized to assign CVE IDs. Options include:

3. Project CNA: Large projects (Apache, Linux kernel, major vendors) are often CNAs and assign their own CVEs
4. GitHub CNA: For projects hosted on GitHub, request through GitHub Security Advisories

5. Root CNA: For projects without another path, request through MITRE or a root CNA

6. Provide required information:

7. Affected product and versions
8. Vulnerability type (CWE if known)
9. Impact description

10. References (advisory, patch, disclosure)

11. Coordinate timing: Request CVE reservation during coordinated disclosure preparation, but do not publish the CVE details until the advisory is public.

GitHub Security Advisory workflow:

1. Navigate to repository → Security → Advisories → New draft advisory
2. Fill in vulnerability details
3. Request CVE assignment (GitHub is a CNA)
4. Coordinate with reporter on disclosure date
5. Publish advisory (CVE becomes public simultaneously)

Distribution Channels and Timing¶

Advisory distribution determines who learns about the vulnerability and when. Effective distribution balances broad reach against the risk of alerting attackers before users can respond.

Distribution channels:

Timing considerations:

• Coordinated disclosure: Work with reporters to establish a disclosure date that allows time for fix development and user preparation. Common windows are 90 days from report (a standard established by Google Project Zero), but this varies by severity and complexity.

• Embargo periods: For critical vulnerabilities, consider private notification to major users or distributions before public disclosure. This requires trusted relationships and clear embargo terms.

• Patch availability: Do not disclose before a fix is available unless the vulnerability is already being exploited or publicly known.

• Day of week: Avoid disclosing on Fridays or before holidays when response teams may be unavailable. Tuesday or Wednesday often work well.

• Time of day: Choose a time that works across major time zones of your user base. Morning in US Eastern time often works for global audiences.

Examples of Effective and Ineffective Advisories¶

Ineffective advisory example:

# Security Fix in Version 2.0

We fixed a security issue. Please upgrade.

Fixed in 2.0.

Problems: - No severity indication - No CVE or identifier - Vague description—users cannot assess impact - Incomplete version information—what versions are affected? - No remediation guidance beyond "upgrade" - No timeline or credit

Effective advisory example:

# ImageMagick Security Advisory: Heap Buffer Overflow in PNG Processing

**Advisory ID**: IMGK-2024-001
**CVE**: CVE-2024-12345
**Severity**: High (CVSS 3.1: 8.1)
**Published**: 2024-03-15

## Summary
A heap buffer overflow vulnerability exists in ImageMagick's PNG processing 
code. An attacker who can cause ImageMagick to process a maliciously crafted 
PNG file can achieve remote code execution with the privileges of the 
ImageMagick process.

## Affected Versions
- ImageMagick 7.1.0-0 through 7.1.1-28
- ImageMagick 6.9.12-0 through 6.9.12-98

## Fixed Versions
- ImageMagick 7.1.1-29
- ImageMagick 6.9.12-99

## Impact
An attacker can exploit this vulnerability by causing a vulnerable ImageMagick 
installation to process a specially crafted PNG image. This could occur through:
- Web applications that process user-uploaded images
- Email systems that generate image thumbnails
- Document processing pipelines

Successful exploitation allows arbitrary code execution.

## Remediation
### Upgrade (Recommended)
Upgrade to ImageMagick 7.1.1-29 or 6.9.12-99 or later.

### Workaround
If immediate upgrade is not possible, disable PNG processing by adding 
the following to your policy.xml:
```xml
<policy domain="coder" rights="none" pattern="PNG" />

Timeline¶

• 2024-02-01: Vulnerability reported by Jane Smith
• 2024-02-15: Fix developed and tested
• 2024-03-15: Fixed versions released, advisory published

Credit¶

This vulnerability was discovered and reported by Jane Smith of Example Security.

References¶

• Patch: https://github.com/ImageMagick/ImageMagick/commit/abc123
• Release notes: https://imagemagick.org/releases/ ```

This advisory works because it: - Provides clear severity assessment - Specifies exact affected and fixed versions - Explains impact in practical terms - Offers both remediation and workaround - Includes timeline and proper credit - Links to relevant resources

Recommendations¶

We recommend the following practices for security advisory writing:

1. Use consistent templates: Standardize advisory format across your project or organization to ensure completeness and enable efficient reading.

2. Write for multiple audiences: Your advisory will be read by security professionals, developers, and managers. Include both technical detail and accessible summaries.

3. Be specific about versions: Ambiguous version information creates uncertainty and delays response. Err on the side of explicit enumeration.

4. Provide actionable remediation: Specific commands and verification steps reduce user effort and increase successful remediation rates.

5. Request CVE early: Begin the CVE assignment process when you confirm the vulnerability, not when you're ready to disclose.

6. Coordinate timing thoughtfully: Balance transparency with responsible disclosure, choosing timing that enables user response.

7. Review before publication: Have someone unfamiliar with the vulnerability review the advisory. If they cannot determine whether they're affected and what to do, revise.

Clear advisories demonstrate respect for your users and contribute to the overall security of the ecosystem. The time invested in writing effective advisories pays dividends in faster, more complete remediation across your user base.