Changelog and Security Disclosure Best Practices

A changelog is a trust document. When users decide whether to update your software, the changelog is their primary source of information. When that changelog includes security fixes, the stakes are higher: users need enough information to assess urgency without receiving a roadmap for exploitation.

Getting this balance right is harder than it looks. Too vague, and users do not understand the urgency. Too detailed, and attackers get a head start before users can patch. Most projects get it wrong in one direction or the other.

The Problem with Current Practices

Under-Disclosure

The most common failure mode: security fixes hidden in changelogs with no indication that they address a vulnerability.

Examples of under-disclosure:

• "Fixed edge case in input handling" (actually fixed a SQL injection vulnerability)
• "Updated parsing logic" (actually fixed a remote code execution through deserialization)
• "Improved error handling" (actually fixed an information disclosure vulnerability)
• No changelog entry at all for a commit that fixes a critical vulnerability

Under-disclosure harms users because they cannot distinguish security-critical updates from routine maintenance. A team that batches all updates monthly will treat a critical security fix the same as a minor refactoring, leaving the vulnerability open for weeks.

Over-Disclosure

The less common but more immediately dangerous failure: disclosing exploit details before users have had time to patch.

Examples of over-disclosure:

• "Fixed SQL injection in the /api/users endpoint when the sort parameter contains unescaped characters"
• "Fixed RCE via crafted YAML payload in the config parsing module (see exploit-poc.py in the tests directory)"

Over-disclosure provides a recipe for exploitation. Attackers monitor changelogs of popular projects specifically for this kind of detail.

Best Practices for Security Changelog Entries

Clear Security Indication

Mark security fixes clearly in the changelog. Use a consistent format that users can search for:

• A dedicated "Security" section in the changelog
• A [SECURITY] prefix on relevant entries
• Severity indicators (Critical, High, Medium, Low)

This allows users to quickly identify security-relevant changes without reading every changelog entry.

Appropriate Detail Level

For each security fix, include:

What to include:

• That it is a security fix (explicitly stated)
• The severity level (Critical, High, Medium, Low)
• The general category of vulnerability (e.g., "cross-site scripting," "denial of service," "authentication bypass")
• Which versions are affected
• The CVE identifier, if one has been assigned
• Credit to the reporter (if they consent)

What not to include:

• The specific code path or endpoint that was vulnerable
• The exact payload or technique needed to exploit the vulnerability
• Proof-of-concept code or links to exploits
• Internal implementation details that reveal the nature of the fix

Example of a Good Security Changelog Entry

## [2.3.1] - 2023-08-15

### Security

- **HIGH**: Fixed a cross-site scripting vulnerability in the
  comment rendering module that could allow execution of
  arbitrary scripts in a user's browser. CVE-2023-XXXXX.
  Affects versions 2.0.0 through 2.3.0. Reported by
  Jane Smith via the bug bounty program.

This entry tells users:

• It is a security fix (they should update)
• It is high severity (they should update soon)
• It is XSS (they can assess their exposure based on whether they use comments)
• Which versions are affected (they can check if they are exposed)
• There is a CVE for tracking purposes

It does not tell attackers:

• Which specific endpoint or parameter is vulnerable
• How to construct a malicious payload
• What the fix looks like (which would reveal the vulnerability pattern)

Coordinated Disclosure Timeline

When your project discovers or receives a report of a vulnerability, the disclosure timeline matters:

Before the Fix is Available

Do not publish the vulnerability in the changelog, issue tracker, or commit messages. The commit that fixes the vulnerability should have a non-descriptive message. If your project uses conventional commits, avoid fix(security): prefixes that draw attention.

When the Fix is Released

Publish the changelog entry with the release. The CVE (if requested) should be published simultaneously. Give your users 24-48 hours to update before publishing detailed information.

After Users Have Had Time to Patch

After a reasonable window (typically 7-30 days depending on the severity and your user base), you can publish a detailed advisory with full technical details. At this point, the information helps defenders more than attackers because most actively maintained deployments should have been updated.

Advisory Database Integration

Your changelog entry should be supplemented by entries in relevant advisory databases:

• GitHub Security Advisories (GHSA): If your project is on GitHub, create a security advisory. GitHub propagates these to downstream tools and scanners.
• OSV.dev: Ensure your vulnerability is represented in the OSV database for broad visibility.
• Ecosystem-specific databases: npm audit, PyPI safety, RubyGems advisory database.

These databases provide the structured data that vulnerability scanners need to detect the issue in downstream users' dependency trees.

Maintaining a Security Policy

Every project should have a SECURITY.md file that describes:

• How to report vulnerabilities (email, HackerOne, GitHub private advisory)
• What to expect after reporting (acknowledgment timeline, fix timeline)
• Supported versions and their security update status
• The project's disclosure policy

The SECURITY.md file sets expectations for both reporters and users. A project without one signals that security reports may not be taken seriously.

Changelog Tooling

Several tools help maintain security-aware changelogs:

• Keep a Changelog format: A simple, human-readable format with a dedicated "Security" category
• Conventional Commits: Structured commit messages that can auto-generate changelogs (but be careful not to include vulnerability details in commit messages)
• Release-please / standard-version: Automated changelog generation from commit messages
• GitHub Releases: Native changelog support with security advisory integration

Whichever tool you use, manually review auto-generated changelog entries for security fixes to ensure they follow disclosure best practices.

For Consumers: Reading Changelogs for Security

When evaluating dependency updates, check changelogs for security indicators:

• Look for dedicated "Security" sections
• Search for keywords: CVE, vulnerability, security fix, security patch
• Check if the version was released out of the normal cadence (emergency releases often indicate security fixes)
• Compare the commit diff for the release if the changelog is sparse
• Check advisory databases for the package even if the changelog does not mention security

How Safeguard.sh Helps

Safeguard.sh monitors changelogs and advisory databases for your dependencies, alerting when security-relevant changes are published. The platform parses changelog entries alongside CVE and advisory data to provide a complete picture of security changes in each dependency update. For organizations that publish software, Safeguard's compliance reporting includes evidence of your disclosure practices, demonstrating to auditors and customers that security fixes are communicated responsibly and in compliance with industry standards.