How to Write a Security Advisory That Actually Helps

A security advisory is the document that tells your users: something is wrong, here is what you need to do about it, and here is how urgent it is. When written well, an advisory drives rapid remediation. When written poorly, it either causes panic without actionable guidance or gets ignored because the urgency is not communicated.

Most software projects publish advisories reactively, written under time pressure, without a template or process. The result is inconsistent, often inadequate advisories that leave users guessing. A little structure goes a long way.

Advisory Structure

An effective advisory has seven sections. Each serves a specific audience and purpose.

1. Title and Identifier

The title should be descriptive enough to identify the issue without revealing exploitation details.

Good: "Authentication bypass in API token validation" Bad: "Security fix" (too vague) Bad: "Token validation skips signature check when header contains null byte" (too specific)

Include all relevant identifiers: CVE ID, GHSA ID, your internal advisory ID. Multiple identifiers help users cross-reference across advisory databases and vulnerability scanners.

2. Severity Rating

Use CVSS to provide a standardized severity score, and include the qualitative rating (Critical, High, Medium, Low). Provide the CVSS vector string so users can see the components of the score.

Also include a plain-language severity summary: "This vulnerability allows unauthenticated remote attackers to bypass authentication and access any user account. Exploitation requires no special privileges or user interaction."

The CVSS score tells scanners how to prioritize. The plain-language summary tells humans whether to drop everything.

3. Affected Versions

Be precise about which versions are affected:

• Affected: versions 2.0.0 through 2.4.3
• Fixed in: version 2.4.4
• Not affected: versions 1.x (the vulnerable code was introduced in 2.0.0)

If the vulnerability exists in multiple release branches, list each branch separately:

• 2.x: affected 2.0.0-2.4.3, fixed in 2.4.4
• 3.x: affected 3.0.0-3.1.1, fixed in 3.1.2

Users need this information to determine if they are exposed and what version to update to.

4. Description

Describe the vulnerability with enough detail for a defender to understand the risk but not enough for an attacker to develop an exploit.

Include:

• The general category of vulnerability (authentication bypass, injection, RCE, etc.)
• The preconditions for exploitation (does the attacker need authentication? Network access? Specific configuration?)
• The impact of successful exploitation (data access, code execution, denial of service?)
• Whether the vulnerability is being exploited in the wild

Exclude:

• The exact code path or function where the vulnerability exists
• The specific input format or payload structure needed for exploitation
• References to proof-of-concept exploits
• Commit hashes that show the fix (which reveal the vulnerability by diffing)

5. Mitigation and Remediation

Tell users exactly what to do:

Primary remediation: "Update to version 2.4.4 or later."

Workaround (if update is not immediately possible): "If you cannot update immediately, disable the affected feature by setting TOKEN_VALIDATION_STRICT=true in your configuration. This mitigates the vulnerability but may affect functionality for users with older token formats."

What does not work: If there are common misconceptions about mitigations, address them. "Web application firewalls (WAFs) do not reliably detect this attack pattern. Updating is the only complete mitigation."

6. Timeline

Provide a disclosure timeline so users and researchers can evaluate your response:

• Date vulnerability was reported
• Date the report was acknowledged
• Date the fix was developed and tested
• Date the advisory and fix were published
• Date (future) full technical details will be published

This transparency builds trust. A timeline showing acknowledgment within 24 hours and a fix within two weeks demonstrates a mature security response process.

7. Credit and Acknowledgment

Credit the reporter (with their permission). This:

• Encourages future responsible disclosure
• Demonstrates that your project values security research
• Provides accountability for the quality of the report

Distribution

Publishing the advisory on your project's GitHub Security Advisories page is necessary but not sufficient. Ensure broad distribution:

Immediate Distribution

• Project website/blog: Publish the advisory prominently
• GitHub Security Advisory: Creates automatic vulnerability alerts for users via Dependabot
• Ecosystem advisory database: Submit to npm audit, PyPI safety, RubyGems advisory, etc.
• CVE: Request a CVE through the appropriate CNA (CVE Numbering Authority)
• OSV.dev: Ensure representation in the OSV database

Notification Distribution

• Mailing list: If your project has a security mailing list, send the advisory
• Social media: Announce the advisory (without vulnerability details) on project social channels
• Direct notification: For critical vulnerabilities, consider directly notifying known large users

Common Mistakes

Downplaying Severity

Some projects minimize severity to avoid negative attention. This is counterproductive. Users who discover they were exposed to a vulnerability that was downplayed lose trust permanently. If a vulnerability is critical, say so.

Mixing Security and Feature Releases

Releasing a security fix bundled with new features forces users to adopt both simultaneously. For significant security fixes, release a minimal patch that only contains the security fix. Users can then update without risking feature-related regressions.

Delayed Disclosure

Sitting on a known vulnerability to bundle it with a scheduled release leaves users exposed longer than necessary. Security fixes should be released as soon as they are ready, independent of the release schedule.

Silent Patching

Fixing a vulnerability without publishing an advisory deprives users of the information they need to assess their exposure and urgency. Users who discover a silent patch lose trust in the project's transparency.

Incomplete Version Ranges

Stating "this vulnerability affects recent versions" without specifying exact version ranges makes it impossible for users to determine if they are affected. Be precise.

Templates

Maintain advisory templates so that under the time pressure of an active vulnerability, you are filling in fields rather than designing a document from scratch. A good template includes all seven sections listed above with placeholder text and formatting guidance.

Many platforms provide advisory templates:

• GitHub Security Advisories provide a structured form
• CERT/CC provides advisory templates
• The OSV schema provides a machine-readable template

How Safeguard.sh Helps

Safeguard.sh accelerates advisory consumption for your organization by parsing advisories from all major databases and correlating them against your dependency inventory within minutes of publication. When your organization publishes software, Safeguard's SBOM and vulnerability data provide the accurate version range and impact information needed to write precise advisories. The platform's compliance reporting documents your advisory publication practices, demonstrating to auditors that your organization communicates security issues responsibly.