Security Advisory Release Notes
How to write release notes for security patches. Covers CVE references, severity levels, affected versions, and responsible disclosure practices.
Security
Detailed Explanation
Security Release Notes
Security releases require special care in documentation. You need to provide enough information for users to assess risk and urgency without revealing exploit details that could be used against unpatched systems.
Required Information
- Severity level (Critical, High, Medium, Low)
- CVE identifier if assigned
- Affected versions range
- Fixed version number
- Brief description of the vulnerability type
- Credit to the reporter (with their permission)
Example
## [1.5.1] - 2026-02-28
### Security
- **HIGH:** Fix SQL injection vulnerability in query builder when using
raw user input with `where()` clause. All versions from 1.3.0 to
1.5.0 are affected. CVE-2026-12345. (Reported by @security-researcher)
- **MEDIUM:** Fix SSRF vulnerability in URL validation that allowed
requests to internal network addresses. Affects versions 1.4.0-1.5.0.
CVE-2026-12346.
### Fixed
- Sanitize all user-provided strings in SQL query builder (#892)
- Add strict URL validation with private IP range blocking (#895)
Communication Strategy
- Coordinate disclosure timing with reporters and affected parties
- Pre-announce the release date without details so users can plan
- After release, wait 24-72 hours before publishing full technical details
- Include the fix in all supported release branches (e.g., v1.4.x, v1.5.x)
- Mark the release as urgent and communicate through multiple channels
Severity Levels
| Level | Description |
|---|---|
| Critical | Remote code execution, data breach without authentication |
| High | Data access, privilege escalation, SQL injection |
| Medium | XSS, CSRF, information disclosure |
| Low | Minor information leaks, denial of service edge cases |
Use Case
Publishing a security patch for a vulnerability discovered through a bug bounty program or security audit, where clear documentation helps users assess whether they are affected and how urgently they need to upgrade.