20.5 Release Notes and Changelog Security¶

Release notes and changelogs serve as the primary communication channel between maintainers and users about what changed between versions. For security-relevant changes, this documentation carries particular weight: it informs users about vulnerabilities they need to address, guides their upgrade decisions, and provides context for why certain changes were made. Yet the same information that helps legitimate users also helps attackers identify exploitable flaws and target systems that haven't yet updated.

When a security fix lands in a new release, how you document it matters. Too vague, and users may not recognize the urgency of upgrading. Too detailed, and you hand attackers a roadmap to exploitation. Finding the right balance requires understanding your audience, the nature of the vulnerability, and the timing of your disclosure.

Security-Relevant Changes in Release Notes¶

Release notes should clearly identify which changes have security implications. Users scanning release notes need to quickly determine whether a release contains security fixes that warrant urgent attention versus routine improvements that can wait for normal update cycles.

Categories of security-relevant changes:

• Vulnerability fixes: Patches for identified security flaws (CVE-tracked or otherwise)
• Security enhancements: New security features, hardening measures, or improved defaults
• Dependency updates: Updates to dependencies that address security issues
• Breaking security changes: Modifications that require user action to maintain security
• Deprecations: Removal of insecure features or patterns

Each category warrants different treatment in release notes. Vulnerability fixes require the most careful balance between disclosure and protection; security enhancements can be documented more freely since they add rather than fix.

Minimum security content for releases:

Every release containing security-relevant changes should include:

1. Clear indication that security fixes are present
2. Severity assessment (Critical, High, Medium, Low)
3. CVE identifiers where assigned
4. Affected version range
5. Brief description sufficient for users to assess relevance
6. Reference to detailed advisory

# Security

### Fixed
- **CVE-2024-12345** (High): Fixed authentication bypass in OAuth handler
  - Affected versions: 2.0.0 - 2.3.4
  - See [Security Advisory SA-2024-001](link) for details

Balancing Transparency with Exploitation Risk¶

The fundamental tension in security release documentation is that the same information helping defenders also helps attackers. A detailed explanation of a vulnerability enables users to understand their risk but also enables attackers to develop exploits.

Factors affecting disclosure detail:

Graduated disclosure approach:

1. Initial release: Minimal detail—severity, affected versions, recommendation to upgrade
2. After adoption window (2-4 weeks): Moderate detail—vulnerability class, attack vector
3. Full disclosure (90 days or after widespread patching): Complete technical details

## Version 2.3.5 Release Notes (Initial)

### Security
- Fixed a High severity authentication issue affecting versions 2.0.0-2.3.4
- All users should upgrade immediately
- CVE-2024-12345 - Full details will be published on [date]

---

## Updated Security Notes (After 30 days)

### CVE-2024-12345: Authentication Bypass
- **Severity**: High (CVSS 8.1)
- **Vector**: Network-accessible, no authentication required
- **Impact**: Attacker could bypass authentication on endpoints using OAuth
- **Mitigation**: Upgrade to 2.3.5 or apply workaround [link]

When to provide immediate detail:

Some situations warrant immediate full disclosure:

• Vulnerability is already being actively exploited
• Exploit code is publicly available
• Details have been disclosed by others
• Vulnerability is trivially discoverable

In these cases, the information asymmetry works against defenders—attackers already know, so withholding detail only handicaps legitimate users.

Changelog Best Practices for Security¶

A well-maintained changelog provides a chronological record of notable changes, enabling users to understand the evolution of a project and make informed upgrade decisions. The Keep a Changelog specification provides a widely-adopted format.

Changelog format recommendations:

# Changelog

All notable changes to this project will be documented in this file.

## [2.3.5] - 2024-03-15

### Security
- Fixed authentication bypass in OAuth handler (CVE-2024-12345)
- Updated dependency `auth-lib` to 1.5.2 (addresses CVE-2024-11111)

### Fixed
- Corrected error handling in file upload validation

### Changed
- Improved rate limiting accuracy under high load

## [2.3.4] - 2024-02-28
...

Security section conventions:

• Place Security section prominently (typically first after version header)
• Include CVE identifiers for all tracked vulnerabilities
• Link to full security advisories
• Note dependency updates that address security issues
• Distinguish between fixes (patching vulnerabilities) and enhancements (adding security features)

Version numbering for security releases:

Semantic versioning (SemVer) conventions for security fixes:

• Patch version (x.y.Z): Security fixes that don't break compatibility
• Minor version (x.Y.0): Security enhancements that add features
• Major version (X.0.0): Breaking security changes that require user action

Some projects use dedicated security release conventions, such as appending -security or issuing rapid point releases. Whatever convention you adopt, document it clearly.

Communicating Breaking Security Changes¶

Some security improvements require breaking backward compatibility. Removing a vulnerable authentication method, changing default permissions, or requiring stronger credential storage may break existing deployments while improving security.

Breaking change communication:

## [3.0.0] - 2024-04-01

### BREAKING CHANGES (Security)

#### Removed: Legacy MD5 password hashing
- MD5 password hashing has been removed due to known weaknesses
- **Migration required**: Existing MD5 hashes must be upgraded before updating
- See [Migration Guide](link) for step-by-step instructions
- Legacy support available through `--allow-legacy-hashing` flag until 3.2.0

#### Changed: Default session timeout
- Default session timeout reduced from 24 hours to 1 hour
- **Action required**: Update configuration if longer sessions needed
- Set `session.timeout` in config to customize

### Upgrade Path
1. Review [Breaking Changes Guide](link)
2. Run migration script: `./migrate-passwords.sh`
3. Update configuration as needed
4. Upgrade to 3.0.0

Best practices for breaking security changes:

1. Provide advance notice: Announce planned breaking changes before the release
2. Offer migration paths: Scripts, documentation, or compatibility layers
3. Allow transition periods: Grace periods where old and new behaviors coexist
4. Explain the rationale: Help users understand why the change is necessary
5. Document rollback: If users cannot immediately upgrade, describe interim mitigations

Deprecation Notices for Insecure Patterns¶

Deprecation signals that a feature will be removed in future versions, giving users time to adapt. For security-related deprecations, clear communication prevents users from relying on soon-to-be-removed insecure functionality.

Deprecation notice best practices:

## Deprecation Notice: Basic Authentication

**Status**: Deprecated in 2.5.0 | Removal planned: 3.0.0

### Why
Basic Authentication transmits credentials with each request, increasing 
exposure risk. Token-based authentication provides better security properties.

### Timeline
- **2.5.0** (Current): Basic Auth deprecated, warnings logged
- **2.6.0**: Basic Auth disabled by default (enable via flag)
- **3.0.0**: Basic Auth removed entirely

### Migration
Replace Basic Auth with token-based authentication:
1. Generate API token: `./generate-token.sh`
2. Update clients to use `Authorization: Bearer <token>`
3. Test authentication flow
4. Remove Basic Auth credentials from configuration

### Resources
- [Token Authentication Guide](link)
- [Migration Script](link)
- [FAQ](link)

Elements of effective deprecation notices:

• Clear statement that the feature is deprecated
• Explanation of why (especially for security reasons)
• Specific timeline with version numbers
• Migration instructions
• Resources for help

Start deprecation warnings in logs well before removal. Users who monitor logs will have advance warning; those who don't will at least see warnings when they eventually update.

Documentation as a Security Feature¶

Comprehensive security documentation reduces the likelihood that users misconfigure your software in ways that create vulnerabilities. Documentation is not merely informational—it is a security control.

Security documentation essentials:

• Security model overview: What threats does the software protect against? What is out of scope?
• Secure configuration guide: Recommended settings for production deployment
• Authentication and authorization: How to properly configure access controls
• Secrets management: How to handle sensitive configuration
• Update procedures: How to safely apply updates, especially security updates
• Security contact: How to report vulnerabilities

Documentation anti-patterns:

• Examples that use insecure defaults (hardcoded passwords, disabled TLS)
• Tutorials that skip security steps for brevity
• Outdated documentation that describes deprecated insecure patterns
• Missing documentation for security-relevant configuration options

Documentation that shows insecure examples will be copied into production. Every example should be production-ready.

Review documentation for security implications just as you review code. Treat documentation bugs that could lead to insecure deployments as security issues.

Timing Considerations for Security Releases¶

When and how you release security fixes affects both attacker and defender timelines.

Release timing recommendations:

• Coordinate with advisory publication: Release fixed version simultaneously with or before advisory publication
• Avoid Fridays and holidays: Give users time to apply updates before weekends when response teams may be reduced
• Consider time zones: Choose release times that work for your global user base
• Allow for testing: If possible, provide release candidates to major users before general availability

Pre-announcement for major changes:

For significant security releases, especially those requiring user action:

1. Announce the upcoming release date (without vulnerability details)
2. Indicate severity and that updates will be required
3. Help users prepare change windows and resources
4. Release fix and advisory at the announced time

This approach, used by major projects like OpenSSL and Kubernetes, allows organizations to prepare for updates without revealing exploitable details to attackers.

Recommendations¶

We recommend the following practices for security release documentation:

1. Maintain a changelog: Use a consistent format that clearly identifies security-relevant changes. The Keep a Changelog specification provides an excellent foundation.

2. Include security sections: Every release with security content should have a dedicated Security section that enables quick identification.

3. Balance detail with timing: Provide enough information for users to assess urgency immediately; add technical details after users have had time to update.

4. Plan breaking changes carefully: Security improvements that break compatibility need advance notice, migration paths, and clear documentation.

5. Deprecate explicitly: When removing insecure features, provide clear timelines and migration guidance.

6. Treat documentation as security-critical: Review documentation for secure defaults, accurate examples, and completeness on security topics.

7. Time releases thoughtfully: Coordinate release timing with advisories and user schedules to maximize defensive advantage.

Release documentation is your ongoing communication channel with users. Treating it as a security-relevant artifact—with appropriate care, review, and strategic consideration—helps users stay secure while using your software.